bayesbay.discretization.Discretization

class bayesbay.discretization.Discretization(name, spatial_dimensions, perturb_std=0.1, n_dimensions=None, n_dimensions_min=1, n_dimensions_max=10, n_dimensions_init_range=0.3, parameters=None, birth_from='prior', **kwargs)

Low-level class to define a discretization

Parameters:

name (str) – name of the discretization, for display and storing purposes
spatial_dimensions (int) – number of spatial dimensions of the discretization, e.g. 1D, 2D, or 3D.
perturb_std (Union[Number, np.ndarray]) – standard deviation of the Gaussians used to randomly perturb the discretization in each dimension.
n_dimensions (Number, optional) – number of dimensions. None (default) results in a trans-dimensional discretization, with the dimensionality of the parameter space allowed to vary in the range n_dimensions_min - n_dimensions_max
n_dimensions_min (Number, optional) – minimum and maximum number of dimensions, by default 1 and 10. These parameters are ignored if n_dimensions is not None, i.e. if the discretization is not trans-dimensional
n_dimensions_max (Number, optional) – minimum and maximum number of dimensions, by default 1 and 10. These parameters are ignored if n_dimensions is not None, i.e. if the discretization is not trans-dimensional
n_dimensions_init_range (Number, optional) –
percentage of the range n_dimensions_min - n_dimensions_max used to initialize the number of dimensions (0.3. by default). For example, if n_dimensions_min = 1, n_dimensions_max = 10, and n_dimensions_init_range = 0.5, the maximum number of dimensions at the initialization is
```
int((n_dimensions_max - n_dimensions_min) * n_dimensions_init_range + n_dimensions_max)
```
parameters (List[Prior], optional) – a list of free parameters, by default None
birth_from ({"prior", "neighbour"}, optional) – whether to initialize the newborn basis functions by randomly drawing from the prior (default) or by perturbing the neighbor one.

Reference Details

is_leaf

name

parameters: all the free parameters defined in this parameter space

perturbation_funcs: a list of perturbation functions allowed in the current parameter space. Each function takes in a state (see State) and returns a new state along with the corresponding partial acceptance probability,

