Channels

class sofia_redux.scan.channels.channels.Channels(name=None, parent=None, info=None, size=0)

Bases: ABC

Creates a Channels instance.

The Channels class holds and operates on each “channel” of an instrument. The channel information generally consists of time- independent characteristics for a single measuring element of the instrument.

A typical example would be camera pixels. Each pixel in the array will have certain characteristics such as a position that does not vary over time. This will also contain flagging information such as whether a channel is working correctly etc. The data attribute contains a numpy array for each “field” (characteristic) with each element representing a single channel.

The Channels class also breaks down individual channels into groups (a collection of channels), divisions (a collection of groups), and modalities (a collection of modes). Each mode in a modality is created from a group in a division. A mode is an object defining the gain properties of a channel group. i.e., a mode reads channel group information to retrieve or set gain.

Parameters:

namestr, optional

The name for the channels.

parentobject, optional

The owner of the channels such as a Reduction, Scan or Integration.

infoInfo, optional

The channel information.

sizeint, optional

The number of stored channels.

Attributes Summary

configuration	Return the configuration.
flagspace	Return the appropriate channel flag space.
n_mapping_channels	Return the number of mapping channels in the instrument.
n_store_channels	Return the number of stored channels (total) in the instrument.
non_detector_flags	Return the flags marking a channel as a non-detector.
parent	Return the channel instance owner.
reference_attributes	Return attributes that should be referenced rather than copied.
size	Return the number of channels.
sourceless_flags	Return the flag marking a channel as having no source.

Methods Summary

add_dependents(dependents)	Add dependents to channel data.
add_division(channel_division)	Adds a channel division to the divisions dictionary.
add_group(channel_group[, name])	Add a channel group to the groups dictionary.
add_modality(modality)	Add a modality to the modalities dictionary.
apply_configuration()	Apply the configuration options to the channels.
calculate_overlaps([point_size])	Calculate channel overlaps.
census([report])	Update the number of available mapping channels.
copy()	Create and return a copy.
create_channel_group([indices, name, ...])	Creates and returns a channel group.
discard(flag[, criterion])	Given a flag, remove channels from data and dependent structures.
edit_scan_header(header[, scans, configuration])	Edit a scan header with available information.
find_fixed_indices(fixed_indices[, cull])	Returns the actual indices given fixed indices.
flag_channel_list(channel_list)	Flag channels as DEAD from a list of channel ranges/fixed indices.
flag_channels()	Flag certain channels.
flag_field(field, specs)	Given a data field name and list of specifications, flag as DEAD.
flag_fields(fields)	Flag channel data by fields.
flag_weights()	Flag channels based on channel weights and gain.
flatten_weights()	Flattens weight according to gain^2.
get_average_beam_fwhm()	Return the average beam FWHM.
get_average_filtering()	Return the average source filtering.
get_blind_channels()	Returns the 'blinds' channel group.
get_channel_data_instance()	Return a channel data instance for these channels.
get_channel_flag_key([prepend])	Return the channel flags and values.
get_detector_channels()	Returns the 'detectors' channel group.
get_division(name, field[, keep_flag, ...])	Creates a channel division based on a given data field.
get_filtering(integration)	Return the filtering for a given integration.
get_fits_data(data)	Add channel data to the FITS data.
get_live_channels()	Returns the 'live' channel group.
get_mapping_pixels([discard_flag, ...])	Return the mapping pixels.
get_max_beam_fwhm()	Return the maximum beam FWHM.
get_min_beam_fwhm()	Return the minimum beam FWHM.
get_name()	Return the name of the channels.
get_observing_channels()	Returns the 'obs-channels' channel group.
get_one_over_f_stat()	Return the 1/frequency statistic (pink noise) of the channels.
get_perimeter_pixels([sections])	Return the pixels at the perimeter positions.
get_pixel_count()	Return the number of pixels in the channels.
get_pixels()	Return the pixels.
get_scan_instance()	Return a scan instance for these channels.
get_sensitive_channels()	Returns the 'sensitive' channel group.
get_source_gains([filter_corrected])	Return the source gains.
get_source_nefd([gain])	Returns the source Noise-Equivalent-Flux-Density (NEFD).
get_stability()	Return the instrument stability in seconds.
get_table_entry(name)	Return a channel parameter for the given name.
get_typical_gain_magnitude(gains[, ...])	Return the mean gain value of data.
has_option(option)	Check whether an option is set in the configuration.
init_divisions()	Initializes channel divisions.
init_groups()	Initializes channel groups.
init_modalities()	Initializes channel modalities.
initialize()	Initializes channel groups, divisions, and modalities.
jackknife()	Randomly inverts half of the channel couplings.
kill_channels([flag])	Given a flag, sets all matching elements to DEAD only flag status.
list_divisions()	Return a list of all division names.
list_modalities()	Return a list of all modality names.
load_channel_data()	Load the channel data.
load_temporary_hardware_gains()	Load the temporary hardware gains in the channel data.
normalize_array_gains()	Normalize the relative channel gains in observing channels.
print_correlated_modalities()	Print all correlated modalities to the log.
print_response_modalities()	Print all response modalities to the log.
read_pixel_data(filename)	Read the pixel data file.
read_scan(filename[, read_fully])	Read a file and return a scan using these channels.
read_wiring_data(filename)	Read the wiring data.
reindex()	Reset the channel indices to range sequentially from 0 -> size.
remove(indices)	Remove channel indices and dependent data.
remove_dependents(dependents)	Remove dependents from channel data.
scramble()	Randomly shuffle position data.
set_blind_channels(fixed_indices)	Set BLIND flag for elements based on fixed indices.
set_channel_flag_defaults()	Sets data values based on currently set flags.
set_data(data)	Set the channel data object.
set_fixed_source_gains()	Multiplies coupling by gain only if this has not been done before.
set_info(info)	Load the static instrument settings, which are date-independent.
set_name(name)	Set the name for the channels.
set_parent(parent)	Set the parent object for channels.
set_sample_weights()	Set the sample weighting.
set_standard_weights()	Set standard weighting.
slim([reindex])	Remove all DEAD or DISCARD flagged channels.
slim_group(channel_group)	Remove indices from a channel group not present in the channel data.
slim_groups()	Remove invalid channels from channel groups, divisions, and modalities.
troubleshoot_few_pixels()	Return suggestions as to how to remedy too few pixels in the model.
uniform_gains([field])	Sets the gain and coupling to 1.0 for all channels.
validate_scan(scan)	Validate the channel data with a scan.
write_channel_data(filename[, header])	Write the channel data to a file.

