Source Code for Module mvpa.misc.param

  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  ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##g 
  9  """Parameter representation""" 
 10   
 11  __docformat__ = 'restructuredtext' 
 12   
 13  import re 
 14  import textwrap 
 15  from mvpa.misc.state import CollectableAttribute 
 16   
 17  if __debug__: 
 18      from mvpa.base import debug 
 19   
 20  _whitespace_re = re.compile('\n\s+|^\s+') 
 21   
 22  __all__ = [ 'Parameter', 'KernelParameter' ] 
 23   
 24 -class Parameter(CollectableAttribute): 
 25      """This class shall serve as a representation of a parameter. 
 26   
 27      It might be useful if a little more information than the pure parameter 
 28      value is required (or even only useful). 
 29   
 30      Each parameter must have a value. However additional property can be 
 31      passed to the constructor and will be stored in the object. 
 32   
 33      BIG ASSUMPTION: stored values are not mutable, ie nobody should do 
 34   
 35      cls.parameter1[:] = ... 
 36   
 37      or we wouldn't know that it was changed 
 38   
 39      Here is a list of possible property names: 
 40   
 41          min   - minimum value 
 42          max   - maximum value 
 43          step  - increment/decrement stepsize 
 44      """ 
 45   
 46 -    def __init__(self, default, name=None, doc=None, index=None, **kwargs): 
 47          """Specify a parameter by its default value and optionally an arbitrary 
 48          number of additional parameters. 
 49   
 50          TODO: :Parameters: for Parameter 
 51          """ 
 52          self.__default = default 
 53   
 54          CollectableAttribute.__init__(self, name=name, doc=doc, index=index) 
 55   
 56          self.resetvalue() 
 57          self._isset = False 
 58   
 59          if __debug__: 
 60              if kwargs.has_key('val'): 
 61                  raise ValueError, "'val' property name is illegal." 
 62   
 63          # XXX probably is too generic... 
 64          for k, v in kwargs.iteritems(): 
 65              self.__setattr__(k, v) 
 66   
 67   
 68 -    def __str__(self): 
 69          res = CollectableAttribute.__str__(self) 
 70          # it is enabled but no value is assigned yet 
 71          res += '=%s' % (self.value,) 
 72          return res 
 73   
 74   
 75 -    def doc(self, indent="  ", width=70): 
 76          """Docstring for the parameter to be used in lists of parameters 
 77   
 78          :Returns: 
 79            string or list of strings (if indent is None) 
 80          """ 
 81          paramsdoc = "  %s" % self.name 
 82          if hasattr(paramsdoc, 'allowedtype'): 
 83              paramsdoc += " : %s" % self.allowedtype 
 84          paramsdoc = [paramsdoc] 
 85          try: 
 86              doc = self.__doc__ 
 87              if not doc.endswith('.'): doc += '.' 
 88              try: 
 89                  doc += " (Default: %s)" % self.default 
 90              except: 
 91                  pass 
 92              # Explicitly deal with multiple spaces, for some reason 
 93              # replace_whitespace is non-effective 
 94              doc = _whitespace_re.sub(' ', doc) 
 95              paramsdoc += ['  ' + x 
 96                            for x in textwrap.wrap(doc, width=width-len(indent), 
 97                                                   replace_whitespace=True)] 
 98          except Exception, e: 
 99              pass 
100   
101          if indent is None: 
102              return paramsdoc 
103          else: 
104              return ('\n' + indent).join(paramsdoc) 
105   
106   
107      # XXX should be named reset2default? correspondingly in 
108      #     ParameterCollection as well 
109 -    def resetvalue(self): 
110          """Reset value to the default""" 
111          #CollectableAttribute.reset(self) 
112          if not self.isDefault: 
113              self._isset = True 
114              self.value = self.__default 
115   
116 -    def _set(self, val): 
117          if self._value != val: 
118              if __debug__: 
119                  debug("COL", 
120                        "Parameter: setting %s to %s " % (str(self), val)) 
121              if hasattr(self, 'min') and val < self.min: 
122                  raise ValueError, \ 
123                        "Minimal value for parameter %s is %s. Got %s" % \ 
124                        (self.name, self.min, val) 
125              if hasattr(self, 'max') and val > self.max: 
126                  raise ValueError, \ 
127                        "Maximal value for parameter %s is %s. Got %s" % \ 
128                        (self.name, self.max, val) 
129              if hasattr(self, 'choices') and (not val in self.choices): 
130                  raise ValueError, \ 
131                        "Valid choices for parameter %s are %s. Got %s" % \ 
132                        (self.name, self.choices, val) 
133              self._value = val 
134              self._isset = True 
135          elif __debug__: 
136              debug("COL", 
137                    "Parameter: not setting %s since value is the same" \ 
138                    % (str(self))) 
139   
140      @property 
141 -    def isDefault(self): 
142          """Returns True if current value is bound to default one""" 
143          return self._value is self.default 
144   
145      @property 
146 -    def equalDefault(self): 
147          """Returns True if current value is equal to default one""" 
148          return self._value == self.__default 
149   
150 -    def setDefault(self, value): 
151          wasdefault = self.isDefault 
152          self.__default = value 
153          if wasdefault: 
154              self.resetvalue() 
155              self._isset = False 
156   
157      # incorrect behavior 
158      #def reset(self): 
159      #    """Override reset so we don't clean the flag""" 
160      #    pass 
161   
162      default = property(fget=lambda x:x.__default, fset=setDefault) 
163      value = property(fget=lambda x:x._value, fset=_set) 
164   
165 -class KernelParameter(Parameter): 
166      """Just that it is different beast""" 
167      pass 
168