Adding FramedDataset class for framed RSA analysis

[johnmarktaylor91]

This pull request adds a FramedDataset class for performing Framed RSA analysis. Together with my earlier pull requests that adds functions for computing sigma_k and V, this provides the remaining functionality needed to do Framed RSA with the toolbox. I note that it uses the sigmak_from_data function from the other pull request, so that one should be evaluated/merged before this one.

Specifically, the FramedDataset class adds the following functionality:

1. Automatically adds the all-zeros and all-c patterns to the dataset. These are given the labels all-z and all-c for the obs_descriptor that the user specifies (which has the variable name cond_descriptor'; I am not attached to this). To make sure that any downstream analyses involving crossvalidation remain kosher, repeats of these patterns are added for every combination of values of the remaining obs_descriptors(such that no matter which of the remaining descriptors might be used for crossvalidation, the user will be covered). An alternative option would be to have the user explicitly provide the cv_descriptor here; I'm open to this too. The all-c pattern is automatically tuned such that its norm is equal to the mean norm of the stimulus patterns times a constant (this scaling constant is a free parameter in framed RSA). If a noise matrix is provided, this scaling is done based on the whitened patterns (i.e., the value ofc` is set such that after whitening, the all-c vector has norm equal to the mean norm of the whitened patterns times a constant); this noise matrix should be the same one used for downstream RSA analysis.
2. The class has a method for returning sigma_k for the dataset, with an option whether or not to estimate this matrix from the data. If so, the sigmak_from_data function is used, and the user must provide a cv_descriptor. If not, sigma_k is assumed to be an identity matrix, with the exception of the entries involving the framed paterns being set to zero (since they have zero variance).
3. The class has a method for returning a binary mask indicating which RDM entries (with conditions defined by cond_descriptor) involve the framed patterns. The rationale for this is that when using framed RSA in conjunction with whitened RDM comparators, it is sometimes useful to incorporate the distances involving the framed patterns into the estimation of V, but not the distances involving only stimulus patterns.

Together, this functionality is sufficient to implement Framed RSA as it currently exists. Possible future changes could include alternative methods for tuning the all-c vector (e.g., based on the mean norm of the projection of the stimulus vectors onto the all-c); I think these could be encompassed with one additional argument to __init__ for the class.

I made the choice to implement these changes via subclassing Dataset. However, an alternative approach would have been to subclass RDM instead, providing a function such as calc_framed_rdm. I'm not sure about the relative tradeoffs of these two options; I went with subclassing Dataset since there's already another Dataset subclass (TemporalDataset) but currently no RDM subclass, and since subclassing RDM wouldn't provide a natural way to calculate sigma_k from the data for FramedRSA (since this requires having the actual augmented dataset). In the event that we want any downstream functionality (e.g. MDS plotting) to change for framed RSA, I did add an is_framed dataset descriptor that should carry over to any downstream RDMs.

Finally, one random thing: currently self.n_obs corresponds to the number of observations for the original stimuli, before the framed entries are added. I don't know if this would be problematic for any downstream functionality.

Happy to provide any other information or testing that would be useful.

[HeikoSchuett]

Generally, this way on including framed RSA seems to be quite benign to me. Thus, if it works, I think we can do it like this.

I think it would be great if you could include a demonstration of framed RSA working as both a demo and a integration test though, so that users can see how these functions are supposed to be used and we can make sure that future changes do not break the ability to run framed RSA.

[johnmarktaylor91]

Sounds good, I'll go ahead and add the demos and tests.

[johnmarktaylor91]

Okay, pushed the unit tests. For the demos, I assume they should follow this format? Looks like interleaving of markdown and jupyter notebook cells, yes?