| Multivariate Pattern Analysis in Python

### Navigation

- index
- next |
- previous |
- ExpPsy Project |
- NeuroDebian Project |
- PyMVPA 0.4.x Home |
- PyMVPA Home |
- Documentation »
- Module Reference »

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).

  Note

  This mapper can only embbed mappers that transform data into a 2D (nsamples x nfeatures) representation. For mappers not supporting this transformation, consider wrapping them in a `ChainMapper` with an appropriate post-processing mapper.

  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

### Navigation

- index
- next |
- previous |
- ExpPsy Project |
- NeuroDebian Project |
- PyMVPA 0.4.x Home |
- PyMVPA Home |
- Documentation »
- Module Reference »