Base of all transformers#

Classes for transforming data to HMP format.

These provide methods to:

  1. Trim the trials data from epoch time 0 (e.g. stimulus) up to a specified interval (e.g. response), optionally including a fixed offset after the interval.

  2. Epochs whose interval exceeds lower and upper interval limits (min_duration and max_duration) are rejected. Additional rejection can be applied based on amplitude thresholds with reject_threshold

  3. Optionally center the data (recommended for covariance based approahces

  4. Project channels to new virtual channel, using the different classes,

    either based on a PCA (ProjPCA), arbitrary linear combination of channels (ProjArbitrary) or the identity of the channels (ProjIdentity)

  5. Whiten the components and standardize each trial’s variance ( common_variance) and

    standardize the components for each participants

Classes#

ProjPCA

Project channels into principal component space based on the covariance matrix among electrodes

ProjArbitrary

Apply a user-defined linear combination of original channels to a new set of virtual channels

ProjIdentity

Returns the channels in the same space

class hmp.transformers.base.BaseTransformer(interval_id, offset_end, offset_start, min_duration, max_duration, reject_threshold, verbose, common_variance, subject_zscore, whiten, center)#

Bases: ABC

Base class for HMP transformer pipelines.

This class provides common transformer steps.

common_preprocess(data)#

Apply core transformer steps including rejection, variance standardization, and centering.

reject_crop_epochs(data)#

Crop each epoch from time 0 of the epoch to its interval with optional rejection criteria. For epoch in the epoch_data xr.Dataset, this function trims the epoch data from epoch time 0 (e.g. stimulus onset) up to the specified interval (e.g. response), optionally

including a fixed offset after the interval.

Epochs whose interval exceeds specified lower and upper limits are rejected. Additional rejection can be applied based on signal amplitude thresholds in the interval.

data_format(data, weights, transformer_model, ori_coords, sfreq, offset)#

Finalize the transformation by formatting the data.

common_preprocess(epoch_data)#
Return type:

DataArray

static compute_covariance(data)#
data_format(data, weights)#

Finalize the transformation, whiten and store attributes.

Return type:

None

reject_crop_epochs(epoch_data)#

Crop each epoch from time 0 of the epoch to its interval with optional rejection criteria.

For epoch in the epoch_data xr.Dataset, this function trims the epoch data from epoch

time 0 (e.g. stimulus onset) up to the specified interval (e.g. response), optionally including a fixed offset after the interval.

Epochs whose interval exceeds specified lower and upper limits are rejected, and

additional rejection can be applied based on signal amplitude thresholds in the interval.

Returns:

epoch_data – Array of cropped epoch data that passed all criteria.

Return type:

np.ndarray

Standard PCA Projection#

Transforms epoched data using a PCA for HMP analysis.

Project channels to principal components space. The PCA is performed on subject-averaged covariance matrix among electrodes. The number of PC is either declared at initialization or a plot opens with

a prompt to select based on the scree plot of the PCA.

class hmp.transformers.pca.ProjPCA(epoch_data, interval_id='rt', offset_end=0, offset_start=0, min_duration=0, max_duration=inf, reject_threshold=None, center=True, whiten=True, common_variance=True, subject_zscore=True, verbose=True, n_comp=None, method='svd')#

Bases: BaseTransformer

Transforms epoched data using a PCA for HMP analysis.

Project channels to principal components space. The PCA is performed on subject-averaged covariance matrix among electrodes. The number of PC is either declared at initialization or a plot opens with

a prompt to select based on the scree plot of the PCA.

Parameters:

  • epoch_data (xr.Dataset) – Input EEG data with dimensions [participant, epoch, sample, channel], from io module

  • interval_id (str) – Name of the variable that contains the trial intervals in the epoch_data used for cropping.

  • offset_end (float) – Time offset after interval end for cropping.

  • offset_start (float) – Time offset before interval start for cropping. Negative number extends epoch before start.

  • min_duration (float, optional) – Minimum duration threshold for keeping epochs.

  • max_duration (float, optional) – Maximum duration threshold for keeping epochs.

  • reject_threshold (float, optional) – Threshold for rejecting noisy epochs.

  • common_variance (bool) – Whether to standardize variance across trials.

  • subject_zscore (bool) – Z-score each component for each participant

  • whiten (bool) – Return the components with unit-variance

  • center (bool) – Whether to center the data across the last dimension before projection

  • verbose (bool) – Whether to print rejection/cropping details.

  • n_comp (int) – Number of components in the PCA to retain for projection. If None (default), a prompt will open asking to select a number

  • method (str) – Perform PCA (‘pca’, Default) or SVD decomposition (‘svd’)

user_input_n_comp(data, n_comp, channel, method)#
Return type:

int

Identity projection#

Transforms epoched data using a the ProjIdentity matrix for HMP analysis.

Returns electrode values after performing transformation steps without the projection. For consistency the channel dimension is renamed ‘component’

class hmp.transformers.identity.ProjIdentity(epoch_data, interval_id='rt', offset_end=0, offset_start=0, min_duration=0, max_duration=inf, reject_threshold=None, center=False, whiten=True, common_variance=False, subject_zscore=False, verbose=True)#

Bases: BaseTransformer

Transforms epoched data using a the ProjIdentity matrix for HMP analysis.

Returns electrode values after performing transformation steps without the projection. For consistency the channel dimension is renamed ‘component’

Parameters:

  • epoch_data (xr.Dataset) – Input EEG data with dimensions [participant, epoch, sample, channel], from io module

  • interval_id (str) – Name of the variable that contains the trial intervals in the epoch_data used for cropping.

  • offset_end (float) – Time offset after interval end for cropping.

  • offset_start (float) – Time offset before interval start for cropping. Negative number extends epoch before start.

  • min_duration (float, optional) – Minimum duration threshold for keeping epochs.

  • max_duration (float, optional) – Maximum duration threshold for keeping epochs.

  • reject_threshold (float, optional) – Threshold for rejecting noisy epochs.

  • common_variance (bool) – Whether to standardize variance across trials.

  • subject_zscore (bool) – Z-score each component for each participant

  • whiten (bool) – Return the components with unit-variance

  • center (bool) – Whether to center the data across the last dimension before projection

  • verbose (bool) – Whether to print rejection/cropping details.

Custom projection#

Transforms epoched data using a custom linear combination for HMP analysis.

Projects channels into a custom space given by a n_chan x n_component matrix.

See example matrix when applying ProjPCA class.

class hmp.transformers.custom.ProjCustom(epoch_data, weights, interval_id='rt', offset_end=0, offset_start=0, min_duration=0, max_duration=inf, reject_threshold=None, center=True, whiten=True, common_variance=True, subject_zscore=True, verbose=True)#

Bases: BaseTransformer

Transforms epoched data using a a custom linear combination for HMP analysis.

Projects channels into a custom space given by a n_chan x n_component matrix.

See example matrix when applying ProjPCA class.

Parameters:

  • epoch_data (xr.Dataset) – Input EEG data with dimensions [participant, epoch, sample, channel], from io module

  • weights (xr.DataArray) –

    Custom linear combination of channels as an xarray.DataArray with ‘channel’ and ‘component’

    dimensions and the weights

  • interval_id (str) – Name of the variable that contains the trial intervals in the epoch_data used for cropping.

  • offset_end (float) – Time offset after interval end for cropping.

  • offset_start (float) – Time offset before interval start for cropping. Negative number extends epoch before start.

  • min_duration (float, optional) – Minimum duration threshold for keeping epochs.

  • max_duration (float, optional) – Maximum duration threshold for keeping epochs.

  • reject_threshold (float, optional) – Threshold for rejecting noisy epochs.

  • center (bool) – Whether to center the data across the last dimension before projection

  • whiten (bool) – Return the components with unit-variance

  • common_variance (bool) – Whether to standardize variance across trials.

  • subject_zscore (bool) – Z-score each component for each participant

  • subject_zscore – Participant-wise standardization of the projection components using zscores

  • verbose (bool) – Whether to print rejection/cropping details.