rsatoolbox.data.noise module

Functions for estimating the precision matrix based on the covariance of either the residuals (temporal based precision matrix) or of the measurements (instance based precision matrix)

rsatoolbox.data.noise.cov_from_measurements(dataset, obs_desc, dof=None, method='shrinkage_diag')

Estimates a covariance matrix from measurements. Allows for shrinkage estimates. Use ‘method’ to choose which estimation method is used.

Parameters:

• dataset (data.Dataset) – rsatoolbox Dataset object

• dof (int or list of int) – degrees of freedom for covariance estimation defaults to n_res - 1, should be corrected for the number of regressors in a GLM if applicable.

• method (str) – which estimate to use: ‘diag’: provides a diagonal matrix, i.e. univariate noise normalizer ‘full’: computes the sample covariance without shrinkage ‘shrinkage_eye’: shrinks the data covariance towards a multiple of the identity. ‘shrinkage_diag’: shrinks the covariance matrix towards the diagonal covariance matrix.

Returns:

sigma_p: covariance matrix over channels

Return type:

numpy.ndarray (or list)

rsatoolbox.data.noise.cov_from_residuals(residuals, dof=None, method='shrinkage_diag')

Estimates a covariance matrix from measurements. Allows for shrinkage estimates. Use ‘method’ to choose which estimation method is used.

Parameters:

• residuals (numpy.ndarray or list of these) – n_residuals x n_channels matrix of residuals

• dof (int or list of int) – degrees of freedom for covariance estimation defaults to n_res - 1, should be corrected for the number of regressors in a GLM if applicable.

• method (str) – which estimate to use: ‘diag’: provides a diagonal matrix, i.e. univariate noise normalizer ‘full’: computes the sample covariance without shrinkage ‘shrinkage_eye’: shrinks the data covariance towards a multiple of the identity. ‘shrinkage_diag’: shrinks the covariance matrix towards the diagonal covariance matrix.

Returns:

sigma_p: covariance matrix over channels

Return type:

numpy.ndarray (or list)

rsatoolbox.data.noise.cov_from_unbalanced(dataset, obs_desc, dof=None, method='shrinkage_diag')

Estimates a covariance matrix from an unbalanced dataset, i.e. from a dataset that contains different numbers of samples for different stimuli.

Parameters:

• dataset (data.Dataset) – rsatoolbox Dataset object

• dof (int or list of int) – degrees of freedom for covariance estimation defaults to n_measurements - n_stimuli, should be corrected if this is not the case

• method (str) – which estimate to use: ‘diag’: provides a diagonal matrix, i.e. univariate noise normalizer ‘full’: computes the sample covariance without shrinkage ‘shrinkage_eye’: shrinks the data covariance towards a multiple of the identity. ‘shrinkage_diag’: shrinks the covariance matrix towards the diagonal covariance matrix.

Returns:

sigma_p: covariance matrix over channels

Return type:

numpy.ndarray (or list)

rsatoolbox.data.noise.prec_from_measurements(dataset, obs_desc, dof=None, method='shrinkage_diag')

Estimates the covariance matrix from measurements and finds its multiplicative inverse (= the precision matrix) Use ‘method’ to choose which estimation method is used.

Parameters:

• residuals (numpy.ndarray or list of these) – n_residuals x n_channels matrix of residuals

• dof (int or list of int) – degrees of freedom for covariance estimation defaults to n_res - 1, should be corrected for the number of regressors in a GLM if applicable.

• method (str) – which estimate to use: ‘diag’: provides a diagonal matrix, i.e. univariate noise normalizer ‘full’: computes the sample covariance without shrinkage ‘shrinkage_eye’: shrinks the data covariance towards a multiple of the identity. ‘shrinkage_diag’: shrinks the covariance matrix towards the diagonal covariance matrix.

Returns:

sigma_p: precision matrix over channels

Return type:

numpy.ndarray (or list)

rsatoolbox.data.noise.prec_from_residuals(residuals, dof=None, method='shrinkage_diag')

Estimates the covariance matrix from residuals and finds its multiplicative inverse (= the precision matrix) Use ‘method’ to choose which estimation method is used.

Parameters:

• residuals (numpy.ndarray or list of these) – n_residuals x n_channels matrix of residuals

• dof (int or list of int) – degrees of freedom for covariance estimation defaults to n_res - 1, should be corrected for the number of regressors in a GLM if applicable.

• method (str) – which estimate to use: ‘diag’: provides a diagonal matrix, i.e. univariate noise normalizer ‘full’: computes the sample covariance without shrinkage ‘shrinkage_eye’: shrinks the data covariance towards a multiple of the identity. ‘shrinkage_diag’: shrinks the covariance matrix towards the diagonal covariance matrix.

Returns:

sigma_p: precision matrix over channels

Return type:

numpy.ndarray (or list)

rsatoolbox.data.noise.prec_from_unbalanced(dataset, obs_desc, dof=None, method='shrinkage_diag')

Estimates the covariance matrix from measurements and finds its multiplicative inverse (= the precision matrix) Use ‘method’ to choose which estimation method is used.

Parameters:

• residuals (numpy.ndarray or list of these) – n_residuals x n_channels matrix of residuals

• dof (int or list of int) – degrees of freedom for covariance estimation defaults to n_res - 1, should be corrected for the number of regressors in a GLM if applicable.

• method (str) – which estimate to use: ‘diag’: provides a diagonal matrix, i.e. univariate noise normalizer ‘full’: computes the sample covariance without shrinkage ‘shrinkage_eye’: shrinks the data covariance towards a multiple of the identity. ‘shrinkage_diag’: shrinks the covariance matrix towards the diagonal covariance matrix.

Returns:

sigma_p: precision matrix over channels

Return type:

numpy.ndarray (or list)

rsatoolbox.data.noise.sigmak_from_measurements(dataset, obs_descriptor, cv_descriptor, noise=None)

Estimates sigma_k, the matrix encoding the noise variance/covariance among the k conditions when two conditions are measured in the same partition (e.g., due to shared fMRI noise from the sluggishness of the HRF when two conditions are adjacent in time). If a noise matrix is provided, prewhitening is performed on the data before computing sigma_k (make sure to do this if using Mahalanobis or crossnobis distance). Assumes that sigma_k is constant across partitions, implementing equation 36 from Diedrichsen et al. (2016), “On the distribution of cross-validated Mahalanobis distances.”

Parameters:

• dataset (data.Dataset) – rsatoolbox Dataset object

• obs_descriptor (String) – descriptor defining experimental conditions

• cv_descriptor (String) – descriptor defining crossvalidation folds/partitions

• noise (numpy.ndarray) – dataset.n_channel x dataset.n_channel precision matrix for noise between channels default: identity matrix, i.e. euclidean distance

Returns:

sigma_k: noise covariance matrix over conditions

n_conditions x n_conditions

Return type:

numpy.ndarray