This content refers to the previous stable release of PyMVPA. Please visit www.pymvpa.org for the most recent version of PyMVPA and its documentation.

mappers.base

Module: mappers.base

Inheritance diagram for mvpa.mappers.base:

Data mapper

Classes

ChainMapper

class mvpa.mappers.base.ChainMapper(mappers, **kwargs)

Bases: mvpa.mappers.base.Mapper

Meta mapper that embedded a chain of other mappers.

Each mapper in the chain is called successively to perform forward or reverse mapping.

Note

In its current implementation the ChainMapper treats all but the last mapper as simple pre-processing (in forward()) or post-processing (in reverse()) steps. All other capabilities, e.g. training and neighbor metrics are provided by or affect only the last mapper in the chain.

With respect to neighbor metrics this means that they are determined based on the input space of the last mapper in the chain and not on the input dataspace of the ChainMapper as a whole

Parameters:

• mappers (list of Mapper instances) –
• **kwargs – All additional arguments are passed to the base-class constructor.

forward(data)

Calls all mappers in the chain successively.

Parameters:data – data to be chain-mapped.

getInSize()

Returns the size of the entity in input space

getNeighbor(outId, *args, **kwargs)

Get the ids of the neighbors of a single feature in output dataspace.

Note

The neighbors are determined based on the input space of the last mapper in the chain and not on the input dataspace of the ChainMapper as a whole!

Parameters:

• outId (int) – Single id of a feature in output space, whos neighbors should be determined.
• **kwargs (*args,) – Additional arguments are passed to the metric of the embedded mapper, that is responsible for the corresponding feature.

Returns a list of outIds

getOutSize()

Returns the size of the entity in output space

reverse(data)

Calls all mappers in the chain successively, in reversed order.

Parameters:data (array) – data array to be reverse mapped into the orginal dataspace.

selectOut(outIds)

Remove some elements from the last mapper in the chain.

Parameters:outIds (sequence) – All output feature ids to be selected/kept.

train(dataset)

Trains the last mapper in the chain.

Parameters:dataset (Dataset or subclass) – A dataset with the number of features matching the outSize of the last mapper in the chain (which is identical to the one of the ChainMapper itself).

CombinedMapper

class mvpa.mappers.base.CombinedMapper(mappers, **kwargs)

Bases: mvpa.mappers.base.Mapper

Meta mapper that combines several embedded mappers.

This mapper can be used the map from several input dataspaces into a common output dataspace. When forward() is called with a sequence of data, each element in that sequence is passed to the corresponding mapper, which in turned forward-maps the data. The output of all mappers is finally stacked (horizontally or column or feature-wise) into a single large 2D matrix (nsamples x nfeatures).

CombinedMapper fully supports forward and backward mapping, training, runtime selection of a feature subset (in output dataspace) and retrieval of neighborhood information.

Parameters:

• mappers (list of Mapper instances) – The order of the mappers in the list is important, as it will define the order in which data snippets have to be passed to forward().
• **kwargs – All additional arguments are passed to the base-class constructor.

forward(data)

Map data from the IN spaces into to common OUT space.

Parameters:data (sequence) – Each element in the data sequence is passed to the corresponding embedded mapper and is mapped individually by it. The number of elements in data has to match the number of embedded mappers. Each element is data has to provide the same number of samples (first dimension). Return type:array Returns:Horizontally stacked array of all embedded mapper outputs.

getInSize()

Returns the size of the entity in input space

getNeighbor(outId, *args, **kwargs)

Get the ids of the neighbors of a single feature in output dataspace.

Parameters:

• outId (int) – Single id of a feature in output space, whos neighbors should be determined.
• **kwargs (*args,) – Additional arguments are passed to the metric of the embedded mapper, that is responsible for the corresponding feature.

Returns a list of outIds

getOutSize()

Returns the size of the entity in output space

reverse(data)

Reverse map data from OUT space into the IN spaces.

Parameters:data (array) – Single data array to be reverse mapped into a sequence of data snippets in their individual IN spaces. Return type:list

selectOut(outIds)

Remove some elements and leave only ids in ‘out’/feature space.

Note

The subset selection is done inplace

Parameters:outIds (sequence) – All output feature ids to be selected/kept.

train(dataset)

Trains all embedded mappers.

