dream: DiffeRential Evolution Adaptive Metropolis (DREAM)
In dream: DiffeRential Evolution Adaptive Metropolis

Description Usage Arguments Details Value References See Also

Efficient global MCMC even in high-dimensional spaces. From J.A. Vrugt, C.J.F. ter Braak et al.

This function is a low-level interface, best suited for experts. If you want to use dream to calibrate a function, use dreamCalibrate instead.

Note that the dream_zs and dream_d algorithms may be superior in your circumstances. These are not implemented in this package. Please read the following references for details.

Vrugt, J. A. and Ter Braak, C. J. F. (2011) DREAM(D): an adaptive Markov Chain Monte Carlo simulation algorithm to solve discrete, noncontinuous, and combinatorial posterior parameter estimation problems, Hydrol. Earth Syst. Sci., 15, 3701-3713, doi:10.5194/hess-15-3701-2011, from http://dx.doi.org/10.5194/hess-15-3701-2011

ter Braak, C. and J. Vrugt (2008). Differential Evolution Markov Chain with snooker updater and fewer chains. Statistics and Computing 18(4): 435-446 DOI: 10.1007/s11222-008-9104-9, from urlhttp://dx.doi.org/10.1007/s11222-008-9104-9

Laloy,E., and J.A. Vrugt. 2012. High-dimensional posterior exploration of hydrologic models using multiple-try DREAM(ZS) and high-performance computing. Water Resources Research, 48, W0156, from urlhttp://dx.doi.org/10.1029/2011WR010608

1 2	dream(FUN, func.type, pars, FUN.pars = list(), INIT = LHSInit, INIT.pars = list(), control = list(), measurement)

`FUN`	model function with first argument a vector of parameter values of length ndim.
`func.type`	type of value `FUN` returns. One of: `"posterior.density"` `FUN` returns the likelihood. `"logposterior.density"` `FUN` returns the log-likelihood. `"calc.loglik"` `FUN` returns the residual vector to be compared with `measurement`. The exponential power density function of Box and Tiao (1973) is used, based on the parameter `control$gamma`, and `measurement$N` and `measurement$sigma`. `"calc.rmse"` `FUN` returns the residual vector to be compared with `measurement`. The likelihood is calculated as the sum of squared residuals to a power `-N`, adjusted by `control$gamma`. `"calc.weighted.rmse"` similar to `"calc.rmse"` but weighted with `measurement$sigma`.
`pars`	a list of variable ranges. Any names will be propagated to output.
`FUN.pars`	a list of any extra arguments to be passed to `FUN`.
`INIT`	A function f(pars,nseq,...) returning an `nseq x ndim` matrix of initial parameter values.
`INIT.pars`	a list of any extra arguments to be passed to the `INIT` function.
`control`	list of settings for the DREAM algorithm. see below.
`measurement`	Required parameter for `func.type`s starting with `calc`. A list with element `data`, a vector containing observed dependent variable values.

Elements of control are:

