Bound and Parameter Types

Bound types and bounded parameter types.

class revrand.btypes.Bound

Define bounds on a variable for the optimiser.

This defaults to all real values allowed (i.e. no bounds).

Parameters:

• lower (float) – The lower bound.
• upper (float) – The upper bound.

lower

float – The lower bound.

upper

float – The upper bound.

Examples

>>> b = Bound(1e-10, upper=1e-5)
>>> b
Bound(lower=1e-10, upper=1e-05)
>>> b.lower
1e-10
>>> b.upper
1e-05
>>> isinstance(b, tuple)
True
>>> tuple(b)
(1e-10, 1e-05)
>>> lower, upper = b
>>> lower
1e-10
>>> upper
1e-05
>>> Bound(42, 10)
Traceback (most recent call last):
    ...
ValueError: lower bound cannot be greater than upper bound!

class revrand.btypes.Parameter(value=None, bounds=Bound(lower=None, upper=None), shape=())

A Parameter class that associates a value with a bound.

value

None, scalar, ndarray, scipy.stats, optional – a value or distribution to associate with this parameter. This is typically used as an initial value for an optimizer, and if a random starts optimiser is used (eg. revrand.optimize.structured_minimizer) it can draw randomly from the distribution.

bound

Bound, optional – a Bound tuple that describes the valid range for all of the elements in value

shape

tuple, optional – the shape of value, this is ignored if value is not a scipy.stats distribution (i.e. it is automatically determined).

Note

• If value is initialised as a distribution from scipy.stats, then self.value is actually the mean of the distribution.
• If you want to set value to a scipy.stats distribution, and also associate it with a shape (i.e. you want an ndarray random variable), then also set the shape parameters to the desired dimensions.

Examples

Null

>>> p = Parameter()
>>> p.value
[]
>>> p.has_value
False

Scalar

>>> p = Parameter(1.2, Bound(1, 2))
>>> p.shape
()
>>> p.value
1.2
>>> p.rvs()
1.2
>>> p.is_random
False

ndarray

>>> p = Parameter(np.ones(3), Positive())
>>> p.shape
(3,)
>>> p.value
array([ 1.,  1.,  1.])
>>> p.rvs()
array([ 1.,  1.,  1.])

scipy.stats scalar

>>> from scipy.stats import gamma
>>> p = Parameter(gamma(a=1, scale=1), Positive())
>>> p.value == gamma(a=1, scale=1).mean()
True
>>> np.isscalar(p.rvs())
True
>>> p.is_random
True

scipy.stats ndarray

>>> from scipy.stats import gamma
>>> p = Parameter(gamma(a=1, scale=1), Positive(), shape=(3,))
>>> all(p.value == np.ones(3) * gamma(a=1, scale=1).mean())
True
>>> p.rvs().shape == (3,)
True

has_value

Test if this Parameter has a value, or is “null”.

is_random

Test if this Parameter was initialised with a distribution.

is_scalar

Test if the Parameter is for a scalar value.

rvs(random_state=None)

Draw a random value from this Parameter’s distribution.

If value was not initialised with a scipy.stats object, then the scalar/ndarray value is returned.

Parameters:random_state (None, int or RandomState, optional) – random seed Returns:of size self.shape, a random draw from the distribution, or self.value if not initialised with a scipy.stats object. Return type:ndarray

Note

Random draws are clipped to the bounds, and so it is up to the user to input a sensible sampling distribution!

class revrand.btypes.Positive

Define a positive only bound for the optimiser.

This may induce the ‘log trick’ in the optimiser (when using an appropriate decorator), which will ignore the ‘smallest’ value (but will stay above 0).

Parameters:upper (float) – The largest value allowed for the optimiser to evaluate (if not using the log trick).

Examples

>>> b = Positive()
>>> b
Positive(upper=None)

Since tuple (and by extension its descendents) are immutable, the lower bound for all instances of Positive are guaranteed to be positive.

revrand.btypes.hstack(tup)

Horizontally stack a sequence of value bounds pairs.

Parameters:tup (sequence) – a sequence of value, Bound pairs Returns:

• value (ndarray) – a horizontally concatenated array1d
• bounds – a list of Bounds

revrand.btypes.ravel(parameter, random_state=None)

Flatten a Parameter.

Parameters:parameter (Parameter) – A Parameter object Returns:

• flatvalue (ndarray) – a flattened array of shape (prod(parameter.shape),)
• flatbounds (list) – a list of bound tuples of length prod(parameter.shape)

revrand.btypes.shape(parameter)

Get the shape of a Parameter.

Parameters:parameter (Parameter) – Parameter object to get the shape of Returns:shape of the Parameter object Return type:tuple