# model - MCMC model types¶

 MCMCModel MCMCM model abstract base class. Density Construct an MCMC model from a probablility density function. LogDensity Construct an MCMC model from a log probablility density function. Simulation Construct an MCMC model from a simulation function. MVNormal multivariate normal negative log likelihood function Mixture Create a mixture model from a list of weighted density models.

MCMC model types

## Usage¶

First create a bumps.dream.bounds.Bounds object. This stores the ranges available on the parameters, and controls how values outside the range are handled:

M_bounds = bounds(minx, maxx, style='reflect|clip|fold|randomize|none')


For simple functions you can use one of the existing models.

If your model f computes the probability density, use Density:

M = Density(f, bounds=M_bounds)


If your model f computes the log probability density, use LogDensity:

M = LogDensity(f, bounds=M_bounds)


If your model f computes a simulation which returns a vector, and you have data associated with the simulation, use Simulation:

M = Simulation(f, data=data, bounds=M_bounds)


The measurement data can have a 1-sigma uncertainty associated with it, as well as a gamma factor if the uncertainty distribution has non-Gaussian kurtosis associated with it.

Multivariate normal distribution:

M = MVNormal(mu, sigma)


Mixture models:

M = Mixture(M1, w1, M2, w2, ...)


For more complex functions, you can subclass MCMCModel:

class Model(MCMCModel):
def __init__(self, ..., bounds=None, ...):
...
self.bounds = bounds
...
def nnlf(self, x):
"Return the negative log likelihood of seeing x"
p = probability of seeing x
return -log(p)

M = Model(..., bounds=M_bounds, ...)


The MCMC program uses only two methods from the model:

apply_bounds(pop)
log_density(pop)


If your model provides these methods, you will not need to subclass MCMCModel in order to interact with DREAM.

## Compatibility with matlab DREAM¶

First generate a bounds handling function:

M_bounds = bounds(ParRange.minn, ParRange.maxn)


Then generate a model, depending on what kind of function you have.

Option 1. Model directly computes posterior density:

model = Density(f, bounds=M_bounds)


Option 2. Model computes simulation, data has known 1-sigma uncertainty:

model = Simulation(f, data=Measurement.MeasData, bounds=M_bounds,
sigma=Measurement.Sigma, gamma = MCMCPar.Gamma)


Option 3. Model computes simulation, data has unknown 1-sigma uncertainty:

model = Simulation(f, data=Measurement.MeasData, bounds=M_bounds,
gamma = MCMCPar.Gamma)


Option 4. Model directly computes log posterior density:

model = LogDensity(f, bounds=M_bounds)


Option 5 is like option 2 but the reported likelihoods do not take the 1-sigma uncertainty into account. The metropolis steps are still based on the 1-sigma uncertainty, so use the style given in option 2 for this case.

class bumps.dream.model.MCMCModel[source]

Bases: object

MCMCM model abstract base class.

Each model must have a negative log likelihood function which operates on a point x, returning the negative log likelihood, or inf if the point is outside the domain.

bounds = None
labels = None
log_density(x)[source]
map(pop)[source]
nllf(x)[source]
plot(x)[source]
class bumps.dream.model.Density(f, bounds=None, labels=None)[source]

Construct an MCMC model from a probablility density function.

f is the density function

bounds = None
labels = None
log_density(x)
map(pop)
nllf(x)[source]
plot(x)
class bumps.dream.model.LogDensity(f, bounds=None, labels=None)[source]

Construct an MCMC model from a log probablility density function.

f is the log density function

bounds = None
labels = None
log_density(x)
map(pop)
nllf(x)[source]
plot(x)
class bumps.dream.model.Simulation(f=None, bounds=None, data=None, sigma=1, gamma=0, labels=None)[source]

Construct an MCMC model from a simulation function.

f is the function which simulates the data data is the measurement(s) to compare it to sigma is the 1-sigma uncertainty of the measurement(s). gamma in (-1, 1] represents kurtosis on the data measurement uncertainty.

Data is assumed to come from an exponential power density:

p(v|S, G) = w(G)/S exp(-c(G) |v/S|^(2/(1+G)))


where S is sigma and G is gamma.

The values of sigma and gamma can be uniform or can vary with the individual measurement points.

Certain values of gamma select particular distributions::
G = 0: normal G = 1: double exponential G -> -1: uniform
bounds = None
labels = None
log_density(x)
map(pop)
nllf(x)[source]
plot(x)[source]
class bumps.dream.model.MVNormal(mu, sigma)[source]

multivariate normal negative log likelihood function

bounds = None
labels = None
log_density(x)
map(pop)
nllf(x)[source]
plot(x)
class bumps.dream.model.Mixture(*args)[source]

Create a mixture model from a list of weighted density models.

MixtureModel( M1, w1, M2, w2, …)

Models M1, M2, … are MCMC models with M.nllf(x) returning the negative log likelihood of x. Weights w1, w2, … are arbitrary scalars.

bounds = None
labels = None
log_density(x)
map(pop)
nllf(x)[source]
plot(x)