Package mvpa :: Package datasets :: Module mapped

[hide private]
[frames] | no frames]

# Source Code for Module mvpa.datasets.mapped

      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  """Mapped dataset"""
     10
     11  __docformat__ = 'restructuredtext'
     12
     13  import mvpa.support.copy as copy
     14
     15  from mvpa.datasets import Dataset
     16  from mvpa.base.dochelpers import enhancedDocString
     17  from mvpa.misc.exceptions import DatasetError
     18
     19 -class MappedDataset(Dataset):
     20      """A `Dataset` which is created by applying a `Mapper` to the data.
     21
     22      Upon contruction `MappedDataset` uses a `Mapper` to transform the
     23      samples from their original into the two-dimensional matrix
     24      representation that is required by the `Dataset` class.
     25
     26      This class enhanced the `Dataset` interface with two additional
     27      methods: `mapForward()` and `mapReverse()`. Both take arbitrary data
     28      arrays (with matching shape) and transform them using the embedded
     29      mapper from the original dataspace into a one- or two-dimensional
     30      representation (for arrays corresponding to the shape of a single or
     31      multiple samples respectively) or vice versa.
     32
     33      Most likely, this class will not be used directly, but rather
     34      indirectly through one of its subclasses (e.g. `MaskedDataset`).
     35      """
     36
     37 -    def __init__(self, samples=None, mapper=None, dsattr=None, **kwargs):
     38          """
     39          If `samples` and `mapper` arguments are not `None` the mapper is
     40          used to forward-map the samples array and the result is passed
     41          to the `Dataset` constructor.
     42
     43          :Parameters:
     44            mapper: Instance of `Mapper`
     45              This mapper will be embedded in the dataset and is used and
     46              updated, by all subsequent mapping or feature selection
     47              procedures.
     48            **kwargs:
     49              All other arguments are simply passed to and handled by
     50              the constructor of `Dataset`.
     51          """
     52          # there are basically two mode for the constructor:
     53          # 1. internal mode - only data and dsattr dict
     54          # 2. user mode - samples != None # and mapper != None
     55
     56          # see if dsattr is none, if so, set to empty dict
     57          if dsattr is None:
     58              dsattr = {}
     59
     60          # if a mapper was passed, store it in dsattr dict that gets passed
     61          # to base Dataset
     62          if not mapper is None:
     63              # TODO: check mapper for compliance with dimensionality within _data
     64              #       may be only within __debug__
     65              dsattr['mapper'] = mapper
     66
     67          # if the samples are passed to the special arg, use the mapper to
     68          # transform them.
     69          if not samples is None:
     70              if not dsattr.has_key('mapper') or dsattr['mapper'] is None:
     71                  raise DatasetError, \
     72                        "Constructor of MappedDataset requires a mapper " \
     73                        "if unmapped samples are provided."
     74              Dataset.__init__(self,
     75                               samples=mapper.forward(samples),
     76                               dsattr=dsattr,
     77                               **(kwargs))
     78          else:
     79              Dataset._checkCopyConstructorArgs(samples=samples,
     80                                                dsattr=dsattr,
     81                                                **kwargs)
     82              Dataset.__init__(self, dsattr=dsattr, **(kwargs))
     83
     84
     85      __doc__ = enhancedDocString('MappedDataset', locals(), Dataset)
     86
     87
     88 -    def mapForward(self, data):
     89          """Map data from the original dataspace into featurespace.
     90          """
     91          return self.mapper.forward(data)
     92
     93
     94 -    def mapReverse(self, data):
     95          """Reverse map data from featurespace into the original dataspace.
     96          """
     97          return self.mapper.reverse(data)
     98
     99
    100 -    def mapSelfReverse(self):
    101          """Reverse samples from featurespace into the original dataspace.
    102          """
    103          return self.mapper.reverse(self.samples)
    104
    105 -    def selectFeatures(self, ids, plain=False, sort=False):
    106          """Select features given their ids.
    107
    108          The methods behaves similar to Dataset.selectFeatures(), but
    109          additionally takes care of adjusting the embedded mapper
    110          appropriately.
    111
    112          :Parameters:
    113            ids: sequence
    114              Iterable container to select ids
    115            plain: boolean
    116              Flag whether to return MappedDataset (or just Dataset)
    117            sort: boolean
    118              Flag whether to sort Ids. Order matters and selectFeatures
    119              assumes incremental order. If not such, in non-optimized
    120              code selectFeatures would verify the order and sort
    121          """
    122
    123          # call base method to get selected feature subset
    124          if plain:
    125              sdata = Dataset(self._data, self._dsattr, check_data=False,
    126                              copy_samples=False, copy_data=False,
    127                              copy_dsattr=False)
    128              return sdata.selectFeatures(ids=ids, sort=sort)
    129          else:
    130              sdata = Dataset.selectFeatures(self, ids=ids, sort=sort)
    131              # since we have new DataSet we better have a new mapper
    132              sdata._dsattr['mapper'] = copy.deepcopy(sdata._dsattr['mapper'])
    133              if sort:
    134                  sdata._dsattr['mapper'].selectOut(sorted(ids))
    135              else:
    136                  sdata._dsattr['mapper'].selectOut(ids)
    137              return sdata
    138
    139
    140      # read-only class properties
    141      mapper = property(fget=lambda self: self._dsattr['mapper'])
    142      samples_original = property(fget=mapSelfReverse,
    143                                  doc="Return samples in the original shape")
    144
    145      # syntactic sugarings
    146      O = property(fget=mapSelfReverse,
    147                   doc="Return samples in the original shape")
    148