paramz.core package

Submodules

paramz.core.constrainable module

class Constrainable(name, default_constraint=None, *a, **kw)

Bases: paramz.core.indexable.Indexable

constrain(transform, warning=True, trigger_parent=True)

Parameters:

• transform – the paramz.transformations.Transformation to constrain the this parameter to.
• warning – print a warning if re-constraining parameters.

Constrain the parameter to the given paramz.transformations.Transformation.

constrain_bounded(lower, upper, warning=True, trigger_parent=True)

Parameters:

• upper (lower,) – the limits to bound this parameter to
• warning – print a warning if re-constraining parameters.

Constrain this parameter to lie within the given range.

constrain_fixed(value=None, warning=True, trigger_parent=True)

Constrain this parameter to be fixed to the current value it carries.

This does not override the previous constraints, so unfixing will restore the constraint set before fixing.

Parameters:warning – print a warning for overwriting constraints.

constrain_negative(warning=True, trigger_parent=True)

Parameters:warning – print a warning if re-constraining parameters.

Constrain this parameter to the default negative constraint.

constrain_positive(warning=True, trigger_parent=True)

Parameters:warning – print a warning if re-constraining parameters.

Constrain this parameter to the default positive constraint.

fix(value=None, warning=True, trigger_parent=True)

Constrain this parameter to be fixed to the current value it carries.

This does not override the previous constraints, so unfixing will restore the constraint set before fixing.

Parameters:warning – print a warning for overwriting constraints.

unconstrain(*transforms)

Parameters:transforms – The transformations to unconstrain from.

remove all paramz.transformations.Transformation transformats of this parameter object.

unconstrain_bounded(lower, upper)

Parameters:upper (lower,) – the limits to unbound this parameter from

Remove (lower, upper) bounded constrain from this parameter/

unconstrain_fixed()

This parameter will no longer be fixed.

If there was a constraint on this parameter when fixing it, it will be constraint with that previous constraint.

unconstrain_negative()

Remove negative constraint of this parameter.

unconstrain_positive()

Remove positive constraint of this parameter.

unfix()

This parameter will no longer be fixed.

If there was a constraint on this parameter when fixing it, it will be constraint with that previous constraint.

is_fixed

paramz.core.gradcheckable module

class Gradcheckable(*a, **kw)

Bases: paramz.core.pickleable.Pickleable, paramz.core.parentable.Parentable

Adds the functionality for an object to be gradcheckable. It is just a thin wrapper of a call to the highest parent for now. TODO: Can be done better, by only changing parameters of the current parameter handle, such that object hierarchy only has to change for those.

checkgrad(verbose=0, step=1e-06, tolerance=0.001, df_tolerance=1e-12)

Check the gradient of this parameter with respect to the highest parent’s objective function. This is a three point estimate of the gradient, wiggling at the parameters with a stepsize step. The check passes if either the ratio or the difference between numerical and analytical gradient is smaller then tolerance.

Parameters:

• verbose (bool) – whether each parameter shall be checked individually.
• step (float) – the stepsize for the numerical three point gradient estimate.
• tolerance (float) – the tolerance for the gradient ratio or difference.
• df_tolerance (float) – the tolerance for df_tolerance

Note

The dF_ratio indicates the limit of accuracy of numerical gradients. If it is too small, e.g., smaller than 1e-12, the numerical gradients are usually not accurate enough for the tests (shown with blue).

paramz.core.index_operations module

class ParameterIndexOperations(constraints=None)

Bases: object

This object wraps a dictionary, whos keys are _operations_ that we’d like to apply to a parameter array, and whose values are np integer arrays which index the parameter array appropriately.

A model instance will contain one instance of this class for each thing that needs indexing (i.e. constraints, ties and priors). Parameters within the model constain instances of the ParameterIndexOperationsView class, which can map from a ‘local’ index (starting 0) to this global index.

Here’s an illustration:

#=======================================================================
model : 0 1 2 3 4 5 6 7 8 9
key1: 4 5
key2: 7 8

