Module parameterized

source code

Probability density functions with support for shared and computed parameters.

This module extends the functionality of csb.statistics.pdf with a specialized and more sophisticated AbstractDensity -- the ParameterizedDensity, which works with AbstractParameter objects rather than simple floats.

Each AbstractParameter holds two properties - AbstractParameter.name and 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

AbstractParameters holding a single float value are indistinguishable from the simple float parameters used in csb.statistics.pdf.BaseDensity. However, each 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 (AbstractParameter._compute). This is a lazy, on demand process. As soon as Sigma's computed value is requested (via 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 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.