glhmm.preproc

Preprocessing functions - General/Gaussian Linear Hidden Markov Model @author: Diego Vidaurre 2023

glhmm.preproc.apply_ica(X, d, algorithm='parallel')

Applies ICA to the input data X.

Parameters:

Xarray-like of shape (n_samples, n_parcels)

The input data to be transformed.

dint or float

If int, the number of components to keep. If float, the percentage of explained variance to keep (according to a PCA decomposition)

algorithm{“parallel”, “deflation”}, default=”parallel”

Specify which algorithm to use for FastICA.

Returns:

Xarray-like of shape (n_samples, n_components)

The transformed data after applying ICA.

icamodesklearn estimator

The estimated ICA model

glhmm.preproc.apply_pca(X, d, whitening=False, exact=True)

Applies PCA to the input data X.

Parameters:

Xarray-like of shape (n_samples, n_parcels)

The input data to be transformed.

dint or float

If int, the number of components to keep. If float, the percentage of explained variance to keep. If array-like of shape (n_parcels, n_components), the transformation matrix.

exactbool, default=True

Whether to use full SVD solver for PCA.

Returns:

Xarray-like of shape (n_samples, n_components)

The transformed data after applying PCA.

pcamodelsklearn estimator

The estimated PCA model

glhmm.preproc.build_data_autoregressive(data, indices, autoregressive_order=1, connectivity=None, center_data=True)

Builds X and Y for the autoregressive model, as well as an adapted indices array and predefined connectivity matrix in the right format. X and Y are centered by default.

Parameters:

dataarray-like of shape (n_samples,n_parcels)

The data timeseries.

indicesarray-like of shape (n_sessions, 2)

The start and end indices of each trial/session in the input data.

autoregressive_orderint, optional, default=1

The number of lags to include in the autoregressive model.

connectivityarray-like of shape (n_parcels, n_parcels), optional, default=None

The matrix indicating which regressors should be used for each variable.

center_databool, optional, default=True

If True, the data will be centered.

Returns:

Xarray-like of shape (n_samples - n_sessions*autoregressive_order, n_parcels*autoregressive_order)

The timeseries of set of variables 1 (i.e., the regressors).

Yarray-like of shape (n_samples - n_sessions*autoregressive_order, n_parcels)

The timeseries of set of variables 2 (i.e., variables to predict, targets).

indices_newarray-like of shape (n_sessions, 2)

The new array of start and end indices for each trial/session.

connectivity_newarray-like of shape (n_parcels*autoregressive_order, n_parcels)

The new connectivity matrix indicating which regressors should be used for each variable.

glhmm.preproc.build_data_partial_connectivity(X, Y, connectivity=None, center_data=True)

Builds X and Y for the partial connectivity model, essentially regressing out things when indicated in connectivity, and getting rid of regressors / regressed variables that are not used; it return connectivity with the right dimensions as well.

Parameters:

Xnp.ndarray of shape (n_samples, n_parcels)

The timeseries of set of variables 1 (i.e., the regressors).

Ynp.ndarray of shape (n_samples, n_parcels)

The timeseries of set of variables 2 (i.e., variables to predict, targets).

connectivitynp.ndarray of shape (n_parcels, n_parcels), optional, default=None

A binary matrix indicating which regressors affect which targets (i.e., variables to predict).

center_databool, default=True

Center data to zero mean.

Returns:

X_newnp.ndarray of shape (n_samples, n_active_parcels)

The timeseries of set of variables 1 (i.e., the regressors) after removing unused predictors and regressing out the effects indicated in connectivity.

Y_newnp.ndarray of shape (n_samples, n_active_parcels)

The timeseries of set of variables 2 (i.e., variables to predict, targets) after removing unused targets and regressing out the effects indicated in connectivity.

connectivity_newnp.ndarray of shape (n_active_parcels, n_active_parcels), optional, default=None

A binary matrix indicating which regressors affect which targets The matrix has the same structure as connectivity after removing unused predictors and targets.

glhmm.preproc.build_data_tde(data, indices, lags, pca=None, standardise_pc=True)

Builds X for the temporal delay embedded HMM, as well as an adapted indices array.

Parameters:

datanumpy array of shape (n_samples, n_parcels)

The data matrix.