param1: 0 1 2 3 4 5
key1: 2 3
key2: 5

param2: 0 1 2 3 4
key1: 0
key2: 2 3
#=======================================================================

The views of this global index have a subset of the keys in this global (model) index.

Adding a new key (e.g. a constraint) to a view will cause the view to pass the new key to the global index, along with the local index and an offset. This global index then stores the key and the appropriate global index (which can be seen by the view).

See also: ParameterIndexOperationsView

add(prop, indices)

clear()

copy()

indices()

items()

properties()

properties_dict_for(index)

Return a dictionary, containing properties as keys and indices as index Thus, the indices for each constraint, which is contained will be collected as one dictionary

Example: let properties: ‘one’:[1,2,3,4], ‘two’:[3,5,6]

>>> properties_dict_for([2,3,5])
{'one':[2,3], 'two':[3,5]}

properties_for(index)

Returns a list of properties, such that each entry in the list corresponds to the element of the index given.

Example: let properties: ‘one’:[1,2,3,4], ‘two’:[3,5,6]

>>> properties_for([2,3,5])
[['one'], ['one', 'two'], ['two']]

remove(prop, indices)

shift_left(start, size)

shift_right(start, size)

update(parameter_index_view, offset=0)

size

class ParameterIndexOperationsView(param_index_operations, offset, size)

Bases: object

add(prop, indices)

clear()

copy()

indices()

items()

properties()

properties_dict_for(index)

Return a dictionary, containing properties as keys and indices as index Thus, the indices for each constraint, which is contained will be collected as one dictionary

Example: let properties: ‘one’:[1,2,3,4], ‘two’:[3,5,6]

>>> property_dict_for([2,3,5])
{'one':[2,3], 'two':[3,5]}

properties_for(index)

Returns a list of properties, such that each entry in the list corresponds to the element of the index given.

Example: let properties: ‘one’:[1,2,3,4], ‘two’:[3,5,6]

>>> properties_for([2,3,5])
[['one'], ['one', 'two'], ['two']]

remove(prop, indices)

shift_left(start, size)

shift_right(start, size)

update(parameter_index_view, offset=0)

size

combine_indices(arr1, arr2)

extract_properties_to_index(index, props)

index_empty(index)

remove_indices(arr, to_remove)

paramz.core.indexable module

class Indexable(name, default_constraint=None, *a, **kw)

Bases: paramz.core.nameable.Nameable, paramz.core.updateable.Updateable

Make an object constrainable with Priors and Transformations.

TODO: Mappings!! (As in ties etc.)

Adding a constraint to a Parameter means to tell the highest parent that the constraint was added and making sure that all parameters covered by this object are indeed conforming to the constraint.

constrain and unconstrain are main methods here

add_index_operation(name, operations)

Add index operation with name to the operations given.

raises: attribute error if operations exist.

remove_index_operation(name)

paramz.core.lists_and_dicts module

class ArrayList

Bases: list

List to store ndarray-likes in. It will look for ‘is’ instead of calling __eq__ on each element.

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

class IntArrayDict(default_factory=None)

Bases: collections.defaultdict

Default will be self._default, if not set otherwise

class ObserverList

Bases: object

A list which containts the observables. It only holds weak references to observers, such that unbound observers dont dangle in memory.

add(priority, observer, callble)

Add an observer with priority and callble

flush()

Make sure all weak references, which point to nothing are flushed (deleted)

remove(priority, observer, callble)

Remove one observer, which had priority and callble.

intarray_default_factory()

paramz.core.nameable module

class Nameable(name, *a, **kw)

Bases: paramz.core.gradcheckable.Gradcheckable

Make an object nameable inside the hierarchy.

hierarchy_name(adjust_for_printing=True)

return the name for this object with the parents names attached by dots.

Parameters:adjust_for_printing (bool) – whether to call adjust_for_printing on the names, recursively

name

The name of this object

adjust_name_for_printing(name)

Make sure a name can be printed, alongside used as a variable name.

paramz.core.observable module

class Observable(*args, **kwargs)

Bases: object

