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

Attributes

descr

Description of the object if any

Methods

__call__(datasets)	Derive a common feature space from a series of datasets.
reset()
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)]

output_dim : int or None, optional

Output common space dimensionality. If None, datasets are aligned to the features of the ref_ds. Otherwise, dimensionality reduction is performed using SVD and only the top SVs are kept. To get all features in SVD-aligned space, give output_dim>=nfeatures. Constraints: (value must be convertible to type ‘int’, and value must be in range [1, inf]), or value must be None. [Default: None]

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]

nproc : int, optional

Number of processes to use to parallelize the last step of alignment. If different from 1, it passes it as n_jobs to joblib.Parallel. Requires joblib package. Constraints: value must be convertible to type ‘int’. [Default: 1]

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 mean_xy at 0x7fdcf1dda578>]

level1_equal_weight : bool, optional

Flag to force all datasets to have the same weight in the level 1 iteration. False (default) means each time the new common space is the average of the current common space and the newly aligned dataset, and therefore earlier datasets have less weight. Constraints: value must be convertible to type bool. [Default: False]

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 mean_axis0 at 0x7fdcf1dda758>]

joblib_backend : {multiprocessing, threading} or None, optional

Backend to use for joblib when using nproc>1. Options are ‘multiprocessing’ and ‘threading’. Default is to use ‘multiprocessing’ unless run on OSX which have known issues with joblib v0.10.3. If it is set to specific value here, then that will be used at the risk of failure. Constraints: value must be one of (‘multiprocessing’, ‘threading’), or value must be None. [Default: None]

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

Attributes

descr

Description of the object if any

Methods

__call__(datasets)	Derive a common feature space from a series of datasets.
reset()
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.