Package mvpa :: Package mappers :: Module mask
[hide private]
[frames] | no frames]

Source Code for Module mvpa.mappers.mask

  1  #emacs: -*- mode: python-mode; py-indent-offset: 4; indent-tabs-mode: nil -*- 
  2  #ex: set 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 which applies mask to the data""" 
 10   
 11  __docformat__ = 'restructuredtext' 
 12   
 13  import numpy as N 
 14   
 15  from mvpa.mappers.base import Mapper 
 16  from mvpa.base.dochelpers import enhancedDocString 
 17  from mvpa.misc.support import isInVolume 
 18   
 19  if __debug__: 
 20      from mvpa.base import debug, warning 
 21      from mvpa.misc.support import isSorted 
 22   
 23   
24 -class MaskMapper(Mapper):
25 """Mapper which uses a binary mask to select "Features" """ 26
27 - def __init__(self, mask, **kwargs):
28 """Initialize MaskMapper 29 30 :Parameters: 31 mask : array 32 an array in the original dataspace and its nonzero elements are 33 used to define the features included in the dataset 34 """ 35 Mapper.__init__(self, **kwargs) 36 37 self.__mask = self.__maskdim = self.__masksize = \ 38 self.__masknonzerosize = self.__forwardmap = \ 39 self.__masknonzero = None # to make pylint happy 40 self._initMask(mask)
41 42 43 __doc__ = enhancedDocString('MaskMapper', locals(), Mapper) 44 45
46 - def __str__(self):
47 return "MaskMapper: %d -> %d" \ 48 % (self.__masksize, self.__masknonzerosize)
49
50 - def __repr__(self):
51 s = super(MaskMapper, self).__repr__() 52 return s.replace("(", "(mask=%s," % self.__mask, 1)
53 54 # XXX 55 # XXX HAS TO TAKE CARE OF SUBCLASSES!!! 56 # XXX 57 # 58 # def __deepcopy__(self, memo=None): 59 # # XXX memo does not seem to be used 60 # if memo is None: 61 # memo = {} 62 # from mvpa.misc.copy import deepcopy 63 # out = MaskMapper.__new__(MaskMapper) 64 # Mapper.__init__(out) 65 # out.__mask = self.__mask.copy() 66 # out.__maskdim = self.__maskdim 67 # out.__masksize = self.__masksize 68 # out.__masknonzero = deepcopy(self.__masknonzero) 69 # out.__masknonzerosize = self.__masknonzerosize 70 # out.__forwardmap = self.__forwardmap.copy() 71 # 72 # return out 73 74
75 - def _initMask(self, mask):
76 """Initialize internal state with mask-derived information 77 78 It is needed to initialize structures for the fast 79 and reverse lookup to don't impose performance hit on any 80 future operation 81 """ 82 # NOTE: If any new class member are added here __deepcopy__() has to 83 # be adjusted accordingly! 84 85 self.__mask = (mask != 0) 86 self.__maskdim = len(mask.shape) 87 self.__masksize = N.prod(mask.shape) 88 89 # Following introduces space penalty but are needed 90 # for efficient processing. 91 # Store all coordinates for backward mapping 92 self.__masknonzero = mask.nonzero() 93 self.__masknonzerosize = len(self.__masknonzero[0]) 94 #from IPython.Shell import IPShellEmbed 95 #ipshell = IPShellEmbed() 96 #ipshell() 97 #import pydb; pydb.debugger() 98 # Store forward mapping (ie from coord into outId) 99 # TODO to save space might take appropriate int type 100 # depending on masknonzerosize 101 # it could be done with a dictionary, but since mask 102 # might be relatively big, it is better to simply use 103 # a chunk of RAM ;-) 104 self.__forwardmap = N.zeros(mask.shape, dtype=N.int64) 105 # under assumption that we +1 values in forwardmap so that 106 # 0 can be used to signal outside of mask 107 108 self.__forwardmap[self.__masknonzero] = \ 109 N.arange(self.__masknonzerosize)
110 111
112 - def forward(self, data):
113 """Map data from the original dataspace into featurespace. 114 """ 115 data = N.asanyarray(data) # assure it is an array 116 datadim = len(data.shape) 117 datashape = data.shape[(-1)*self.__maskdim:] 118 if not datashape == self.__mask.shape: 119 raise ValueError, \ 120 "The shape of data to be mapped %s " % `datashape` \ 121 + " does not match the mapper's mask shape %s" \ 122 % `self.__mask.shape` 123 124 if self.__maskdim == datadim: 125 # we had to select by __masknonzero if we didn't sort 126 # Ids and wanted to preserve the order 127 #return data[ self.__masknonzero ] 128 return data[ self.__mask ] 129 elif self.__maskdim+1 == datadim: 130 # XXX XXX XXX below line should be accomodated also 131 # to make use of self.__masknonzero instead of 132 # plain mask if we want to preserve the (re)order 133 return data[ :, self.__mask ] 134 else: 135 raise ValueError, \ 136 "Shape of the to be mapped data, does not match the " \ 137 "mapper mask. Only one (optional) additional dimension " \ 138 "exceeding the mask shape is supported."
139 140
141 - def reverse(self, data):
142 """Reverse map data from featurespace into the original dataspace. 143 """ 144 data = N.asanyarray(data) 145 datadim = len(data.shape) 146 if not datadim in [1, 2]: 147 raise ValueError, \ 148 "Only 2d or 1d data can be reverse mapped. "\ 149 "Got data of shape %s" % (data.shape,) 150 151 if datadim == 1: 152 # Verify that we are trying to reverse data of proper dimension. 153 # In 1D case numpy would not complain and will broadcast 154 # the values 155 if __debug__ and self.nfeatures != len(data): 156 raise ValueError, \ 157 "Cannot reverse map data with %d elements, whenever " \ 158 "mask knows only %d" % (len(data), self.nfeatures) 159 mapped = N.zeros(self.__mask.shape, dtype=data.dtype) 160 mapped[self.__mask] = data 161 elif datadim == 2: 162 mapped = N.zeros(data.shape[:1] + self.__mask.shape, 163 dtype=data.dtype) 164 mapped[:, self.__mask] = data 165 166 return mapped
167 168
169 - def getInSize(self):
170 """InShape is a shape of original mask""" 171 return self.__masksize
172 173
174 - def getOutSize(self):
175 """OutSize is a number of non-0 elements in the mask""" 176 return self.__masknonzerosize
177 178
179 - def getMask(self, copy = True):
180 """By default returns a copy of the current mask. 181 182 If 'copy' is set to False a reference to the mask is returned instead. 183 This shared mask must not be modified! 184 """ 185 if copy: 186 return self.__mask.copy() 187 else: 188 return self.__mask
189 190
191 - def getInId(self, outId):
192 """Returns a features coordinate in the original data space 193 for a given feature id. 194 195 If this method is called with a list of feature ids it returns a 196 2d-array where the first axis corresponds the dimensions in 'In' 197 dataspace and along the second axis are the coordinates of the features 198 on this dimension (like the output of NumPy.array.nonzero()). 199 200 XXX it might become __get_item__ access method 201 202 """ 203 # XXX Might be improved by storing also transpose of 204 # __masknonzero 205 return N.array([self.__masknonzero[i][outId] 206 for i in xrange(self.__maskdim)])
207 208
209 - def getInIds(self):
210 """Returns a 2d array where each row contains the coordinate of the 211 feature with the corresponding id. 212 """ 213 return N.transpose(self.__masknonzero)
214 215
216 - def isValidInId(self, inId):
217 mask = self.mask 218 return (isInVolume(inId, mask.shape) and mask[tuple(inId)] != 0)
219 220
221 - def getOutId(self, coord):
222 """Translate a feature mask coordinate into a feature ID. 223 """ 224 # FIXME Since lists/arrays accept negative indexes to go from 225 # the end -- we need to check coordinates explicitely. Otherwise 226 # we would get warping effect 227 try: 228 tcoord = tuple(coord) 229 if self.__mask[tcoord] == 0: 230 raise ValueError, \ 231 "The point %s didn't belong to the mask" % (`coord`) 232 return self.__forwardmap[tcoord] 233 except TypeError: 234 raise ValueError, \ 235 "Coordinates %s are of incorrect dimension. " % `coord` + \ 236 "The mask has %d dimensions." % self.__maskdim 237 except IndexError: 238 raise ValueError, \ 239 "Coordinates %s are out of mask boundary. " % `coord` + \ 240 "The mask is of %s shape." % `self.__mask.shape`
241 242
243 - def selectOut(self, outIds):
244 """Only listed outIds would remain. 245 246 *Function assumes that outIds are sorted*. In __debug__ mode selectOut 247 would check if obtained IDs are sorted and would warn the user if they 248 are not. 249 250 .. note:: 251 If you feel strongly that you need to remap features 252 internally (ie to allow Ids with mixed order) please contact 253 developers of mvpa to discuss your use case. 254 255 The function used to accept a matrix-mask as the input but now 256 it really has to be a list of IDs 257 258 Feature/Bug: 259 * Negative outIds would not raise exception - just would be 260 treated 'from the tail' 261 """ 262 if __debug__ and 'CHECK_SORTEDIDS' in debug.active: 263 # per short conversation with Michael -- we should not 264 # allow reordering since we saw no viable use case for 265 # it. Thus -- warn user is outIds are not in sorted order 266 # and no sorting was requested may be due to performance 267 # considerations 268 if not isSorted(outIds): 269 warning("IDs for selectOut must be provided " + 270 "in sorted order, otherwise .forward() would fail"+ 271 " on the data with multiple samples") 272 273 # adjust mask and forwardmap 274 discarded = N.array([ True ] * self.nfeatures) 275 discarded[outIds] = False # create a map of discarded Ids 276 discardedin = tuple(self.getInId(discarded)) 277 self.__mask[discardedin] = False 278 279 self.__masknonzerosize = len(outIds) 280 self.__masknonzero = [ x[outIds] for x in self.__masknonzero ] 281 282 # adjust/remap not discarded in forwardmap 283 # since we merged _tent/maskmapper-init-noloop it is not necessary 284 # to zero-out discarded entries since we anyway would check with mask 285 # in getOutId(s) 286 self.__forwardmap[self.__masknonzero] = \ 287 N.arange(self.__masknonzerosize)
288 289
290 - def discardOut(self, outIds):
291 """Listed outIds would be discarded 292 293 """ 294 295 # adjust mask and forwardmap 296 discardedin = tuple(self.getInId(outIds)) 297 self.__mask[discardedin] = False 298 # since we merged _tent/maskmapper-init-noloop it is not necessary 299 # to zero-out discarded entries since we anyway would check with mask 300 # in getOutId(s) 301 # self.__forwardmap[discardedin] = 0 302 303 self.__masknonzerosize -= len(outIds) 304 self.__masknonzero = [ N.delete(x, outIds) 305 for x in self.__masknonzero ] 306 307 # adjust/remap not discarded in forwardmap 308 self.__forwardmap[self.__masknonzero] = \ 309 N.arange(self.__masknonzerosize)
310 311 # OPT: we can adjust __forwardmap only for ids which are higher than 312 # the smallest outId among discarded. Similar strategy could be done 313 # for selectOut but such index has to be figured out first there 314 # .... 315 316 317 # comment out for now... introduce when needed 318 # def getInEmpty(self): 319 # """Returns empty instance of input object""" 320 # raise NotImplementedError 321 # 322 # 323 # def getOutEmpty(self): 324 # """Returns empty instance of output object""" 325 # raise NotImplementedError 326 327
328 - def convertOutIds2OutMask(self, outIds):
329 """Returns a boolean mask with all features in `outIds` selected. 330 331 :Parameters: 332 outIds: list or 1d array 333 To be selected features ids in out-space. 334 335 :Returns: 336 ndarray: dtype='bool' 337 All selected features are set to True; False otherwise. 338 """ 339 fmask = N.repeat(False, self.nfeatures) 340 fmask[outIds] = True 341 342 return fmask
343 344
345 - def convertOutIds2InMask(self, outIds):
346 """Returns a boolean mask with all features in `ouIds` selected. 347 348 This method works exactly like Mapper.convertOutIds2OutMask(), but the 349 feature mask is finally (reverse) mapped into in-space. 350 351 :Parameters: 352 outIds: list or 1d array 353 To be selected features ids in out-space. 354 355 :Returns: 356 ndarray: dtype='bool' 357 All selected features are set to True; False otherwise. 358 """ 359 return self.reverse(self.convertOutIds2OutMask(outIds))
360 361 362 # Read-only props 363 mask = property(fget=lambda self:self.getMask(False))
364 365 366 # TODO Unify tuple/array conversion of coordinates. tuples are needed 367 # for easy reference, arrays are needed when doing computation on 368 # coordinates: for some reason numpy doesn't handle casting into 369 # array from tuples while performing arithm operations... 370