Observable pattern for parameterization.

This Object allows for observers to register with self and a (bound!) function as an observer. Every time the observable changes, it sends a notification with self as only argument to all its observers.

add_observer(observer, callble, priority=0)

Add an observer observer with the callback callble and priority priority to this observers list.

change_priority(observer, callble, priority)

notify_observers(which=None, min_priority=None)

Notifies all observers. Which is the element, which kicked off this notification loop. The first argument will be self, the second which.

Note

notifies only observers with priority p > min_priority!

Parameters:min_priority – only notify observers with priority > min_priority if min_priority is None, notify all observers in order

remove_observer(observer, callble=None)

Either (if callble is None) remove all callables, which were added alongside observer, or remove callable callble which was added alongside the observer observer.

set_updates(on=True)

paramz.core.observable_array module

class ObsAr(*a, **kw)

Bases: numpy.ndarray, paramz.core.pickleable.Pickleable, paramz.core.observable.Observable

An ndarray which reports changes to its observers.

Warning

ObsAr tries to not ever give back an observable array itself. Thus, if you want to preserve an ObsAr you need to work in memory. Let a be an ObsAr and you want to add a random number r to it. You need to make sure it stays an ObsAr by working in memory (see numpy for details):

a[:] += r

The observers can add themselves with a callable, which will be called every time this array changes. The callable takes exactly one argument, which is this array itself.

copy()

Make a copy. This means, we delete all observers and return a copy of this array. It will still be an ObsAr!

values

Return the ObsAr underlying array as a standard ndarray.

paramz.core.parameter_core module

Core module for parameterization. This module implements all parameterization techniques, split up in modular bits.

Observable: Observable Pattern for patameterization

class OptimizationHandlable(name, default_constraint=None, *a, **kw)

Bases: paramz.core.constrainable.Constrainable

This enables optimization handles on an Object as done in GPy 0.4.

…_optimizer_copy_transformed: make sure the transformations and constraints etc are handled

parameter_names(add_self=False, adjust_for_printing=False, recursive=True, intermediate=False)

Get the names of all parameters of this model or parameter. It starts from the parameterized object you are calling this method on.

Note: This does not unravel multidimensional parameters,

use parameter_names_flat to unravel parameters!

Parameters:

• add_self (bool) – whether to add the own name in front of names
• adjust_for_printing (bool) – whether to call adjust_name_for_printing on names
• recursive (bool) – whether to traverse through hierarchy and append leaf node names
• intermediate (bool) – whether to add intermediate names, that is parameterized objects

parameter_names_flat(include_fixed=False)

Return the flattened parameter names for all subsequent parameters of this parameter. We do not include the name for self here!

If you want the names for fixed parameters as well in this list, set include_fixed to True.

if not hasattr(obj, ‘cache’):

obj.cache = FunctionCacher()

Parameters:include_fixed (bool) – whether to include fixed names here.

randomize(rand_gen=None, *args, **kwargs)

Randomize the model. Make this draw from the rand_gen if one exists, else draw random normal(0,1)

Parameters:

• rand_gen – np random number generator which takes args and kwargs
• loc (flaot) – loc parameter for random number generator
• scale (float) – scale parameter for random number generator
• kwargs (args,) – will be passed through to random number generator

gradient_full

Note to users: This does not return the gradient in the right shape! Use self.gradient for the right gradient array.

To work on the gradient array, use this as the gradient handle. This method exists for in memory use of parameters. When trying to access the true gradient array, use this.

num_params

Return the number of parameters of this parameter_handle. Param objects will always return 0.

optimizer_array

Array for the optimizer to work on. This array always lives in the space for the optimizer. Thus, it is untransformed, going from Transformations.

Setting this array, will make sure the transformed parameters for this model will be set accordingly. It has to be set with an array, retrieved from this method, as e.g. fixing will resize the array.

The optimizer should only interfere with this array, such that transformations are secured.

class Parameterizable(*args, **kwargs)

Bases: paramz.core.parameter_core.OptimizationHandlable

A parameterisable class.

