pydream package

pydream.Dream module

class pydream.Dream.Dream(model, variables=None, nseedchains=None, nCR=3, adapt_crossover=True, adapt_gamma=False, crossover_burnin=None, DEpairs=1, lamb=0.05, zeta=1e-12, history_thin=10, snooker=0.1, p_gamma_unity=0.2, gamma_levels=1, start_random=True, save_history=True, history_file=False, crossover_file=False, gamma_file=False, multitry=False, parallel=False, verbose=False, model_name=False, hardboundaries=True, **kwargs)

An implementation of the MT-DREAM_(ZS) algorithm introduced in:

Laloy, E. & Vrugt, J. A. High-dimensional posterior exploration of hydrologic models using multiple-try DREAM_(ZS) and high-performance computing. Water Resources Research 48, W01526 (2012).

Parameters:

variables : iterable of instance(s) of SampledParam class

Model parameters to be sampled with specified prior.

nseedchains : int

Number of draws with which to initialize the DREAM history. Default = 10 * n dimensions

nCR : int

Number of crossover values to sample from during run (and to fit during crossover burn-in period). Default = 3

adapt_crossover : bool

Whether to adapt crossover values during the burn-in period. Default is to adapt.

crossover_burnin : int

Number of iterations to fit the crossover values. Defaults to 10% of total iterations.

DEpairs : int or list

Number of chain pairs to use for crossover and selection of next point. Default = 1. Can pass a list to have a random number of pairs selected every iteration.

lamb : float

e sub d in DREAM papers. Random error for ergodicity. Default = .05

zeta : float

Epsilon in DREAM papers. Randomization term. Default = 1e-12

history_thin : int

Thinning rate for history to reduce storage requirements. Every n-th iteration will be added to the history.

snooker : float

Probability of proposing a snooker update. Default is .1. To forego snooker updates, set to 0.

p_gamma_unity : float

Probability of proposing a point with gamma=unity (i.e. a point relatively far from the current point to enable jumping between disconnected modes). Default = .2.

start_random : bool

Whether to intialize chains from a random point in parameter space drawn from the prior (default = yes). Will override starting position set when sample was called, if any.

save_history : bool

Whether to save the history to file at the end of the run (essential if you want to continue the run). Default is yes.

history_file : str

Name of history file to be loaded. Assumed to be in directory you ran the script from. If False, no file to be loaded.

crossover_file : str

Name of crossover file to be loaded. Assumed to be in directory you ran the script from. If False, no file to be loaded.

multitry : bool

Whether to utilize multi-try sampling. Default is no. If set to True, will be set to 5 multiple tries. Can also directly specify an integer if desired.

parallel : bool

Whether to run multi-try samples in parallel (using multiprocessing). Default is false. Irrelevant if multitry is set to False.

verbose : bool

Whether to print verbose progress. Default is false.

model_name : str

A model name to be used as a prefix when saving history and crossover value files.

hardboundaries : bool

Whether to relect point back into bounds of hard prior (i.e., if using a uniform prior, reflect points outside of boundaries back in, so you don’t waste time looking at points with logpdf = -inf).

pydream.core module

pydream.core.run_dream(parameters, likelihood, nchains=5, niterations=50000, start=None, restart=False, verbose=True, nverbose=10, tempering=False, **kwargs)

Run DREAM given a set of parameters with priors and a likelihood function.

Parameters:

parameters: iterable of SampledParam class

A list of parameter priors

likelihood: function

A user-defined likelihood function

nchains: int, optional

The number of parallel DREAM chains to run. Default = 5

niterations: int, optional

The number of algorithm iterations to run. Default = 50,000

start: iterable of arrays or single array, optional

Either a list of start locations to initialize chains in, or a single start location to initialize all chains in. Default: None

restart: Boolean, optional

Whether run is a continuation of an earlier run. Pass this with the model_name argument to automatically load previous history and crossover probability files. Default: False

verbose: Boolean, optional

Whether to print verbose output (including acceptance or rejection of moves and the current acceptance rate). Default: True

tempering: Boolean, optional

Whether to use parallel tempering for the DREAM chains. Warning: this feature is untested. Use at your own risk! Default: False

kwargs:

Other arguments that will be passed to the Dream class on initialization. For more information, see Dream class.

Returns:

sampled_params : list of arrays

Sampled parameters for each chain

log_ps : list of arrays

Log probability for each sampled point for each chain

pydream.parameters module

class pydream.parameters.SampledParam(scipy_distribution, *args, **kwargs)

A SciPy-based parameter prior class.

Parameters:

scipy_distribution: SciPy continuous random variable class

A SciPy statistical distribution (i.e. scipy.stats.norm)

args:

Arguments for the SciPy distribution

kwargs:

keyword arguments for the SciPy distribution

class pydream.parameters.FlatParam(test_value)

A Flat parameter class (returns 0 at all locations).

Parameters:

test_value: array

Representative value for the parameter. Used to infer the parameter dimension, which is needed in the DREAM algorithm.