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')[source]

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')[source]

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')[source]

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')[source]

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')[source]

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')[source]

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)