""" Probability density functions with support for shared and computed parameters. This module extends the functionality of L{csb.statistics.pdf} with a specialized and more sophisticated L{AbstractDensity} -- the L{ParameterizedDensity}, which works with L{AbstractParameter} objects rather than simple floats. Each L{AbstractParameter} holds two properties - L{AbstractParameter.name} and L{AbstractParameter.value}: >>> class Sigma(AbstractParameter): >>> def _validate(self, value): >>> return float(value) >>> def _compute(self, base_value): >>> return 1.0 / base_value ** 0.5 >>> >>> sigma = Sigma(3) >>> sigma.name, sigma.value sigma, 3 L{AbstractParameter}s holding a single float value are indistinguishable from the simple float parameters used in L{csb.statistics.pdf.BaseDensity}. However, each L{AbstractParameter} supports the concept of binding: >>> sigma.is_virtual False >>> precision = Precision(1) >>> sigma.bind_to(precision) >>> sigma.is_virtual True >>> precision.set(2) # triggers an implicit, lazy update in sigma >>> sigma.set(1) ParameterizationError: Virtual parameters can't be updated explicitly The instance of Sigma is now a virtual parameter which receives automatic updates from another base parameter using a predefined rule (L{AbstractParameter._compute}). This is a lazy, on demand process. As soon as Sigma's computed value is requested (via C{s.value}), Sigma will query the parameter it depends on (Precision), which in turn will get recomputed first based on its own base, etc. Thus, the L{AbstractParameter} model supports a parameter dependency chain with linear or tree-like topologies:: sigma -- y / precision -- sigma2 -- x In this graph precision is a base (non-virtual) parameter and sigma, sigma2, x, and y are all virtual (computed). Binding precision to another parameter will immediately turn it into a virtual one. However, cycles are not allowed (e.g. precision can't be bound to sigma2 or x) and each virtual parameter must have exactly one base. Computed parameters can then be used to implement custom PDFs with dependent parameters within one PDF or spanning multiple PDFs. """ import csb.statistics.pdf as pdf from abc import abstractmethod class ParameterizationError(ValueError): pass class ParameterValueError(pdf.ParameterValueError): pass class ParameterizedDensity(pdf.AbstractDensity): """ Base abstract class for all PDFs, which operate on simple or computed (chained) parameters. Parameters of type different from L{AbstractParameter} will trigger TypeError-s. """ def _set(self, param, value): if not isinstance(value, AbstractParameter): raise TypeError(value) super(ParameterizedDensity, self)._set(param, value) class AbstractParameter(object): """ Abstract parameterization, which can exist independently or be coupled to other parameters upon request. Virtual/coupled/derived parameters cannot be overwritten explicitly, but their values will get recomputed once their corresponding base parameters get updated. This is a lazy process - parameter recalculation happens only when an out of date parameter is requested. This triggers a real-time cascaded update which affects all parameters from the nearest consistent base down to the current inconsistent node. Implementing subclasses must override L{AbstractParameter._validate} and virtual parameters should additionally override L{AbstractParameter._compute}. @param value: initial value (defaults to None / AbstractParameter.NULL) @type value: object @param name: name of parameter (this is the name of the class by default) @type name: str @param base: optional base parameter to compute this instance from @type base: L{AbstractParameter} """ NULL = None def __init__(self, value=NULL, name=None, base=None): self._derivatives = set() self._base = None self._consistent = True if name is None: name = self.__class__.__name__.lower() self._name = str(name) self._value = AbstractParameter.NULL self._update(value) if base is not None: self.bind_to(base) @property def name(self): """ Parameter name """ return self._name @property def value(self): """ Parameter value (guaranteed to be up to date) """ self._ensure_consistency() return self._value @property def is_virtual(self): """ True if this parameter is virtual (computed) """ return self._base is not None def set(self, value): """ Update the value of this parameter. This is not possible for virtual parameters. @param value: new value @type value: object @raise ParameterizationError: if this is a virtual parameter @raise ParameterValueError: on invalid value """ if self.is_virtual: raise ParameterizationError( "Virtual parameters can't be updated explicitly") self._update(value) self._invalidate() self._consistent = True def bind_to(self, parameter): """ Bind the current parameter to a base parameter. This converts the current parameter to a virtual one, whose value will get implicitly updated to be consistent with its base. Note that virtual parameters must have exactly one base; computing a parameter from multiple bases is not allowed. Cycles are also not allowed; the topology must always stay a tree with a non-virtual parameter at the root. @param parameter: base parameter to compute this instance from @param parameter: L{AbstractParameter} @raise ParameterizationError: if this parameter is already virtual @raise ParameterizationError: on attempt to create a circular dependency """ if not isinstance(parameter, AbstractParameter): raise TypeError(parameter) if parameter.find_base_parameter() is self: raise ParameterizationError("Circular dependency detected") if self.is_virtual: msg = "Parameter {0.name} is already bound to {1.name}" raise ParameterizationError(msg.format(self, self._base)) self._set_base(parameter) self._base._add_derived(self) self._invalidate() def _set_base(self, parameter): self._base = parameter def _add_derived(self, parameter): self._derivatives.add(parameter) def _invalidate(self): """ Mark self and its virtual children as inconsistent """ for p in self._derivatives: p._invalidate() self._consistent = False def _update(self, value): """ Overwrite the current value of the parameter. This triggers an abstract (custom) validation hook, but has no side effects (i.e. it doesn't propagate!) """ sanitized = self._validate(value) self._value = sanitized @abstractmethod def _validate(self, value): """ Validate and sanitize the specified value before assignment. @return: sanitized value @raise ParameterValueError: on invalid value """ return value def _compute(self, base_value): """ Compute a new value for the current parameter given the value of a base parameter (assuming self.is_virtual). By default this returns the value of the base parameter (i.e. self just inherits the value of its base untouched). """ return base_value def _ensure_consistency(self): """ Make sure that the current value is up to date. If it isn't, trigger a real-time cascaded update following the path from the nearest consistent base down to self. Also mark all nodes consistent in the course of doing this update. """ if not self._consistent: path = self._nearest_consistent_base() for parameter in reversed(path): parameter._recompute(consistent=True) def _recompute(self, consistent=True): """ If self is virtual, force the current parameter to recompute itself from its immediate base. This operation has no side effects and does not propagate. """ if self.is_virtual: value = self._compute(self._base._value) self._update(value) if consistent: self._consistent = True def _recompute_derivatives(self): """ Recompute all derived parameters starting from self and mark them consistent. """ self._recompute(consistent=True) for p in self._derivatives: p._recompute_derivatives() def _nearest_consistent_base(self): """ Compute and return the path from self to the nearest consistent base parameter. @return: path, leaf-to-root @rtype: list of L{AbstractParameter} """ root = self path = [self] while not root._consistent: root = root._base path.append(root) return path def find_base_parameter(self): """ Find and return the non-virtual base parameter that is the root of the current hierarchy. If self is not virtual, return self. @return: base parameter @rtype: L{AbstractParameter} """ root = self while root.is_virtual: root = root._base return root class Parameter(AbstractParameter): """ Default parameter implementation which accepts float values only. """ def __init__(self, value=0.0, name=None, base=None): super(Parameter, self).__init__(value, name, base) def _validate(self, value): try: return float(value) except (ValueError, TypeError): raise ParameterValueError(self.name, value) class NonVirtualParameter(Parameter): """ A float L{Parameter} that is explicitly non-computed and cannot be bound to another L{Parameter}. """ def bind_to(self, parameter): raise ParameterizationError( "This parameter is explicitly non-computed") @property def is_virtual(self): return False