Attributes Documentation

configuration

Return the configuration.

Returns:

Configuration

flagspace

Return the appropriate channel flag space.

Returns:

Flags

n_mapping_channels

Return the number of mapping channels in the instrument.

Returns:

int

n_store_channels

Return the number of stored channels (total) in the instrument.

Returns:

int

non_detector_flags

Return the flags marking a channel as a non-detector.

Returns:

flagenum.Enum

parent

Return the channel instance owner.

Returns:

object

reference_attributes

Return attributes that should be referenced rather than copied.

Returns:

set

size

Return the number of channels.

Returns:

int

sourceless_flags

Return the flag marking a channel as having no source.

Returns:

flagenum.Enum

Methods Documentation

add_dependents(dependents)

Add dependents to channel data.

Parameters:

dependentsnumpy.ndarray (float)

Returns:

None

add_division(channel_division)

Adds a channel division to the divisions dictionary.

A channel division contains sets of groups. Will also add any groups to the groups dictionary.

Parameters:

channel_divisionChannelDivision

The channel division to add.

Returns:

None

add_group(channel_group, name=None)

Add a channel group to the groups dictionary.

Parameters:

channel_groupGroup

A channel group.

namestr, optional

The name of the group. If not supplied, will be determined from the name of the group. If supplied, will set the group object name if not previously set.

Returns:

None

add_modality(modality)

Add a modality to the modalities dictionary.

Parameters:

modalityModality

Returns:

None

apply_configuration()

Apply the configuration options to the channels.

Returns:

None

calculate_overlaps(point_size=None)

Calculate channel overlaps.

Parameters:

point_sizeastropy.units.Quantity, optional

The overlap point size (beam FWHM for example). The default is the instrument spatial resolution.

Returns:

None

census(report=False)

Update the number of available mapping channels.

Parameters:

reportbool, optional

If True, produce a log message for the number of mapping channels and number of mapping pixels.

Returns:

None

copy()

Create and return a copy.

Returns:

Channels

create_channel_group(indices=None, name=None, keep_flag=None, discard_flag=None, match_flag=None)

Creates and returns a channel group.

A channel group is a referenced subset of the channel data. Operations performed on a channel group will be applied to the original channel data.

Parameters:

indicesnumpy.ndarray (int), optional

The indices to reference. If not supplied, defaults to all channels.

namestr, optional

The name of the channel group. If not supplied, defaults to the name of the channel data.

discard_flagint or str or ChannelFlagTypes, optional

Flags to discard_flag from the new group.

keep_flagint or str or ChannelFlagTypes, optional

Keep channels with these matching flags.