This class provides the parameters list (ArrayList) and standard parameter handling, such as {link|unlink}_parameter(), traverse hierarchy and param_array, gradient_array and the empty parameters_changed().

This class is abstract and should not be instantiated. Use paramz.Parameterized() as node (or leaf) in the parameterized hierarchy. Use paramz.Param() for a leaf in the parameterized hierarchy.

disable_caching()

enable_caching()

initialize_parameter()

Call this function to initialize the model, if you built it without initialization.

This HAS to be called manually before optmizing or it will be causing unexpected behaviour, if not errors!

parameters_changed()

This method gets called when parameters have changed. Another way of listening to param changes is to add self as a listener to the param, such that updates get passed through. See :py:function:paramz.param.Observable.add_observer

save(filename, ftype='HDF5')

Save all the model parameters into a file (HDF5 by default).

This is not supported yet. We are working on having a consistent, human readable way of saving and loading GPy models. This only saves the parameter array to a hdf5 file. In order to load the model again, use the same script for building the model you used to build this model. Then load the param array from this hdf5 file and set the parameters of the created model:

>>> m[:] = h5_file['param_array']

This is less then optimal, we are working on a better solution to that.

traverse(visit, *args, **kwargs)

Traverse the hierarchy performing visit(self, *args, **kwargs) at every node passed by downwards. This function includes self!

See visitor pattern in literature. This is implemented in pre-order fashion.

Example:

#Collect all children:

children = []
self.traverse(children.append)
print children

traverse_parents(visit, *args, **kwargs)

Traverse the hierarchy upwards, visiting all parents and their children except self. See “visitor pattern” in literature. This is implemented in pre-order fashion.

Example:

parents = [] self.traverse_parents(parents.append) print parents

gradient

num_params

param_array

Array representing the parameters of this class. There is only one copy of all parameters in memory, two during optimization.

!WARNING!: setting the parameter array MUST always be done in memory: m.param_array[:] = m_copy.param_array

unfixed_param_array

Array representing the parameters of this class. There is only one copy of all parameters in memory, two during optimization.

!WARNING!: setting the parameter array MUST always be done in memory: m.param_array[:] = m_copy.param_array

paramz.core.parentable module

class Parentable(*args, **kwargs)

Bases: object

Enable an Object to have a parent.

Additionally this adds the parent_index, which is the index for the parent to look for in its parameter list.

has_parent()

Return whether this parentable object currently has a parent.

paramz.core.pickleable module

class Pickleable(*a, **kw)

Bases: object

Make an object pickleable (See python doc ‘pickling’).

This class allows for pickling support by Memento pattern. _getstate returns a memento of the class, which gets pickled. _setstate(<memento>) (re-)sets the state of the class to the memento

copy(memo=None, which=None)

Returns a (deep) copy of the current parameter handle.

All connections to parents of the copy will be cut.

Parameters:

• memo (dict) – memo for deepcopy
• which (Parameterized) – parameterized object which started the copy process [default: self]

pickle(f, protocol=-1)

Parameters:

• f – either filename or open file object to write to. if it is an open buffer, you have to make sure to close it properly.
• protocol – pickling protocol to use, python-pickle for details.

paramz.core.updateable module

class Updateable(*args, **kwargs)

Bases: paramz.core.observable.Observable

A model can be updated or not. Make sure updates can be switched on and off.

toggle_update()

trigger_update(trigger_parent=True)

Update the model from the current state. Make sure that updates are on, otherwise this method will do nothing

Parameters:trigger_parent (bool) – Whether to trigger the parent, after self has updated

update_model(updates=None)

Get or set, whether automatic updates are performed. When updates are off, the model might be in a non-working state. To make the model work turn updates on again.

Parameters:updates (bool|None) – bool: whether to do updates None: get the current update state

update_toggle()

Module contents

Core

This package holds the core modules for the parameterization

HierarchyError: raised when an error with the hierarchy occurs (circles etc.)

exception HierarchyError

Bases: exceptions.Exception

Gets thrown when something is wrong with the parameter hierarchy.