brainda.algorithms.utils package

Submodules

brainda.algorithms.utils.covariance module

class brainda.algorithms.utils.covariance.Covariance(estimator='cov', n_jobs=1)

Bases: BaseEstimator, TransformerMixin

Estimation of covariance matrix.

Parameters:

  • estimator (str or callable object, optional) –

    Covariance estimator to use (the default is cov, which uses empirical covariance estimator). For regularization, consider lwf or oas.

    supported estimators

    cov: empirial covariance estimator

    lwf: ledoit wolf covariance estimator

    oas: oracle approximating shrinkage covariance estimator

    mcd: minimum covariance determinant covariance estimator

  • n_jobs (int or None, optional) – The number of CPUs to use to do the computation (the default is 1, -1 for all processors).

See also

ERPCovariance

fit(X, y=None)

Not used, only for compatibility with sklearn API.

Parameters:

  • X (ndarray) – EEG signal, shape (…, n_channels, n_samples).

  • y (ndarray) – Labels.

Returns:

self – The Covariance instance.

Return type:

Covariance instance

transform(X)

Transform EEG to covariance matrix.

Parameters:

X (ndarray) – EEG signal, shape (…, n_channels, n_samples).

Returns:

covmats – Estimated covariances, shape (…, n_channels, n_channels)

Return type:

ndarray

brainda.algorithms.utils.covariance.covariances(X: ndarray, estimator: Union[str, Callable[[ndarray], ndarray]] = 'cov', n_jobs: int = 1) → ndarray

Estimation of covariance matrix.

Parameters:

  • X (ndarray) – EEG signal, shape (…, n_channels, n_samples).

  • estimator (str or callable object, optional) –

    Covariance estimator to use (the default is cov, which uses empirical covariance estimator). For regularization, consider lwf or oas.

    supported estimators

    cov: empirial covariance estimator

    lwf: ledoit wolf covariance estimator

    oas: oracle approximating shrinkage covariance estimator

    mcd: minimum covariance determinant covariance estimator

  • n_jobs (int or None, optional) – The number of CPUs to use to do the computation (the default is 1, -1 for all processors).

Returns:

covmats – covariance matrices, shape (…, n_channels, n_channels)

Return type:

ndarray

See also

covariances_erp

brainda.algorithms.utils.covariance.expm(Ci: ndarray, n_jobs: Optional[int] = None)

Return the matrix exponential of a covariance matrix.

Parameters:

Ci (ndarray) – Input positive-definite matrix.

Returns:

Exponential matrix of Ci.

Return type:

ndarray

Notes

\[\mathbf{C} = \mathbf{V} \exp{(\mathbf{\Lambda})} \mathbf{V}^T\]

where \(\mathbf{\Lambda}\) is the diagonal matrix of eigenvalues and \(\mathbf{V}\) the eigenvectors of \(\mathbf{Ci}\).

brainda.algorithms.utils.covariance.invsqrtm(Ci: ndarray, n_jobs: Optional[int] = None)

Return the inverse matrix square root of a covariance matrix.

Parameters:

Ci (ndarray) – Input positive-definite matrix.

Returns:

Inverse matrix square root of Ci.

Return type:

ndarray

Notes

\[\mathbf{C} = \mathbf{V} \left( \mathbf{\Lambda} \right)^{-1/2} \mathbf{V}^T\]

where \(\mathbf{\Lambda}\) is the diagonal matrix of eigenvalues and \(\mathbf{V}\) the eigenvectors of \(\mathbf{Ci}\).

brainda.algorithms.utils.covariance.isPD(B: ndarray) → bool

Returns true when input matrix is positive-definite, via Cholesky decompositon method.

Parameters:

B (ndarray) – Any matrix, shape (N, N)

Returns:

True if B is positve-definite.

Return type:

bool

Notes

Use numpy.linalg rather than scipy.linalg. In this case, scipy.linalg has unpredictable behaviors.

brainda.algorithms.utils.covariance.logm(Ci: ndarray, n_jobs: Optional[int] = None)

Return the matrix logrithm of a covariance matrix.

Parameters:

Ci (ndarray) – Input positive-definite matrix.

Returns:

Logrithm matrix of Ci.

Return type:

ndarray

Notes

\[\mathbf{C} = \mathbf{V} \log{(\mathbf{\Lambda})} \mathbf{V}^T\]

where \(\mathbf{\Lambda}\) is the diagonal matrix of eigenvalues and \(\mathbf{V}\) the eigenvectors of \(\mathbf{Ci}\).

brainda.algorithms.utils.covariance.matrix_operator(Ci: ndarray, operator: Callable[[ndarray], ndarray], n_jobs: Optional[int] = None) → ndarray

Apply operator to any matrix.

Parameters:

  • Ci (ndarray) – Input positive definite matrix.

  • operator (callable object) – Operator function or callable object.

  • n_jobs (int, optional) – the number of jobs to use.

Returns:

Co – Operated matrix.

Return type:

ndarray

Raises:

ValueError – If Ci is not positive definite.

Notes

\[\begin{split}\mathbf{Ci} = \mathbf{V} \left( \mathbf{\Lambda} \right) \mathbf{V}^T \\ \mathbf{Co} = \mathbf{V} operator\left( \mathbf{\Lambda} \right) \mathbf{V}^T\end{split}\]

where \(\mathbf{\Lambda}\) is the diagonal matrix of eigenvalues and \(\mathbf{V}\) the eigenvectors of \(\mathbf{Ci}\).

brainda.algorithms.utils.covariance.nearestPD(A: ndarray) → ndarray

