Signal¶

class sofia_redux.scan.signal.signal.Signal(integration, mode=None, values=None, is_floating=False)[source]¶

Bases: ABC

Initialize a Signal object.

The Signal object is used to extract a gain signal from an integration.

Parameters:

integrationsofia_redux.scan.integration.integration.Integration: The integration to which the signal belongs.
modesofia_redux.scan.channels.mode.mode.Mode, optional: The channel mode for which to create the signal.
valuesnumpy.ndarray (float), optional: Optional signal values to apply.
is_floatingbool, optional: If True, indicates that the signal values have some arbitrary DC offset. This indicates that it would be advisable to “level” (subtract this offset) from the signal values before any type of application.

Attributes Summary

`configuration`	Return the configuration applicable to the signal.
`info`	Return the info object specific to the signal integration.
`referenced_attributes`
`size`	Return the length of the signal.

Methods Summary

`add`(value)	Add a DC offset to all signal and drift values.
`add_drifts`()	Add the drifts onto the signal value.
`copy`()	Return a copy of the signal.
`differentiate`()	Differentiate the signal values in-place.
`get_covariance`()	Return the signal covariance over all samples (frames, channels).
`get_differential`()	Return a differentiated copy of the signal.
`get_gain_increment`([robust])	Return the gain increment and weight increment for each mode channel.
`get_integral`()	Return an integrated copy of the signal.
`get_mean`()	Return the mean signal value and weight.
`get_median`()	Return the median signal value and weight.
`get_ml_gain_increment`()	Get the maximum-likelihood (ML) gain increment for the signal.
`get_resolution`()	Return the signal resolution.
`get_rms`()	Get the signal RMS.
`get_robust_gain_increment`()	Get the robust (median derived) gain increment for the signal.
`get_variance`()	Get the signal variance.
`integrate`()	Integrate the signal values in-place using the trapezoidal rule.
`level`([start_frame, end_frame, robust])	Remove the mean value from the signal values.
`prepare_frame_temp_fields`()	Prepare precalculated values for subsequent processing.
`remove_drifts`([n_frames, ...])	Remove drifts from the signal.
`resync_gains`()	Resynchronize gains if any changes have occurred.
`scale`(factor)	Scale the signal, drifts, and sync_gains by a given factor.
`set_sync_gains`(gains)	Copy the gains to the sync_gains attribute.
`smooth`(fwhm)	Smooth the signal to a given FWHM (given in frames).
`smooth_with_kernel`(kernel)	Smooth the signal with a given kernel.
`subtract`(value)	Subtract a DC offset from all signal and drift values.
`synchronize_gains`([sum_wc2, is_temp_ready])	Synchronize gains in the signal.
`value_at`(frame)	Return the signal value for a given integration frame index.
`weight_at`(frame)	Return the signal weight for a given integration frame index.
`write_signal_values`(out_file)	Write the signal information to a text file.

Attributes Documentation

configuration¶

Return the configuration applicable to the signal.

Returns:

Configuration

info¶

Return the info object specific to the signal integration.

Returns:

Info

referenced_attributes = ['mode', 'integration']¶

size¶

Return the length of the signal.

Returns:

n_signalint

Methods Documentation

add(value)[source]¶

Add a DC offset to all signal and drift values.

Parameters:

valuefloat: The value to add.

Returns:

None

add_drifts()[source]¶

Add the drifts onto the signal value.

All drifts are erased following this operation.

Returns:

None

copy()[source]¶

Return a copy of the signal.

Returns:

Signal

differentiate()[source]¶

Differentiate the signal values in-place.

Note that the spacing between sample values is assumed to be in seconds when calculating the gradient. The is_floating attribute is set to False following this operation indicating that the differentiated signal has no DC offset.

Returns:

None

get_covariance()[source]¶

Return the signal covariance over all samples (frames, channels).

The covariance only includes unflagged channels and unflagged samples. The signal covariance is given as:

C = sum_{channels}(xs * xs) / sum_{channels}(ss * xx)

where xs = sum_{frames}(w * x * s), ss = sum_{frames}(w * s * s), and xx = sum_{frames}(w * x * x). Here w is the channel weight, s is the signal value for each frame, and x are the frame data values.

Returns:

covariancefloat

get_differential()[source]¶

Return a differentiated copy of the signal.

Returns:

Signal

get_gain_increment(robust=False)[source]¶

Return the gain increment and weight increment for each mode channel.

For the robust method, the gain increment value is determined as:

increment = median(frame_data / signal_value)

while the maximum-likelihood method gives the gain increment as:

increment = sum(frame_data * frame_weight * signal_value) / increment_w

Both methods are weighted by frame_weight * signal_value^2 and result in an increment weight of:

increment_w = sum(frame_weight * signal_value^2).

Parameters:

robustbool, optional: If True, use the robust method (median) to determine gain increments. Otherwise, use the maximum-likelihood method (mean).

Returns:

increment, increment_wnumpy.ndarray, numpy.ndarray: The gain increment and increment weight, both of shape (n_channels,).

get_integral()[source]¶

Return an integrated copy of the signal.

Returns:

Signal

get_mean()[source]¶

Return the mean signal value and weight.

Returns:

mean_value, mean_weight

get_median()[source]¶

Return the median signal value and weight.