Element	Default	Description
`ndim`		Number of parameters. Calculated from parameters `pars`
`nseq`	`ndim`	Number of parallel chains to evolve
`DEpairs`	`(nseq-1)/2`	Number of pairs to evolve at each generation
`nCR`	3	Crossover values used to generate proposals (geometric series). scalar
`gamma`	0	Kurtosis parameter Bayesian Inference Scheme. You may know this as beta instead.
`steps`	10	Number of steps in sem
`eps`	5e-2	Random error for ergodicity
`outlierTest`	'IQR_test'	Test used to detect outlier chains. One of: IQR_test, Grubbs_test, Mahal_test
`pCR.Update`	`TRUE`	Whether to use adaptive tuning of crossover values
`boundHandling`	'reflect'	Method used to handle parameter values outside of parameter bounds. One of: "reflect", "bound", "fold", "none","rand"
`burnin.length`	0.1	If `<1` proportion of function evaluations to use as burn-in period. If `>1` number of function evaluations to use. In the burnin-period, adaptive tuning of crossover values is performed if `pCR.Update=TRUE` and the method specified by `outlierTest` is used to remove outliers. If outliers are detected outside the burn-in period, dream emits a warning and returns to the burn-in period for another `burnin.length` iterations. If `=0` there is no burn-in period, and all outlier warnings are suppressed.
`thin.t`	NA	MCMC chain thinning interval. NA if thinning is not desired
`REPORT`	1000	Approximate number of function evaluations between calculation and reporting of convergence diagnostics. 0 if no reporting or calculation is desired. Frequent calculation is likely to slow performance. The summary function can use `gelman.diag` to calculate convergence statistic after completion
`parallel`	`"none"`	Character vector of packages to use for parallelisation of function evaluations, in order of preference. Options are `"multicore", "snow", "foreach"`. For foreach, a backend must be registered from one of the doMC, doMPI, doSNOW packages. For expert users using dream with an external program, see `"snow.chains"`.
`ndraw`	1e5	Maximum number of function evaluations. May terminate before convergence.
`maxtime`	Inf	Maximum duration of optimization in seconds. May terminate before convergence.
`Rthres`	1.01	Value of Gelman & Rubin's convergence diagnostic R value below which the sequences are considered to have converged, and execution is terminated. Vrugt suggests 1.2

Execution terminates when Gelman-Rubin statistic < control$Rthres, or control$ndraw or control$maxtime are reached

Two options for INIT are provided: latin hypercube sampling LHSInit and covariance-based sampling CovInit.

Default settings may not be sufficient for model to run. For few parameters, nseq may need to be increased.

If dream frequently warns that it is reentering the burn-period, control$burnin.length may need to be increased.

A list with elements:

`X`	converged nseq points in parameter space. matrix `nseq x ndim`.
`Sequences`	`mcmc.list`. `nseq` mcmc elements of `ndim` variables. The thinned chains if `control$thin.t!=NA`
`hist.logp`	History of log(`p`) values. matrix `nseq x n.elem`.
`AR`	Acceptance rate for each draw. matrix `n.elem x 2`.
`outlier`	Iterations at which chains were replaced. vector of variable length
`R.stat`	`gelman.diag` statistic for each variable at each step, matrix `n.elem/steps x 1+ndim`. This is a measure of convergence of the parallel MCMC chains to the posterior distribution. (N.B. in nonlinear optimisation, this is not a measure of convergence to an optimum parameter set)
`CR`	Probability of crossover at each step. matrix `n.elem/steps x 1+length(pCR)`.
`in.burnin`	Boolean showing whether dream was in the burn-in period at termination (see description above).
`fun.evals`	Total number of function evaluations.
`time`	running time (wall time) in seconds.
`EXITMSG`	a message about the stopping condition.

Vrugt, J. A., ter Braak, C. J. F., Diks, C. G. H., Robinson, B. A., Hyman, J. M., Higdon, D., 2009. Accelerating Markov chain Monte Carlo simulation by differential evolution with self-adaptive randomized subspace sampling. International Journal of Nonlinear Sciences and Numerical Simulation 10 (3), 273-290. http://dx.doi.org/10.1515/IJNSNS.2009.10.3.273

Vrugt, J. A., ter Braak, C. J. F., Gupta, H. V., Robinson, B. A., 2009. Equifinality of formal (DREAM) and informal (GLUE) Bayesian approaches in hydrologic modeling? Stochastic Environmental Research and Risk Assessment 23 (7), 1011–1026. http://dx.doi.org/10.1007/s00477-008-0274-y

dreamCalibrate to calibrate a function using dream. snow.chains for parallelised calibration of external models (expert users only).

S3 generic methods for print, summary, plot, coef, simulate, window

Demos:

demo(example1) Fitting a banana shaped distribution - as in the original matlab code
demo(example2)Fitting an n-dimensional Gaussian distribution as in the original matlab code

dream documentation built on May 2, 2019, 5:21 p.m.