Find the nearest positive-definite matrix to input.

Parameters:

A (ndarray) – Any square matrxi, shape (N, N)

Returns:

A3 – positive-definite matrix to A

Return type:

ndarray

Notes

A Python/Numpy port of John D’Errico’s nearestSPD MATLAB code [1], which origins at [2].

References

brainda.algorithms.utils.covariance.powm(Ci: ndarray, alpha: float, n_jobs: Optional[int] = None)

Return the matrix power of a covariance matrix.

Parameters:

  • Ci (ndarray) – Input positive-definite matrix.

  • alpha (float) – Exponent.

Returns:

Power matrix of Ci.

Return type:

ndarray

Notes

\[\mathbf{C} = \mathbf{V} \left( \mathbf{\Lambda} \right)^{\alpha} \mathbf{V}^T\]

where \(\mathbf{\Lambda}\) is the diagonal matrix of eigenvalues and \(\mathbf{V}\) the eigenvectors of \(\mathbf{Ci}\).

brainda.algorithms.utils.covariance.sqrtm(Ci: ndarray, n_jobs: Optional[int] = None)

Return the matrix square root of a covariance matrix.

Parameters:

Ci (ndarray) – Input positive-definite matrix.

Returns:

Square root matrix of Ci.

Return type:

ndarray

Notes

\[\mathbf{C} = \mathbf{V} \left( \mathbf{\Lambda} \right)^{1/2} \mathbf{V}^T\]

where \(\mathbf{\Lambda}\) is the diagonal matrix of eigenvalues and \(\mathbf{V}\) the eigenvectors of \(\mathbf{Ci}\).

brainda.algorithms.utils.model_selection module

class brainda.algorithms.utils.model_selection.EnhancedLeaveOneGroupOut(return_validate: bool = True)

Bases: LeaveOneGroupOut

split(X, y=None, groups=None)

Generate indices to split data into training and test set.

Parameters:

  • X (array-like of shape (n_samples, n_features)) – Training data, where n_samples is the number of samples and n_features is the number of features.

  • y (array-like of shape (n_samples,), default=None) – The target variable for supervised learning problems.

  • groups (array-like of shape (n_samples,)) – Group labels for the samples used while splitting the dataset into train/test set.

Yields:

  • train (ndarray) – The training set indices for that split.

  • test (ndarray) – The testing set indices for that split.

class brainda.algorithms.utils.model_selection.EnhancedStratifiedKFold(n_splits: int = 5, shuffle: bool = False, return_validate: bool = True, random_state: Optional[Union[int, RandomState]] = None)

Bases: StratifiedKFold

Enhanced Stratified KFold cross-validator.

if return_validate is True, split return (train, validate, test) indexs, else (train, test) as the sklearn StratifiedKFold.fit

the validate size should be the same as the test size.

split(X, y, groups=None)

Generate indices to split data into training and test set.

Parameters:

  • X (array-like of shape (n_samples, n_features)) –

    Training data, where n_samples is the number of samples and n_features is the number of features.

    Note that providing y is sufficient to generate the splits and hence np.zeros(n_samples) may be used as a placeholder for X instead of actual training data.

  • y (array-like of shape (n_samples,)) – The target variable for supervised learning problems. Stratification is done based on the y labels.

  • groups (object) – Always ignored, exists for compatibility.

Yields:

  • train (ndarray) – The training set indices for that split.

  • test (ndarray) – The testing set indices for that split.

Notes

Randomized CV splitters may return different results for each call of split. You can make the results identical by setting random_state to an integer.

class brainda.algorithms.utils.model_selection.EnhancedStratifiedShuffleSplit(test_size: float, train_size: float, n_splits: int = 5, validate_size: Optional[float] = None, return_validate: bool = True, random_state: Optional[Union[int, RandomState]] = None)

Bases: StratifiedShuffleSplit

split(X, y, groups=None)

Generate indices to split data into training and test set.

Parameters:

  • X (array-like of shape (n_samples, n_features)) –

    Training data, where n_samples is the number of samples and n_features is the number of features.

    Note that providing y is sufficient to generate the splits and hence np.zeros(n_samples) may be used as a placeholder for X instead of actual training data.

  • y (array-like of shape (n_samples,) or (n_samples, n_labels)) – The target variable for supervised learning problems. Stratification is done based on the y labels.

  • groups (object) – Always ignored, exists for compatibility.

Yields:

  • train (ndarray) – The training set indices for that split.

  • test (ndarray) – The testing set indices for that split.

Notes

Randomized CV splitters may return different results for each call of split. You can make the results identical by setting random_state to an integer.

brainda.algorithms.utils.model_selection.generate_kfold_indices(meta: DataFrame, kfold: int = 5, random_state: Optional[Union[int, RandomState]] = None)
brainda.algorithms.utils.model_selection.generate_loo_indices(meta: DataFrame)
brainda.algorithms.utils.model_selection.generate_shuffle_indices(meta: DataFrame, n_splits: int = 5, test_size: float = 0.1, validate_size: float = 0.1, train_size: float = 0.8, random_state: Optional[Union[int, RandomState]] = None)
brainda.algorithms.utils.model_selection.match_kfold_indices(k: int, meta: DataFrame, indices)
brainda.algorithms.utils.model_selection.match_loo_indices(k: int, meta: DataFrame, indices)
brainda.algorithms.utils.model_selection.match_shuffle_indices(k: int, meta: DataFrame, indices)
brainda.algorithms.utils.model_selection.set_random_seeds(seed: int)

Set seeds for python random module numpy.random and torch.

Parameters:

seed (int) – Random seed.

Module contents