match_flagint or str or ChannelFlagTypes, optional

Keep only channels with a flag exactly matching this flag.

Returns:

Group

A newly created channel group.

discard(flag, criterion=None)

Given a flag, remove channels from data and dependent structures.

Will also remove discarded channels from channel groups, divisions, and modalities.

Parameters:

flagint or ChannelFlagTypes, optional

The flag to discard_flag.

criterionstr, optional

One of {‘DISCARD_ANY’, ‘DISCARD_ALL’, ‘DISCARD_MATCH’, ‘KEEP_ANY’, ‘KEEP_ALL’, ‘KEEP_MATCH’}. *_ANY refers to any flag that is not zero (unflagged). *_ALL refers to any flag that contains flag, and *_MATCH refers to any flag that exactly matches flag. The default (None), uses DISCARD_ANY if flag is None, and DISCARD_ALL otherwise.

Returns:

None

edit_scan_header(header, scans=None, configuration=None)

Edit a scan header with available information.

Parameters:

headerastropy.io.fits.header.Header

The FITS header to edit.

scanslist (Scan), optional

A list of scans to use during editing.

configurationConfiguration, optional

A different configuration to use if necessary

Returns:

None

find_fixed_indices(fixed_indices, cull=True)

Returns the actual indices given fixed indices.

The fixed indices are those that are initially loaded. Returned indices are their locations in the data arrays.

Parameters:

fixed_indicesint or np.ndarray (int)

The fixed indices.

cullbool, optional

If True, do not include fixed indices not found in the result. If False, missing indices will be replaced by -1.

Returns:

indicesnumpy.ndarray (int)

The indices of fixed_indices in the data arrays. A tuple will be returned, in the case where we are examining more than one dimension.

flag_channel_list(channel_list)

Flag channels as DEAD from a list of channel ranges/fixed indices.

Parameters:

channel_listlist or str

If provided as a string, elements should be comma delimited. Each element can be an int or string specifying fixed indices to flag. Note that ranges can be specified via ‘min:max’ or ‘min-max’.

Returns:

None

flag_channels()

Flag certain channels.

Returns:

None

flag_field(field, specs)

Given a data field name and list of specifications, flag as DEAD.

The specifications may define a single value or range of values. Any data value within that range or equal to a specified value will be flagged as dead.

Parameters:

fieldstr

The data field name.

specslist of str

Each element may contain a single value or range of values (marked by lower-upper or lower:upper) that should be flagged as dead.

Returns:

None

flag_fields(fields)

Flag channel data by fields.

Parameters:

fieldsdict

The fields dict should have the field names for keys (attributes in channel data to flag) and channel ranges for values. values may be in the form lower-upper, lower:upper. Any channels with that field attribute in the given range will be flagged as DEAD.

Returns:

None

flag_weights()

Flag channels based on channel weights and gain.

Only detector channels are used during flagging (based on noise weights, not source weights). Channels with zero degrees of freedom are flagged with the DOF channel flag and unflagged when the degrees of freedom are greater than zero.

The ‘weighting.noiserange’ configuration option sets the minimum and maximum allowable noise ranges for a channel in standard deviations. The mean value of the channel gain is taken from all detector channels that have sufficient DOF, weight, and gain.

Those channels that fall outside the acceptable noise ranges are flagged with the SENSITIVITY channel flag, whereas any others will be unflagged.

Errors will be raised if there are no channels with nonzero DOF, or all channels are flagged as insensitive.

Returns:

None

flatten_weights()

Flattens weight according to gain^2.

Does not include hardware gains.

Returns:

None

get_average_beam_fwhm()

Return the average beam FWHM.

Returns:

fwhmastropy.units.Quantity

get_average_filtering()

Return the average source filtering.

Returns:

filteringfloat

get_blind_channels()

Returns the ‘blinds’ channel group.

Returns:

blind_channelsChannelGroup

get_channel_data_instance()

Return a channel data instance for these channels.

Returns:

ChannelData

get_channel_flag_key(prepend='')

Return the channel flags and values.

Parameters:

prependstr

A string to prepend to all names.

Returns:

dict

A key containing key=name, value=value (int).

get_detector_channels()

Returns the ‘detectors’ channel group.

Returns:

detector_channelsChannelGroup

get_division(name, field, keep_flag=None, discard_flag=None, match_flag=None)

Creates a channel division based on a given data field.

A single group will be created for each unique field value. The name of each group will be <field>-<value>. Channels may be discarded from any groups using the standard flagging mechanisms (keep, discard_flag, match).

Parameters:

namestr

The name of the channel division.

fieldstr

The data field on which to base division creation.

