Package mvpa :: Package misc :: Module param

[hide private]
[frames] | no frames]

# 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