Package mvpa :: Package mappers :: Module array

[hide private]
[frames] | no frames]

# 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