Mode

class sofia_redux.scan.channels.mode.mode.Mode(channel_group=None, gain_provider=None, name=None)

Bases: ABC

Create a mode operating on a given channel group.

A mode is an object that is applied to a given channel group, defining what constitutes its “gain” and how to operate thereon. This is also dependent on a gain provider.

Parameters:

channel_groupChannelGroup, optional

The channel group owned by the mode.

gain_providerstr or GainProvider, optional

If a string is provided a FieldGainProvider will be set to operate on the given field of the channel group.

namestr, optional

The name of the mode. If not provided, will be determined from the channel group name (if available).

Attributes Summary

flagspace	Return the flagspace for the mode channel group.
size	Return the size of the channel group.

Methods Summary

add_coupled_mode(coupled_mode)	Add a coupled mode to the available coupled modes of the mode.
apply_provider_gains(validate)	Sets the internal gain values as returned by the gain provider.
derive_gains(integration[, robust])	Return gains and weights derived from an integration.
flag_gains(normalize)	Flag gain values and propagate back to channel group.
get_frame_resolution(integration)	Returns the integration frame resolution.
get_gains([validate])	Return the gain values of the mode.
set_channel_group(channel_group)	Apply a channel group to the mode.
set_gain_provider(gain_provider)	Set the gain provider that operates on the channel group.
set_gains(gain[, flag_normalized])	Set the gain values of the mode.
set_name([name])	Set the name of the mode.
signal_length(integration)	Return the length of signal in terms of integration frame resolution.
sync_all_gains(integration, sum_wc2[, ...])	Synchronize all gains in the mode.
to_string()	Returns a long description of channels in the mode.
uniform_gains()	Sets all gains to unity.

Attributes Documentation

flagspace

Return the flagspace for the mode channel group.

Returns:

Flags

size

Return the size of the channel group.

Returns:

int

The number of channels owned by the channel group.

Methods Documentation

add_coupled_mode(coupled_mode)

Add a coupled mode to the available coupled modes of the mode.

Parameters:

coupled_modeCoupledMode

A coupled mode to append to the contained coupled modes of mode.

Returns:

None

apply_provider_gains(validate)

Sets the internal gain values as returned by the gain provider.

Any NaN gain values will be replaced by zeros.

Parameters:

validatebool

If True, causes the gain provider to “validate” the mode. This could mean anything, but is usually used to update internal gain provider settings.

Returns:

None

derive_gains(integration, robust=True)

Return gains and weights derived from an integration.

The returned values are the integration gains plus the mode gains. Weights are determined from only the integration.

Parameters:

integrationIntegration

robustbool, optional

If True, derives the gain increment from the integration using the “robust” definition. This is only applicable if the integration is not phase modulated.

Returns:

gains, weightsnumpy.ndarray (float), numpy.ndarray (float)

The gains and weights derived from the integration and mode. Note that all non-finite values are reset to zero weight and zero value.

flag_gains(normalize)

Flag gain values and propagate back to channel group.

Gains that are outside of the gain_range attribute range are flagged as the specified gain flag in the gain_flag attribute. Note that previously flagged channels may be unflagged if in-range.

Parameters:

normalizebool

If True, before checking if the gain values are within the allowable gain range, normalize with respect to the average gain of those channels previously flagged.

Returns:

flaggingbool

True if gains were checked for flagging and False otherwise. Note that this does not necessarily mean any flags were actually updated.

get_frame_resolution(integration)

Returns the integration frame resolution.

Parameters:

integrationIntegration

Returns:

resolutionint

The integration frame resolution.

get_gains(validate=True)

Return the gain values of the mode.

If no gains are available and no gain provider is available, will return an array of ones.

Parameters:

validatebool, optional

If True (default), will cause the gain provider to “validate” the mode itself. This could mean anything and is dependent on the gain provider.

Returns:

gainsnumpy.ndarray (float)

The gain values.

set_channel_group(channel_group)

Apply a channel group to the mode.

During this phase the gain flag type is determined as the zeroth flag of the channel group flagspace if previously undefined. In addition, the name of the mode will be set to the name of the channel group if not previously defined.

Parameters:

channel_groupChannelGroup

Returns:

None

set_gain_provider(gain_provider)

Set the gain provider that operates on the channel group.

The gain provider determines what attributes or fields of a channel group will be defined as the gain.

Parameters:

gain_providerstr or GainProvider

If a string is provided, a FieldGainProvider will be created that defines the gain as that field of the channel group data. If a gain provider is explicitly provided, it will be used instead.

Returns:

None

set_gains(gain, flag_normalized=True)

Set the gain values of the mode.

If a gain provider is available, it will be used to update the gain values, which could also update values in the channel group. Gains may be flagged depending on whether a gain range has been set (in the gain_range attribute). Note that any flagging will back propagate to the channel group and therefore, the channels themselves.

Parameters:

gainnumpy.ndarray (float)

The new gain values to apply.

flag_normalizedbool, optional

If True, will flag gain values outside the gain range after normalizing to the average gain value of those previously flagged.

Returns:

flaggingbool

If gain flagging was performed. This does not necessarily mean any channels were flagged, just that it was attempted.

set_name(name=None)

Set the name of the mode.

If not provided, the name will be determined from the channel group. If no channel group is available, the name will not be set.

Parameters:

namestr, optional

The new name of the mode.

Returns:

None

signal_length(integration)

Return the length of signal in terms of integration frame resolution.

Parameters:

integrationIntegration

Returns:

lengthint

The length of the signal in terms of integration frame resolution.

sync_all_gains(integration, sum_wc2, is_temp_ready=False)

Synchronize all gains in the mode.

Parameters:

integrationIntegration

sum_wc2numpy.ndarray (float)

An array of channel gains of shape (n_channels,)

is_temp_readybool, optional

Indicates whether the frame temporary values have already been calculated. These should contain:

temp_c = signal_value
temp_wc = relative_weight * signal_value
temp_wc2 = relative_weight * signal_value^2

Returns:

None

to_string()

Returns a long description of channels in the mode.

Returns:

descriptionstr

uniform_gains()

Sets all gains to unity.

Returns:

None