PyDREAM Documentation

Transcription

1 PyDREAM Documentation Release 1.0 Erin Shockley Feb 24, 2018

2

3 Contents 1 Installing PyDREAM Requirements pydream package pydream.dream module pydream.core module pydream.parameters module Indices and tables 9 Python Module Index 11 i

4 ii

5 PyDREAM Documentation, Release 1.0 Quickstart: The main function to run DREAM is in pydream.core.run_dream(). This provides reasonable defaults, but a variety of options are available for customizing DREAM. These can be passed as keyword arguments to pydream.core.run_dream(). See the pydream.dream.dream class for a list of options. Examples are available in the examples directory of the GitHub repo. Contents: Contents 1

6 PyDREAM Documentation, Release Contents

7 CHAPTER 1 Installing PyDREAM PyDREAM can be installed from the Python Package Index using pip: pip install pydream 1.1 Requirements PyDREAM requires the multiprocess package, which will be installed with PyDREAM using pip. 3

8 PyDREAM Documentation, Release Chapter 1. Installing PyDREAM

9 CHAPTER 2 pydream package 2.1 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. Highdimensional posterior exploration of hydrologic models using multiple-try DREAM (ZS) and highperformance 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 5

10 PyDREAM Documentation, Release 1.0 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 6 Chapter 2. pydream package

11 PyDREAM Documentation, Release 1.0 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). 2.2 pydream.core module pydream.core.run_dream(parameters, likelihood, nchains=5, niterations=50000, start=none, restart=false, verbose=true, 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 2.2. pydream.core module 7

12 PyDREAM Documentation, Release 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 args: A SciPy statistical distribution (i.e. scipy.stats.norm) 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. 8 Chapter 2. pydream package

13 CHAPTER 3 Indices and tables genindex modindex search 9

14 PyDREAM Documentation, Release Chapter 3. Indices and tables

15 Python Module Index p pydream.core, 7 11

16 PyDREAM Documentation, Release Python Module Index

17 Index D Dream (class in pydream.dream), 5 F FlatParam (class in pydream.parameters), 8 P pydream.core (module), 7 R run_dream() (in module pydream.core), 7 S SampledParam (class in pydream.parameters), 8 13