Home       Trees       Indices       Help   
PyMVPA: Python MultiVariate Pattern Analysis
Package mvpa :: Package mappers :: Module mask :: Class MaskMapper
[hide private]
[frames] | no frames]

Class MaskMapper

source code

Mapper which uses a binary mask to select "Features" 

Constructor information for `MaskMapper` class
______________________________________________

Initialize MaskMapper

        :Parameters:
          mask : array
            an array in the original dataspace and its nonzero elements are
            used to define the features included in the dataset
          metric : Metric
            Corresponding metric for the space. No attempt is made to
            determine whether a certain metric is reasonable for this
            mapper. If `metric` is None -- `DescreteMetric`
            is constructed that assumes an equal (1) spacing of all mask
            elements with a `distance_function` given as a parameter listed
            below.
          distance_function : functor
            Distance function to use as the parameter to
            `DescreteMetric` if `metric` is not specified,
          elementsize : list or scalar
            Determines spacing within `DescreteMetric`. If it is given as a
            scalar, corresponding value is assigned to all dimensions, which
            are found within `mask`

        :Note: parameters `elementsize` and `distance_function` are relevant
               only if `metric` is None
        


Documentation for base classes of `MaskMapper`
===============================================

Documentation for class `MetricMapper`
--------------------------------------

Mapper which has information about the metrics of the dataspace it is
    mapping.
    

Constructor information for `MetricMapper` class
________________________________________________

Cheap initialisation.

        'metric' is a subclass of Metric.
        


Documentation for base classes of `MetricMapper`
=================================================

Documentation for class `Mapper`
--------------------------------

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

    Subclasses should define 'dsshape' and 'nfeatures' properties that point to
    `getInShape` and `getOutSize` respectively. This cannot be
    done in the baseclass as standard Python properties would still point to
    the baseclass methods.
    

Constructor information for `Mapper` class
__________________________________________

Does nothing.

Documentation for class `Metric`
--------------------------------

Abstract class for any finder.

    Classes subclasses from this class show know about structure of
    the data and thus be able to provide information about the
    neighbors.
    At least one of the methods (getNeighbors, getNeighbor) has to be
    overriden in the derived class.
    NOTE: derived #2 from derived class #1 has to override all methods
    which were overrident in class #1
Instance Methods [hide private]
 
__init__(self, mask, metric=None, distance_function=<function cartesianDistance at 0x87b072c>, elementsize=None)
Initialize MaskMapper		 source code
 
__str__(self)
str(x)		 source code
 
__deepcopy__(self, memo=None) source code
 
_initMask(self, mask)
Initialize internal state with mask-derived information		 source code
 
forward(self, data)
Map data from the original dataspace into featurespace.		 source code
 
reverse(self, data)
Reverse map data from featurespace into the original dataspace.		 source code
 
getInShape(self)
InShape is a shape of original mask		 source code
 
getInSize(self)
InShape is a shape of original mask		 source code
 
getOutShape(self)
OutShape is a shape of target dataset		 source code
 
getOutSize(self)
OutSize is a number of non-0 elements in the mask		 source code
 
getMask(self, copy=True)
By default returns a copy of the current mask.		 source code
 
getInId(self, outId)
Returns a features coordinate in the original data space for a given feature id.		 source code
 
getInIds(self)
Returns a 2d array where each row contains the coordinate of the feature with the corresponding id.		 source code
 
getOutId(self, coord)
Translate a feature mask coordinate into a feature ID.		 source code
 
selectOut(self, outIds, sort=False)
Only listed outIds would remain.		 source code
 
discardOut(self, outIds)
Listed outIds would be discarded		 source code
 
getNeighborIn(self, inId, radius=0)
Return the list of coordinates for the neighbors.		 source code
 
getNeighbor(self, outId, radius=0)
Return the list of Ids for the neighbors.		 source code
 
convertOutIds2OutMask(self, outIds)
Returns a boolean mask with all features in outIds selected.		 source code
 
convertOutIds2InMask(self, outIds)
Returns a boolean mask with all features in ouIds selected.		 source code

Inherited from metric.MetricMapper: getMetric, setMetric

Inherited from base.Mapper: __call__, train

Inherited from datasets.metric.Metric: getNeighbors

Inherited from object: __delattr__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__

Class Variables [hide private]
  __doc__ = enhancedDocString('MaskMapper', locals(), MetricMapper)

Inherited from base.Mapper: nfeatures

Properties [hide private]
  dsshape
InShape is a shape of original mask
  mask

Inherited from metric.MetricMapper: metric

Inherited from object: __class__

Method Details [hide private]

__init__(self, mask, metric=None, distance_function=<function cartesianDistance at 0x87b072c>, elementsize=None)
(Constructor)

