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