Experimental Inference tools

Experimental Inference tools#

The following tools are experimental and may change in future releases. They help with the Bayesian inference of the model parameters using the PyMC library.

Functions#

Experimental functions, might have breaking changes in the future.

icomo.experimental.priors_for_cps(cp_dim, time_dim, name_positions, name_magnitudes, name_durations, beta_magnitude=1, sigma_magnitude_fix=None, dist_magnitudes=pymc.Normal, absolute_magnitude_parametrization=False, empirical_bayes_hyper_sigma=False, centered_parametrization=False, model=None)[source]#

Create priors for changepoints.

Their positions are uniformly distributed between the first and last timepoint. The magnitudes are sampled from a hierarchical prior with a beta distribution. The durations are sampled from a normal distribution with mean equal to the mean distance between changepoints and standard deviation equal to the standard deviation of the distance between changepoints.

Parameters:

  • cp_dim (str) – Dimension of the pymc.Model for the changepoints. Define it by passing coords={cp_dim: np.arange(num_cps)} to pymc.Model at creation. The length of this dimension determines the number of changepoints.

  • time_dim (str) – Dimension of the pymc.Model for the time.

  • name_positions (str) – Name under which the positions of the changepoints are stored in pymc.Model

  • name_magnitudes (str) – Name under which the magnitudes of the changepoints are stored in pymc.Model

  • name_durations (str) – Name under which the durations of the changepoints are stored in pymc.Model

  • beta_magnitude (float, default=1) – Beta parameter of the hierarchical prior for the magnitudes

  • sigma_magnitude_fix (float, default=None) – If not None, the standard deviation from which the magnitudes are sampled is fixed

  • dist_magnitudes (pymc.Distribution, default=pm.Normal) – Distribution from which the magnitudes are sampled. Can for example be functools.partial(pm.StudentT, nu=4) to sample from a StudentT distribution for a more robust model.

  • absolute_magnitude_parametrization (bool, default=False) – Whether to use an parametrization that is absolute or relative to previous values for the magnitudes.

  • empirical_bayes_hyper_sigma (bool, default=False) – Whether to set the standard deviation of the hierarchical magnitudes to the maximum likelihood estimate instead of sampling. Corresponds to an empirical Bayes approach.

  • centered_parametrization (bool, default=False) – Whether to use a centered parametrization for the hierarchical priors of the magnitudes.

  • model (pymc.Model, default=None) – pm.Model in which the priors are created. If None, the pm.Model is taken from the context.

Returns:

positions, magnitudes, durations (pytensor.Variable) – Variables of dim cp_dim that define the positions, magnitudes and durations of the changepoints

icomo.experimental.sigmoidal_changepoints(ts_out, positions_cp, magnitudes_cp, durations_cp, reorder_cps=False)[source]#

Modulation of a time series by sigmoidal changepoints.

The changepoints are defined by their position, magnitude and duration. The resulting equation is:

\[f(t) = \sum_{i=1}^{\mathrm{num_cps}} \frac{\mathrm{magnitudes\_cp}[i]}{1 + exp(-4 \cdot \mathrm{slope}[i] \cdot (t - \mathrm{positions_cp}[i]))}\]

where slope[i] = magnitudes_cp[i] / durations_cp[i].

Parameters:

  • t_out (1d-array) – timepoints where modulation is evaluated, shape: (time, )

  • t_cp (nd-array) – timepoints of the changepoints, shape: (num_cps, further dims…)

  • magnitudes (nd-array) – magnitude of the changepoints, shape: (num_cps, further dims…)

  • durations (nd-array) – magnitude of the changepoints, shape: (num_cps, further dims…)

  • reorder_cps (bool, default=False) – reorder changepoints such that their timepoints are linearly increasing

Returns:

modulation_t ((n+1)d-array) – shape: (time, further dims…)

icomo.experimental.hierarchical_priors(name, dims, beta=1, fix_hyper_sigma=None, dist_values=pymc.Normal, centered_parametrization=False, empirical_sigma=False)[source]#

Create hierarchical priors for a variable.

Create an n-dimensional variable with hierarchical prior with name name and dimensions dims. The prior is a normal distribution with standard deviation sigma which is sample from a half-cauchy distribution with beta parameter beta.

Parameters:

  • name (str) – Name under which the variable is stored in pm.Model

  • dims (tuple of str) – Dimensions over which the variable is defined. Define a dimension by passing coords={dim_name: np.arange(size)} to pm.Model at creation.

  • beta (float, default=1) – Beta parameter of the half-cauchy distribution

  • fix_hyper_sigma (float, default=None) – If not None, the standard deviation from which the variable is sampled is fixed

  • dist_values (pymc.Distribution, default=pm.Normal) – Distribution from which the values are sampled. Can for example be functools.partial(pm.StudentT, nu=4) to sample from a StudentT distribution for a more robust model.

  • centered_parametrization (bool, default=False) – Whether to use a centered or non-centered parametrization for the hierarchical prior

  • empirical_sigma (bool, default=False) – Whether to set the standard deviation of the normal distribution to the standard deviation of the sampled value. Corresponds to an empirical Bayes approach.

Returns:

values (pm.Variable) – pm.Variable for the variable with name name