indicesarray-like of shape (n_sessions, 2)

The start and end indices of each trial/session in the input data.

lagslist or array-like

The lags to use for the embedding.

pcaNone or int or float or numpy array, default=None

The number of components for PCA, the explained variance for PCA, the precomputed PCA projection matrix, or None to skip PCA.

standardise_pcbool, default=True

Whether or not to standardise the principal components before returning.

Returns:

Xnumpy array of shape (n_samples - n_sessions*rwindow, n_parcels*n_lags)

The delay-embedded timeseries data.

indices_newnumpy array of shape (n_sessions, 2)

The adapted indices for each segment of delay-embedded data.

pcamodelsklearn estimator, optional

If doing PCA, the estimated PCA model

PCA can be run optionally: if pca >=1, that is the number of components; if pca < 1, that is explained variance; if pca is a numpy array, then it is a precomputed PCA projection matrix; if pca is None, then no PCA is run.

glhmm.preproc.dampen_peaks(X, strength=5)

Applies dampening of extreme peaks to the input data X, at the group level. If the absolute value of X goes beyond 2 standard deviation of X, it gets substituted by the logarithm of the absolute value of X.

Parameters:

Xarray-like of shape (n_samples, n_parcels)

The input data to be transformed.

strengthpositive int

The strength of dampening. This value refers to the base of the logarithm to use. The bigger the base, the stronger the dampening.

Returns:

X_transformedarray-like of shape (n_samples, n_parcels)

The transformed data after applying extreme peak dampening.

glhmm.preproc.load_files(files, I=None, do_only_indices=False)

glhmm.preproc.preprocess_data(data, indices, fs=1, dampen_extreme_peaks=None, standardise=True, filter=None, detrend=False, onpower=False, onphase=False, pca=None, exact_pca=True, ica=None, ica_algorithm='parallel', post_standardise=None, downsample=None)

Preprocess the input data.

Parameters:

dataarray-like of shape (n_samples, n_parcels)

The input data to be preprocessed.

indicesarray-like of shape (n_sessions, 2)

The start and end indices of each trial/session in the input data.

fsint or float, default=1

The frequency of the input data.

dampen_extreme_peaksint, True or None, default=None

determines whether to dampen extreme peaks in the data and the strength of the dampening. If this is chosen, the data are centered first (per subject). If int, the strength of dampening If True, the dampening is done with default value 5. If None, no dampening will be applied.

standardisebool, default=True.

Whether to standardize the input data.

filtertuple of length 2 or None, default=None

The low-pass and high-pass thresholds to apply to the input data. If None, no filtering will be applied. If a tuple, the first element is the low-pass threshold and the second is the high-pass threshold.

detrendbool, default=False

Whether to detrend the input data.

onpowerbool, default=False

Whether to calculate the power of the input data using the Hilbert transform.

onphasebool, default=False

Whether to calculate the phase of the input data using the Hilbert transform. If both onpower and onphase are set to True, power and phase will be included as separate columns in the output array

pcaint or float or None, default=None

If int, the number of components to keep after applying PCA. If float, the percentage of explained variance to keep after applying PCA (must be >=0 and >=1) If None, no PCA will be applied.

exact_pcabool, default=True

Whether to use full SVD solver for PCA.

icaint or float or None, default=None

determines whether to apply ICA (if pca is also specified, it is overridden, and only ica is used) If int, the number of independent components to estimate If float, the number of components is given by the percentage of explained variance from PCA. If None, no PCA will be applied.

ica_algorithm{“parallel”, “deflation”}, default=”parallel”

Specify which algorithm to use for ICA (based on FastICA).

post_standardisebool, default=False if pca is used; =True if ica is used;

Whether to standardize after applying PCA/ICA (recommended when using the TDE-HMM)

downsampleint or float or None, default=None

The new frequency of the input data after downsampling. If None, no downsampling will be applied.

Returns:

dataarray-like of shape (n_samples_processed, n_parcels)

The preprocessed input data.

indices_newarray-like of shape (n_sessions_processed, 2)

The start and end indices of each trial/session in the preprocessed data.

logdict

Dictionary logging which preprocessing has been applied, to be passed onto the glhmm object instance. This contains the variables passed to the function and (where relevant) the estimators (PCA/ICA models)