keep_flagint or str or ChannelFlagTypes, optional

If supplied, all groups in the division will only contain channels flagged with keep_flag.

discard_flagint or str or ChannelFlagTypes, optional

If supplied, all groups in the division will not contain any channels flagged with discard_flag.

match_flagint or str or ChannelFlagTypes, optional

If supplied, all groups in the division will only contain channels containing flags exactly matching match_flag. Overrides keep_flag and discard_flag.

Returns:

ChannelDivision

The newly created channel division.

get_filtering(integration)

Return the filtering for a given integration.

Parameters:

integrationIntegration

Returns:

filteringnumpy.ndarray (float)

get_fits_data(data)

Add channel data to the FITS data.

Parameters:

datadict

Returns:

None

get_live_channels()

Returns the ‘live’ channel group.

Returns:

live_channelsChannelGroup

get_mapping_pixels(discard_flag=None, keep_flag=None, match_flag=None)

Return the mapping pixels.

Parameters:

discard_flagint or str or ChannelFlagTypes

keep_flagint or str or ChannelFlagTypes

match_flagint or str or ChannelFlagTypes

Returns:

ChannelGroup

get_max_beam_fwhm()

Return the maximum beam FWHM.

Returns:

fwhmastropy.units.Quantity

get_min_beam_fwhm()

Return the minimum beam FWHM.

Returns:

fwhmastropy.units.Quantity

get_name()

Return the name of the channels.

Returns:

namestr

get_observing_channels()

Returns the ‘obs-channels’ channel group.

Returns:

obs_channelsChannelGroup

get_one_over_f_stat()

Return the 1/frequency statistic (pink noise) of the channels.

Returns:

float

The 1/frequency statistic.

get_perimeter_pixels(sections=None)

Return the pixels at the perimeter positions.

The algorithm to determine perimeter pixels divides the pixel array into sections angular slices about the mean pixel position, and then returns the furthest pixel from the central position for that slice. If no pixels exist in that slice, the slice is excluded.

Parameters:

sectionsint, optional

The number of perimeter pixels to return (approximate). If not supplied, will be determined from the configuration.

Returns:

perimeter_pixelsChannelGroup

get_pixel_count()

Return the number of pixels in the channels.

Returns:

pixelsint

get_pixels()

Return the pixels.

Returns:

ChannelData

get_scan_instance()

Return a scan instance for these channels.

Returns:

Scan

get_sensitive_channels()

Returns the ‘sensitive’ channel group.

Returns:

sensitive_channelsChannelGroup

get_source_gains(filter_corrected=True)

Return the source gains.

The source gains are taken from the coupling data. If gains are not fixed (as determined by “source.fixedgains”), gains are multiplied by the channel gains. It will also be multiplied by the source filter if filter_corrected is True.

Parameters:

filter_correctedbool, optional

Apply source filtering.

Returns:

gainsnumpy.ndarray (float)

The source gains.

get_source_nefd(gain=1.0)

Returns the source Noise-Equivalent-Flux-Density (NEFD).

The NEFD is given as:

nefd = sqrt(n * t / sum(g^2 / v)) / abs(integration_gain)

where n are the number of mapping channels (unflagged and positive weights), t is the integration time, g is the source gain, and v is the channel variance. Note that t will be converted to units of seconds if necessary.

Parameters:

gainfloat, optional

Normalizing gain value. The default is 1.0.

Returns:

source_nefdfloat

get_stability()

Return the instrument stability in seconds.

Will look in the configuration for “stability”, and if not found, will return 10 seconds.

Returns:

stability_timeastropy.units.Quantity

The stability time in seconds.

get_table_entry(name)

Return a channel parameter for the given name.

Parameters:

namestr

Returns:

value

get_typical_gain_magnitude(gains, keep_flag=None, discard_flag=None, match_flag=None)

Return the mean gain value of data.

The mean value may be calculated given a number of flag criteria. The outer 10% of log(1 + |gain|) are excluded from the mean calculation.

Parameters:

gainsnumpy.ndarray (float)

keep_flagint or ChannelFlagTypes, optional

Flag values to keep in the calculation.

discard_flagint or ChannelFlagTypes, optional

Flag values to discard_flag from the calculation.

match_flagint or ChannelFlagTypes, optional

Only matching flag values will be used in the calculation.

Returns:

meanfloat

The mean gain value.

has_option(option)

Check whether an option is set in the configuration.

Parameters:

optionstr

The configuration option.

Returns:

is_configuredbool

init_divisions()

Initializes channel divisions.

Divisions contain sets of channel groups.

Returns:

None

init_groups()

Initializes channel groups.