\[\begin{split}\underbrace{\alpha_{p}}_{\begin{array}{c} \text{Partial} \\ \text{acceptance} \\ \text{probability} \end{array}} = \underbrace{\frac{p\left({\bf m'}\right)}{p\left({\bf m}\right)}}_{\text{Prior ratio}} \underbrace{\frac{q\left({\bf m} \mid {\bf m'}\right)}{q\left({\bf m'} \mid {\bf m}\right)}}_{\text{Proposal ratio}} \underbrace{\lvert \mathbf{J} \rvert}_{\begin{array}{c} \text{Jacobian} \\ \text{determinant} \end{array}},\end{split}\]

perturbation_weights

a list of perturbation weights, corresponding to each of the perturbation_funcs() that determines the probability of each of them to be chosen during each step

The weights are not normalized and have the following default values:

Birth/Death perturbations: 3
Parameter values perturbation: 6

trans_d: indicates whether the current configuration allows changes in dimensionality

add_hyper_params(hyper_params)

Sets the attributes from the given dict and checks for errors

Parameters:: hyper_params (Dict[str, Union[Number, np.ndarray]]) – dictionary of attributes to be set

abstractmethod birth(param_space_state)

adds a dimension to the current parameter space and returns the thus obtained new state along with the log of the corresponding partial acceptance probability,

\[\begin{split}\underbrace{\alpha_{p}}_{\begin{array}{c} \text{Partial} \\ \text{acceptance} \\ \text{probability} \end{array}} = \underbrace{\frac{p\left({\bf m'}\right)}{p\left({\bf m}\right)}}_{\text{Prior ratio}} \underbrace{\frac{q\left({\bf m} \mid {\bf m'}\right)}{q\left({\bf m'} \mid {\bf m}\right)}}_{\text{Proposal ratio}} \underbrace{\lvert \mathbf{J} \rvert}_{\begin{array}{c} \text{Jacobian} \\ \text{determinant} \end{array}}.\end{split}\]

Parameters:

ParameterSpaceState – initial parameter space state

Returns:

ParameterSpaceState – new parameter space state
Number – log of the partial acceptance probability, \(\alpha_{p} = \log( \frac{p({\bf m'})}{p({\bf m})} \frac{q\left({\bf m} \mid {\bf m'}\right)}{q\left({\bf m'} \mid {\bf m}\right)} \lvert \mathbf{J} \rvert)\)

abstractmethod death(param_space_state)

removes a dimension from the given parameter space and returns the thus obtained new state along with the log of the corresponding partial acceptance probability,

\[\begin{split}\underbrace{\alpha_{p}}_{\begin{array}{c} \text{Partial} \\ \text{acceptance} \\ \text{probability} \end{array}} = \underbrace{\frac{p\left({\bf m'}\right)}{p\left({\bf m}\right)}}_{\text{Prior ratio}} \underbrace{\frac{q\left({\bf m} \mid {\bf m'}\right)}{q\left({\bf m'} \mid {\bf m}\right)}}_{\text{Proposal ratio}} \underbrace{\lvert \mathbf{J} \rvert}_{\begin{array}{c} \text{Jacobian} \\ \text{determinant} \end{array}}.\end{split}\]

Parameters:

ParameterSpaceState – initial parameter space state

Returns:

ParameterSpaceState – new parameter space state
Number – log of the partial acceptance probability, \(\alpha_{p} = \log( \frac{p({\bf m'})}{p({\bf m})} \frac{q\left({\bf m} \mid {\bf m'}\right)}{q\left({\bf m'} \mid {\bf m}\right)} \lvert \mathbf{J} \rvert)\)

get_hyper_param(hyper_param, position=None)

Retrieves the value corresponding to the specified attribute, which may be a function of position

Parameters:

hyper_param (str) – the name of the attribute
position (Union[np.ndarray, Number], optional) – the position (in the discretization domain) associated with the value, None by default

Returns:

value corresponding to the specified attribute

Return type:

Union[Number, np.ndarray]

get_perturb_std(*args): get the standard deviation of the Gaussian used to perturb the discretization

get_perturb_std_birth(position=None)

get the standard deviation of the Gaussian used to perturb the parameter at birth, which may be dependent on the position in the discretization domain

Parameters:: position (Union[Number, np.ndarray], optional) – the position in the discretization domain at which the standard deviation of the Gaussian used to perturb the parameter at birth is returned. Default is None
Returns:: standard deviation of the Gaussian used to perturb the parameter at birth, possibly at the specified position
Return type:: Number

has_hyper_param(hyper_param)

Whether or not the Prior instance has the specified attribute

Parameters:: hyper_param (str) – the name of the attribute

abstractmethod initialize(*args)

initializes the values of this discretization including its paramter values

Returns:: an initial parameter space state, or a list of paramtere space states
Return type:: Union[ParameterSpaceState, List[ParameterSpaceState]

abstractmethod log_prior(param_space_state)

calculates the log of the prior probability of occurrence of the given value, which may depend on the considered position

Parameters:

value (Number) – the value to calculate the probability density for
position (Number, optional) – the position (in the discretization domain) associated with the value, None by default

Returns:

the log prior probability density

Return type:

Number

abstractmethod log_prob_initialize_discretization(ps_state)

The log of the partial acceptance probability of the birth of the discretization. This includes only the discretization but not the parameter values.

\(\frac{p(k')}{p(k)} \frac{p(c'|k')}{p(c|k)} \frac{q(c'|m)}{q(c|m')}\)

Parameters:: ps_state (ParameterSpaceState) – the newly-born parameter space state
Returns:: the log of the partial acceptance probability of the birth of the discretization
Return type:: Number

abstractmethod nearest_neighbour(discretization, query_point)

returns the index of the nearest neighbour of a given query point in the discretization

Parameters:

discretization (np.ndarray) – the discretization
query_point (Union[Number, np.ndarray]) – the query point

Returns:

the index of the nearest neighbour point

Return type:

int

abstractmethod perturb_value(param_space_state, idimension)

perturbs the parameter space inherent to the discretization and calculates the log of the corresponding partial acceptance probability

\[\begin{split}\underbrace{\alpha_{p}}_{\begin{array}{c} \text{Partial} \\ \text{acceptance} \\ \text{probability} \end{array}} = \underbrace{\frac{p\left({\bf m'}\right)}{p\left({\bf m}\right)}}_{\text{Prior ratio}} \underbrace{\frac{q\left({\bf m} \mid {\bf m'}\right)}{q\left({\bf m'} \mid {\bf m}\right)}}_{\text{Proposal ratio}} \underbrace{\lvert \mathbf{J} \rvert}_{\begin{array}{c} \text{Jacobian} \\ \text{determinant} \end{array}}.\end{split}\]

Note

All free parameters linked to the discretization will be perturbed at the specified index.

Parameters:

ParameterSpaceState – initial parameter space state
idimension (int) – index of the parameter-space dimension to be perturbed

Returns:

the perturbed value and \(\alpha_{p} = \log( \frac{p({\bf m'})}{p({\bf m})} \frac{q\left({\bf m} \mid {\bf m'}\right)}{q\left({\bf m'} \mid {\bf m}\right)} \lvert \mathbf{J} \rvert)\)

Return type:

Tuple[ParameterSpaceState, Number]

sample(*args): sample a random ParameterSpaceState instance, including the number of dimensions, the Voronoi sites, and the parameter values

abstractmethod sample_discretization(*args): sample a parameter space state that only contains the discretization

set_custom_initialize(initialize_func)

sets a custom initialization function

Parameters:: initialize_func (Callable[["Prior", np.ndarray], np.ndarray]) – The function to use for initialization. This function should take a Prior instance and optionally an array of positions as input arguments, and produce an array of values as output.

Examples

def my_init(
    param: bb.prior.Prior,
    position: np.ndarray
) -> np.ndarray:
    print("This is my custom init!")
    return np.ones(len(position))

my_param.set_custom_initialize(my_init)

back to top