The provided training dataset is splitted appropriately and the corresponding pieces are passed to the train() method of each embedded mapper.

Parameters:dataset (Dataset or subclass) – A dataset with the number of features matching the outSize of the CombinedMapper.

Mapper

class mvpa.mappers.base.Mapper(metric=None)

Bases: object

Interface to provide mapping between two spaces: IN and OUT. Methods are prefixed correspondingly. forward/reverse operate on the entire dataset. get(In|Out)Id[s] operate per element:

     forward
    --------->
IN              OUT
    <--------/
      reverse

Parameters:metric (Metric) – Optional metric

forward(data)

Map data from the IN dataspace into OUT space.

getInId(outId)

Translate a feature id into a coordinate/index in input space.

Such a translation might not be meaningful or even possible for a particular mapping algorithm and therefore cannot be relied upon.

getInSize()

Returns the size of the entity in input space

getMetric()

To make pylint happy

getNeighbor(outId, *args, **kwargs)

Get feature neighbors in input space, given an id in output space.

This method has to be reimplemented whenever a derived class does not provide an implementation for getInId().

getNeighborIn(inId, *args, **kwargs)

Return the list of coordinates for the neighbors.

Parameters:

• inId – id (index) of an element in input dataspace.
• **kwargs (*args,) – Any additional arguments are passed to the embedded metric of the mapper.

XXX See TODO below: what to return – list of arrays or list of tuples?

getNeighbors(outId, *args, **kwargs)

Return the list of coordinates for the neighbors.

By default it simply constructs the list based on the generator returned by getNeighbor()

getOutSize()

Returns the size of the entity in output space

isValidInId(inId)

Validate id in IN space.

Override if IN space is not simly a 1D vector

isValidOutId(outId)

Validate feature id in OUT space.

Override if OUT space is not simly a 1D vector

metric

To make pylint happy

nfeatures = 'property'

reverse(data)

Reverse map data from OUT space into the IN space.

selectOut(outIds)

Limit the OUT space to a certain set of features.

Parameters:outIds (sequence) – Subset of ids of the current feature in OUT space to keep.

setMetric(metric)

To make pylint happy

train(dataset)

Perform training of the mapper.

This method is called to put the mapper in a state that allows it to perform to intended mapping.

Parameters:dataset (Dataset or subclass) –

Note

The default behavior of this method is to do nothing.

ProjectionMapper

class mvpa.mappers.base.ProjectionMapper(selector=None, demean=True)

Bases: mvpa.mappers.base.Mapper

Linear mapping between multidimensional spaces.

This class cannot be used directly. Sub-classes have to implement the _train() method, which has to compute the projection matrix _proj and optionally offset vectors _offset_in and _offset_out (if initialized with demean=True, which is default) given a dataset (see _train() docstring for more information).

Once the projection matrix is available, this class provides functionality to perform forward and backwards linear mapping of data, the latter by default using pseudo-inverse (but could be altered in subclasses, like hermitian (conjugate) transpose in case of SVD). Additionally, ProjectionMapper supports optional selection of arbitrary component (i.e. columns of the projection matrix) of the projection.

Forward and back-projection matrices (a.k.a. projection and reconstruction) are available via the proj and recon properties.

See also

Please refer to the documentation of the base class for more information:

Mapper

Initialize the ProjectionMapper

Parameters:

• selector (None | list) – Which components (i.e. columns of the projection matrix) should be used for mapping. If selector is None all components are used. If a list is provided, all list elements are treated as component ids and the respective components are selected (all others are discarded).
• demean (bool) – Either data should be demeaned while computing projections and applied back while doing reverse()

forward(data, demean=None)

Perform forward projection.

Parameters:

• data (ndarray) – Data array to map
• demean (boolean | None) – Override demean setting for this method call.

Return type:

NumPy array

getInSize()

Returns the number of original features.

getOutSize()

Returns the number of components to project on.

proj

Projection matrix

recon

Backprojection matrix

reverse(data)

Reproject (reconstruct) data into the original feature space.

Return type:NumPy array

selectOut(outIds)

Choose a subset of components (and remove all others).

train(dataset, *args, **kwargs)

Determine the projection matrix.

Parameters:

• dataset (Dataset) – Dataset to operate on
• *args – Optional positional arguments to pass to _train of subclass
• **kwargs – Optional keyword arguments to pass to _train of subclass