Modality¶

class sofia_redux.scan.channels.modality.modality.Modality(name=None, identity=None, channel_division=None, gain_provider=None, mode_class=None)[source]¶

Bases: ABC

Create a Modality.

A Modality is a collection of channel modes. A channel mode extracts/sets/operates-on gains from a channel group (collection of channels). Modes are created by the modality from a channel division which is a collection of channel groups. The type of mode may be explicitly defined or will be set to a default mode class for the modality.

The name of the modality should be set, as it is used by the modality to apply specific configuration options.

Parameters:

namestr, optional: The name of the modality.
identitystr, optional: A shorthand abbreviation for the modality.
channel_divisionChannelDivision, optional: A ChannelDivision object containing groups from which to create channel modes.
gain_providerGainProvider or str, optional: If a string is provided, a FieldGainProvider will be created that defined the gain as that field of the channel group data. If a gain provider is explicitly provided, it will be used instead.
mode_classclass, optional: The mode class to be used when creating modes from the channel groups inside the channel division. If not supplied, the default mode class for a modality will be used.

Attributes Summary

`fields`	Return the available channel data fields.
`flagspace`	Retrieves the channel flagspace from the first valid mode.
`size`	Returns the number of modes in the modality.

Methods Summary

`apply_gains`(integration, gains, gain_weights)	Apply gains to an integration for the modality.
`average_gains`(integration, gains, gain_weights)	Average gains from an integration with supplied gains for the modality.
`default_class_mode`()	Return a default mode class based on modality class name.
`get_mode_name_index`(mode_name)	Given a mode name, return its mode index.
`set_channel_division`(channel_division)	Create modes from a channel division.
`set_default_names`()	Sets the default name for each mode in the modality.
`set_gain_direction`(gain_direction)	Sets the gain direction to signed or bi-directional for each mode.
`set_gain_flag`(gain_flag)	Set the gain flag for each mode in the modality.
`set_gain_provider`(gain_provider)	Define the gain provider for each mode in the modality.
`set_gain_range`(gain_range)	Sets the allowable gain range for each mode in the modality.
`set_mode_class`(mode_class)	Set the mode class.
`set_options`(configuration[, branch])	Apply a configuration to the modality and modes therein.
`set_phase_gains`([phase_gains])	Set whether phase gains are applied to each mode in modality.
`to_string`()	Returns a long description of modes and associated channels.
`update_all_gains`(integration[, robust])	Update all gains in the integration from the modality.
`validate_mode_index`(index_or_mode_name)	Return the valid index of a given mode.

Attributes Documentation

fields¶

Return the available channel data fields.

Returns:

set (str)

flagspace¶

Retrieves the channel flagspace from the first valid mode.

Returns:

ChannelFlags

size¶

Returns the number of modes in the modality.

Returns:

n_modesint

Methods Documentation

apply_gains(integration, gains, gain_weights)[source]¶

Apply gains to an integration for the modality.

Parameters:

integrationIntegration
gainsnumpy.ndarray (float): The gain values to apply.
gain_weightsnumpy.ndarray (float): The weight of the gain values to apply.

Returns:

flaggedbool: Indicates whether any channels in the modality were flagged with out-of-range gain values.

average_gains(integration, gains, gain_weights, robust=False)[source]¶

Average gains from an integration with supplied gains for the modality.

Gains and weights are updated in-place.

Parameters:

integrationIntegration
gainsnumpy.ndarray (float): The current gains with which to average integration gains.
gain_weightsnumpy.ndarray (float): The current gain weights of the averaging.
robustbool, optional: If True, use the robust (median) method to determine means. Otherwise, use a weighted mean.

Returns:

None

classmethod default_class_mode()[source]¶

Return a default mode class based on modality class name.

For example, A CoupledModality should return CoupledMode. If no analogous mode is found, a default base Mode will be returned.

Returns:

Mode

get_mode_name_index(mode_name)[source]¶

