rsatoolbox.rdm.calc module¶
Calculation of RDMs from datasets @author: heiko, benjamin
- rsatoolbox.rdm.calc.calc_rdm(dataset: DatasetBase, method: str = 'euclidean', descriptor: str | None = None, noise: NDArray | None = None, cv_descriptor: str | None = None, prior_lambda: float = 1, prior_weight: float = 0.1, remove_mean: bool = False)[source]¶
calculates an RDM from an input dataset
This should usually be called with the method and the descriptor argument to specify the dissimilarity measure and which observations in the dataset belong to which condition.
- Parameters:
dataset (rsatoolbox.data.dataset.DatasetBase) – The dataset the RDM is computed from
method (String) – a description of the dissimilarity measure (e.g. ‘Euclidean’)
descriptor (String) – obs_descriptor used to define the rows/columns of the RDM
noise (numpy.ndarray) – dataset.n_channel x dataset.n_channel precision matrix used to calculate the RDM used only for Mahalanobis and Crossnobis estimators defaults to an identity matrix, i.e. euclidean distance
remove_mean (bool) – whether the mean of each pattern shall be removed before distance calculation. This has no effect on poisson based and correlation distances.
- Returns:
RDMs object with the one RDM
- Return type:
- rsatoolbox.rdm.calc.calc_rdm_correlation(dataset, descriptor=None)[source]¶
calculates an RDM from an input dataset using correlation distance If multiple instances of the same condition are found in the dataset they are averaged.
- Parameters:
dataset (rsatoolbox.data.DatasetBase) – The dataset the RDM is computed from
descriptor (String) – obs_descriptor used to define the rows/columns of the RDM defaults to one row/column per row in the dataset
- Returns:
RDMs object with the one RDM
- Return type:
- rsatoolbox.rdm.calc.calc_rdm_crossnobis(dataset, descriptor, noise=None, cv_descriptor=None, remove_mean: bool = False)[source]¶
calculates an RDM from an input dataset using Cross-nobis distance This performs leave one out crossvalidation over the cv_descriptor.
As the minimum input provide a dataset and a descriptor-name to define the rows & columns of the RDM. You may pass a noise precision. If you don’t an identity is assumed. Also a cv_descriptor can be passed to define the crossvalidation folds. It is recommended to do this, to assure correct calculations. If you do not, this function infers a split in order of the dataset, which is guaranteed to fail if there are any unbalances.
This function also accepts a list of noise precision matricies. It is then assumed that this is the precision of the mean from the corresponding crossvalidation fold, i.e. if multiple measurements enter a fold, please compute the resulting noise precision in advance!
To assert equal ordering in the folds the dataset is initially sorted according to the descriptor used to define the patterns.
- Parameters:
dataset (rsatoolbox.data.dataset.DatasetBase) – The dataset the RDM is computed from
descriptor (String) – obs_descriptor used to define the rows/columns of the RDM defaults to one row/column per row in the dataset
noise (numpy.ndarray) – dataset.n_channel x dataset.n_channel precision matrix used to calculate the RDM default: identity matrix, i.e. euclidean distance
cv_descriptor (String) – obs_descriptor which determines the cross-validation folds
remove_mean (bool) – whether the mean of each pattern shall be removed before calculating distances.
- Returns:
RDMs object with the one RDM
- Return type:
- rsatoolbox.rdm.calc.calc_rdm_euclidean(dataset: DatasetBase, descriptor: str | None = None, remove_mean: bool = False)[source]¶
- Parameters:
dataset (rsatoolbox.data.DatasetBase) – The dataset the RDM is computed from
descriptor (String) – obs_descriptor used to define the rows/columns of the RDM defaults to one row/column per row in the dataset
remove_mean (bool) – whether the mean of each pattern shall be removed before calculating distances.
- Returns:
RDMs object with the one RDM
- Return type:
- rsatoolbox.rdm.calc.calc_rdm_mahalanobis(dataset, descriptor=None, noise=None, remove_mean: bool = False)[source]¶
calculates an RDM from an input dataset using mahalanobis distance If multiple instances of the same condition are found in the dataset they are averaged.
- Parameters:
dataset (rsatoolbox.data.dataset.DatasetBase) – The dataset the RDM is computed from
descriptor (String) – obs_descriptor used to define the rows/columns of the RDM defaults to one row/column per row in the dataset
noise (numpy.ndarray) – dataset.n_channel x dataset.n_channel precision matrix used to calculate the RDM default: identity matrix, i.e. euclidean distance
remove_mean (bool) – whether the mean of each pattern shall be removed before calculating distances.
- Returns:
RDMs object with the one RDM
- Return type:
- rsatoolbox.rdm.calc.calc_rdm_movie(dataset, method='euclidean', descriptor=None, noise=None, cv_descriptor=None, prior_lambda=1, prior_weight=0.1, time_descriptor='time', bins=None, unbalanced=False)[source]¶
calculates an RDM movie from an input TemporalDataset
- Parameters:
dataset (rsatoolbox.data.dataset.TemporalDataset) – The dataset the RDM is computed from
method (String) – a description of the dissimilarity measure (e.g. ‘Euclidean’)
descriptor (String) – obs_descriptor used to define the rows/columns of the RDM
noise (numpy.ndarray) – dataset.n_channel x dataset.n_channel precision matrix used to calculate the RDM used only for Mahalanobis and Crossnobis estimators defaults to an identity matrix, i.e. euclidean distance
time_descriptor (String) – descriptor key that points to the time dimension in dataset.time_descriptors. Defaults to ‘time’.
bins (array-like) – list of bins, with bins[i] containing the vector of time-points for the i-th bin. Defaults to no binning.
unbalanced (bool) – if set to True use calc_rdm_unbalanced, else and by default use calc_rdm
- Returns:
RDMs object with RDM movie
- Return type:
- rsatoolbox.rdm.calc.calc_rdm_poisson(dataset, descriptor=None, prior_lambda=1, prior_weight=0.1)[source]¶
calculates an RDM from an input dataset using the symmetrized KL-divergence assuming a poisson distribution. If multiple instances of the same condition are found in the dataset they are averaged.
- Parameters:
dataset (rsatoolbox.data.DatasetBase) – The dataset the RDM is computed from
descriptor (String) – obs_descriptor used to define the rows/columns of the RDM defaults to one row/column per row in the dataset
- Returns:
RDMs object with the one RDM
- Return type:
- rsatoolbox.rdm.calc.calc_rdm_poisson_cv(dataset, descriptor=None, prior_lambda=1, prior_weight=0.1, cv_descriptor=None)[source]¶
calculates an RDM from an input dataset using the crossvalidated symmetrized KL-divergence assuming a poisson distribution
To assert equal ordering in the folds the dataset is initially sorted according to the descriptor used to define the patterns.
- Parameters:
dataset (rsatoolbox.data.DatasetBase) – The dataset the RDM is computed from
descriptor (String) – obs_descriptor used to define the rows/columns of the RDM defaults to one row/column per row in the dataset
cv_descriptor (str) – The descriptor that indicates the folds to use for crossvalidation
- Returns:
RDMs object with the one RDM
- Return type: