API Reference

Study types

Study([silent]) Fits with fixed hyper-parameters and hyper-parameter optimization.
HyperStudy([silent]) Infers hyper-parameter distributions.
ChangepointStudy([silent]) Infers change-points and structural breaks.
OnlineStudy([storeHistory, silent]) Enables model selection for online data streams.

Note

These Study classes are imported directly into the module namespace for convenient access.

import bayesloop as bl
S = bl.Study()

In bayesloop, each new data study is handled by an instance of a Study-class. In this way, all data, the inference results and the appropriate post-processing routines are stored in one object that can be accessed conveniently or stored in a file. Apart from the basic Study class, there exist a number of specialized classes that extend the basic fit method, for example to infer the full distribution of hyper-parameters or to apply model selection to on-line data streams.

class bayesloop.core.ChangepointStudy(silent=False)

Infers change-points and structural breaks. This class builds on the HyperStudy-class and the change-point transition model to perform a series of analyses with varying change point times. It subsequently computes the average model from all possible change points and creates a probability distribution of change point times. It supports any number of change-points and arbitarily combined models.

fit(forwardOnly=False, evidenceOnly=False, silent=False, nJobs=1)

This method over-rides the corresponding method of the HyperStudy-class. It runs the algorithm for all possible combinations of change-points (and possible scans a range of values for other hyper-parameters). The posterior sequence represents the average model of all analyses. Posterior mean values are computed from this average model.

Parameters:
  • forwardOnly (bool) – If set to True, the fitting process is terminated after the forward pass. The resulting posterior distributions are so-called “filtering distributions” which - at each time step - only incorporate the information of past data points. This option thus emulates an online analysis.
  • evidenceOnly (bool) – If set to True, only forward pass is run and evidence is calculated. In contrast to the forwardOnly option, no posterior mean values are computed and no posterior distributions are stored.
  • silent (bool) – If set to True, reduced output is generated by the fitting method.
  • nJobs (int) – Number of processes to employ. Multiprocessing is based on the ‘pathos’ module.
getDD(names, plot=False, **kwargs)

See ChangepointStudy.getDurationDistribution().

getDurationDistribution(names, plot=False, **kwargs)

Computes the distribution of the number of time steps between two change/break-points. This distribution of duration is created from the joint distribution of the two specified change/break-points.

Parameters:
  • names (list) – List of two parameter names of change/break-points to display (first and second model parameter)
  • plot (bool) – If True, a bar chart of the distribution is created
  • **kwargs – All further keyword-arguments are passed to the bar-plot (see matplotlib documentation)
Returns:

The first array contains the number of time steps, the second one the corresponding

probability values.

Return type:

ndarray, ndarray

class bayesloop.core.HyperStudy(silent=False)

Infers hyper-parameter distributions. This class serves as an extension to the basic Study class and allows to compute the distribution of hyper-parameters of a given transition model. For further information, see the documentation of the fit-method of this class.

fit(forwardOnly=False, evidenceOnly=False, silent=False, nJobs=1, customHyperGrid=False)

This method over-rides the according method of the Study-class. It runs the algorithm for equally spaced hyper- parameter values as defined by the variable ‘hyperGrid’. The posterior sequence represents the average model of all analyses. Posterior mean values are computed from this average model.

Parameters:
  • forwardOnly (bool) – If set to True, the fitting process is terminated after the forward pass. The resulting posterior distributions are so-called “filtering distributions” which - at each time step - only incorporate the information of past data points. This option thus emulates an online analysis.
  • evidenceOnly (bool) – If set to True, only forward pass is run and evidence is calculated. In contrast to the forwardOnly option, no posterior mean values are computed and no posterior distributions are stored.
  • silent (bool) – If set to true, reduced output is created by this method.
  • nJobs (int) – Number of processes to employ. Multiprocessing is based on the ‘pathos’ module.
  • customHyperGrid (bool) – If set to true, the method “_createHyperGrid” is not called before starting the fit. This is used by the class “ChangepointStudy”, which employs a custom version of “_createHyperGrid”.
getHPD(name, plot=False, **kwargs)

See HyperStudy.getHyperParameterDistribution().

getHyperParameterDistribution(name, plot=False, **kwargs)

Computes marginal hyper-parameter distribution of a single hyper-parameter in a HyperStudy fit.

Parameters:
  • name (str) – Name of the hyper-parameter to display (first model hyper-parameter)
  • plot (bool) – If True, a bar chart of the distribution is created
  • **kwargs – All further keyword-arguments are passed to the bar-plot (see matplotlib documentation)
Returns:

The first array contains the hyper-parameter values, the second one the

corresponding probability values

Return type:

ndarray, ndarray

getJHPD(names, plot=False, figure=None, subplot=111, **kwargs)

See HyperStudy.getJointHyperParameterDistribution().

getJointHyperParameterDistribution(names, plot=False, figure=None, subplot=111, **kwargs)

Computes the joint distribution of two hyper-parameters of a HyperStudy and optionally creates a 3D bar chart. Note that the 3D plot can only be included in an existing plot by passing a figure object and subplot specification.

Parameters:
  • names (list) – List of two hyper-parameter names to display
  • plot (bool) – If True, a 3D-bar chart of the distribution is created
  • figure – In case the plot is supposed to be part of an existing figure, it can be passed to the method. By default, a new figure is created.
  • subplot – Characterization of subplot alignment, as in matplotlib. Default: 111
  • **kwargs – all further keyword-arguments are passed to the bar3d-plot (see matplotlib documentation)
Returns:

The first and second array contains the hyper-parameter values, the

third one the corresponding probability values

Return type:

ndarray, ndarray, ndarray

optimize(*args, **kwargs)

Uses the COBYLA minimization algorithm from SciPy to perform a maximization of the log-evidence with respect to all hyper-parameters (the parameters of the transition model) of a time seris model. The starting values are the values set by the user when defining the transition model.

For the optimization, only the log-evidence is computed and no parameter distributions are stored. When a local maximum is found, the parameter distribution is computed based on the optimal values for the hyper-parameters.

Parameters:
  • parameterList (list) – List of hyper-parameter names to optimize. For nested transition models with multiple, identical hyper-parameter names, the sub-model index can be provided. By default, all hyper-parameters are optimized.
  • forwardOnly (bool) – If set to True, the fitting process is terminated after the forward pass. The resulting posterior distributions are so-called “filtering distributions” which - at each time step - only incorporate the information of past data points.
  • - All other keyword parameters are passed to the 'minimize' routine of scipy.optimize. (**kwargs) –
plot(name, **kwargs)

Convenience method to plot the temporal evolution of observation model parameters, the distribution of a parameter at a specific time step, or the distribution of a hyper-parameter.

Parameters:
  • name (str) – name of the (hyper-)parameter to display
  • color – color from which a light colormap is created (for parameter evolution only)
  • gamma (float) – exponent for gamma correction of the displayed marginal distribution; default: 0.5 (for parameter evolution only)
  • t – Time step/stamp for which the parameter distribution is evaluated
  • density (bool) – If true, probability density is plotted; if false, probability values. Note: Only availble for parameters, not hyper-parameters.
  • kwargs – all further keyword-arguments are passed to the axes object of the plot
class bayesloop.core.OnlineStudy(storeHistory=False, silent=False)

Enables model selection for online data streams. This class builds on the Study-class and features a step-method to include new data points in the study as they arrive from a data stream. This online-analysis is performed in an forward-only way, resulting in filtering-distributions only. In contrast to a normal study, however, one can add multiple transition models to account for different types of parameter dynamics (similar to a Hyper study). The Online study then computes the probability distribution over all transition models for each new data point (or all past data points), enabling real-time model selection.

Parameters:storeHistory (bool) – If true, posterior distributions and their mean values, as well as hyper-posterior distributions are stored for all time steps.
add(name, transitionModel)

See OnlineStudy.addTransitionModel().

addTM(name, transitionModel)

See OnlineStudy.addTransitionModel().

addTransitionModel(name, transitionModel)

Adds a transition model to the list of transition models that are fitted in each time step. Note that a list of hyper-parameter values can be supplied.

Parameters:
  • name (str) – a custom name for this transition model to identify it in post-processing methods
  • transitionModel – instance of a transition model class.

Example

Here, ‘S’ denotes the OnlineStudy instance. In the first example, we assume a Poisson observation model and add a Gaussian random walk with varying standard deviation to the rate parameter ‘lambda’:

S.setObservationModel(bl.om.Poisson(‘lambda’, bl.oint(0, 6, 1000))) S.addTransitionModel(bl.tm.GaussianRandomWalk(‘sigma’, [0, 0.1, 0.2, 0.3], target=’lambda’))
fit(*args, **kwargs)

This method over-rides the according method of the Study-class. It runs the algorithm for equally spaced hyper- parameter values as defined by the variable ‘hyperGrid’. The posterior sequence represents the average model of all analyses. Posterior mean values are computed from this average model.

Parameters:
  • forwardOnly (bool) – If set to True, the fitting process is terminated after the forward pass. The resulting posterior distributions are so-called “filtering distributions” which - at each time step - only incorporate the information of past data points. This option thus emulates an online analysis.
  • evidenceOnly (bool) – If set to True, only forward pass is run and evidence is calculated. In contrast to the forwardOnly option, no posterior mean values are computed and no posterior distributions are stored.
  • silent (bool) – If set to true, reduced output is created by this method.
  • nJobs (int) – Number of processes to employ. Multiprocessing is based on the ‘pathos’ module.
  • customHyperGrid (bool) – If set to true, the method “_createHyperGrid” is not called before starting the fit. This is used by the class “ChangepointStudy”, which employs a custom version of “_createHyperGrid”.
getCHPD(name, plot=False, **kwargs)

See :meth:`.OnlineStudy.getCurrentHyperParameterDistribution.

getCPD(name, plot=False, density=True, **kwargs)

See OnlineStudy.getCurrentParameterDistribution().

getCTMD(local=False)

See OnlineStudy.getCurrentTransitionModelDistribution().

getCTMP(transitionModel, local=False)

See :meth:`.OnlineStudy.getCurrentTransitionModelProbability.

getCurrentHyperParameterDistribution(name, plot=False, **kwargs)

Computes marginal hyper-parameter distribution of a single hyper-parameter at the current time step in an OnlineStudy fit.

Parameters:
  • name (str) – hyper-parameter name
  • plot (bool) – If True, a bar chart of the distribution is created
  • **kwargs – All further keyword-arguments are passed to the bar-plot (see matplotlib documentation)
Returns:

The first array contains the hyper-parameter values, the second one the

corresponding probability values

Return type:

ndarray, ndarray

getCurrentParameterDistribution(name, plot=False, density=True, **kwargs)

Compute the current marginal parameter distribution.

Parameters:
  • name (str) – Name of the parameter to display
  • plot (bool) – If True, a plot of the distribution is created
  • density (bool) – If true, probability density is plotted; if false, probability values.
  • **kwargs – All further keyword-arguments are passed to the plot (see matplotlib documentation)
Returns:

The first array contains the parameter values, the second one the corresponding

probability values

Return type:

ndarray, ndarray

getCurrentParameterMeanValue(name)

Returns the posterior mean value for a given parameter of the observation model.

Parameters:name (str) – Name of the parameter
Returns:posterior mean value
Return type:float
getCurrentTransitionModelDistribution(local=False)

Returns the current probabilities for each transition model defined in the Online Study.

Parameters:local (bool) – If true, transition model distribution taking into account only the last data point is returned.
Returns:Arrays of transition model names and normalized probabilities.
Return type:ndarray, ndarray
getCurrentTransitionModelProbability(transitionModel, local=False)

Returns the current posterior probability for a specified transition model.

Parameters:
  • transitionModel (str) – Name of the transition model
  • local (bool) – If true, transition model probability taking into account only the last data point is returned.
Returns:

Posterior probability value for the specified transition model

Return type:

float

getHPD(t, name, plot=False, **kwargs)

See :meth:`.OnlineStudy.getHyperParameterDistribution.

getHPDs(name)

See :meth:`.OnlineStudy.getHyperParameterDistributions.

getHyperParameterDistribution(t, name, plot=False, **kwargs)

Computes marginal hyper-parameter distribution of a single hyper-parameter at a specific time step in an OnlineStudy fit. Only available if Online Study is created with flag ‘storeHistory=True’.

Parameters:
  • t (int) – Time step at which to compute distribution, or ‘avg’ for time-averaged distribution
  • name (str) – hyper-parameter name
  • plot (bool) – If True, a bar chart of the distribution is created
  • **kwargs – All further keyword-arguments are passed to the bar-plot (see matplotlib documentation)
Returns:

The first array contains the hyper-parameter values, the second one the

corresponding probability values

Return type:

ndarray, ndarray

getHyperParameterDistributions(name)

Computes marginal hyper-parameter distributions of a single hyper-parameter for all time steps in an OnlineStudy fit. Only available if Online Study is created with flag ‘storeHistory=True’.

Parameters:name (str) – hyper-parameter name
Returns:
The first array contains the hyper-parameter values, the second one the
corresponding probability values (first axis is time).
Return type:ndarray, ndarray
getHyperParameterMeanValue(t, name)

Computes the mean value of the joint hyper-parameter distribution for a given hyper-parameter at a given time step. Only available if Online Study is created with flag ‘storeHistory=True’.

Parameters:
  • t (int) – Time step at which to compute distribution
  • name (str) – name of hyper-parameter
Returns:

Array containing the mean values of all hyper-parameters of the given transition model

Return type:

ndarray

getHyperParameterMeanValues(name)

Computes the sequence of mean value of the joint hyper-parameter distribution for a given hyper-parameter for all time steps. Only available if Online Study is created with flag ‘storeHistory=True’.

Parameters:name (str) – name of hyper-parameter
Returns:Array containing the sequences of mean values of the given hyper-parameter
Return type:ndarray
getJointHyperParameterDistribution(names, plot=False, figure=None, subplot=111, **kwargs)

Computes the joint distribution of two hyper-parameters of a HyperStudy and optionally creates a 3D bar chart. Note that the 3D plot can only be included in an existing plot by passing a figure object and subplot specification.

Parameters:
  • names (list) – List of two hyper-parameter names to display
  • plot (bool) – If True, a 3D-bar chart of the distribution is created
  • figure – In case the plot is supposed to be part of an existing figure, it can be passed to the method. By default, a new figure is created.
  • subplot – Characterization of subplot alignment, as in matplotlib. Default: 111
  • **kwargs – all further keyword-arguments are passed to the bar3d-plot (see matplotlib documentation)
Returns:

The first and second array contains the hyper-parameter values, the

third one the corresponding probability values

Return type:

ndarray, ndarray, ndarray

getPD(t, name, plot=False, density=True, **kwargs)

See OnlineStudy.getParameterDistribution().

getPDs(name, plot=False, density=True, **kwargs)

See OnlineStudy.getParameterDistributions().

getParameterDistribution(t, name, plot=False, density=True, **kwargs)

Compute the marginal parameter distribution at a given time step. Only available if Online Study is created with flag ‘storeHistory=True’.

Parameters:
  • t (int, float) – Time step/stamp for which the parameter distribution is evaluated
  • name (str) – Name of the parameter to display
  • plot (bool) – If True, a plot of the distribution is created
  • density (bool) – If true, probability density is plotted; if false, probability values.
  • **kwargs – All further keyword-arguments are passed to the plot (see matplotlib documentation)
Returns:

The first array contains the parameter values, the second one the corresponding

probability values

Return type:

ndarray, ndarray

getParameterDistributions(name, plot=False, density=True, **kwargs)

Computes the time series of marginal posterior distributions with respect to a given model parameter. Only available if Online Study is created with flag ‘storeHistory=True’.

Parameters:
  • name (str) – Name of the parameter to display
  • plot (bool) – If True, a plot of the series of distributions is created (density map)
  • density (bool) – If true, probability density is plotted; if false, probability values.
  • **kwargs – All further keyword-arguments are passed to the plot (see matplotlib documentation)
Returns:

The first array contains the parameter values, the second one the sequence of

corresponding posterior distributions.

Return type:

ndarray, ndarray

getParameterMeanValue(t, name)

Returns the posterior mean value for a given parameter of the observation model at a specified time step. Only available if Online Study is created with flag ‘storeHistory=True’.

Parameters:
  • t (int) – Time step at which to compute parameter mean value
  • name (str) – Name of the parameter
Returns:

posterior mean value

Return type:

float

getParameterMeanValues(name)

Returns the posterior mean value for a given parameter of the observation model for all time steps. Only available if Online Study is created with flag ‘storeHistory=True’.

Parameters:name (str) – Name of the parameter
Returns:posterior mean values
Return type:ndarray
getTMPs(transitionModel, local=False)

See :meth:`.OnlineStudy.getTransitionModelProbabilities.

getTransitionModelDistributions(local=False)

The transition model distribution contains posterior probability values for all transition models included in the online study. This distribution is available for all time steps analyzed. Only available if Online Study is created with flag ‘storeHistory=True’.

Parameters:local (bool) – If true, transition model distributions taking into account only the data point at the corresponding time step is returned.
Returns:
Arrays containing the names and posterior probability values for all transition models
included in the online study for all time steps analyzed
Return type:ndarray, ndarray
getTransitionModelProbabilities(transitionModel, local=False)

Returns posterior probability values for a specified transition model. This distribution is available for all time steps analyzed. Only available if Online Study is created with flag ‘storeHistory=True’.

Parameters:
  • transitionModel (str) – Name of the transition model
  • local (bool) – If true, transition model probabilities taking into account only the data point at the corresponding time step is returned.
Returns:

Array containing the posterior probability values for the specified transition model for all time

steps analyzed

transitionModel(str): Name of the transition model

Return type:

ndarray

plot(name, **kwargs)

Convenience method to plot the temporal evolution of (hyper-)parameters, the distribution of a (hyper-)parameter at a specific time step, or the temporal evolution of the probability of a transition model.

Parameters:
  • name (str) – name of the (hyper-)parameter or transition model to display
  • color – color from which a light colormap is created (for (hyper-)parameter evolution only)
  • gamma (float) – exponent for gamma correction of the displayed marginal distribution; default: 0.5 (for (hyper-)parameter evolution only)
  • t – Time step/stamp for which the parameter distribution is evaluated
  • density (bool) – If true, probability density is plotted; if false, probability values. Note: Only availble for parameters, not hyper-parameters.
  • local (bool) – If true, transition model probabilities taking into account only the data point at the corresponding time step is returned
  • kwargs – all further keyword-arguments are passed to the axes object of the plot
plotHyperParameterEvolution(name, color='b', gamma=0.5, **kwargs)

Plot method to display a series of marginal posterior distributions corresponding to a single model parameter. This method includes the removal of plotting artefacts, gamma correction as well as an overlay of the posterior mean values. Only available if Online Study is created with flag ‘storeHistory=True’.

Parameters:
  • name (str) – hyper-parameter name
  • color – color from which a light colormap is created
  • gamma (float) – exponent for gamma correction of the displayed marginal distribution; default: 0.5
  • kwargs – all further keyword-arguments are passed to the plot of the posterior mean values
plotParameterEvolution(name, color='b', gamma=0.5, **kwargs)

Plots a series of marginal posterior distributions corresponding to a single model parameter, together with the posterior mean values. Only available if Online Study is created with flag ‘storeHistory=True’.

Parameters:
  • name (str) – Name of the parameter to display
  • color – color from which a light colormap is created
  • gamma (float) – exponent for gamma correction of the displayed marginal distribution; default: 0.5
  • kwargs – all further keyword-arguments are passed to the plot of the posterior mean values
setTransitionModelPrior(transitionModelPrior, silent=False)

Sets prior probabilities for transition models added to the online study instance.

Parameters:
  • transitionModelPrior – List/Array of probabilities, one for each transition model. If the list does not sum to one, it will be re-normalised.
  • silent – If true, no output is generated by this method.
step(dataPoint)

Update the current parameter distribution by adding a new data point to the data set.

Parameters:dataPoint (float, int, ndarray) – Float, int, or 1D-array of those (for multidimensional data).
class bayesloop.core.Study(silent=False)

Fits with fixed hyper-parameters and hyper-parameter optimization. This class implements a forward-backward-algorithm for analyzing time series data using hierarchical models. For efficient computation, all parameter distributions are discretized on a parameter grid.

eval(query, t=None, silent=False)

Convenience method to evaluate arithmetic operations on (hyper-)parameters. See parser.Parser() for more information. Note: This method is slow for evaluating a lot of queries subsequently, as it initializes a new Parser instance for each query. Use a dedicated Parser instance in that case (i.e.: P = Parser(S); P(‘query’)).

Parameters:
  • query (str) – (In-)equality to compute probability for, or just an arithmetic operation on parameters (the distribution will be returned in the latter case).
  • t – Time step/stamp to evaluate all parameters at
  • silent (bool) – If true, no output is generated by this method.
Returns:

Probability of queried (in-)equality, or values and corresponding probability values of derived distribution.

fit(forwardOnly=False, evidenceOnly=False, silent=False)

Computes the sequence of posterior distributions and evidence for each time step. Evidence is also computed for the complete data set.

Parameters:
  • forwardOnly (bool) – If set to True, the fitting process is terminated after the forward pass. The resulting posterior distributions are so-called “filtering distributions” which - at each time step - only incorporate the information of past data points. This option thus emulates an online analysis.
  • evidenceOnly (bool) – If set to True, only forward pass is run and evidence is calculated. In contrast to the forwardOnly option, no posterior mean values are computed and no posterior distributions are stored.
  • silent (bool) – If set to True, no output is generated by the fitting method.
getHyperParameterValue(name)

Returns the currently set value of a hyper-parameter. Note: The returned value is NOT an inferred value, but simply the last value used by the fitting method.

Parameters:name (str) – Hyper-parameter name.
Returns:current value of the specified hyper-parameter.
Return type:float
getPD(t, name, plot=False, density=True, **kwargs)

See Study.getParameterDistribution().

getPDs(name, plot=False, density=True, **kwargs)

See Study.getParameterDistributions().

getParameterDistribution(t, name, plot=False, density=True, **kwargs)

Compute the marginal parameter distribution at a given time step.

Parameters:
  • t – Time step/stamp for which the parameter distribution is evaluated (or ‘avg’ for time-averaged parameter distribution)
  • name (str) – Name of the parameter to display
  • plot (bool) – If True, a plot of the distribution is created
  • density (bool) – If true, probability density is returned; if false, probability values
  • **kwargs – All further keyword-arguments are passed to the plot (see matplotlib documentation)
Returns:

The first array contains the parameter values, the second one the corresponding

probability (density) values

Return type:

ndarray, ndarray

getParameterDistributions(name, plot=False, density=True, **kwargs)

Computes the time series of marginal posterior distributions with respect to a given model parameter.

Parameters:
  • name (str) – Name of the parameter to display
  • plot (bool) – If True, a plot of the series of distributions is created (density map)
  • density (bool) – If true, probability density is returned; if false, probability values
  • **kwargs – All further keyword-arguments are passed to the plot (see matplotlib documentation)
Returns:

The first array contains the parameter values, the second one the sequence of corresponding posterior distributions.

Return type:

ndarray, ndarray

getParameterMeanValues(name)

Returns posterior mean values for a parameter of the observation model.

Parameters:name (str) – Name of the parameter to display
Returns:array of posterior mean values for the selected parameter
Return type:ndarray
load(array, timestamps=None, silent=False)

See Study.loadData().

loadData(array, timestamps=None, silent=False)

Loads Numpy array as data.

Parameters:
  • array (ndarray) – Numpy array containing time series data
  • timestamps (ndarray) – Array of timestamps (same length as data array)
  • silent (bool) – If set to True, no output is generated by this method.
loadExampleData(silent=False)

Loads UK coal mining disaster data.

Parameters:silent (bool) – If set to True, no output is generated by this method.
optimize(parameterList=[], forwardOnly=False, **kwargs)

Uses the COBYLA minimization algorithm from SciPy to perform a maximization of the log-evidence with respect to all hyper-parameters (the parameters of the transition model) of a time seris model. The starting values are the values set by the user when defining the transition model.

For the optimization, only the log-evidence is computed and no parameter distributions are stored. When a local maximum is found, the parameter distribution is computed based on the optimal values for the hyper-parameters.

Parameters:
  • parameterList (list) – List of hyper-parameter names to optimize. For nested transition models with multiple, identical hyper-parameter names, the sub-model index can be provided. By default, all hyper-parameters are optimized.
  • forwardOnly (bool) – If set to True, the fitting process is terminated after the forward pass. The resulting posterior distributions are so-called “filtering distributions” which - at each time step - only incorporate the information of past data points.
  • - All other keyword parameters are passed to the 'minimize' routine of scipy.optimize. (**kwargs) –
plot(name, **kwargs)

Convenience method to plot the temporal evolution of observation model parameters, or the parameter distribution at a specific time step. Extended functionality for other study classes.

Parameters:
  • name (str) – name of the parameter to display
  • color – color from which a light colormap is created (for parameter evolution only)
  • gamma (float) – exponent for gamma correction of the displayed marginal distribution; default: 0.5 (for parameter evolution only)
  • t – Time step/stamp for which the parameter distribution is evaluated
  • density (bool) – If true, probability density is plotted; if false, probability values
  • kwargs – all further keyword-arguments are passed to the axes object of the plot
plotParameterEvolution(name, color='b', gamma=0.5, **kwargs)

Extended plot method to display a series of marginal posterior distributions corresponding to a single model parameter. In contrast to getMarginalParameterDistributions(), this method includes the removal of plotting artefacts, gamma correction as well as an overlay of the posterior mean values.

Parameters:
  • name (str) – name of the parameter to display
  • color – color from which a light colormap is created
  • gamma (float) – exponent for gamma correction of the displayed marginal distribution; default: 0.5
  • kwargs – all further keyword-arguments are passed to the plot of the posterior mean values
set(*args, **kwargs)

Set observation model or transition model, or both. See Study.setTransitionModel() and Study.setObservationModel().

Parameters:
  • args – Sequence of Observation model instance and Transition model instance, or just one of those two types
  • silent (bool) – If true, no output is printed by this method
setOM(L, silent=False)

See Study.setObservationModel().

setObservationModel(L, silent=False)

Sets observation model (likelihood function) for analysis and creates parameter grid for inference routine.

Parameters:
  • L – Observation model class (see observationModels.py)
  • silent (bool) – If set to True, no output is generated by this method.
setTM(T, silent=False)

See Study.setTransitionModel().

setTransitionModel(T, silent=False)

Set transition model which describes the parameter dynamics.

Parameters:
  • T – Transition model class (see transitionModels.py)
  • silent (bool) – If true, no output is printed by this method
simulate(x, t=None, density=False)

Computes the probability (density) for a set of observations, based on the inferred parameter distributions of a given time step, or based on the time-averaged parameter distributions. It can be used to compute the expected distribution of the observed data, taking into account the uncertainty in the parameters (as well as hyper-parameters for Hyper-Studies).

Parameters:
  • x – array of observation values
  • t – Time step/stamp for which the parameter distribution is evaluated
  • density – If true, probability density is computed; if false, probability value is computed
Returns:

probability (density) values corresponding to observation values

Return type:

ndarray

Observation models

SymPy(rv, *args, **kwargs) Model based on sympy.stats random variable.
SciPy(rv, *args, **kwargs) Model based on scipy.stats distribution.
NumPy(function, *args, **kwargs) Model based on NumPy functions.
Bernoulli([name, value, prior]) Bernoulli trial.
Poisson([name, value, prior]) Poisson observation model.
Gaussian([name1, value1, name2, value2, prior]) Gaussian observations.
GaussianMean([name, value, prior]) Observations with given error interval.
WhiteNoise([name, value, prior]) White noise process.
AR1([name1, value1, name2, value2, prior]) Auto-regressive process of first order.
ScaledAR1([name1, value1, name2, value2, prior]) Scaled auto-regressive process of first order. Recusively defined as

Note

You can use the short-form om to access all observation models:

import bayesloop as bl
L = bl.om.SymPy(...)

Observation models refer to likelihood functions, describing the probability (density) of a measurement at a certain time step, given the time-varying parameter values and past measurements. Observation models thus represent the low- level model in a bayesloop study, as compared to transition models that represent the high-level models and specify how the time-varying parameter change over time.

class bayesloop.observationModels.AR1(name1='correlation coefficient', value1=None, name2='noise amplitude', value2=None, prior=None)

Auto-regressive process of first order. This model describes a simple stochastic time series model with an exponential autocorrelation-function. It can be recursively defined as: d_t = r_t * d_(t-1) + s_t * e_t, with d_t being the data point at time t, r_t the correlation coefficient of subsequent data points and s_t being the noise amplitude of the process. e_t is distributed according to a standard normal distribution.

Parameters:
  • name1 (str) – custom name for correlation coefficient
  • value1 (list, tuple, ndarray) – Regularly spaced parameter values for the correlation coefficient
  • name2 (str) – custom name for noise amplitude
  • value2 (list, tuple, ndarray) – Regularly spaced parameter values for the noise amplitude
  • prior – custom prior distribution that may be passed as a Numpy array that has tha same shape as the parameter grid, as a(lambda) function or as a (list of) SymPy random variable(s)
estimateParameterValues(name, rawData)

Returns estimated boundaries based on the imported data. Is called in case fit method is called and no boundaries are defined.

Parameters:
  • name (str) – name of a parameter of the observation model
  • rawData (ndarray) – observed data points that may be used to determine appropriate parameter boundaries
Returns:

parameter boundaries.

Return type:

list

pdf(grid, dataSegment)

Probability density function of the Auto-regressive process of first order

Parameters:
  • grid (list) – Parameter grid for discrete values of the correlation coefficient and noise amplitude
  • dataSegment (ndarray) – Data segment from formatted data (in this case a pair of measurements)
Returns:

Discretized pdf (for data point d_t, given d_(t-1) and parameters).

Return type:

ndarray

class bayesloop.observationModels.Bernoulli(name='p', value=None, prior='Jeffreys')

Bernoulli trial. This distribution models a random variable that takes the value 1 with a probability of p, and a value of 0 with the probability of (1-p). Subsequent data points are considered independent. The model has one parameter, p, which describes the probability of “success”, i.e. to take the value 1.

Parameters:
  • name (str) – custom name for model parameter p
  • value (list, tuple, ndarray) – Regularly spaced parameter values for the model parameter p
  • prior – custom prior distribution that may be passed as a Numpy array that has tha same shape as the parameter grid, as a(lambda) function or as a (list of) SymPy random variable(s)
estimateParameterValues(name, rawData)

Returns appropriate boundaries based on the imported data. Is called in case fit method is called and no boundaries are defined.

Parameters:
  • name (str) – name of a parameter of the observation model
  • rawData (ndarray) – observed data points that may be used to determine appropriate parameter boundaries
Returns:

Regularly spaced parameter values for the specified parameter.

Return type:

list

jeffreys(x)

Jeffreys prior for Bernoulli model.

pdf(grid, dataSegment)

Probability density function of the Bernoulli model

Parameters:
  • grid (list) – Parameter grid for discrete values of the parameter p
  • dataSegment (ndarray) – Data segment from formatted data (in this case a single number of events)
Returns:

Discretized Bernoulli pdf (with same shape as grid)

Return type:

ndarray

class bayesloop.observationModels.Gaussian(name1='mean', value1=None, name2='std', value2=None, prior='Jeffreys')

Gaussian observations. All observations are independently drawn from a Gaussian distribution. The model has two parameters, mean and standard deviation.

Parameters:
  • name1 (str) – custom name for mean
  • value1 (list, tuple, ndarray) – Regularly spaced parameter values for the model parameter mean
  • name2 (str) – custom name for standard deviation
  • value2 (list, tuple, ndarray) – Regularly spaced parameter values for the model parameter standard deviation
  • prior – custom prior distribution that may be passed as a Numpy array that has tha same shape as the parameter grid, as a(lambda) function or as a (list of) SymPy random variable(s)
estimateParameterValues(name, rawData)

Returns appropriate boundaries based on the imported data. Is called in case fit method is called and no boundaries are defined.

Parameters:
  • name (str) – name of a parameter of the observation model
  • rawData (ndarray) – observed data points that may be used to determine appropriate parameter boundaries
Returns:

parameter boundaries.

Return type:

list

jeffreys(mu, sigma)

Jeffreys prior for Gaussian model.

pdf(grid, dataSegment)

Probability density function of the Gaussian model.

Parameters:
  • grid (list) – Parameter grid for discrete values of mean and standard deviation
  • dataSegment (ndarray) – Data segment from formatted data (containing a single measurement)
Returns:

Discretized Normal pdf (with same shape as grid).

Return type:

ndarray

class bayesloop.observationModels.GaussianMean(name='mean', value=None, prior=None)

Observations with given error interval. This observation model represents a Gaussian distribution with given standard deviation, only the mean of the distribution is a free parameter. It can be used if the data at hand contains for example mean values and corresponding error intervals. The data is supplied as an array of tuples, where each tuple contains the observed mean value and the corresponding standard deviation for an individual time step:

[["mean (t=1)", "std (t=1)"], ["mean (t=2)", "std (t=2)"], ...]
Parameters:
  • name (str) – custom name for the mean parameter
  • value (list, tuple, ndarray) – Regularly spaced parameter values for the mean parameter
  • prior – custom prior distribution that may be passed as a Numpy array that has tha same shape as the parameter grid, as a(lambda) function or as a (list of) SymPy random variable(s)
estimateParameterValues(name, rawData)

Returns appropriate boundaries based on the imported data. Is called in case fit method is called and no boundaries are defined.

Parameters:
  • name (str) – name of a parameter of the observation model
  • rawData (ndarray) – observed data points that may be used to determine appropriate parameter boundaries
Returns:

parameter boundaries.

Return type:

list

pdf(grid, dataSegment)

Probability density function of the Gaussian mean model.

Parameters:
  • grid (list) – Parameter grid for discrete values of the mean
  • dataSegment (ndarray) – Data segment from formatted data (containing a tuple of observed mean value and the given standard deviation)
Returns:

Discretized Normal pdf (with same shape as grid).

Return type:

ndarray

class bayesloop.observationModels.Laplace(name1='mean', value1=None, name2='scale', value2=None, prior='Jeffreys')

Laplace model. All observations are independently drawn from a Laplace (double-sided exponential) distribution. The model has two parameters, mean and scale.

Parameters:
  • name1 (str) – custom name for mean
  • value1 (list, tuple, ndarray) – Regularly spaced parameter values for the model parameter mean
  • name2 (str) – custom name for the scale parameter
  • value2 (list, tuple, ndarray) – Regularly spaced parameter values for the scale parameter
  • prior – custom prior distribution that may be passed as a Numpy array that has tha same shape as the parameter grid, as a(lambda) function or as a (list of) SymPy random variable(s)
estimateParameterValues(name, rawData)

Returns appropriate boundaries based on the imported data. Is called in case fit method is called and no boundaries are defined.

Parameters:
  • name (str) – name of a parameter of the observation model
  • rawData (ndarray) – observed data points that may be used to determine appropriate parameter boundaries
Returns:

parameter boundaries.

Return type:

list

jeffreys(mu, scale)

Jeffreys prior for the Laplace model.

pdf(grid, dataSegment)

Probability density function of the Laplace model.

Parameters:
  • grid (list) – Parameter grid for discrete values of mean and scale
  • dataSegment (ndarray) – Data segment from formatted data (containing a single measurement)
Returns:

Discretized Normal pdf (with same shape as grid).

Return type:

ndarray

class bayesloop.observationModels.NumPy(function, *args, **kwargs)

Model based on NumPy functions. This observation model class allows the user to create new observation models by expressing the likelihood function as a Python function that takes a data point (or vector) and arrays of parameter values as input, and outputs the probability density of those parameter values. Note that the Python function must be able to broadcast the arrays of parameter values, so that the output array has the same shape as the input arrays.

Parameters:
  • function – Likelihood function that takes a data point as the first argument and one NumPy array per model parameter (see example below).
  • args – succession of names and corresponding parameter values (using bayesloop.cint() or bayesloop.oint()) Example: ‘mu’, bl.cint(-1, 1, 100), ‘sigma’, bl.oint(0, 3, 100)
  • prior – custom prior distribution that may be passed as a NumPy array that has tha same shape as the parameter grid, as a(lambda) function or as a (list of) SymPy random variable(s)

Example:

# Assume that we have a data set of Gaussian random variates. We know the standard deviation for each random
# variate, but not the mean value. The data has the form [[variate_1, std_1], [variate_2, std_2], ...]. We can
# design an observation model to infer the mean value of the data taking into account the known standard
# deviation as follows:

import bayesloop as bl
S = bl.Study()

data = np.array([[0.12, 0.2], [-0.23, 0.2], [-0.03, 0.1], [0.12, 0.1]])
S.loadData(data)

def likelihood(data, mu):
    # read in one data point of the form [variate_n, std_n]
    x, std = data

    # define Gaussian likelihood function (pdf) with known standard deviation
    pdf = np.exp((x - mu)**2./(2*std**2.))/np.sqrt(2*np.pi*std**2.)

    return pdf

L = bl.om.NumPy(likelihood, 'mu', bl.cint(-3, 3, 1000))
S.setOM(L)
pdf(grid, dataSegment)

Probability density function of custom models

Parameters:
  • grid (list) – Parameter grid for discrete parameter values
  • dataSegment (ndarray) – Data segment from formatted data
Returns:

Discretized pdf (with same shape as grid)

Return type:

ndarray

class bayesloop.observationModels.ObservationModel

Observation model class that handles missing data points and multi-dimensional data. All observation models included in bayesloop inherit from this class.

processedPdf(grid, dataSegment)

This method is called by the fit-method of the Study class (and the step method of the OnlineStudy class) and processes multidimensional data and missing data and passes it to the pdf-method of the child class.

Parameters:
  • grid (list) – Discrete parameter grid
  • dataSegment (ndarray) – Data segment from formatted data
Returns:

Discretized pdf (with same shape as grid)

Return type:

ndarray

class bayesloop.observationModels.Poisson(name='lambda', value=None, prior='Jeffreys')

Poisson observation model. Subsequent data points are considered independent and distributed according to the Poisson distribution. Input data consists of integer values, typically the number of events in a fixed time interval. The model has one parameter, often denoted by lambda, which describes the rate of the modeled events.

Parameters:
  • name (str) – custom name for rate parameter lambda
  • value (list, tuple, ndarray) – Regularly spaced parameter values for the model parameter lambda
  • prior – custom prior distribution that may be passed as a Numpy array that has tha same shape as the parameter grid, as a(lambda) function or as a (list of) SymPy random variable(s)
estimateParameterValues(name, rawData)

Returns appropriate boundaries based on the imported data. Is called in case fit method is called and no boundaries are defined.

Parameters:
  • name (str) – name of a parameter of the observation model
  • rawData (ndarray) – observed data points that may be used to determine appropriate parameter boundaries
Returns:

parameter boundaries.

Return type:

list

jeffreys(x)

Jeffreys prior for Poisson model.

pdf(grid, dataSegment)

Probability density function of the Poisson model

Parameters:
  • grid (list) – Parameter grid for discrete rate (lambda) values
  • dataSegment (ndarray) – Data segment from formatted data (in this case a single number of events)
Returns:

Discretized Poisson pdf (with same shape as grid)

Return type:

ndarray

class bayesloop.observationModels.ScaledAR1(name1='correlation coefficient', value1=None, name2='standard deviation', value2=None, prior=None)
Scaled auto-regressive process of first order. Recusively defined as
d_t = r_t * d_(t-1) + s_t*sqrt(1 - (r_t)^2) * e_t,

with r_t the correlation coefficient of subsequent data points and s_t being the standard deviation of the observations d_t. For the standard AR1 process, s_t defines the noise amplitude of the process. For uncorrelated data, the two observation models are equal.

Parameters:
  • name1 (str) – custom name for correlation coefficient
  • value1 (list, tuple, ndarray) – Regularly spaced parameter values for the correlation coefficient
  • name2 (str) – custom name for standard deviation
  • value2 (list, tuple, ndarray) – Regularly spaced parameter values for the standard deviation
  • prior – custom prior distribution that may be passed as a Numpy array that has tha same shape as the parameter grid, as a(lambda) function or as a (list of) SymPy random variable(s)
estimateParameterValues(name, rawData)

Returns estimated boundaries based on the imported data. Is called in case fit method is called and no boundaries are defined.

Parameters:
  • name (str) – name of a parameter of the observation model
  • rawData (ndarray) – observed data points that may be used to determine appropriate parameter boundaries
Returns:

parameter boundaries.

Return type:

list

pdf(grid, dataSegment)

Probability density function of the Auto-regressive process of first order

Parameters:
  • grid (list) – Parameter grid for discerete values of the correlation coefficient and standard deviation
  • dataSegment (ndarray) – Data segment from formatted data (in this case a pair of measurements)
Returns:

Discretized pdf (for data point d_t, given d_(t-1) and parameters).

Return type:

ndarray

class bayesloop.observationModels.SciPy(rv, *args, **kwargs)

Model based on scipy.stats distribution. This observation model class allows to create new observation models on-the-fly from scipy.stats probability distributions.

Parameters:
  • rv – SciPy random distribution
  • args – succession of names and corresponding parameter values (using bayesloop.cint() or bayesloop.oint()) Example: ‘mu’, bl.cint(-1, 1, 100), ‘sigma’, bl.oint(0, 3, 100)
  • fixedParameters (dict) – Dictionary defining the names and values of fixed parameters
  • prior – custom prior distribution that may be passed as a Numpy array that has tha same shape as the parameter grid, as a(lambda) function or as a (list of) SymPy random variable(s)

Note that scipy.stats does not use the canonical way of naming the parameters of the probability distributions, but instead includes the parameter ‘loc’ (for discrete & continuous distributions) and ‘scale’ (for continuous only).

See http://docs.scipy.org/doc/scipy/reference/stats.html for further information on the available distributions and the parameter notation.

Example:

import bayesloop as bl
import scipy.stats
L = bl.om.SciPy(scipy.stats.poisson, 'mu', bl.oint(0, 6, 1000), fixedParameters={'loc': 0})

This will result in a model for poisson-distributed observations with a rate parameter ‘mu’ between 0 and 6. The distribution is not shifted (loc = 0).

Note that while the parameters ‘loc’ and ‘scale’ have default values in scipy.stats and do not necessarily need to be set, they have to be added to the fixedParameters dictionary in bayesloop to be treated as a constant. Using SciPy.stats distributions, bayesloop uses a flat prior by default.

pdf(grid, dataSegment)

Probability density function of custom scipy.stats models

Parameters:
  • grid (list) – Parameter grid for discrete rate values
  • dataSegment (ndarray) – Data segment from formatted data
Returns:

Discretized pdf (with same shape as grid)

Return type:

ndarray

class bayesloop.observationModels.SymPy(rv, *args, **kwargs)

Model based on sympy.stats random variable. This observation model class allows to create new observation models on-the-fly from sympy.stats random variables.

Parameters:
  • rv – SymPy random symbol
  • args – succession of names and corresponding parameter values (using bayesloop.cint() or bayesloop.oint()) Example: ‘mu’, bl.cint(-1, 1, 100), ‘sigma’, bl.oint(0, 3, 100)
  • determineJeffreysPrior (bool) – If set to true, Jeffreys prior is analytically derived
  • prior – custom prior distribution that may be passed as a Numpy array that has tha same shape as the parameter grid, as a(lambda) function or as a (list of) SymPy random variable(s)

Observation models can be defined symbolically using the SymPy module in a convenient way. In contrast to the SciPy probability distributions, fixed parameters are directly set and do not have to be passed as a dictionary.

See http://docs.sympy.org/dev/modules/stats.html for further information on the available distributions and the parameter notation.

Example:

import bayesloop as bl
from sympy import Symbol
from sympy.stats import Normal

mu = 4
sigma = Symbol('sigma', positive=True)
rv = Normal('normal', mu, sigma)

L = bl.om.SymPy(rv, {'sigma': bl.oint(0, 3, 1000)})

This will result in a model for normally distributed observations with a fixed ‘mu’ (mean) of 4, leaving ‘sigma’ (the standard deviation) as the only free parameter to be inferred. Using SymPy random variables to create an observation model, bayesloop tries to determine the corresponding Jeffreys prior. This behavior can be turned off by setting the keyword-argument ‘determineJeffreysPrior=False’.

pdf(grid, dataSegment)

Probability density function of custom sympy.stats models

Parameters:
  • grid (list) – Parameter grid for discrete rate values
  • dataSegment (ndarray) – Data segment from formatted data
Returns:

Discretized pdf (with same shape as grid)

Return type:

ndarray

class bayesloop.observationModels.WhiteNoise(name='std', value=None, prior='Jeffreys')

White noise process. All observations are independently drawn from a Gaussian distribution with zero mean and a finite standard deviation, the noise amplitude. This process is basically an auto-regressive process with zero correlation.

Parameters:
  • name (str) – custom name for standard deviation
  • value (list, tuple, ndarray) – Regularly spaced parameter values for the model parameter standard deviation
  • prior – custom prior distribution that may be passed as a Numpy array that has tha same shape as the parameter grid, as a(lambda) function or as a (list of) SymPy random variable(s)
estimateParameterValues(name, rawData)

Returns appropriate boundaries based on the imported data. Is called in case fit method is called and no boundaries are defined.

Parameters:
  • name (str) – name of a parameter of the observation model
  • rawData (ndarray) – observed data points that may be used to determine appropriate parameter boundaries
Returns:

parameter boundaries.

Return type:

list

jeffreys(sigma)

Jeffreys prior for Gaussian model.

pdf(grid, dataSegment)

Probability density function of the white noise process.

Parameters:
  • grid (list) – Parameter grid for discrete values of noise amplitude
  • dataSegment (ndarray) – Data segment from formatted data (containing a single measurement)
Returns:

Discretized pdf (with same shape as grid).

Return type:

ndarray

Transition models

Static() Constant parameters over time.
Deterministic([function, target, prior]) Deterministic parameter variations.
GaussianRandomWalk([name, value, target, prior]) Gaussian parameter fluctuations.
AlphaStableRandomWalk([name1, value1, …]) Parameter changes follow alpha-stable distribution.
ChangePoint([name, value, prior]) Abrupt parameter change at a specified time step.
RegimeSwitch([name, value, prior]) Small probability for a parameter jump in each time step.
Independent() Observations are treated as independent.
NotEqual([name, value, prior]) Unlikely parameter values are preferred in the next time step.
CombinedTransitionModel(*args) Different models act at the same time.
SerialTransitionModel(*args) Different models act at different time steps.

Note

You can use the short-form tm to access all transition models:

import bayesloop as bl
T = bl.tm.ChangePoint(...)

Transition models refer to stochastic or deterministic models that describe how the time-varying parameter values of a given time series model change from one time step to another. The transition model can thus be compared to the state transition matrix of Hidden Markov models. However, instead of explicitly stating transition probabilities for all possible states, a transformation is defined that alters the distribution of the model parameters in one time step according to the transition model. This altered distribution is subsequently used as a prior distribution in the next time step.

class bayesloop.transitionModels.AlphaStableRandomWalk(name1='c', value1=None, name2='alpha', value2=None, target=None, prior=(None, None))

Parameter changes follow alpha-stable distribution. This model assumes that parameter changes are distributed according to the symmetric alpha-stable distribution. For each parameter, two hyper-parameters can be set: the width of the distribution (c) and the shape (alpha).

Parameters:
  • name1 (str) – custom name of the hyper-parameter c
  • value1 (float, list, tuple, ndarray) – width(s) of the distribution (c >= 0).
  • name2 (str) – custom name of the hyper-parameter alpha
  • value2 (float, list, tuple, ndarray) – shape(s) of the distribution (0 < alpha <= 2).
  • target (str) – parameter name of the observation model to apply transition model to
  • prior – list of two hyper-prior distributions, where each may be passed as a(lambda) function, as a SymPy random variable, or directly as a Numpy array with probability values for each hyper-parameter value
computeForwardPrior(posterior, t)

Compute new prior from old posterior (moving forwards in time).

Parameters:
  • posterior (ndarray) – Parameter distribution from current time step
  • t (int) – integer time step
Returns:

Prior parameter distribution for subsequent time step

Return type:

ndarray

convolve(distribution)

Convolves distribution with alpha-stable kernel.

Parameters:distribution (ndarray) – Discrete probability distribution to convolve.
Returns:convolution
Return type:ndarray
createKernel(c, alpha, axis)

Create alpha-stable distribution on a grid as a kernel for convolution.

Parameters:
  • c (float) – Scale parameter.
  • alpha (float) – Tail parameter (alpha = 1: Cauchy, alpha = 2: Gauss)
  • axis (int) – Axis along which the distribution is defined, for 2D-Kernels
Returns:

kernel

Return type:

ndarray

class bayesloop.transitionModels.BreakPoint(name='tBreak', value=None, prior=None)

Break-point. This class can only be used to specify break-point within a SerialTransitionModel instance.

Parameters:
  • name (str) – custom name of the hyper-parameter tBreak
  • value (int, list, tuple, ndarray) – Value(s) of the time step(s) of the break point
  • prior – hyper-prior distribution that may be passed as a(lambda) function, as a SymPy random variable, or directly as a Numpy array with probability values for each hyper-parameter value
class bayesloop.transitionModels.ChangePoint(name='tChange', value=None, prior=None)

Abrupt parameter change at a specified time step. Parameter values are allowed to change only at a single point in time, right after a specified time step (Hyper-parameter tChange). Note that a uniform parameter distribution is used at this time step to achieve this “reset” of parameter values.

Parameters:
  • name (str) – custom name of the hyper-parameter tChange
  • value (int, list, tuple, ndarray) – Integer value(s) of the time step of the change point
  • prior – hyper-prior distribution that may be passed as a(lambda) function, as a SymPy random variable, or directly as a Numpy array with probability values for each hyper-parameter value
computeForwardPrior(posterior, t)

Compute new prior from old posterior (moving forwards in time).

Parameters:
  • posterior (ndarray) – Parameter distribution from current time step
  • t (int) – integer time step
Returns:

Prior parameter distribution for subsequent time step

Return type:

ndarray

class bayesloop.transitionModels.CombinedTransitionModel(*args)

Different models act at the same time. This class allows to combine different transition models to be able to explore more complex parameter dynamics. All sub-models are passed to this class as arguments on initialization. Note that a different order of the sub-models can result in different parameter dynamics.

Parameters:*args – Sequence of transition models
computeForwardPrior(posterior, t)

Compute new prior from old posterior (moving forwards in time).

Parameters:
  • posterior (ndarray) – Parameter distribution from current time step
  • t (int) – integer time step
Returns:

Prior parameter distribution for subsequent time step

Return type:

ndarray

class bayesloop.transitionModels.Deterministic(function=None, target=None, prior=None)

Deterministic parameter variations. Given a function with time as the first argument and further keyword-arguments as hyper-parameters, plus the name of a parameter of the observation model that is supposed to follow this function over time, this transition model shifts the parameter distribution accordingly. Note that these models are entirely deterministic, as the hyper-parameter values are entered by the user. However, the hyper-parameter distributions can be inferred using a Hyper-study or can be optimized using the ‘optimize’ method of the Study class.

Parameters:
  • function (function) – A function that takes the time as its first argument and further takes keyword-arguments that correspond to the hyper-parameters of the transition model which the function defines.
  • target (str) – The observation model parameter that is manipulated according to the function defined above.
  • prior – List of hyper-prior distributions (one for each hyper-parameter), where each may be passed as a(lambda) function, as a SymPy random variable, or directly as a Numpy array with probability values for each hyper-parameter value

Example:

def quadratic(t, a=0, b=0):
    return a*(t**2) + b*t

S = bl.Study()
...
S.setObservationModel(bl.om.WhiteNoise('std', bl.oint(0, 3, 1000)))
S.setTransitionModel(bl.tm.Deterministic(quadratic, target='signal'))
computeForwardPrior(posterior, t)

Compute new prior from old posterior (moving forwards in time).

Parameters:
  • posterior (ndarray) – Parameter distribution from current time step
  • t (int, float) – time stamp (integer time index by default)
Returns:

Prior parameter distribution for subsequent time step

Return type:

ndarray

class bayesloop.transitionModels.GaussianRandomWalk(name='sigma', value=None, target=None, prior=None)

Gaussian parameter fluctuations. This model assumes that parameter changes are Gaussian-distributed. The standard deviation can be set individually for each model parameter.

Parameters:
  • name (str) – custom name of the hyper-parameter sigma
  • value (float, list, tuple, ndarray) – standard deviation(s) of the Gaussian random walk for target parameter
  • target (str) – parameter name of the observation model to apply transition model to
  • prior – hyper-prior distribution that may be passed as a(lambda) function, as a SymPy random variable, or directly as a Numpy array with probability values for each hyper-parameter value
computeForwardPrior(posterior, t)

Compute new prior from old posterior (moving forwards in time).

Parameters:
  • posterior (ndarray) – Parameter distribution from current time step
  • t (int) – integer time step
Returns:

Prior parameter distribution for subsequent time step

Return type:

ndarray

class bayesloop.transitionModels.Independent

Observations are treated as independent. This transition model restores the prior distribution for the parameters at each time step, effectively assuming independent observations.

Note

Mostly used with an instance of OnlineStudy.

computeForwardPrior(posterior, t)

Compute new prior from old posterior (moving forwards in time).

Parameters:
  • posterior (ndarray) – Parameter distribution from current time step
  • t (int) – integer time step
Returns:

Prior parameter distribution for subsequent time step

Return type:

ndarray

class bayesloop.transitionModels.NotEqual(name='log10pMin', value=None, prior=None)

Unlikely parameter values are preferred in the next time step. Assumes an “inverse” parameter distribution at each new time step. The new prior is derived by substracting the posterior probability values from their maximal value and subsequently re-normalizing. To assure that no parameter value is set to zero probability, one may specify a minimal probability for all parameter values. This transition model is mostly used in instances of OnlineStudy to detect time step when parameter distributions change significantly.

Parameters:
  • name (str) – custom name of the hyper-parameter log10pMin
  • value (float, list, tuple, ndarray) – Log10-value of the minimal probability that is set to all possible parameter values of the inverted parameter distribution
  • prior – hyper-prior distribution that may be passed as a(lambda) function, as a SymPy random variable, or directly as a Numpy array with probability values for each hyper-parameter value

Note

Mostly used with an instance of OnlineStudy.

computeForwardPrior(posterior, t)

Compute new prior from old posterior (moving forwards in time).

Parameters:
  • posterior (ndarray) – Parameter distribution from current time step
  • t (int) – integer time step
Returns:

Prior parameter distribution for subsequent time step

Return type:

ndarray

class bayesloop.transitionModels.RegimeSwitch(name='log10pMin', value=None, prior=None)

Small probability for a parameter jump in each time step. In case the number of change-points in a given data set is unknown, the regime-switching model may help to identify potential abrupt changes in parameter values. At each time step, all parameter values within the set boundaries are assigned a minimal probability density of being realized in the next time step, effectively allowing abrupt parameter changes at every time step.

Parameters:
  • name (str) – custom name of the hyper-parameter log10pMin
  • value (float, list, tuple, ndarray) – Minimal probability density (log10 value) that is assigned to every parameter value
  • prior – hyper-prior distribution that may be passed as a(lambda) function, as a SymPy random variable, or directly as a Numpy array with probability values for each hyper-parameter value
computeForwardPrior(posterior, t)

Compute new prior from old posterior (moving forwards in time).

Parameters:
  • posterior (ndarray) – Parameter distribution from current time step
  • t (int) – integer time step
Returns:

Prior parameter distribution for subsequent time step

Return type:

ndarray

class bayesloop.transitionModels.SerialTransitionModel(*args)

Different models act at different time steps. To model fundamental changes in parameter dynamics, different transition models can be serially coupled. Depending on the time step, a corresponding sub-model is chosen to compute the new prior distribution from the posterior distribution. If a break-point lies in between two transition models, the parameter values do not change abruptly at the time step of the break-point, whereas a change-point not only changes the transition model, but also allows the parameters to change (the parameter distribution is re-set to the prior distribution).

Parameters:*args – Sequence of transition models and break-points/change-points (for n models, n-1 break-points/change-points have to be provided)

Example:

T = bl.tm.SerialTransitionModel(bl.tm.Static(),
                                bl.tm.BreakPoint('t_1', 50),
                                bl.tm.RegimeSwitch('log10pMin', -7),
                                bl.tm.BreakPoint('t_2', 100),
                                bl.tm.GaussianRandomWalk('sigma', 0.2, target='x'))

In this example, parameters are assumed to be constant until ‘t_1’ (time step 50), followed by a regime-switching- process until ‘t_2’ (time step 100). Finally, we assume Gaussian parameter fluctuations for parameter ‘x’ until the last time step. Note that models and time steps do not necessarily have to be passed in an alternating way.

computeForwardPrior(posterior, t)

Compute new prior from old posterior (moving forwards in time).

Parameters:
  • posterior (ndarray) – Parameter distribution from current time step
  • t (int) – integer time step
Returns:

Prior parameter distribution for subsequent time step

Return type:

ndarray

class bayesloop.transitionModels.Static

Constant parameters over time. This trivial model assumes no change of parameter values over time.

computeForwardPrior(posterior, t)

Compute new prior from old posterior (moving forwards in time).

Parameters:
  • posterior (ndarray) – Parameter distribution from current time step
  • t (int) – integer time step
Returns:

Prior parameter distribution for subsequent time step

Return type:

ndarray

class bayesloop.transitionModels.TransitionModel

Parent class for transition models. All transition models inherit from this class. It is currently only used to identify transition models as such.

File I/O

The following functions save or load instances of all Study types using the Python package dill.

bayesloop.fileIO.load(filename)

Load an instance of a bayesloop study class that was saved using the bayesloop.save() function.

Parameters:filename (str) – Path + filename to stored bayesloop study
Returns:Study instance
bayesloop.fileIO.save(filename, study)

Save an instance of a bayesloop study class to file.

Parameters:
  • filename (str) – Path + filename to store bayesloop study
  • study – Instance of study class (Study, HyperStudy, etc.)

Note

Both file I/O functions are imported directly into the module namespace for convenient access.

import bayesloop as bl
S = bl.Study()
...
bl.save('test.bl', S)
...
S = bl.load('test.bl')

Probability Parser

class bayesloop.Parser(*studies)

Computes derived probability values and distributions based on arithmetic operations of (hyper-)parameters.

Parameters:studies – One or more bayesloop study instances. All (hyper-)parameters in the specified study object(s) will be available to the parser.

Example:

S = bl.Study()
...
P = bl.Parser(S)
P('sqrt(rate@1910) > 1.')