# API Reference¶

## Study types¶

 Study() Fits with fixed hyper-parameters and hyper-parameter optimization. HyperStudy() Infers hyper-parameter distributions. ChangepointStudy() Infers change-points and structural breaks. OnlineStudy([storeHistory]) 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

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)
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) The first array contains the number of time steps, the second one the corresponding probability values. ndarray, ndarray
class bayesloop.core.HyperStudy

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, referenceLogEvidence=None, 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. referenceLogEvidence (float) – Reference value to increase numerical stability when computing average posterior sequence. Ideally, this value represents the mean value of all log-evidence values. As an approximation, the default behavior sets it to the log-evidence of the first set of hyper-parameter values. 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)
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) The first array contains the hyper-parameter values, the second one the corresponding probability values ndarray, ndarray
getJHPD(names, plot=False, figure=None, subplot=111, **kwargs)
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) The first and second array contains the hyper-parameter values, the third one the corresponding probability values ndarray, ndarray, ndarray
class bayesloop.core.OnlineStudy(storeHistory=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.
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’))
getCHPD(name, plot=False, **kwargs)

See :meth:.OnlineStudy.getCurrentHyperParameterDistribution.

getCPD(name, plot=False, **kwargs)
getCTMD(local=False)
getCTMP(transitionModel, local=False)

See :meth:.OnlineStudy.getCurrentTransitionModelProbability.

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

Computes marginal hyper-parameter distribution of a single hyper-parameter at a specific 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) The first array contains the hyper-parameter values, the second one the corresponding probability values ndarray, ndarray
getCurrentParameterDistribution(name, plot=False, **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 **kwargs – All further keyword-arguments are passed to the plot (see matplotlib documentation) The first array contains the parameter values, the second one the corresponding probability values ndarray, ndarray
getCurrentParameterMeanValue(name)

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

Parameters: name (str) – Name of the parameter posterior mean value 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. Arrays of transition model names and normalized probabilities. 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. Posterior probability value for the specified transition model 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.

Parameters: t (int) – Time step at which to compute 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) The first array contains the hyper-parameter values, the second one the corresponding probability values ndarray, ndarray
getHyperParameterDistributions(name)

Computes marginal hyper-parameter distributions of a single hyper-parameter for all time steps in an OnlineStudy fit.

Parameters: name (str) – hyper-parameter name The first array contains the hyper-parameter values, the second one the corresponding probability values (first axis is time). 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 Array containing the mean values of all hyper-parameters of the given transition model ndarray
getHyperParameterMeanValues(name)

Computes the sequence of mean value of the joint hyper-parameter distribution for a given hyper-parameter for all time steps.

Parameters: name (str) – name of hyper-parameter Array containing the sequences of mean values of the given hyper-parameter ndarray
getPD(t, name, plot=False, **kwargs)
getPDs(name, plot=False, **kwargs)
getParameterDistribution(t, name, plot=False, **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 **kwargs – All further keyword-arguments are passed to the plot (see matplotlib documentation) The first array contains the parameter values, the second one the corresponding probability values ndarray, ndarray
getParameterDistributions(name, plot=False, **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) **kwargs – All further keyword-arguments are passed to the plot (see matplotlib documentation) The first array contains the parameter values, the second one the sequence of corresponding posterior distributions. ndarray, 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. Arrays containing the names and posterior probability values for all transition models included in the online study for all time steps analyzed 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. Array containing the posterior probability values for the specified transition model for all time steps analyzed transitionModel(str): Name of the transition model ndarray
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.

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

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.

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. current value of the specified hyper-parameter. float
getPD(t, name, plot=False, **kwargs)
getPDs(name, plot=False, **kwargs)
getParameterDistribution(t, name, plot=False, **kwargs)

Compute the marginal parameter distribution at a given time step.

Parameters: t – 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 **kwargs – All further keyword-arguments are passed to the plot (see matplotlib documentation) The first array contains the parameter values, the second one the corresponding probability values ndarray, ndarray
getParameterDistributions(name, plot=False, **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) **kwargs – All further keyword-arguments are passed to the plot (see matplotlib documentation) The first array contains the parameter values, the second one the sequence of corresponding posterior distributions. ndarray, ndarray
getParameterMeanValues(name)

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

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

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=[], **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. - All other keyword parameters are passed to the 'minimize' routine of scipy.optimize. (**kwargs) –
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
setOM(L, silent=False)
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)
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

## Observation models¶

 SymPy(rv[, valueDict, prior, ...]) Model based on sympy.stats random variable. SciPy(rv[, valueDict, prior, fixedParameters]) Model based on scipy.stats distribution. 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.

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 parameter boundaries. 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) Discretized pdf (for data point d_t, given d_(t-1) and parameters). 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 Regularly spaced parameter values for the specified parameter. 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) Discretized Bernoulli pdf (with same shape as grid) 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 parameter boundaries. 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) Discretized Normal pdf (with same shape as grid). 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 parameter boundaries. 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) Discretized Normal pdf (with same shape as grid). 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 Discretized pdf (with same shape as grid) 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 parameter boundaries. 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) Discretized Poisson pdf (with same shape as grid) 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 parameter boundaries. 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) Discretized pdf (for data point d_t, given d_(t-1) and parameters). ndarray
class bayesloop.observationModels.SciPy(rv, valueDict={}, prior=None, fixedParameters={})

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 valueDict – dictionary containing names and corresponding parameter values (using bayesloop.cint() or bayesloop.oint()) 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 Discretized pdf (with same shape as grid) ndarray
class bayesloop.observationModels.SymPy(rv, valueDict={}, prior=None, determineJeffreysPrior=True)

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 valueDict – dictionary containing names and corresponding parameter values (using bayesloop.cint() or bayesloop.oint()) 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 Discretized pdf (with same shape as grid) 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 parameter boundaries. 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) Discretized pdf (with same shape as grid). 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 Prior parameter distribution for subsequent time step ndarray
convolve(distribution)

Convolves distribution with alpha-stable kernel.

Parameters: distribution (ndarray) – Discrete probability distribution to convolve. convolution 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 kernel 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 Prior parameter distribution for subsequent time step 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 Prior parameter distribution for subsequent time step 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)))

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) Prior parameter distribution for subsequent time step 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 Prior parameter distribution for subsequent time step 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 Prior parameter distribution for subsequent time step 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 Prior parameter distribution for subsequent time step 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 Prior parameter distribution for subsequent time step 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 Prior parameter distribution for subsequent time step 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 Prior parameter distribution for subsequent time step ndarray

## 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 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)
...
`