# Bumps 0.9.1 documentation

## 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.Density(f, bounds=None, labels=None)

  Bases: `MCMCModel`

  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)
  plot(x)

class bumps.dream.model.LogDensity(f, bounds=None, labels=None)

  Bases: `MCMCModel`

  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)
  plot(x)

class bumps.dream.model.MCMCModel

  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)
  map(pop)
  nllf(x)
  plot(x)

class bumps.dream.model.MVNormal(mu, sigma)

  Bases: `MCMCModel`

  multivariate normal negative log likelihood function

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

class bumps.dream.model.Mixture(*args)

  Bases: `MCMCModel`

  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)
  plot(x)

class bumps.dream.model.Simulation(f=None, bounds=None, data=None, sigma=1, gamma=0, labels=None)

  Bases: `MCMCModel`

  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)
  plot(x)