source code 
Initialize MaskMapper
Parameters:
  • mask (array) - an array in the original dataspace and its nonzero elements are used to define the features included in the dataset
  • metric (Metric) - Corresponding metric for the space. No attempt is made to determine whether a certain metric is reasonable for this mapper. If metric is None -- DescreteMetric is constructed that assumes an equal (1) spacing of all mask elements with a distance_function given as a parameter listed below.
  • distance_function (functor) - Distance function to use as the parameter to DescreteMetric if metric is not specified,
  • elementsize (list or scalar) - Determines spacing within DescreteMetric. If it is given as a scalar, corresponding value is assigned to all dimensions, which are found within mask
Overrides: object.__init__

Note: parameters elementsize and distance_function are relevant only if metric is None

__str__(self)
(Informal representation operator)

source code 
str(x)
Overrides: object.__str__
(inherited documentation)

_initMask(self, mask)

source code 

Initialize internal state with mask-derived information

It is needed to initialize structures for the fast and reverse lookup to don't impose performance hit on any future operation

forward(self, data)

source code 
Map data from the original dataspace into featurespace.
Overrides: base.Mapper.forward

reverse(self, data)

source code 
Reverse map data from featurespace into the original dataspace.
Overrides: base.Mapper.reverse

getInShape(self)

source code 
InShape is a shape of original mask
Overrides: base.Mapper.getInShape

getInSize(self)

source code 
InShape is a shape of original mask
Overrides: base.Mapper.getInSize

getOutShape(self)

source code 
OutShape is a shape of target dataset
Overrides: base.Mapper.getOutShape

getOutSize(self)

source code 
OutSize is a number of non-0 elements in the mask
Overrides: base.Mapper.getOutSize

getMask(self, copy=True)

source code 

By default returns a copy of the current mask.

If 'copy' is set to False a reference to the mask is returned instead. This shared mask must not be modified!

getInId(self, outId)

source code 

Returns a features coordinate in the original data space for a given feature id.

If this method is called with a list of feature ids it returns a 2d-array where the first axis corresponds the dimensions in 'In' dataspace and along the second axis are the coordinates of the features on this dimension (like the output of NumPy.array.nonzero()).

XXX it might become __get_item__ access method

selectOut(self, outIds, sort=False)

source code 

Only listed outIds would remain.

The function used to accept a matrix-mask as the input but now it really has to be a list of IDs

Function assumes that outIds are sorted. If not - please set sort to True. While in __debug__ mode selectOut would check if obtained IDs are sorted and would warn the user if they are not.

If you feel strongly that you need to remap features internally (ie to allow Ids with mixed order) please contact developers of mvpa to discuss your use case.

See tests.test_maskmapper.testSelectOrder for basic testing

Feature/Bug:
  • Negative outIds would not raise exception - just would be treated 'from the tail'

Older comments on 'order' - might be useful in future if reordering gets ressurrected Order will be taken into account -- ie items will be remapped if order was changed... need to check if neighboring still works... no -- it doesn't. For the data without samples .forward can be easily adjusted by using masknonzero instead of plain mask, but for data with samplesI don't see a clean way... see forward() above... there is no testcase for order preservation for DIM+1 case

Overrides: base.Mapper.selectOut

getNeighborIn(self, inId, radius=0)

source code 
Return the list of coordinates for the neighbors. XXX See TODO below: what to return -- list of arrays or list of tuples?

getNeighbor(self, outId, radius=0)

source code 

Return the list of Ids for the neighbors.

Returns a list of outIds

Overrides: datasets.metric.Metric.getNeighbor

convertOutIds2OutMask(self, outIds)

source code 
Returns a boolean mask with all features in outIds selected.
Parameters:
  • outIds, list, or, 1d, array - To be selected features ids in out-space.
Returns:
ndarray: dtype='bool'
All selected features are set to True; False otherwise.

convertOutIds2InMask(self, outIds)

source code 

Returns a boolean mask with all features in ouIds selected.

This method works exactly like Mapper.convertOutIds2OutMask(), but the feature mask is finally (reverse) mapped into in-space.

Parameters:
  • outIds, list, or, 1d, array - To be selected features ids in out-space.
Returns:
ndarray: dtype='bool'
All selected features are set to True; False otherwise.

Property Details [hide private]

dsshape

InShape is a shape of original mask
Get Method:
getInShape(self) - InShape is a shape of original mask

mask

Get Method:
unreachable(self)

   Home       Trees       Indices       Help   
PyMVPA: Python MultiVariate Pattern Analysis
Generated by Epydoc 3.0.1 on Thu Jul 3 13:06:13 2008 http://epydoc.sourceforge.net