Source Code for Module mvpa.mappers.array

  1  # emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*- 
  2  # vi: set ft=python sts=4 ts=4 sw=4 et: 
  3  ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ## 
  4  # 
  5  #   See COPYING file distributed along with the PyMVPA package for the 
  6  #   copyright and license terms. 
  7  # 
  8  ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ## 
  9  """Data mapper""" 
 10   
 11  __docformat__ = 'restructuredtext' 
 12   
 13  import numpy as N 
 14  from operator import isSequenceType 
 15   
 16  from mvpa.mappers.mask import MaskMapper 
 17  from mvpa.mappers.metric import DescreteMetric, cartesianDistance 
 18  from mvpa.base.dochelpers import enhancedDocString 
 19   
 20  if __debug__: 
 21      from mvpa.base import warning 
 22      from mvpa.misc.support import isSorted 
 23   
 24   
 25   
 26 -class DenseArrayMapper(MaskMapper): 
 27      """Mapper for equally spaced dense arrays.""" 
 28   
 29      """TODO: yoh thinks we should move that 'metric' assignment into 
 30      MaskMapper, based on the fact if distance_function is given either 
 31      as an argument or may be class variable. That would pretty much 
 32      remove the need for a separate class of DenseArrayMapper and it 
 33      could become just a sugaring helper function which would initiate 
 34      MaskMapper (or some other mapper may be with appropriate 
 35      distance_function and/or mapper 
 36   
 37      Otherwise it is again -- orthogonality -- will we need to device 
 38      NonmaskedArrayMapper which has no mask assigned but might be a 
 39      good cartesian cube on its own or smth like that? 
 40      """ 
 41   
 42 -    def __init__(self, mask=None, metric=None, 
 43                   distance_function=cartesianDistance, 
 44                   elementsize=None, shape=None, **kwargs): 
 45          """Initialize DenseArrayMapper 
 46   
 47          :Parameters: 
 48            mask : array 
 49              an array in the original dataspace and its nonzero elements are 
 50              used to define the features included in the dataset. alternatively, 
 51              the `shape` argument can be used to define the array dimensions. 
 52            metric : Metric 
 53              Corresponding metric for the space. No attempt is made to 
 54              determine whether a certain metric is reasonable for this 
 55              mapper. If `metric` is None -- `DescreteMetric` 
 56              is constructed that assumes an equal (1) spacing of all mask 
 57              elements with a `distance_function` given as a parameter listed 
 58              below. 
 59            distance_function : functor 
 60              Distance function to use as the parameter to 
 61              `DescreteMetric` if `metric` is not specified, 
 62            elementsize : list or scalar 
 63              Determines spacing within `DescreteMetric`. If it is given as a 
 64              scalar, corresponding value is assigned to all dimensions, which 
 65              are found within `mask` 
 66            shape: tuple 
 67              The shape of the array to be mapped. If `shape` is provided instead 
 68              of `mask`, a full mask (all True) of the desired shape is 
 69              constructed. If `shape` is specified in addition to `mask`, the 
 70              provided mask is extended to have the same number of dimensions. 
 71   
 72          :Note: parameters `elementsize` and `distance_function` are relevant 
 73                 only if `metric` is None 
 74          """ 
 75          if mask is None: 
 76              if shape is None: 
 77                  raise ValueError, \ 
 78                        "Either `shape` or `mask` have to be specified." 
 79              else: 
 80                  # make full dataspace mask if nothing else is provided 
 81                  mask = N.ones(shape, dtype='bool') 
 82          else: 
 83              if not shape is None: 
 84                  # expand mask to span all dimensions but first one 
 85                  # necessary e.g. if only one slice from timeseries of volumes is 
 86                  # requested. 
 87                  mask = N.array(mask, ndmin=len(shape)) 
 88                  # check for compatibility 
 89                  if not shape == mask.shape: 
 90                      raise ValueError, \ 
 91                          "The mask dataspace shape %s is not " \ 
 92                          "compatible with the provided shape %s." \ 
 93                          % (mask.shape, shape) 
 94   
 95          # configure the baseclass with the processed mask 
 96          MaskMapper.__init__(self, mask, metric=metric, **kwargs) 
 97   
 98          # We must have metric assigned 
 99          if self.metric == None: 
100              if elementsize is None: 
101                  elementsize = [1]*len(mask.shape) 
102              else: 
103                  if isSequenceType(elementsize): 
104                      if len(elementsize) != len(mask.shape): 
105                          raise ValueError, \ 
106                                "Number of elements in elementsize [%d]" % \ 
107                                len(elementsize) + " doesn't match shape " + \ 
108                                "of the mask [%s]" % (`mask.shape`) 
109                  else: 
110                      elementsize = [ elementsize ] * len(mask.shape) 
111              self.metric = DescreteMetric(elementsize=[1]*len(mask.shape), 
112                                           distance_function=distance_function) 
113   
114   
115      __doc__ = enhancedDocString('DenseArrayMapper', locals(), MaskMapper) 
116   
117   
118 -    def __str__(self): 
119          return "DenseArrayMapper: %d -> %d" \ 
120              % (self.getInSize(), self.getOutSize()) 
121