Operations on RDMs

The rsatoolbox provides various ways to manipulate RDMs objects.

Matrices and Vectors

To access the underlying RDMs in vectorized or matrix form you can use the methods get_vectors and get_matrices. The RDMs are returned as 2D or 3D numpy arrays respectively.

Subset and Split

There are 2x2 methods for extracting parts of the RDMs object: subset, subsample, subset_pattern, and subsample_pattern. All four methods take the name of a descriptor and the values to be selected as input.

subset and subsample select some of the RDMs, subset_pattern and subsample_pattern select some of the patterns/conditions. The subset variant ignores repetitions in the allowed set, the subsample function uses as many repetitions as provided in the set.

For example rdms.subset('index', [0,2,2]) selects only the rdms number 0 and 2 and will thus contain 2 RDMs, while rdms.subsample('index', [0,2,2]) repeats rdm number 2 and thus contains 3 RDMs.

When patterns are repeated in subsample_pattern the resulting RDM will contain entries that correspond to the similarity of a condition to itself. These are set to NaN.

Concatenate

For concatenating RDMs there is a function called rsatoolbox.rdm.concat, which takes a list of RDMs as input and returns a RDMs object containing all RDMs.

Also RDMs objects have a method append, which allows appending a single other RDMs object.

Only RDMs objects with an equal number of conditions can be concatenated.

Missing data

If you have several RDMs, but they don’t all cover all conditions, you may want to expand them into larger RDMs with missing values, so that you can compare them or perform other operations on them that require them to have the same dimensions. This can be achieved with the from_partials() function:

from numpy import array
from rsatoolbox.rdm.rdms import RDMs
from rsatoolbox.rdm.combine import from_partials
rdms1 = RDMs(
    array(1, 2, 3),
    pattern_descriptors={'conds': ['a', 'b', 'c']}
)
rdms2 = RDMs(
    array(6, 7, 8),
    pattern_descriptors={'conds': ['b', 'c', 'd']}
)
partial_rdms = from_partials([rdms1, rdms2])
partial_rdms.n_conds  ## this is now 4

Sort and reorder

To change the order of conditions/patterns in the RDMs object there are two functions reorder and sort_by.

reorder expects a new order of conditions/patterns, e.g. rdms.reorder([1,2,0]) will change the order of conditions, moving the first condition to the end.

sort_by sorts conditions according to a descriptor, e.g. rdms.sort_by(condition='alpha') sorts the conditions according to the ‘condition’ descriptor alphanumerically.

Caution: Both reorder and sort_by operate in place, i.e. the RDMs object rdms is changed by calling them!

Transformations

To transform all RDM entries by a function rsatoolbox offers specific functions for the most common transformations and a general transform function, which takes the function to be applied as input. These functions are available in rsatoolbox.rdm

The specific transformations are: rank_transform, positive_transform, sqrt_transform and minmax_transform. They take only a RDMs object as input and compute a rank transform, set all negative values to 0, compute a square root of each value respectively, or normalize them into a range of 0 to 1.

There are also and two important transformations as part of the Topological RSA framework, geotopological_transform and geodesic_transform. These RDM transformations emphasize both the geometric and topological properties of the representations, in terms of neighborhood information, global structure, as well as graph theoretical measures. For more information regarding the Topological RSA framework, please refer to “The Topology and Geometry of Neural Representations” by Lin, B., & Kriegeskorte, N. (2023, arXiv:2309.11028).

For example:

rdms_rank = rsatoolbox.rdm.rank_transform(rdms)

will produce a rank transformed version of the data in rdms

The general rsatoolbox.rdm.transform function takes a function to be applied as an input and can thus implement any transform on the RDM.

To compute the square of each RDM entry you could use the following code for example:

def square(x):
    return x ** 2
rdms_square = rsatoolbox.rdm.transform(rdms, square)

The function you pass must take a 2D numpy array of vectorized RDMs as input and return an array of equal shape.