ezmsg.sigproc.fbcca

Functions

calc_softmax(cv, axis, beta=1.0)

Parameters:

• cv (ndarray)

• axis (int)

• beta (float)

cca_rho_max(X, Y)

X: (n_time, n_ch) Y: (n_time, n_ref) # design matrix for one frequency returns: largest canonical correlation in [0,1]

Parameters:

• X (ndarray)

• Y (ndarray)

Return type:

float

Classes

class FBCCA(*args, settings=None, **kwargs)

Bases: BaseTransformerUnit[FBCCASettings, AxisArray, AxisArray, FBCCATransformer]

Parameters:

settings (Settings | None)

SETTINGS

alias of FBCCASettings

class FBCCASettings(time_dim, ch_dim, filterbank_dim=None, harmonics=5, freqs=<factory>, softmax_beta=1.0, target_freq_dim='target_freq', max_int_time=0.0)

Bases: Settings

Settings for FBCCATransformer

Parameters:

• time_dim (str)

• ch_dim (str)

• filterbank_dim (str | None)

• harmonics (int)

• freqs (List[float])

• softmax_beta (float)

• target_freq_dim (str)

• max_int_time (float)

time_dim: str

The time dim in the data array.

ch_dim: str

The channels dim in the data array.

filterbank_dim: str | None = None

The filter bank subband dim in the data array. If unspecified, method falls back to CCA None (default): the input has no subbands; just use CCA

harmonics: int = 5

The number of additional harmonics beyond the fundamental to use for the ‘design’ matrix. 5 (default): Evaluate 5 harmonics of the base frequency. Many periodic signals are not pure sinusoids, and inclusion of higher harmonics can help evaluate the presence of signals with higher frequency harmonic content

freqs: List[float]

Frequencies (in hz) to evaluate the presence of within the input signal. [] (default): an empty list; frequencies will be found within the input SampleMessages. AxisArrays have no good place to put this metadata, so specify frequencies here if only AxisArrays will be passed as input to the generator. If the input has a trigger attr of type SampleTriggerMessage, the processor looks for the freqs attribute within that trigger for a list of frequencies to evaluate. This field is present in the SSVEPSampleTriggerMessage defined in ezmsg.tasks.ssvep from the ezmsg-tasks package. NOTE: Avoid frequencies that have line-noise (60 Hz/50 Hz) as a harmonic.

softmax_beta: float = 1.0

Beta parameter for softmax on output –> “probabilities”. 1.0 (default): Use the shifted softmax transformation to output 0-1 probabilities. If 0.0, the maximum singular value of the SVD for each design matrix is output

target_freq_dim: str = 'target_freq'

Name for dim to put target frequency outputs on. ‘target_freq’ (default)

max_int_time: float = 0.0

Maximum integration time (in seconds) to use for calculation. 0 (default): Use all time provided for the calculation. Useful for artificially limiting the amount of data used for the CCA method to evaluate the necessary integration time for good decoding performance

__init__(time_dim, ch_dim, filterbank_dim=None, harmonics=5, freqs=<factory>, softmax_beta=1.0, target_freq_dim='target_freq', max_int_time=0.0)

Parameters:

• time_dim (str)

• ch_dim (str)

• filterbank_dim (str | None)

• harmonics (int)

• freqs (List[float])

• softmax_beta (float)

• target_freq_dim (str)

• max_int_time (float)

Return type:

None

class FBCCATransformer(*args, settings=None, **kwargs)

Bases: BaseTransformer[FBCCASettings, AxisArray, AxisArray]

A canonical-correlation (CCA) signal decoder for detection of periodic activity in multi-channel timeseries recordings. It is particularly useful for detecting the presence of steady-state evoked responses in multi-channel EEG data. Please see Lin et. al. 2007 for a description on the use of CCA to detect the presence of SSVEP in EEG data. This implementation also includes the “Filterbank” extension of the CCA decoding approach which utilizes a filterbank to decompose input multi-channel EEG data into several frequency sub-bands; each of which is analyzed with CCA, then combined using a weighted sum; allowing CCA to more readily identify harmonic content in EEG data. Read more about this approach in Chen et. al. 2015.

## Further reading: * [Lin et. al. 2007](https://ieeexplore.ieee.org/document/4015614) * [Nakanishi et. al. 2015](https://doi.org/10.1371%2Fjournal.pone.0140703) * [Chen et. al. 2015](http://dx.doi.org/10.1088/1741-2560/12/4/046008)

Parameters:

settings (SettingsType)

class StreamingFBCCA(*args, settings=None, **kwargs)

Bases: BaseTransformerUnit[StreamingFBCCASettings, AxisArray, AxisArray, StreamingFBCCATransformer]

Parameters:

settings (Settings | None)

SETTINGS

alias of StreamingFBCCASettings

class StreamingFBCCASettings(time_dim, ch_dim, filterbank_dim=None, harmonics=5, freqs=<factory>, softmax_beta=1.0, target_freq_dim='target_freq', max_int_time=0.0, window_dur=4.0, window_shift=0.5, window_dim='fbcca_window', filter_bw=7.0, filter_low=7.0, trans_bw=2.0, ripple_db=20.0, subbands=12)

Bases: FBCCASettings

Perform rolling/streaming FBCCA on incoming EEG. Decomposes the input multi-channel timeseries data into multiple sub-bands using a FilterbankDesign Transformer, then accumulates data using Window into short-time observations for analysis using an FBCCA Transformer.

Parameters:

• time_dim (str)

• ch_dim (str)

• filterbank_dim (str | None)

• harmonics (int)

• freqs (List[float])

• softmax_beta (float)

• target_freq_dim (str)

• max_int_time (float)

• window_dur (float)

• window_shift (float)

• window_dim (str)

• filter_bw (float)

• filter_low (float)

• trans_bw (float)

• ripple_db (float)

• subbands (int)

window_dur: float = 4.0

window_shift: float = 0.5

window_dim: str = 'fbcca_window'

filter_bw: float = 7.0

filter_low: float = 7.0

trans_bw: float = 2.0

__init__(time_dim, ch_dim, filterbank_dim=None, harmonics=5, freqs=<factory>, softmax_beta=1.0, target_freq_dim='target_freq', max_int_time=0.0, window_dur=4.0, window_shift=0.5, window_dim='fbcca_window', filter_bw=7.0, filter_low=7.0, trans_bw=2.0, ripple_db=20.0, subbands=12)

Parameters:

• time_dim (str)

• ch_dim (str)

• filterbank_dim (str | None)

• harmonics (int)

• freqs (List[float])

• softmax_beta (float)

• target_freq_dim (str)

• max_int_time (float)

• window_dur (float)

• window_shift (float)

• window_dim (str)

• filter_bw (float)

• filter_low (float)

• trans_bw (float)

• ripple_db (float)

• subbands (int)

Return type:

None

ripple_db: float = 20.0

time_dim: str

The time dim in the data array.

ch_dim: str

The channels dim in the data array.

freqs: List[float]

Frequencies (in hz) to evaluate the presence of within the input signal. [] (default): an empty list; frequencies will be found within the input SampleMessages. AxisArrays have no good place to put this metadata, so specify frequencies here if only AxisArrays will be passed as input to the generator. If the input has a trigger attr of type SampleTriggerMessage, the processor looks for the freqs attribute within that trigger for a list of frequencies to evaluate. This field is present in the SSVEPSampleTriggerMessage defined in ezmsg.tasks.ssvep from the ezmsg-tasks package. NOTE: Avoid frequencies that have line-noise (60 Hz/50 Hz) as a harmonic.

subbands: int = 12

class StreamingFBCCATransformer(*args, **kwargs)

Bases: CompositeProcessor[StreamingFBCCASettings, AxisArray, AxisArray]

class FBCCASettings(time_dim, ch_dim, filterbank_dim=None, harmonics=5, freqs=<factory>, softmax_beta=1.0, target_freq_dim='target_freq', max_int_time=0.0)

Bases: Settings

Settings for FBCCATransformer

Parameters:

• time_dim (str)

• ch_dim (str)

• filterbank_dim (str | None)

• harmonics (int)

• freqs (List[float])

• softmax_beta (float)

• target_freq_dim (str)

• max_int_time (float)

time_dim: str

The time dim in the data array.

ch_dim: str

The channels dim in the data array.

filterbank_dim: str | None = None

The filter bank subband dim in the data array. If unspecified, method falls back to CCA None (default): the input has no subbands; just use CCA

harmonics: int = 5

The number of additional harmonics beyond the fundamental to use for the ‘design’ matrix. 5 (default): Evaluate 5 harmonics of the base frequency. Many periodic signals are not pure sinusoids, and inclusion of higher harmonics can help evaluate the presence of signals with higher frequency harmonic content

freqs: List[float]

Frequencies (in hz) to evaluate the presence of within the input signal. [] (default): an empty list; frequencies will be found within the input SampleMessages. AxisArrays have no good place to put this metadata, so specify frequencies here if only AxisArrays will be passed as input to the generator. If the input has a trigger attr of type SampleTriggerMessage, the processor looks for the freqs attribute within that trigger for a list of frequencies to evaluate. This field is present in the SSVEPSampleTriggerMessage defined in ezmsg.tasks.ssvep from the ezmsg-tasks package. NOTE: Avoid frequencies that have line-noise (60 Hz/50 Hz) as a harmonic.

softmax_beta: float = 1.0

Beta parameter for softmax on output –> “probabilities”. 1.0 (default): Use the shifted softmax transformation to output 0-1 probabilities. If 0.0, the maximum singular value of the SVD for each design matrix is output

target_freq_dim: str = 'target_freq'

Name for dim to put target frequency outputs on. ‘target_freq’ (default)

max_int_time: float = 0.0

Maximum integration time (in seconds) to use for calculation. 0 (default): Use all time provided for the calculation. Useful for artificially limiting the amount of data used for the CCA method to evaluate the necessary integration time for good decoding performance

__init__(time_dim, ch_dim, filterbank_dim=None, harmonics=5, freqs=<factory>, softmax_beta=1.0, target_freq_dim='target_freq', max_int_time=0.0)

Parameters:

• time_dim (str)

• ch_dim (str)

• filterbank_dim (str | None)

• harmonics (int)

• freqs (List[float])

• softmax_beta (float)

• target_freq_dim (str)

• max_int_time (float)

Return type:

None

class FBCCATransformer(*args, settings=None, **kwargs)

Bases: BaseTransformer[FBCCASettings, AxisArray, AxisArray]

A canonical-correlation (CCA) signal decoder for detection of periodic activity in multi-channel timeseries recordings. It is particularly useful for detecting the presence of steady-state evoked responses in multi-channel EEG data. Please see Lin et. al. 2007 for a description on the use of CCA to detect the presence of SSVEP in EEG data. This implementation also includes the “Filterbank” extension of the CCA decoding approach which utilizes a filterbank to decompose input multi-channel EEG data into several frequency sub-bands; each of which is analyzed with CCA, then combined using a weighted sum; allowing CCA to more readily identify harmonic content in EEG data. Read more about this approach in Chen et. al. 2015.

## Further reading: * [Lin et. al. 2007](https://ieeexplore.ieee.org/document/4015614) * [Nakanishi et. al. 2015](https://doi.org/10.1371%2Fjournal.pone.0140703) * [Chen et. al. 2015](http://dx.doi.org/10.1088/1741-2560/12/4/046008)

Parameters:

settings (SettingsType)

class FBCCA(*args, settings=None, **kwargs)

Bases: BaseTransformerUnit[FBCCASettings, AxisArray, AxisArray, FBCCATransformer]

Parameters:

settings (Settings | None)

SETTINGS

alias of FBCCASettings

class StreamingFBCCASettings(time_dim, ch_dim, filterbank_dim=None, harmonics=5, freqs=<factory>, softmax_beta=1.0, target_freq_dim='target_freq', max_int_time=0.0, window_dur=4.0, window_shift=0.5, window_dim='fbcca_window', filter_bw=7.0, filter_low=7.0, trans_bw=2.0, ripple_db=20.0, subbands=12)

Bases: FBCCASettings

Perform rolling/streaming FBCCA on incoming EEG. Decomposes the input multi-channel timeseries data into multiple sub-bands using a FilterbankDesign Transformer, then accumulates data using Window into short-time observations for analysis using an FBCCA Transformer.

Parameters:

• time_dim (str)

• ch_dim (str)

• filterbank_dim (str | None)

• harmonics (int)

• freqs (List[float])

• softmax_beta (float)

• target_freq_dim (str)

• max_int_time (float)

• window_dur (float)

• window_shift (float)

• window_dim (str)

• filter_bw (float)

• filter_low (float)

• trans_bw (float)

• ripple_db (float)

• subbands (int)

window_dur: float = 4.0

window_shift: float = 0.5

window_dim: str = 'fbcca_window'

filter_bw: float = 7.0

filter_low: float = 7.0

trans_bw: float = 2.0

__init__(time_dim, ch_dim, filterbank_dim=None, harmonics=5, freqs=<factory>, softmax_beta=1.0, target_freq_dim='target_freq', max_int_time=0.0, window_dur=4.0, window_shift=0.5, window_dim='fbcca_window', filter_bw=7.0, filter_low=7.0, trans_bw=2.0, ripple_db=20.0, subbands=12)

Parameters:

• time_dim (str)

• ch_dim (str)

• filterbank_dim (str | None)

• harmonics (int)

• freqs (List[float])

• softmax_beta (float)

• target_freq_dim (str)

• max_int_time (float)

• window_dur (float)

• window_shift (float)

• window_dim (str)

• filter_bw (float)

• filter_low (float)

• trans_bw (float)

• ripple_db (float)

• subbands (int)

Return type:

None

ripple_db: float = 20.0

subbands: int = 12

class StreamingFBCCATransformer(*args, **kwargs)

Bases: CompositeProcessor[StreamingFBCCASettings, AxisArray, AxisArray]

class StreamingFBCCA(*args, settings=None, **kwargs)

Bases: BaseTransformerUnit[StreamingFBCCASettings, AxisArray, AxisArray, StreamingFBCCATransformer]

Parameters:

settings (Settings | None)

SETTINGS

alias of StreamingFBCCASettings

cca_rho_max(X, Y)

X: (n_time, n_ch) Y: (n_time, n_ref) # design matrix for one frequency returns: largest canonical correlation in [0,1]

Parameters:

• X (ndarray)

• Y (ndarray)

Return type:

float

calc_softmax(cv, axis, beta=1.0)

Parameters:

• cv (ndarray)

• axis (int)

• beta (float)