Returns:

median_value, median_weightfloat, float

get_ml_gain_increment()[source]¶

Get the maximum-likelihood (ML) gain increment for the signal.

The maximum likelihood gain increment for a given channel (c) is:

dG = sum(frame_data_{c} * frame_weight * signal_value) / dW dW = sum(frame_weight * signal_value^2)

No invalid frames of modeling frames will be included in the sum. Additionally, no flagged samples will be included.

Returns:

gain_increments, increment_weightsnumpy.ndarray, numpy.ndarray: The gain increments and increment weights for each channel in the signal mode channel group. Both are arrays of shape (n_channels,).

get_resolution()[source]¶

Return the signal resolution.

The signal resolution is basically the number of frames for which a single signal value may be applicable.

Returns:

resolutionint

get_rms()[source]¶

Get the signal RMS.

Returns:

rmsfloat

get_robust_gain_increment()[source]¶

Get the robust (median derived) gain increment for the signal.

The gain increment for a given channel is:

increment = median(frame_data / signal_value) increment_weight = sum(frame_weight * signal_value^2)

No invalid frames of modeling frames will be included in the sum. Additionally, no flagged samples will be included.

Returns:

gain_increments, increment_weightsnumpy.ndarray, numpy.ndarray: The gain increments and increment weights for each channel in the signal mode channel group. Both are arrays of shape (n_channels,).

get_variance()[source]¶

Get the signal variance.

Returns:

variancefloat

integrate()[source]¶

Integrate the signal values in-place using the trapezoidal rule.

Note that the spacing between sample values is assumed to be in seconds. The is_floating attribute is set to True following this operation indicating that the integrated signal has an arbitrary DC offset.

Returns:

None

level(start_frame=None, end_frame=None, robust=False)[source]¶

Remove the mean value from the signal values.

The mean signal between a given start and end frame is calculated and subtracted from the signal. This value is returned to the user.

Parameters:

start_frameint, optional: The starting frame from which to level. The default is the first frame (0).
end_frameint, optional: The last frame from to level (non-inclusive). The default is the total number of frames.
robustbool, optional: If True, subtract the median value rather than the mean.

Returns:

averagefloat: The average signal value that was removed.

prepare_frame_temp_fields()[source]¶

Prepare precalculated values for subsequent processing.

The signal values are stored in the temp_* fields of the frame data. These contain:

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

Invalid frames have zero values. Frames flagged as “MODELING” are set to zero weight.

Returns:

None

remove_drifts(n_frames=None, is_reconstructable=True, robust=False)[source]¶

Remove drifts from the signal.

A drift is defined as the average signal for a given block of frames (the length of which is given by n_frames. For each drift, the average signal value is calculated and subtracted from all signal values within that drift block. If the drifts are marked as “reconstructable”, they average signal values are stored in the drifts attribute.

Parameters:

n_framesint, optional: The number of frames in each drift. The default is the number of frames in the signal’s integration filter time scale.
is_reconstructablebool, optional: If True, save the drift values for later use.
robustbool, optional: If True, the robust (median) method will be used to determined the average signal level for each drift.

Returns:

None

resync_gains()[source]¶

Resynchronize gains if any changes have occurred.

The delta gains are calculated for each channel as:: current_gain - last_gain

For any non-zero delta_gain, frame data (x) for that channel will be updated by decrementing that value by:

x[frame, channel] -= signal[frame] * delta_gain[channel]

Returns:

None

scale(factor)[source]¶

Scale the signal, drifts, and sync_gains by a given factor.

Signal values and drifts are multiplied by the given factor. Sync gains (previous gain values) are divided by the given factor.

Parameters:

factorfloat

Returns:

None

set_sync_gains(gains)[source]¶

Copy the gains to the sync_gains attribute.

Parameters:

gainsnumpy.ndarray (float): An array of gains to copy to sync_gains.

Returns:

None

smooth(fwhm)[source]¶

Smooth the signal to a given FWHM (given in frames).

Parameters:

fwhmfloat or int: The FWHM in given in units of frames.

Returns:

None

smooth_with_kernel(kernel)[source]¶

Smooth the signal with a given kernel.

Kernel spacing should be in units of self.resolution (number of frames).

Parameters:

kernelnumpy.ndarray (float): The kernel to smooth the signal values by.

Returns:

None

subtract(value)[source]¶

Subtract a DC offset from all signal and drift values.

Parameters:

valuefloat

Returns:

None

synchronize_gains(sum_wc2=None, is_temp_ready=True)[source]¶

Synchronize gains in the signal.

If the gains have been updated, applies any changes to the data and updates dependencies.

Parameters:

sum_wc2numpy.ndarray (float), optional

An array of gain weights 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

value_at(frame)[source]¶

Return the signal value for a given integration frame index.

Parameters:

frameint or numpy.ndarray (int)

Returns:

signal_valuefloat

weight_at(frame)[source]¶

Return the signal weight for a given integration frame index.

Note that the standard signal object does not have an associated weight.

Parameters:

frameint or numpy.ndarray (int)

Returns:

signal_weightfloat

write_signal_values(out_file)[source]¶

Write the signal information to a text file.

Note that in crush this is the “print” method.

Parameters:

out_filestr: The name of the file to write to.

Returns:

None

Navigation

Signal¶