Integrating Framed RSA into rsatoolbox

[johnmarktaylor91]

Hello, Niko and I are getting close to submitting the Framed RSA paper and planning to integrate it into the toolbox. Starting this issue to consolidate discussion (from email threads and another issue) on how best to go about this.

The basic concept of Framed RSA is adding two "framing patterns" that add information about the global position and orientation of the stimulus patterns (in particular, allowing their mean activation to be linearly recovered from the RDM).

These are the design issues I can think of:

• These "framing patterns" sometimes require different treatment because they involve no noise. They will have to be marked in some way (perhaps as a pattern descriptor)

• One of the framing patterns is the all-zeros, and the other is all-c, with c being some constant value. The all-zeros is easy, but the all-c often involves some tuning: for instance, c is often chosen such that the length of the all-c is some multiple of the mean length of the other vectors. If using Mahalanobis or crossnobis distance, this is often done based on the mean length of the whitened stimulus patterns, such that this tuning requires the voxel-by-voxel covariance matrix. It's not immediately clear to me whether to fold all of this tuning into the rsatoolbox code, or to just add the capacity for marking "frozen" patterns, leaving it up to the user to calculate and provide these patterns.

• Using whitened RDM comparators with Framed RSA requires using an adjusted formula for the V matrix (i.e., covariance between dissimilarity estimates) derived by Heiko (attached)

This matrix requires the whitened mean patterns for each condition, and also knowing which of the patterns are "frozen" patterns. There also a few further toggles when it comes to computing it (e.g., sometimes it's useful to treat distances between the stimulus patterns as zero, but use the estimated distances if they involve the framing patterns).

Here is one potential proposal for doing all this, intended as a starting point:

1. Make 'FramedDataset' and 'FramedRDM' subclasses of the dataset and RDM classes. These would enforce having a descriptor that marks which patterns are "frozen" patterns, and the FramedDataset class would have built-in functionality for automatically tuning and adding the framing patterns, sparing the user the trouble of doing this themselves.

2. Add a dedicated function for computing V (the dissimilarity covariance matrix), with an option for returning either the signal-dependent (Heiko's new formula) or signal-independent (the existing toolbox formula) variants of V.

3. Make V an optional argument in the compare function, replacing sigma_k (which would then be an argument in the new function for computing V). If no V is provided, the default would be to use the current estimate for V in the toolbox, with sigma_k being the identity matrix.

The motivation for #2 and #3 is to avoid bloat in the compare function: since V is only relevant for whitened RDM comparators, it seems desirable not to pack in very many additional arguments that won't be relevant for other comparators. Replacing sigma_k with V as an argument in compare might also be a bit more user-friendly; if a user isn't using whitened comparators it seems a bit easier to understand that V is an irrelevant argument for their purposes than for sigma_k (since sigma_k is only relevant as an ingredient in calculating V).

Sorry for the wall of text, folks should feel free to chime in on whatever parts they have thoughts about. Happy to proceed however works best for everyone.