mvpa2.algorithms.hyperalignment.Hyperalignment

class mvpa2.algorithms.hyperalignment.Hyperalignment(**kwargs)

Align the features across multiple datasets into a common feature space.

This is a three-level algorithm. In the first level, a series of input datasets is projected into a common feature space using a configurable mapper. The common space is initially defined by a chosen exemplar from the list of input datasets, but is subsequently refined by iteratively combining the common space with the projected input datasets.

In the second (optional) level, the original input datasets are again aligned with (or projected into) the intermediate first-level common space. Through a configurable number of iterations the common space is further refined by repeated projections of the input datasets and combination/aggregation of these projections into an updated common space.

In the third level, the input datasets are again aligned with the, now final, common feature space. The output of this algorithm are trained mappers (one for each input dataset) that transform the individual features spaces into the common space.

Level 1 and 2 are performed by the train() method, and level 3 is performed when the trained Hyperalignment instance is called with a list of datasets. This dataset list may or may not be identical to the training datasets.

The default values for the parameters of the algorithm (e.g. projection via Procrustean transformation, common space aggregation by averaging) resemble the setup reported in Haxby et al., Neuron (2011) A common, high-dimensional model of the representational space in human ventral temporal cortex.

Notes

Available conditional attributes:

• chosen_ref_ds+: Index of the input dataset used as 1st-level reference dataset.
• residual_errors: Residual error (norm of the difference between common space and projected data) per each dataset. The residuals are stored in a single-row dataset with one column per input dataset.
• training_residual_errors: Residual error (norm of the difference between common space and projected data) per each training dataset at each level. The residuals are stored in a dataset with one row per level, and one column per input dataset. The first row corresponds to the error 1st-level of hyperalignment the remaining rows store the residual errors for each 2nd-level iteration.

(Conditional attributes enabled by default suffixed with +)

Examples

>>> # get some example data
>>> from mvpa2.testing.datasets import datasets
>>> from mvpa2.misc.data_generators import random_affine_transformation
>>> ds4l = datasets['uni4large']
>>> # generate a number of distorted variants of this data
>>> dss = [random_affine_transformation(ds4l) for i in xrange(4)]
>>> ha = Hyperalignment()
>>> ha.train(dss)
>>> mappers = ha(dss)
>>> len(mappers)
4

Methods

train(datasets)

Derive a common feature space from a series of datasets.

Initialize instance of Hyperalignment

Parameters:

alignment :

The multidimensional transformation mapper. If None (default) an instance of ProcrusteanMapper is used. [Default: ProcrusteanMapper(space=’commonspace’, oblique_rcond=-1.0)]

alpha : float, optional

Regularization parameter to traverse between (Shrinkage)-CCA (canonical correlation analysis) and regular hyperalignment. Setting alpha to 1 makes the algorithm identical to hyperalignment and alpha of 0 makes it CCA. By default, it is 1, therefore hyperalignment. Constraints: value must be convertible to type ‘float’, and value must be in range [0, 1]. [Default: 1]

level2_niter : int, optional

Number of 2nd-level iterations. Constraints: value must be convertible to type ‘int’, and value must be in range [0, inf]. [Default: 1]

ref_ds : int or None, optional

Index of a dataset to use as 1st-level common space reference. If None, then the dataset with the maximum number of features is used. Constraints: (value must be in range [0, inf], and value must be convertible to type ‘int’), or value must be None. [Default: None]

zscore_all : bool, optional

Flag to Z-score all datasets prior hyperalignment. Turn it off if Z-scoring is not desired or was already performed. If True, returned mappers are ChainMappers with the Z-scoring prepended to the actual projection. Constraints: value must be convertible to type bool. [Default: False]

zscore_common : bool, optional

Flag to Z-score the common space after each adjustment. This should be left enabled in most cases. Constraints: value must be convertible to type bool. [Default: True]

combiner1 :

How to update common space in the 1st-level loop. This must be a callable that takes two arguments. The first argument is one of the input datasets after projection onto the 1st-level common space. The second argument is the current 1st-level common space. The 1st-level combiner is called iteratively for each projected input dataset, except for the reference dataset. By default the new common space is the average of the current common space and the recently projected dataset. [Default: <function <lambda> at 0x7fb63de7d1b8>]

combiner2 :

How to combine all individual spaces to common space. This must be a callable that take a sequence of datasets as an argument. The callable must return a single array. This combiner is called once with all datasets after 1st-level projection to create an updated common space, and is subsequently called again after each 2nd-level iteration. [Default: <function <lambda> at 0x7fb63de7d230>]

enable_ca : None or list of str

Names of the conditional attributes which should be enabled in addition to the default ones

disable_ca : None or list of str

Names of the conditional attributes which should be disabled

descr : str

Description of the instance

Methods

train(datasets)

Derive a common feature space from a series of datasets.

train(datasets)

Derive a common feature space from a series of datasets.

Parameters:datasets : sequence of datasets Returns:A list of trained Mappers matching the number of input datasets. :