Each group contains a subset of the channel data, referenced by index.

Returns:

None

init_modalities()

Initializes channel modalities.

A modality is based of a channel division and contains a mode for each channel group in the channel division.

Returns:

None

initialize()

Initializes channel groups, divisions, and modalities.

Returns:

None

jackknife()

Randomly inverts half of the channel couplings.

Returns:

None

kill_channels(flag=None)

Given a flag, sets all matching elements to DEAD only flag status.

Parameters:

flagint or ChannelFlagTypes

Returns:

None

list_divisions()

Return a list of all division names.

Returns:

list (str)

list_modalities()

Return a list of all modality names.

Returns:

list (str)

load_channel_data()

Load the channel data.

The pixel data and wiring data files should be defined in the configuration.

Returns:

None

load_temporary_hardware_gains()

Load the temporary hardware gains in the channel data.

The hardware gains are also reset from the info.

Returns:

None

normalize_array_gains()

Normalize the relative channel gains in observing channels.

Returns:

average_gainfloat

The average gain prior to normalization.

print_correlated_modalities()

Print all correlated modalities to the log.

Returns:

None

print_response_modalities()

Print all response modalities to the log.

Returns:

None

read_pixel_data(filename)

Read the pixel data file.

If the instrument integration time is greater than zero, will set weighting accordingly. Otherwise, standard weights are used.

Parameters:

filenamestr

Path to the pixel data file.

Returns:

None

read_scan(filename, read_fully=True)

Read a file and return a scan using these channels.

Parameters:

filenamestr

The file path to the scan.

read_fullybool, optional

If True, fully read the scan.

Returns:

Scan

read_wiring_data(filename)

Read the wiring data.

Parameters:

filenamestr

Path to the wiring data file.

Returns:

None

reindex()

Reset the channel indices to range sequentially from 0 -> size.

Returns:

None

remove(indices)

Remove channel indices and dependent data.

In addition to removing channels from the channel data, also remove those channel references from channel groups, divisions, and modalities.

Parameters:

indicesnumpy.ndarray of int

Returns:

None

remove_dependents(dependents)

Remove dependents from channel data.

Parameters:

dependentsnumpy.ndarray (float)

Returns:

None

scramble()

Randomly shuffle position data.

Returns:

None

set_blind_channels(fixed_indices)

Set BLIND flag for elements based on fixed indices.

Will kill (set flag to only DEAD) any previously defined BLIND channels. All new blinded channels will only have the BLIND flag.

Parameters:

fixed_indicesnumpy.ndarray of int

Returns:

None

set_channel_flag_defaults()

Sets data values based on currently set flags.

Returns:

None

set_data(data)

Set the channel data object.

Parameters:

dataChannelData

Returns:

None

set_fixed_source_gains()

Multiplies coupling by gain only if this has not been done before.

Returns:

None

set_info(info)

Load the static instrument settings, which are date-independent.

Parameters:

infoInfo

Returns:

None

set_name(name)

Set the name for the channels.

Parameters:

namestr

Returns:

None

set_parent(parent)

Set the parent object for channels.

Parameters:

parentobject

Returns:

None

set_sample_weights()

Set the sample weighting.

If not already applied, multiplies the channel weighting by sqrt(integration_time).

Returns:

None

set_standard_weights()

Set standard weighting.

If not already applied, divides the channels weights by sqrt(integration_time)

Returns:

None

slim(reindex=True)

Remove all DEAD or DISCARD flagged channels.

Will also update channel groups, divisions, and modalities.

Parameters:

reindexbool, optional

If True, reindex channels if slimmed.

Returns:

slimmedbool

True if channels were discarded, False otherwise.

slim_group(channel_group)

Remove indices from a channel group not present in the channel data.

Parameters:

channel_groupChannelGroup

Returns:

None

slim_groups()

Remove invalid channels from channel groups, divisions, and modalities.

Returns:

None

troubleshoot_few_pixels()

Return suggestions as to how to remedy too few pixels in the model.

Returns:

suggestionslist (str)

uniform_gains(field=None)

Sets the gain and coupling to 1.0 for all channels.

Parameters:

fieldstr, optional

If supplied, sets all values of the requested field to unity.

Returns:

None

validate_scan(scan)

Validate the channel data with a scan.

The steps are:

1. Load the channel data

2. Set appropriate flags

3. Initialize channel groups, divisions, and modalities.

4. Apply the configuration options

Parameters:

scanScan

Returns:

None

write_channel_data(filename, header=None)

Write the channel data to a file.

Parameters:

filenamestr

The file name to write to.

headerstr, optional

An optional header line to write to the file.

Returns:

None