Given a mode name, return its mode index.

Parameters:

mode_namestr: The name of the mode.

Returns:

indexint

set_channel_division(channel_division)[source]¶

Create modes from a channel division.

A Channel division contains a collection of channel groups. No gain provider is defined at this stage, but the name of each mode will be set to <name>:<channel data name in group>.

Parameters:

channel_divisionDivision

Returns:

None

set_default_names()[source]¶

Sets the default name for each mode in the modality.

The default name is set to <modality name>:<channel data name in group>.

Returns:

None

set_gain_direction(gain_direction)[source]¶

Sets the gain direction to signed or bi-directional for each mode.

Gain direction is predominantly important when a mode is flagging gains. The two directions are GAINS_SIGNED, or GAINS_BIDIRECTIONAL. If the gains are “bidirectional”, the absolute value is used during the flagging operation.

Parameters:

gain_directionInstrumentFlagTypes or str or int: May be one of {InstrumentFlagTypes.GAINS_SIGNED} or {InstrumentFlagTypes.GAINS_BIDIRECTIONAL}. Allowable string values are {“GAINS_SIGNED”, “GAINS_BIDIRECTIONAL”} (case irrelevant). If integers are used, care should be taken to ensure the appropriate flag is set.

Returns:

None

set_gain_flag(gain_flag)[source]¶

Set the gain flag for each mode in the modality.

Parameters:

gain_flagChannelFlagTypes or str or int: The gain flag marking channel types for gain determination. A string can be supplied such as ‘GAIN’, ‘DEAD’, etc., the flag type itself, or an integer. Integers should be used with care since meaning may vary between various flag types.

Returns:

None

set_gain_provider(gain_provider)[source]¶

Define the gain provider for each mode in the modality.

The gain provider determines what constitutes “gain” given channel data for each mode.

Parameters:

gain_providerstr or GainProvider: If a string is provided a FieldGainProvider will be set to operate on the given field of the channel group. Otherwise, a gain provider must be specifically defined.

Returns:

None

set_gain_range(gain_range)[source]¶

Sets the allowable gain range for each mode in the modality.

The gain range defines the allowable range of gain values. Values outside this range are flagged.

Parameters:

gain_rangeRange: A Range object with lower and upper bounds.

Returns:

None

set_mode_class(mode_class)[source]¶

Set the mode class.

Parameters:

mode_classMode class

Returns:

None

set_options(configuration, branch=None)[source]¶

Apply a configuration to the modality and modes therein.

The following information is extracted and applied:

resolution (in seconds)
triggers
whether to solve for gains
whether phase gains are used
the gain range
whether SIGNED or BIDIRECTIONAL gain flagging should be applied
whether no gain fields exist (gain provider is disabled)

Parameters:

configurationConfiguration or dict: Either a configuration object, or a specific subsection of a configuration relevant to the modality.
branchstr, optional: If a configuration object was provided, specifies the branch that applies to this modality. If not supplied, the branch name is defined as the modality name.

Returns:

None

set_phase_gains(phase_gains=None)[source]¶

Set whether phase gains are applied to each mode in modality.

Parameters:

phase_gainsbool, optional: If not supplied, all mode phase gains are set to that indicated in the modality. Otherwise, the new setting is applied to each mode and updated in the modality.

Returns:

None

to_string()[source]¶

Returns a long description of modes and associated channels.

Returns:

descriptionstr

update_all_gains(integration, robust=False)[source]¶

Update all gains in the integration from the modality.

Parameters:

integrationIntegration: The integration to update.
robustbool, optional: If True, use the robust (median) method to calculate means. Use a simple mean otherwise.

Returns:

updatedbool: True if gains were updated.

validate_mode_index(index_or_mode_name)[source]¶

Return the valid index of a given mode.

Raises an error if invalid.

Parameters:

index_or_mode_nameint or str: The name of the mode, or the mode index.

Returns:

indexint

Navigation

Modality¶