rsatoolbox.rdm.rdms module

Definition of RSA RDMs class and subclasses

@author: baihan

class rsatoolbox.rdm.rdms.RDMs(dissimilarities, dissimilarity_measure=None, descriptors=None, rdm_descriptors=None, pattern_descriptors=None)[source]

Bases: object

RDMs class

Parameters:
  • dissimilarities (numpy.ndarray) – either a 2d np-array (n_rdm x vectorform of dissimilarities) or a 3d np-array (n_rdm x n_cond x n_cond)

  • dissimilarity_measure (String) – a description of the dissimilarity measure (e.g. ‘Euclidean’)

  • descriptors (dict) – descriptors with 1 value per RDMs object

  • rdm_descriptors (dict) – descriptors with 1 value per RDM

  • pattern_descriptors (dict) – descriptors with 1 value per RDM column

Variables:
  • n_rdm (int) – number of rdms

  • n_cond (int) – number of patterns

append(rdm)[source]

appends an rdm to the object The rdm should have the same shape and type as this object. Its pattern_descriptor and descriptor are ignored

Parameters:

rdm (rsatoolbox.rdm.RDMs) – the rdm to append

Returns:

copy() RDMs[source]

Return a copy of this object, with all properties equal to the original’s

Returns:

Value copy

Return type:

RDMs

descriptors: Dict
dissimilarities: ndarray
dissimilarity_measure: str | None
get_matrices()[source]

Returns RDMs as np.ndarray with each RDM as a matrix

Returns:

RDMs as a 3-Tensor with one matrix per RDM

Return type:

numpy.ndarray

get_vectors()[source]

Returns RDMs as np.ndarray with each RDM as a vector

Returns:

RDMs as a matrix with one row per RDM

Return type:

numpy.ndarray

mean(weights=None)[source]

Average rdm of all rdms contained

Parameters:

weights (str or ndarray, optional) – One of: None: No weighting applied str: Use the weights contained in the rdm_descriptor with this name ndarray: Weights array of the shape of RDMs.dissimilarities

Returns:

New RDMs object with one vector

Return type:

rsatoolbox.rdm.rdms.RDMs

pattern_descriptors: Dict
rdm_descriptors: Dict
reorder(new_order)[source]

Reorder the patterns according to the index in new_order

Parameters:

new_order (numpy.ndarray) – new order of patterns, vector of length equal to the number of patterns

save(filename, file_type='hdf5', overwrite=False)[source]

saves the RDMs object into a file

Parameters:
  • filename (String) – path to file to save to [or opened file]

  • file_type (String) – Type of file to create: hdf5: hdf5 file pkl: pickle file

  • overwrite (Boolean) – overwrites file if it already exists

sort_by(reindex: bool = True, **kwargs)[source]

Reorder the patterns by sorting a descriptor

Parameters:

reindex (bool) – whether to reset the ‘index’ descriptor following sorting

Pass keyword arguments that correspond to descriptors, with value indicating the sort type. Supported methods:

‘alpha’: sort alphabetically (using np.sort)

list/np.array: specify the new order explicitly. Values should

correspond to the descriptor values

Examples

The following code sorts the ‘condition’ descriptor alphabetically:

rdms.sort_by(condition='alpha')

The following code sort the ‘condition’ descriptor in the order 1, 3, 2, 4, 5:

rdms.sort_by(condition=[1, 3, 2, 4, 5])
Raises:

ValueError – Raised if the method chosen is not implemented

subsample(by, value)[source]

Returns a subsampled RDMs with repetitions if values are repeated

Parameters:
  • by (String) – the descriptor by which the subset selection is made from descriptors

  • value – the value by which the subset selection is made from descriptors

Returns:

RDMs object, with subsampled RDMs

subsample_pattern(by, value)[source]

Returns a subsampled RDMs with repetitions if values are repeated

This function now generates Nans where the off-diagonal 0s would appear. These values are trivial to predict for models and thus need to be marked and excluded from the evaluation.

Parameters:
  • by (String) – the descriptor by which the subset selection is made from descriptors

  • value – the value(s) by which the subset selection is made from descriptors

Returns:

RDMs object, with subsampled patterns

subset(by, value)[source]

Returns a set of fewer RDMs matching descriptor values

Parameters:
  • by (String) – the descriptor by which the subset selection is made from descriptors

  • value – the value by which the subset selection is made from descriptors

Returns:

RDMs object, with fewer RDMs

subset_pattern(by, value)[source]

Returns a smaller RDMs with patterns with certain descriptor values

Parameters:
  • by (String) – the descriptor by which the subset selection is made from pattern_descriptors

  • value – the value by which the subset selection is made from pattern_descriptors

Returns:

RDMs object, with fewer patterns

to_df()[source]

Return a new long-form pandas DataFrame representing this RDM

See rsatoolbox.io.pandas.rdms_to_df for details

Returns:

The DataFrame for this RDMs object

Return type:

pandas.DataFrame

to_dict()[source]

converts the object into a dictionary, which can be saved to disk

Returns:

dictionary containing all information required to

recreate the RDMs object

Return type:

rdm_dict(dict)

rsatoolbox.rdm.rdms.concat(*rdms)[source]

concatenates rdm objects requires that the rdms have the same shape descriptor and pattern descriptors are taken from the first rdms object for rdm_descriptors concatenation is tried the rdm index is reinitialized

Parameters:
  • rdms (iterable of pyrsa.rdm.RDMs) – RDMs objects to be concatenated

  • arguments (or multiple RDMs as separate) –

Returns:

concatenated rdms object

Return type:

rsatoolbox.rdm.RDMs

rsatoolbox.rdm.rdms.get_categorical_rdm(category_vector, category_name='category')[source]

generates an RDM object containing a categorical RDM, i.e. RDM = 0 if the category is the same and 1 if they are different

Parameters:
  • category_vector (iterable) – a category index per condition

  • category_name (String) – name for the descriptor in the object, defaults to ‘category’

Returns:

constructed RDM

Return type:

rsatoolbox.rdm.RDMs

rsatoolbox.rdm.rdms.inverse_permute_rdms(rdms)[source]

Gimmick function to reverse the effect of permute_rdms()

rsatoolbox.rdm.rdms.load_rdm(filename, file_type=None)[source]

loads a RDMs object from disk

Parameters:

filename (String) – path to file to load

rsatoolbox.rdm.rdms.permute_rdms(rdms, p=None)[source]

Permute rows, columns and corresponding pattern descriptors of RDM matrices according to a permutation vector

Parameters:

p (numpy.ndarray) – permutation vector (values must be unique integers from 0 to n_cond of RDM matrix). If p = None, a random permutation vector is created.

Returns:

the rdm object with a permuted matrix

and pattern descriptors

Return type:

rdm_p(rsatoolbox.rdm.RDMs)

rsatoolbox.rdm.rdms.rdms_from_dict(rdm_dict)[source]

creates a RDMs object from a dictionary

Parameters:

rdm_dict (dict) – dictionary with information

Returns:

the regenerated RDMs object

Return type:

rdms(RDMs)