EpochAverage

class gpype.backend.flow.epoch_average.EpochAverage

Bases: IONode

Averages epochs as they arrive, and says how many it used.

An evoked response is buried well below the ongoing EEG, so it only appears once many trials are averaged. Until now the only averaging in the package happened inside a scope’s paint routine, on a leaf with no output, so an averaged response could be looked at but never written to a file, sent to another program, measured, or compared against another condition.

Trials that are obviously contaminated should not be averaged in at all, so rejection is part of this node rather than a separate one: one rejected trial is a discarded epoch, not a pipeline branch.

The count travels on its own port, because an average without its trial count cannot be interpreted.

OUTPUT_PORT_NAMES = ('out', 'count')

Two outputs, so they are declared. Same names the constructor builds its OPort configurations from.

PORT_COUNT = 'count'

Port carrying the number of epochs in the current average.

class Configuration

Bases: Configuration

Configuration class for EpochAverage parameters.

class Keys

Bases: Keys

Configuration keys for EpochAverage settings.

MODE = 'mode'

How epochs are combined

class OptionalKeys

Bases: OptionalKeys

Optional configuration keys.

COUNT = 'count'

Number of epochs in a moving or exponential average

REJECT_LEVEL = 'reject_level'

Reject an epoch exceeding this absolute amplitude

REJECT_PEAK_TO_PEAK = 'reject_peak_to_peak'

Reject an epoch exceeding this peak-to-peak amplitude

CUMULATIVE = 'cumulative'

Average every epoch seen so far.

MOVING = 'moving'

Average the last count epochs.

EXPONENTIAL = 'exponential'

Exponentially weight recent epochs, with count as the constant.

__init__(mode='cumulative', count=None, reject_level=None, reject_peak_to_peak=None, **kwargs)

Initialize the epoch average.

Parameters:

• mode (str) – CUMULATIVE, MOVING or EXPONENTIAL.

• count (Optional[int]) – Number of epochs for MOVING, or the weighting constant for EXPONENTIAL. Required for both.

• reject_level (Optional[float]) – Discard an epoch if any sample of any signal channel exceeds this absolute amplitude.

• reject_peak_to_peak (Optional[float]) – Discard an epoch if any channel’s peak-to-peak amplitude exceeds this.

• **kwargs – Additional arguments for the parent IONode.

Raises:

ValueError – If the mode is unknown, if a count is needed and missing, or if a rejection limit is not positive.

property accepted

Number of epochs averaged in so far.

property rejected

Number of epochs discarded by the rejection limits.

reset()

Discard the average and start again.

Return type:

None

setup(data, port_context_in)

Describe the averaged output and the count port.

Parameters:

• data (dict[str, ndarray]) – Initial data dictionary.

• port_context_in (dict[str, dict]) – Input port contexts.

Return type:

dict[str, dict]

Returns:

Output port contexts.

step(data)

Average one epoch in and emit the current average.

Parameters:

data (dict[str, ndarray]) – Input epoch.

Return type:

dict[str, ndarray]

Returns:

The current average and its trial count, or None while there is nothing to report.

process(data)

Average a whole (time, channel, trial) block, in one call.

The counterpart of step() for a batch run, where a node such as Epochs hands over every trial at once instead of one epoch per cycle (D-BATCH-89). mode, reject_level and reject_peak_to_peak are not consulted: there is no arrival order to be cumulative, moving or exponential about, and no cycle-by-cycle amplitude check to run – the whole cube is averaged in one call.

Parameters:

data (dict[str, ndarray]) – The complete block, shape (time, channel, trial), under key PORT_IN.

Return type:

dict[str, ndarray]

Returns:

The mean over the trial axis, shape (time, channel), under PORT_OUT, and the trial count under PORT_COUNT.

Raises:

ValueError – If the input is not three-dimensional.