diff --git a/BayesianTools/R/MAP.R b/BayesianTools/R/MAP.R index 6877e8c..287e8ef 100644 --- a/BayesianTools/R/MAP.R +++ b/BayesianTools/R/MAP.R @@ -1,8 +1,9 @@ + #' calculates the Maxiumum APosteriori value (MAP) #' @author Florian Hartig #' @param bayesianOutput an object of class BayesianOutput (mcmcSampler, smcSampler, or mcmcList) #' @param ... optional values to be passed on the the getSample function -#' @details Currently, this function simply returns the parameter combination with the highest posterior in the chain. A more refined option would be to take the MCMC sample and do additional calculations, e.g. use an optimizer, a kerne delnsity estimator, or some other tool to search / interpolate around the best value in the chain +#' @details Currently, this function simply returns the parameter combination with the highest posterior in the chain. A more refined option would be to take the MCMC sample and do additional calculations, e.g. use an optimizer, a kernel density estimator, or some other tool to search / interpolate around the best value in the chain. #' @seealso \code{\link{WAIC}}, \code{\link{DIC}}, \code{\link{marginalLikelihood}} #' @export MAP <- function(bayesianOutput, ...){ diff --git a/BayesianTools/R/SBC.R b/BayesianTools/R/SBC.R index 3ec1b4d..769c31c 100644 --- a/BayesianTools/R/SBC.R +++ b/BayesianTools/R/SBC.R @@ -1,11 +1,9 @@ #' Simulation-based calibration tests #' #' This function performs simulation-based calibration tests based on the idea that posteriors averaged over the prior should yield the prior. -#' -#' @param posteriorList a list with posterior samples. List items must be of a class that is supported by \code{\link{getSample}}. This includes BayesianTools objects, but also matrix and data.frame -#' @param priorDraws a matrix with parameter values, drawn from the prior, that were used to simulate the data underlying the posteriorList. If colnames are provided, these will be used in the plots +#' @param posteriorList a list of posterior samples. List items must be of a class that is supported by \code{\link{getSample}}. This includes BayesianTools objects, but also matrix and data.frame objects. +#' @param priorDraws a matrix of parameter values, drawn from the prior, that were used to simulate the data underlying the posteriorList. If colnames are provided, they are used in the plots #' @param ... arguments to be passed to \code{\link{getSample}}. Consider in particular the thinning option. -#' #' @details The purpose of this function is to evaluate the results of a simulation-based calibration of an MCMC analysis. #' #' Briefly, the idea is to repeatedly diff --git a/BayesianTools/R/SMC.R b/BayesianTools/R/SMC.R index 65211c1..d740eb5 100644 --- a/BayesianTools/R/SMC.R +++ b/BayesianTools/R/SMC.R @@ -1,13 +1,14 @@ + #' SMC sampler #' @author Florian Hartig #' @description Sequential Monte Carlo Sampler #' @param bayesianSetup either an object of class bayesianSetup created by \code{\link{createBayesianSetup}} (recommended), or a log target function #' @param initialParticles initial particles - either a draw from the prior, provided as a matrix with the single parameters as columns and each row being one particle (parameter vector), or a numeric value with the number of desired particles. In this case, the sampling option must be provided in the prior of the BayesianSetup. #' @param iterations number of iterations -#' @param resampling if new particles should be created at each iteration +#' @param resampling logical, specifies whether new particles should be created at each iteration #' @param resamplingSteps how many resampling (MCMC) steps between the iterations -#' @param proposal optional proposal class -#' @param adaptive should the covariance of the proposal be adapted during sampling +#' @param proposal optional, proposal class +#' @param adaptive logical, should the covariance of the proposal be adapted during sampling? #' @param proposalScale scaling factor for the proposal generation. Can be adapted if there is too much / too little rejection #' @details The sampler can be used for rejection sampling as well as for sequential Monte Carlo. For the former case set the iterations to one. #' diff --git a/BayesianTools/R/VSEM.R b/BayesianTools/R/VSEM.R index 9dbc09f..75cf450 100644 --- a/BayesianTools/R/VSEM.R +++ b/BayesianTools/R/VSEM.R @@ -1,9 +1,10 @@ + #' Very simple ecosystem model #' @description A very simple ecosystem model, based on three carbon pools and a basic LUE model #' @param pars a parameter vector with parameters and initial states #' @param PAR Forcing, photosynthetically active radiation (PAR) MJ /m2 /day #' @param C switch to choose whether to use the C or R version of the model. C is much faster. -#' @return a matrix with colums NEE, CV, CR and CS units and explanations see details +#' @return a matrix with columns NEE, CV, CR and CS units and explanations see details #' @import Rcpp #' @useDynLib BayesianTools, .registration = TRUE #' @details This Very Simple Ecosystem Model (VSEM) is a 'toy' model designed to be very simple but yet bear some resemblance to deterministic processed based ecosystem models (PBMs) that are commonly used in forest modelling. @@ -12,7 +13,7 @@ #' #' The model calculates Gross Primary Productivity (GPP) using a very simple light-use efficiency (LUE) formulation multiplied by light interception. Light interception is calculated via Beer's law with a constant light extinction coefficient operating on Leaf Area Index (LAI). #' -#' A parameter (GAMMA) determines the fraction of GPP that is autotrophic respiration. The Net Primary Productivity (NPP) is then allocated to above and below-ground vegetation via a fixed allocation fraction. Carbon is lost from the plant pools to a single soil pool via fixed turnover rates. Heterotropic respiration in the soil is determined via a soil turnover rate. +#' A parameter (GAMMA) determines the fraction of GPP that is autotrophic respiration. The Net Primary Productivity (NPP) is then allocated to above and below-ground vegetation via a fixed allocation fraction. Carbon is lost from the plant pools to a single soil pool via fixed turnover rates. Heterotrophic respiration in the soil is determined via a soil turnover rate. #' #' The model equations are #' @@ -166,8 +167,8 @@ VSEMcreatePAR <- function(days = 1:(3*365)){ #' Create an example dataset, and from that a likelihood or posterior for the VSEM model #' @author Florian Hartig -#' @param likelihoodOnly switch to devide whether to create only a likelihood, or a full bayesianSetup with uniform priors. -#' @param plot switch to decide whether data should be plotted +#' @param likelihoodOnly logical, decides whether to create only a likelihood, or a full bayesianSetup with uniform priors. +#' @param plot logical, decides whether data should be plotted #' @param selection vector containing the indices of the selected parameters #' @details The purpose of this function is to be able to conveniently create a likelihood for the VSEM model for demonstration purposes. The function creates example data --> likelihood --> BayesianSetup, where the latter is the #' @export diff --git a/BayesianTools/R/WAIC.R b/BayesianTools/R/WAIC.R index 0af9eda..93520e8 100644 --- a/BayesianTools/R/WAIC.R +++ b/BayesianTools/R/WAIC.R @@ -1,4 +1,3 @@ - # TODO - implement WAIC as AIC, can look at https://github.com/jrnold/mcmcStats/blob/master/R/waic.R, check against http://finzi.psych.upenn.edu/library/blmeco/html/WAIC.html, https://cran.r-project.org/web/packages/loo/index.html, http://stats.stackexchange.com/questions/173128/watanabe-akaike-widely-applicable-information-criterion-waic-using-pymc @@ -7,7 +6,7 @@ #' @param bayesianOutput an object of class BayesianOutput. Must implement a log-likelihood density function that can return point-wise log-likelihood values ("sum" argument). #' @param numSamples the number of samples to calculate the WAIC #' @param ... optional values to be passed on the the getSample function -#' @note The function requires that the likelihood passed on to BayesianSetup contains the option sum = T/F, with defaul F. If set to true, the likelihood for each data point must be returned. +#' @note The function requires that the likelihood passed on to BayesianSetup contains the option sum = T/F, with default F. If set to true, the likelihood for each data point must be returned. #' @details #' #' diff --git a/BayesianTools/R/blockUpdate.R b/BayesianTools/R/blockUpdate.R index e63fbc4..63487b3 100644 --- a/BayesianTools/R/blockUpdate.R +++ b/BayesianTools/R/blockUpdate.R @@ -2,7 +2,7 @@ #' Determine the groups of correlated parameters #' @author Stefan Paul #' @param chain MCMC chain including only the parameters (not logP,ll, logP) -#' @param blockSettings list with settings +#' @param blockSettings a list with settings #' @return groups #' @keywords internal updateGroups <- function(chain,blockSettings){ @@ -60,7 +60,7 @@ getBlock <- function(blockSettings){ #' getblockSettings -#' @description Transforms the original settings in settings used in the model runs +#' @description Transforms the original settings to settings used in the model runs #' @param blockUpdate input settings #' @return list with block settings #' @keywords internal diff --git a/BayesianTools/R/classBayesianOutput.R b/BayesianTools/R/classBayesianOutput.R index 2bc278c..51d5011 100644 --- a/BayesianTools/R/classBayesianOutput.R +++ b/BayesianTools/R/classBayesianOutput.R @@ -1,21 +1,20 @@ # NOTE: The functions in this class are just templates that are to be implemented for all subclasses of BayesianOutput. They are not functional. - #' Extracts the sample from a bayesianOutput #' @author Florian Hartig #' @param sampler an object of class mcmcSampler, mcmcSamplerList, smcSampler, smcSamplerList, mcmc, mcmc.list, double, numeric #' @param parametersOnly for a BT output, if F, likelihood, posterior and prior values are also provided in the output -#' @param coda works only for mcmc classes - provides output as a coda object. Note: if mcmcSamplerList contains mcmc samplers such as DE that have several chains, the internal chains will be collapsed. This may not be the desired behavior for all applications. -#' @param start for mcmc samplers start value in the chain. For SMC samplers, start particle +#' @param coda works only for mcmc classes - returns output as a coda object. Note: if mcmcSamplerList contains mcmc samplers such as DE that have several chains, the internal chains will be collapsed. This may not be desired for all applications. +#' @param start for mcmc samplers, start value in the chain. For SMC samplers, start particle #' @param end for mcmc samplers end value in the chain. For SMC samplers, end particle -#' @param thin thinning parameter. Either an integer determining the thinning intervall (default is 1) or "auto" for automatic thinning. -#' @param numSamples sample size (only used if thin = 1). If you want to use numSamples set thin to 1. +#' @param thin thinning parameter. Either an integer determining the thinning interval (default is 1) or "auto" for automatic thinning. +#' @param numSamples sample size (only used if thin = 1). If you want to use numSamples, set thin to 1. #' @param whichParameters possibility to select parameters by index #' @param reportDiagnostics logical, determines whether settings should be included in the output #' @param ... further arguments #' @example /inst/examples/getSampleHelp.R -#' @details If thin is greater than the total number of samples in the sampler object the first and the last element (of each chain if a sampler with multiples chains is used) are sampled. If numSamples is greater than the total number of samples all samples are selected. In both cases a warning is displayed. -#' @details If thin and numSamples is passed, the function will use the thin argument if it is valid and greater than 1, else numSamples will be used. +#' @details If thin is greater than the total number of samples in the sampler object, the first and the last element (of each chain if a sampler with multiples chains is used) are sampled. If numSamples is greater than the total number of samples all samples are selected. A warning will be displayed in both cases. +#' @details If both thin and numSamples are provided, the function will use thin only if it is valid and greater than 1; otherwise, numSamples will be used. #' @export getSample <- function(sampler, parametersOnly = T, coda = F, start = 1, end = NULL, thin = 1, numSamples = NULL, whichParameters = NULL, reportDiagnostics = FALSE, ...) UseMethod("getSample") diff --git a/BayesianTools/R/classBayesianSetup.R b/BayesianTools/R/classBayesianSetup.R index f7dbc8b..db80517 100644 --- a/BayesianTools/R/classBayesianSetup.R +++ b/BayesianTools/R/classBayesianSetup.R @@ -9,20 +9,20 @@ #' @param best vector with best prior values #' @param names optional vector with parameter names #' @param parallel parallelization option. Default is F. Other options include T, or "external". See details. -#' @param parallelOptions list containing three lists. First "packages" determines the R packages necessary to run the likelihood function. Second "variables" the objects in the global environment needed to run the likelihood function and third "dlls" the DLLs needed to run the likelihood function (see Details and Examples). -#' @param catchDuplicates Logical, determines whether unique parameter combinations should only be evaluated once. Only used when the likelihood accepts a matrix with parameter as columns. +#' @param parallelOptions list containing three lists.\itemize{ \item First, "packages" determines the R packages necessary to run the likelihood function.\item Second, "variables" - the objects in the global environment needed to run the likelihood function and \item Third, "dlls" is needed to run the likelihood function (see Details and Examples).} +#' @param catchDuplicates logical, determines whether unique parameter combinations should only be evaluated once. Only used when the likelihood accepts a matrix with parameter as columns. #' @param plotLower vector with lower limits for plotting #' @param plotUpper vector with upper limits for plotting #' @param plotBest vector with best values for plotting #' @details If prior is of class prior (e.g. create with \code{\link{createPrior}}), priorSampler, lower, upper and best will be ignored.\cr If prior is a function (log prior density), priorSampler (custom sampler), or lower/upper (uniform sampler) is required.\cr If prior is NULL, and lower and upper are passed, a uniform prior (see \code{\link{createUniformPrior}}) will be created with boundaries lower and upper. #' -#' For parallelization, Bayesiantools requies that the likelihood can evaluate several parameter vectors (supplied as a matrix) in parallel. +#' For parallelization, Bayesiantools requires that the likelihood can evaluate multiple parameter vectors (supplied as a matrix) in parallel. #' -#' * parallel = T means that an automatic parallelization of the likelihood via a standard R socket cluster is attempted, using the function \code{\link{generateParallelExecuter}}. By default, of the N cores detected on the computer, N-1 cores are requested. Alternatively, you can provide a integer number to parallel, specifying the cores reserved for the cluster. When the cluster is cluster is created, a copy of your workspace, including DLLs and objects are exported to the cluster workers. Because this can be very inefficient, you can explicitly specify the packages, objects and DLLs that are to be exported via parallelOptions. Using parallel = T requires that the function to be parallelized is well encapsulate, i.e. can run on a shared memory / shared hard disk machine in parallel without interfering with each other. +#' * parallel = T attempts to parallelize likelihood via a standard R socket cluster using the \code{\link{generateParallelExecuter}} function. By default, of the N cores detected on the computer, N-1 cores are requested. Alternatively, you can provide a integer number to parallel, specifying the cores reserved for the cluster. When the cluster is created, a copy of your workspace, including DLLs and objects are exported to the cluster workers. As this approach can be highly inefficient, it is recommended to explicitly specify the packages, objects and DLLs to export using parallelOptions. Using parallel = T requires that the function to be parallelized is well encapsulated, i.e. can run in parallel on a shared memory / shared hard disk machine in parallel without interfering with each other. #' -#' If automatic parallelization cannot be done (e.g. because dlls are not thread-safe or write to shared disk), and only in this case, you should specify parallel = "external". In this case, it is assumed that the likelihood is programmed such that it accepts a matrix with parameters as columns and the different model runs as rows. It is then up to the user if and how to parallelize this function. This option gives most flexibility to the user, in particular for complicated parallel architecture or shared memory problems. +#' If automatic parallelization is not possible (e.g., because dlls are not thread-safe or write to shared disk), and only in this case, you should specify parallel = "external". In this case, it is assumed that the likelihood is programmed to accept a matrix with parameters as columns and the different model runs as rows. The user can then choose whether and how to parallelize this function. This option provides optimal flexibility for the user, especially regarding complicated parallel architectures or shared memory issues. #' -#' For more details on parallelization, make sure to read both vignettes, in particular the section on the likelihood in the main vignette, and the section on parallelization in the vignette on interfacing models. +#' For more details on parallelization, make sure to read both vignettes, especially the section on likelihood in the main vignette and the section on parallelization in the vignette on interfacing models. #' #' @export #' @seealso \code{\link{checkBayesianSetup}} \cr diff --git a/BayesianTools/R/classLikelihood.R b/BayesianTools/R/classLikelihood.R index 905d9a5..d07769b 100644 --- a/BayesianTools/R/classLikelihood.R +++ b/BayesianTools/R/classLikelihood.R @@ -1,10 +1,10 @@ #' Creates a standardized likelihood class#' #' @author Florian Hartig -#' @param likelihood Log likelihood density -#' @param names Parameter names (optional) -#' @param parallel parallelization , either i) no parallelization --> F, ii) native R parallelization --> T / "auto" will select n-1 of your available cores, or provide a number for how many cores to use, or iii) external parallelization --> "external". External means that the likelihood is already able to execute parallel runs in form of a matrix with -#' @param catchDuplicates Logical, determines whether unique parameter combinations should only be evaluated once. Only used when the likelihood accepts a matrix with parameter as columns. -#' @param parallelOptions list containing two lists. First "packages" determines the R packages necessary to run the likelihood function. Second "objects" the objects in the global envirnment needed to run the likelihood function (for details see \code{\link{createBayesianSetup}}). +#' @param likelihood log likelihood density +#' @param names parameter names (optional) +#' @param parallel parallelization , either i) no parallelization --> F, ii) native R parallelization --> T / "auto" will select n-1 of your available cores, or provide a number for how many cores to use, or iii) external parallelization --> "external". External means that the likelihood is already able to execute parallel runs in the form of a matrix. +#' @param catchDuplicates logical, determines whether unique parameter combinations should only be evaluated once. This is only applicable when the likelihood accepts a matrix with parameters as columns. +#' @param parallelOptions a list containing two lists. First, "packages" specifies the R packages necessary to run the likelihood function. Second, "objects" contains the objects in the global environment needed to run the likelihood function (for details see \code{\link{createBayesianSetup}}). #' @param sampler sampler #' @seealso \code{\link{likelihoodIidNormal}} \cr #' \code{\link{likelihoodAR1}} \cr @@ -105,7 +105,6 @@ createLikelihood <- function(likelihood, names = NULL, parallel = F, catchDuplic #library(mvtnorm) #library(sparseMVN) - #' Normal / Gaussian Likelihood function #' @author Florian Hartig #' @param predicted vector of predicted values diff --git a/BayesianTools/R/classMcmcSampler.R b/BayesianTools/R/classMcmcSampler.R index 8d9fc3e..bc01194 100644 --- a/BayesianTools/R/classMcmcSampler.R +++ b/BayesianTools/R/classMcmcSampler.R @@ -113,6 +113,7 @@ getSample.mcmcSampler <- function(sampler, parametersOnly = T, coda = F, start = + #' @method summary mcmcSampler #' @author Stefan Paul #' @export diff --git a/BayesianTools/R/classMcmcSamplerList.R b/BayesianTools/R/classMcmcSamplerList.R index 67fad61..cadba14 100644 --- a/BayesianTools/R/classMcmcSamplerList.R +++ b/BayesianTools/R/classMcmcSamplerList.R @@ -1,7 +1,8 @@ + #' Convenience function to create an object of class mcmcSamplerList from a list of mcmc samplers #' @author Florian Hartig -#' @param mcmcList a list with each object being an mcmcSampler -#' @return Object of class "mcmcSamplerList" +#' @param mcmcList list of objects, each of which is an mcmcSampler +#' @return object of class "mcmcSamplerList" #' @export createMcmcSamplerList <- function(mcmcList){ # mcmcList <- list(mcmcList) -> This line didn't make any sense at all. Better would be to allow the user to simply provide several inputs without a list, but I guess the list option should be maintained, as this is convenient when scripting. diff --git a/BayesianTools/R/classPosterior.R b/BayesianTools/R/classPosterior.R index 9c4b3c5..9a2ca25 100644 --- a/BayesianTools/R/classPosterior.R +++ b/BayesianTools/R/classPosterior.R @@ -1,8 +1,8 @@ #' Creates a standardized posterior class #' @author Florian Hartig #' @param prior prior class -#' @param likelihood Log likelihood density -#' @details Function is internally used in \code{\link{createBayesianSetup}} to create a standarized posterior class. +#' @param likelihood log likelihood density +#' @details Function is internally used in \code{\link{createBayesianSetup}} to create a standardized posterior class. #' @export createPosterior <- function(prior, likelihood){ @@ -45,6 +45,7 @@ createPosterior <- function(prior, likelihood){ return(out) } + # likelihood <- function(x)stop("a") # prior <- createPrior(function(x) sum(dunif(x, log = T))) # diff --git a/BayesianTools/R/classPrior.R b/BayesianTools/R/classPrior.R index efb0215..f5f89a4 100644 --- a/BayesianTools/R/classPrior.R +++ b/BayesianTools/R/classPrior.R @@ -1,11 +1,11 @@ #' Creates a standardized prior class #' @author Florian Hartig -#' @param density Prior density +#' @param density prior density #' @param sampler Sampling function for density (optional) #' @param lower vector with lower bounds of parameters #' @param upper vector with upper bounds of parameter #' @param best vector with "best" parameter values -#' @details This is the general prior generator. It is highly recommended to not only implement the density, but also the sampler function. If this is not done, the user will have to provide explicit starting values for many of the MCMC samplers. Note the existing, more specialized prior function. If your prior can be created by those, they are preferred. Note also that priors can be created from an existing MCMC output from BT, or another MCMC sample, via \code{\link{createPriorDensity}}. +#' @details This is the general prior generator. It is highly recommended to implement both the density and sampler function. If not, the user will have to provide explicit starting values for many of the MCMC samplers. Note the existing, more specialized prior functions. It is recommended to use those specialized prior functions, if possible. Also note that priors can be created from an existing MCMC output from BT, or another MCMC sample, via \code{\link{createPriorDensity}}. #' @note min and max truncate, but not re-normalize the prior density (so, if a pdf that integrated to one is truncated, the integral will in general be smaller than one). For MCMC sampling, this doesn't make a difference, but if absolute values of the prior density are a concern, one should provide a truncated density function for the prior. #' @export #' @seealso \code{\link{createPriorDensity}} \cr @@ -247,9 +247,7 @@ createPriorDensity <- function(sampler, method = "multivariate", eps = 1e-10, lo #' @author Maximilian Pichler - #' @export - print.prior <- function(x, ...){ cat('Prior: \n\n') diff --git a/BayesianTools/R/classSMCSamplerList.R b/BayesianTools/R/classSMCSamplerList.R index 529e0e0..d693e45 100644 --- a/BayesianTools/R/classSMCSamplerList.R +++ b/BayesianTools/R/classSMCSamplerList.R @@ -1,7 +1,8 @@ + #' Convenience function to create an object of class SMCSamplerList from a list of mcmc samplers #' @author Florian Hartig #' @param ... a list of MCMC samplers -#' @return a list of class smcSamplerList with each object being an smcSampler +#' @return a list of class smcSamplerList with objects of smcSampler #' @export createSmcSamplerList <- function(...){ smcList <- list(...) diff --git a/BayesianTools/R/classSmcSampler.R b/BayesianTools/R/classSmcSampler.R index 2eb931a..ab47c45 100644 --- a/BayesianTools/R/classSmcSampler.R +++ b/BayesianTools/R/classSmcSampler.R @@ -1,3 +1,4 @@ + #' @author Florian Hartig #' @export getSample.smcSampler <- function(sampler, parametersOnly = T, coda = F, start = 1, end = NULL, thin = 1, numSamples = NULL, whichParameters = NULL, reportDiagnostics = FALSE, ...){ diff --git a/BayesianTools/R/codaFunctions.R b/BayesianTools/R/codaFunctions.R index 715d27d..d467a5e 100644 --- a/BayesianTools/R/codaFunctions.R +++ b/BayesianTools/R/codaFunctions.R @@ -1,7 +1,8 @@ + #' Function to combine chains #' #' @param x a list of MCMC chains -#' @param merge logical determines whether chains should be merged +#' @param merge should chains be merged? (T or F) #' @return combined chains #' #' @note to combine several chains to a single McmcSamplerList, see \code{\link{createMcmcSamplerList}} @@ -44,10 +45,10 @@ combineChains <- function(x, merge = T){ #' Helper function to change an object to a coda mcmc class, #' #' @param chain mcmc Chain -#' @param start for mcmc samplers start value in the chain. For SMC samplers, start particle -#' @param end for mcmc samplers end value in the chain. For SMC samplers, end particle +#' @param start For MCMC samplers, the initial value in the chain. For SMC samplers, initial particle +#' @param end For MCMC samplers, the end value in the chain. For SMC samplers, end particle. #' @param thin thinning parameter -#' @return object of class coda::mcmc +#' @return object an object of class coda::mcmc #' @details Very similar to coda::mcmc but with less overhead #' @keywords internal makeObjectClassCodaMCMC <- function (chain, start = 1, end = numeric(0), thin = 1){ diff --git a/BayesianTools/R/convertCoda.R b/BayesianTools/R/convertCoda.R index b00739a..c269ac0 100644 --- a/BayesianTools/R/convertCoda.R +++ b/BayesianTools/R/convertCoda.R @@ -1,16 +1,12 @@ - #' Convert coda::mcmc objects to BayesianTools::mcmcSampler -#' @description Function is used to make the plot and diagnostic functions -#' available for coda::mcmc objects -#' @param sampler An object of class mcmc or mcmc.list -#' @param names vector giving the parameter names (optional) -#' @param info matrix (or list with matrices for mcmc.list objects) with three coloumns containing log posterior, log likelihood and log prior of the sampler for each time step (optional; but see Details) -#' @param likelihood likelihood function used in the sampling (see Details) -#' @details The parameter 'likelihood' is optional for most functions but can be needed e.g for -#' using the \code{\link{DIC}} function. +#' @description Function to support plotting and diagnostic functions for coda::mcmc objects. +#' @param sampler an object of class mcmc or mcmc.list +#' @param names a vector with parameter names (optional) +#' @param info a matrix (or list with matrices for mcmc.list objects) with three columns containing log posterior, log likelihood and log prior of the sampler for each time step (optional; but see Details) +#' @param likelihood likelihood function used for sampling (see Details) +#' @details The parameter 'likelihood' is optional for most functions but can be needed e.g for \code{\link{DIC}} function. #' -#' Also the parameter info is optional for most uses. However for some functions (e.g. \code{\link{MAP}}) -#' the matrix or single coloumns (e.g. log posterior) are necessary for the diagnostics. +#' Also, the parameter information is typically optional for most uses. However, for certain functions (e.g. \code{\link{MAP}}), the matrix or single columns (e.g. log posterior) are necessary for diagnostics. #' @export convertCoda <- function(sampler, names = NULL, info = NULL, likelihood = NULL){ diff --git a/BayesianTools/R/getVolume.R b/BayesianTools/R/getVolume.R index 3eef157..c84a439 100644 --- a/BayesianTools/R/getVolume.R +++ b/BayesianTools/R/getVolume.R @@ -1,10 +1,11 @@ + #' Calculate posterior volume #' @author Florian Hartig -#' @param sampler an object of superclass bayesianOutput or any other class that has the getSample function implemented (e.g. Matrix) -#' @param prior schould also prior volume be calculated +#' @param sampler an object of superclass bayesianOutput or any other class that has implemented the getSample function (e.g. Matrix) +#' @param prior logical, should prior volume be calculated? #' @param method method for volume estimation. Currently, the only option is "MVN" #' @param ... additional parameters to pass on to the \code{\link{getSample}} -#' @details The idea of this function is to provide an estimate of the "posterior volume", i.e. how "broad" the posterior is. One potential application is to the overall reduction of parametric uncertainty between different data types, or between prior and posterior. +#' @details The idea of this function is to provide an estimate of the "posterior volume", i.e. how "broad" the posterior is. One potential application is the overall reduction of parametric uncertainty between different data types, or between prior and posterior. #' #' Implemented methods for volume estimation: #' diff --git a/BayesianTools/R/marginalLikelihood.R b/BayesianTools/R/marginalLikelihood.R index 764c4e3..529e42b 100644 --- a/BayesianTools/R/marginalLikelihood.R +++ b/BayesianTools/R/marginalLikelihood.R @@ -3,7 +3,6 @@ # https://radfordneal.wordpress.com/2008/08/17/the-harmonic-mean-of-the-likelihood-worst-monte-carlo-method-ever/ # https://gist.github.com/gaberoo/4619102 - # ' @export #marginalLikelihood <- function(x,lik,V,sampler$setup$likelihood$density,sampler$setup$prior$density,..., num.samples=1000,log=TRUE) UseMethod("marginalLikelihood") @@ -24,17 +23,17 @@ #' #' In BT, we return the log ML, so you will have to exp all values for this formula. #' -#' It is well-known that the ML is VERY dependent on the prior, and in particular the choice of the width of uninformative priors may have major impacts on the relative weights of the models. It has therefore been suggested to not use the ML for model averaging / selection on uninformative priors. If you have no informative priors, and option is to split the data into two parts, use one part to generate informative priors for the model, and the second part for the model selection. See help for an example. +#' It is well-known that the ML is strongly dependent on the prior, and in particular the choice of the width of uninformative priors may have major impacts on the relative weights of the models. It has therefore been suggested to not use the ML for model averaging / selection on uninformative priors. If you have no informative priors, and option is to split the data into two parts, use one part to generate informative priors for the model, and the second part for the model selection. See help for an example. #' #' The marginalLikelihood function currently implements four ways to calculate the marginal likelihood. Be aware that marginal likelihood calculations are notoriously prone to numerical stability issues. Especially in high-dimensional parameter spaces, there is no guarantee that any of the implemented algorithms will converge reasonably fast. The recommended (and default) method is the method "Chib" (Chib and Jeliazkov, 2001), which is based on MCMC samples, with a limited number of additional calculations. Despite being the current recommendation, note there are some numeric issues with this algorithm that may limit reliability for larger dimensions. #' -#' The harmonic mean approximation, is implemented only for comparison. Note that the method is numerically unrealiable and usually should not be used. +#' The harmonic mean approximation, is implemented only for comparison. Note that the method is numerically unreliable and usually should not be used. #' #' The third method is simply sampling from the prior. While in principle unbiased, it will only converge for a large number of samples, and is therefore numerically inefficient. #' #' The Bridge method uses bridge sampling as implemented in the R package "bridgesampling". It is potentially more exact than the Chib method, but might require more computation time. However, this may be very dependent on the sampler. #' -#' @return A list with log of the marginal likelihood, as well as other diagnostics depending on the chose method +#' @return A list with log of the marginal likelihood, as well as other diagnostics depending on the chosen method #' #' @example /inst/examples/marginalLikelihoodHelp.R #' @references diff --git a/BayesianTools/R/mcmcDE.R b/BayesianTools/R/mcmcDE.R index 734f080..1589079 100644 --- a/BayesianTools/R/mcmcDE.R +++ b/BayesianTools/R/mcmcDE.R @@ -1,237 +1,235 @@ - - -#' Differential-Evolution MCMC -#' @author Francesco Minunno and Stefan Paul -#' @param bayesianSetup a BayesianSetup with the posterior density function to be sampled from -#' @param settings list with parameter settings -#' @param startValue (optional) eiter a matrix with start population, a number to define the number of chains that are run or a function that samples a starting population. -#' @param iterations number of function evaluations. -#' @param burnin number of iterations treated as burn-in. These iterations are not recorded in the chain. -#' @param thin thinning parameter. Determines the interval in which values are recorded. -#' @param f scaling factor gamma -#' @param eps small number to avoid singularity -#' @param blockUpdate list determining whether parameters should be updated in blocks. For possible settings see Details. -#' @param message logical determines whether the sampler's progress should be printed -#' @references Braak, Cajo JF Ter. "A Markov Chain Monte Carlo version of the genetic algorithm Differential Evolution: easy Bayesian computing for real parameter spaces." Statistics and Computing 16.3 (2006): 239-249. -#' @export -#' @example /inst/examples/DEfamilyHelp.R -#' @seealso \code{\link{DEzs}} -#' @details For blockUpdate the first element in the list determines the type of blocking. -#' Possible choices are -#' \itemize{ -#' \item{"none"}{ (default), no blocking of parameters} -#' \item{"correlation"} { blocking based on correlation of parameters. Using h or k (see below)} -#' \item{"random"} { random blocking. Using k (see below)} -#' \item{"user"} { user defined groups. Using groups (see below)} -#' } -#' Further seven parameters can be specified. "k" determnined the number of groups, "h" the strength -#' of the correlation used to group parameter and "groups" is used for user defined groups. -#' "groups" is a vector containing the group number for each parameter. E.g. for three parameters -#' with the first two in one group, "groups" would be c(1,1,2). -#' Further pSel and pGroup can be used to influence the choice of groups. In the sampling process -#' a number of groups is randomly drawn and updated. pSel is a vector containing relative probabilities -#' for an update of the respective number of groups. E.g. for always updating only one group pSel = 1. -#' For updating one or two groups with the same probability pSel = c(1,1). By default all numbers -#' have the same probability. -#' The same principle is used in pGroup. Here the user can influence the probability of each group -#' to be updated. By default all groups have the same probability. -#' Finally "groupStart" defines the starting point of the groupUpdate and "groupIntervall" the intervall -#' in which the groups are evaluated. - -DE <- function(bayesianSetup, - settings = list( - startValue = NULL, - iterations = 10000, - f = -2.38, - burnin = 0, - thin = 1, - eps = 0, - consoleUpdates = 100, - blockUpdate = list("none", k = NULL, h = NULL, pSel = NULL, pGroup = NULL, - groupStart = 1000, groupIntervall = 1000), - currentChain = 1, - message = TRUE - ) - ){ - - if("bayesianOutput" %in% class(bayesianSetup)){ - restart <- TRUE - } else restart <- FALSE - - - if(restart){ - if(is.null(settings)) settings <- bayesianSetup$settings - else settings <- applySettingsDefault(settings = settings, sampler = "DE") - - }else{ - # If nothing provided use default settings - settings <- applySettingsDefault(settings = settings, sampler = "DE") - } - - if(!restart){ - setup <- bayesianSetup - }else{ - setup <- bayesianSetup$setup - } - - - setup <- checkBayesianSetup(setup, parallel = settings$parallel) # calling parallel will check if requested parallelization in settings is provided by the BayesianSetup - if(is.null(settings$parallel)) settings$parallel = setup$parallel # checking back - if no parallelization is provided, we use the parallelization in the BayesianSetup. We could also set parallel = F, but I feel it makes more sense to use the Bayesiansetup as default - - if(!restart){ - if(is.null(settings$startValue)){ - parLen = length(bayesianSetup$prior$sampler(1)) - X = bayesianSetup$prior$sampler(3 * parLen) - } - if(is.function(settings$startValue)){ - X = settings$startValue() - } - if(class(settings$startValue)[1] == "numeric"){ - X = bayesianSetup$prior$sampler(settings$startValue) - } - if(is.matrix(settings$startValue)) X <- settings$startValue - }else{ - X <- bayesianSetup$X - } - - # X = startValue - if (!is.matrix(X)) stop("wrong starting values") - - FUN = setup$posterior$density - - ## Initialize blockUpdate parameters and settings - blockdefault <- list("none", k = NULL, h = NULL, pSel = NULL, pGroup = NULL, - groupStart = 1000, groupIntervall = 1000) - - if(!is.null(settings$blockUpdate)){ - blockUpdate <- modifyList(blockdefault, settings$blockUpdate) - blockUpdate[[1]] <- settings$blockUpdate[[1]] # to catch first argument - if(blockUpdate[[1]] == "none"){ - blockUpdateType <- "none" - blocks = FALSE - BlockStart = FALSE - }else{ - groupStart <- blockUpdate$groupStart - groupIntervall <- blockUpdate$groupIntervall - blockUpdateType = blockUpdate[[1]] - blocks = TRUE - ## Initialize BlockStart - BlockStart = FALSE - Bcount = 0 - } - }else{ - blockUpdateType <- "none" - blocks = FALSE - BlockStart = FALSE - } - - - - Npar <- ncol(X) - Npop <- nrow(X) - burnin <- settings$burnin/Npop - n.iter <- ceiling(settings$iterations/Npop) - - if (n.iter < 2) stop ("The total number of iterations must be greater than the number of parameters to fit times 3.") - - lChain <- ceiling((n.iter - burnin)/settings$thin)+1 - #pChain <- array(NA, dim=c(n.iter*Npop, Npar+3)) - - pChain <- array(NA, dim=c(lChain, Npar+3, Npop)) - - - colnames(pChain) <- c(setup$names, "LP", "LL", "LPr") - - counter <- 1 - iseq <- 1:Npop - - - F2 = abs(settings$f)/sqrt(2*Npar) - if (settings$f>0) F1 = F2 else F1 = 0.98 - - logfitness_X <- FUN(X, returnAll = T) - - # Write first values in chain - pChain[1,,] <- t(cbind(X,logfitness_X)) - - # Print adjusted iterations - # cat("Iterations adjusted to", n.iter*Npop,"to fit settings", "\n") - - #### - eps <- settings$eps - currentChain <- settings$currentChain - iterations <- settings$iterations - - for (iter in 2:n.iter) { - - if (iter%%10) F_cur = F2 else F_cur = F1 - - - if(blocks){ - ### Update the groups. - if(iter == groupStart+ Bcount*groupIntervall){ - blockSettings <- updateGroups(chain = pChain[1:counter,, ], blockUpdate) - BlockStart <- TRUE - Bcount <- Bcount + 1 - } - } - #### - - for (i in iseq){ - # select to random different individuals (and different from i) in rr, a 2-vector - - rr <- sample(iseq[-i], 2, replace = FALSE) - x_prop <- X[i,] + F_cur * (X[rr[1],]-X[rr[2],]) + eps * rnorm(Npar,0,1) - - if(BlockStart){ - # Get the current group and update the proposal accordingly - Member <- getBlock(blockSettings) - x_prop[-Member] <- X[i,-Member] - #### - } - - logfitness_x_prop <- FUN(x_prop, returnAll = T) - if(!is.na(logfitness_x_prop[1] - logfitness_X[i,1])){ # To catch possible error - if ((logfitness_x_prop[1] - logfitness_X[i,1] ) > log(runif(1))){ - X[i,] <- x_prop - logfitness_X[i,] <- logfitness_x_prop - } - } - } #iseq - if ((iter > burnin) && (iter %% settings$thin == 0) ) { # retain sample - counter <- counter+1 - pChain[counter,,] <- t(cbind(X,logfitness_X)) - - } - - if(settings$message){ - if( (iter %% settings$consoleUpdates == 0) | (iter == n.iter)) cat("\r","Running DE-MCMC, chain ", currentChain, - "iteration" ,iter*Npop,"of",n.iter*Npop,". Current logp ", - logfitness_X[,1], - "Please wait!","\r") - flush.console() - } - - } # n.iter - iterationsOld <- 0 - - pChain <- pChain[1:counter,,] - - if(restart){ # Combine chains - newchains <- array(NA, dim = c((counter+nrow(bayesianSetup$chain[[1]])), (Npar+3), Npop)) - - for(i in 1:Npop){ - for(k in 1:(Npar+3)){ - newchains[,k,i] <- c(bayesianSetup$chain[[i]][,k],pChain[,k,i]) - } - } - pChain <- newchains - } - - - - pChain<- coda::as.mcmc.list(lapply(1:Npop,function(i) coda::as.mcmc(pChain[,1:(Npar+3),i]))) - - - list(Draws = pChain, X = as.matrix(X[,1:Npar])) - } +#' Differential-Evolution MCMC +#' @author Francesco Minunno and Stefan Paul +#' @param bayesianSetup a BayesianSetup with the posterior density function to be sampled from +#' @param settings list with parameter settings +#' @param startValue (optional) either a matrix with start population, a number defining the number of chains to be run or a function that samples a starting population. +#' @param iterations number of function evaluations. +#' @param burnin number of iterations treated as burn-in. These iterations are not recorded in the chain. +#' @param thin thinning parameter. Determines the interval in which values are recorded. +#' @param f scaling factor gamma +#' @param eps small number to avoid singularity +#' @param blockUpdate list determining whether parameters should be updated in blocks. For possible settings see Details. +#' @param message logical, Specifies whether to print the progress of the sampler. +#' @references Braak, Cajo JF Ter. "A Markov Chain Monte Carlo version of the genetic algorithm Differential Evolution: easy Bayesian computing for real parameter spaces." Statistics and Computing 16.3 (2006): 239-249. +#' @export +#' @example /inst/examples/DEfamilyHelp.R +#' @seealso \code{\link{DEzs}} +#' @details For blockUpdate the first element in the list determines the type of blocking. +#' Possible choices are +#' \itemize{ +#' \item{"none"}{ (default), no blocking of parameters} +#' \item{"correlation"} { blocking based on correlation of parameters. Using h or k (see below)} +#' \item{"random"} { random blocking. Using k (see below)} +#' \item{"user"} { user defined groups. Using groups (see below)} +#' } +#' Further, seven parameters can be specified. "k" defines the number of groups, "h" the strength +#' of the correlation used to group the parameters and "groups" is used for user defined groups. +#' "groups" is a vector containing the group number for each parameter. E.g. for three parameters +#' with the first two in one group, "groups" would be c(1,1,2). +#' Moreover, pSel and pGroup can be used to influence the choice of groups. In the sampling process +#' a number of groups are drawn at random and updated. pSel is a vector containing relative probabilities +#' for updating the respective number of groups. E.g. To update one group at a time pSel = 1. +#' For updating one or two groups with the same probability pSel = c(1,1). By default all numbers +#' have the same probability. +#' The same principle is used for pGroup. Here the user can influence the probability of each group +#' to be updated. By default all groups have the same probability. +#' Finally, "groupStart" defines the starting point of the groupUpdate and "groupIntervall" - the interval +#' in which the groups are evaluated. + +DE <- function(bayesianSetup, + settings = list( + startValue = NULL, + iterations = 10000, + f = -2.38, + burnin = 0, + thin = 1, + eps = 0, + consoleUpdates = 100, + blockUpdate = list("none", k = NULL, h = NULL, pSel = NULL, pGroup = NULL, + groupStart = 1000, groupIntervall = 1000), + currentChain = 1, + message = TRUE + ) + ){ + + if("bayesianOutput" %in% class(bayesianSetup)){ + restart <- TRUE + } else restart <- FALSE + + + if(restart){ + if(is.null(settings)) settings <- bayesianSetup$settings + else settings <- applySettingsDefault(settings = settings, sampler = "DE") + + }else{ + # If nothing provided use default settings + settings <- applySettingsDefault(settings = settings, sampler = "DE") + } + + if(!restart){ + setup <- bayesianSetup + }else{ + setup <- bayesianSetup$setup + } + + + setup <- checkBayesianSetup(setup, parallel = settings$parallel) # calling parallel will check if requested parallelization in settings is provided by the BayesianSetup + if(is.null(settings$parallel)) settings$parallel = setup$parallel # checking back - if no parallelization is provided, we use the parallelization in the BayesianSetup. We could also set parallel = F, but I feel it makes more sense to use the Bayesiansetup as default + + if(!restart){ + if(is.null(settings$startValue)){ + parLen = length(bayesianSetup$prior$sampler(1)) + X = bayesianSetup$prior$sampler(3 * parLen) + } + if(is.function(settings$startValue)){ + X = settings$startValue() + } + if(class(settings$startValue)[1] == "numeric"){ + X = bayesianSetup$prior$sampler(settings$startValue) + } + if(is.matrix(settings$startValue)) X <- settings$startValue + }else{ + X <- bayesianSetup$X + } + + # X = startValue + if (!is.matrix(X)) stop("wrong starting values") + + FUN = setup$posterior$density + + ## Initialize blockUpdate parameters and settings + blockdefault <- list("none", k = NULL, h = NULL, pSel = NULL, pGroup = NULL, + groupStart = 1000, groupIntervall = 1000) + + if(!is.null(settings$blockUpdate)){ + blockUpdate <- modifyList(blockdefault, settings$blockUpdate) + blockUpdate[[1]] <- settings$blockUpdate[[1]] # to catch first argument + if(blockUpdate[[1]] == "none"){ + blockUpdateType <- "none" + blocks = FALSE + BlockStart = FALSE + }else{ + groupStart <- blockUpdate$groupStart + groupIntervall <- blockUpdate$groupIntervall + blockUpdateType = blockUpdate[[1]] + blocks = TRUE + ## Initialize BlockStart + BlockStart = FALSE + Bcount = 0 + } + }else{ + blockUpdateType <- "none" + blocks = FALSE + BlockStart = FALSE + } + + + + Npar <- ncol(X) + Npop <- nrow(X) + burnin <- settings$burnin/Npop + n.iter <- ceiling(settings$iterations/Npop) + + if (n.iter < 2) stop ("The total number of iterations must be greater than the number of parameters to fit times 3.") + + lChain <- ceiling((n.iter - burnin)/settings$thin)+1 + #pChain <- array(NA, dim=c(n.iter*Npop, Npar+3)) + + pChain <- array(NA, dim=c(lChain, Npar+3, Npop)) + + + colnames(pChain) <- c(setup$names, "LP", "LL", "LPr") + + counter <- 1 + iseq <- 1:Npop + + + F2 = abs(settings$f)/sqrt(2*Npar) + if (settings$f>0) F1 = F2 else F1 = 0.98 + + logfitness_X <- FUN(X, returnAll = T) + + # Write first values in chain + pChain[1,,] <- t(cbind(X,logfitness_X)) + + # Print adjusted iterations + # cat("Iterations adjusted to", n.iter*Npop,"to fit settings", "\n") + + #### + eps <- settings$eps + currentChain <- settings$currentChain + iterations <- settings$iterations + + for (iter in 2:n.iter) { + + if (iter%%10) F_cur = F2 else F_cur = F1 + + + if(blocks){ + ### Update the groups. + if(iter == groupStart+ Bcount*groupIntervall){ + blockSettings <- updateGroups(chain = pChain[1:counter,, ], blockUpdate) + BlockStart <- TRUE + Bcount <- Bcount + 1 + } + } + #### + + for (i in iseq){ + # select to random different individuals (and different from i) in rr, a 2-vector + + rr <- sample(iseq[-i], 2, replace = FALSE) + x_prop <- X[i,] + F_cur * (X[rr[1],]-X[rr[2],]) + eps * rnorm(Npar,0,1) + + if(BlockStart){ + # Get the current group and update the proposal accordingly + Member <- getBlock(blockSettings) + x_prop[-Member] <- X[i,-Member] + #### + } + + logfitness_x_prop <- FUN(x_prop, returnAll = T) + if(!is.na(logfitness_x_prop[1] - logfitness_X[i,1])){ # To catch possible error + if ((logfitness_x_prop[1] - logfitness_X[i,1] ) > log(runif(1))){ + X[i,] <- x_prop + logfitness_X[i,] <- logfitness_x_prop + } + } + } #iseq + if ((iter > burnin) && (iter %% settings$thin == 0) ) { # retain sample + counter <- counter+1 + pChain[counter,,] <- t(cbind(X,logfitness_X)) + + } + + if(settings$message){ + if( (iter %% settings$consoleUpdates == 0) | (iter == n.iter)) cat("\r","Running DE-MCMC, chain ", currentChain, + "iteration" ,iter*Npop,"of",n.iter*Npop,". Current logp ", + logfitness_X[,1], + "Please wait!","\r") + flush.console() + } + + } # n.iter + iterationsOld <- 0 + + pChain <- pChain[1:counter,,] + + if(restart){ # Combine chains + newchains <- array(NA, dim = c((counter+nrow(bayesianSetup$chain[[1]])), (Npar+3), Npop)) + + for(i in 1:Npop){ + for(k in 1:(Npar+3)){ + newchains[,k,i] <- c(bayesianSetup$chain[[i]][,k],pChain[,k,i]) + } + } + pChain <- newchains + } + + + + pChain<- coda::as.mcmc.list(lapply(1:Npop,function(i) coda::as.mcmc(pChain[,1:(Npar+3),i]))) + + + list(Draws = pChain, X = as.matrix(X[,1:Npar])) + } diff --git a/BayesianTools/R/mcmcDEzs.R b/BayesianTools/R/mcmcDEzs.R index ed99255..289eb6c 100644 --- a/BayesianTools/R/mcmcDEzs.R +++ b/BayesianTools/R/mcmcDEzs.R @@ -4,9 +4,9 @@ #' @author Francesco Minunno and Stefan Paul #' @param bayesianSetup a BayesianSetup with the posterior density function to be sampled from #' @param settings list with parameter settings -#' @param startValue (optional) eiter a matrix with start population, a number to define the number of chains that are run or a function that samples a starting population. +#' @param startValue (optional) either a matrix with start population, a number to define the number of chains that are run or a function that samples a starting population. #' @param Z starting Z population -#' @param iterations iterations to run +#' @param iterations number of iterations to run #' @param pSnooker probability of Snooker update #' @param burnin number of iterations treated as burn-in. These iterations are not recorded in the chain. #' @param thin thinning parameter. Determines the interval in which values are recorded. @@ -17,12 +17,12 @@ #' @param eps.mult random term (multiplicative error) #' @param eps.add random term #' @param blockUpdate list determining whether parameters should be updated in blocks. For possible settings see Details. -#' @param message logical determines whether the sampler's progress should be printed +#' @param message logical, specifies whether to print the progress of the sampler. #' @references ter Braak C. J. F., and Vrugt J. A. (2008). Differential Evolution Markov Chain with snooker updater and fewer chains. Statistics and Computing http://dx.doi.org/10.1007/s11222-008-9104-9 #' @export #' @example /inst/examples/DEfamilyHelp.R #' @seealso \code{\link{DE}} -#' @details For parallel computing, the likelihood density in the bayesianSetup needs to be parallelized, i.e. needs to be able to operate on a matrix of proposals +#' @details For parallel computing, the likelihood density in the bayesianSetup needs to be parallelized, i.e., it needs to be able to operate on a matrix of proposals #' #' For blockUpdate the first element in the list determines the type of blocking. #' Possible choices are @@ -32,19 +32,20 @@ #' \item{"random"} { random blocking. Using k (see below)} #' \item{"user"} { user defined groups. Using groups (see below)} #' } -#' Further seven parameters can be specified. "k" determnined the number of groups, "h" the strength +#' Further, seven parameters can be specified. "k" defines the number of groups, "h" the strength #' of the correlation used to group parameter and "groups" is used for user defined groups. #' "groups" is a vector containing the group number for each parameter. E.g. for three parameters #' with the first two in one group, "groups" would be c(1,1,2). -#' Further pSel and pGroup can be used to influence the choice of groups. In the sampling process -#' a number of groups is randomly drawn and updated. pSel is a vector containing relative probabilities -#' for an update of the respective number of groups. E.g. for always updating only one group pSel = 1. +#' Moreover, pSel and pGroup can be used to influence the choice of groups. In the sampling process +#' a number of groups is drawn at random and updated. pSel is a vector containing relative probabilities +#' for updating the respective number of groups. E.g. To update one group at a time pSel = 1. #' For updating one or two groups with the same probability pSel = c(1,1). By default all numbers #' have the same probability. -#' The same principle is used in pGroup. Here the user can influence the probability of each group +#' The same principle is used in pGroup. Here, the user can influence the probability of each group #' to be updated. By default all groups have the same probability. -#' Finally "groupStart" defines the starting point of the groupUpdate and "groupIntervall" the intervall +#' Finally, "groupStart" defines the starting point of the groupUpdate and "groupIntervall" - the interval #' in which the groups are evaluated. +#' DEzs <- function(bayesianSetup, settings = list(iterations=10000, Z = NULL, diff --git a/BayesianTools/R/mcmcDREAM.R b/BayesianTools/R/mcmcDREAM.R index ead86c5..e903258 100644 --- a/BayesianTools/R/mcmcDREAM.R +++ b/BayesianTools/R/mcmcDREAM.R @@ -1,44 +1,45 @@ ### DREAM algorithm + #' DREAM #' @author Stefan Paul -#' @param bayesianSetup Object of class 'bayesianSetup' or 'bayesianOuput'. +#' @param bayesianSetup object of class 'bayesianSetup' or 'bayesianOuput'. #' @param settings list with parameter values -#' @param iterations Number of model evaluations +#' @param iterations number of model evaluations #' @param nCR parameter determining the number of cross-over proposals. If nCR = 1 all parameters are updated jointly. -#' @param updateInterval determining the intervall for the pCR update +#' @param updateInterval determines the interval for the pCR update #' @param gamma Kurtosis parameter Bayesian Inference Scheme #' @param eps Ergodicity term #' @param e Ergodicity term -#' @param pCRupdate If T, crossover probabilities will be updated +#' @param pCRupdate logical, if T, crossover probabilities will be updated #' @param burnin number of iterations treated as burn-in. These iterations are not recorded in the chain. -#' @param thin thin thinning parameter. Determines the interval in which values are recorded. -#' @param adaptation Number or percentage of samples that are used for the adaptation in DREAM (see Details). -#' @param DEpairs Number of pairs used to generate proposal -#' @param startValue eiter a matrix containing the start values (see details), an integer to define the number of chains that are run, a function to sample the start values or NUll, in which case the values are sampled from the prior. -#' @param consoleUpdates Intervall in which the sampling progress is printed to the console -#' @param message logical determines whether the sampler's progress should be printed +#' @param thin thinning parameter. Determines the interval in which values are recorded. +#' @param adaptation number or percentage of samples that are used for the adaptation in DREAM (see Details). +#' @param DEpairs number of pairs used to generate proposal +#' @param startValue either a matrix containing the start values (see details), an integer to define the number of chains to be run, a function to sample the start values or NUll - in which case the values are sampled from the prior. +#' @param consoleUpdates interval at which the sampling progress is printed to the console +#' @param message logical, determines whether the sampler's progress should be printed #' @return mcmc.object containing the following elements: chains, X, pCR #' @references Vrugt, Jasper A., et al. "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 (2009): 273-290. -#' @details Insted of a bayesianSetup, the function can take the output of a previous run to restart the sampler +#' @details Instead of a bayesianSetup, the function can take the output of a previous run to restart the sampler #' from the last iteration. Due to the sampler's internal structure you can only use the output #' of DREAM. -#' If you provide a matrix with start values the number of rows determines the number of chains that are run. +#' If you provide a matrix with start values, the number of rows determines the number of chains that will be run. #' The number of coloumns must be equivalent to the number of parameters in your bayesianSetup. \cr\cr #' There are several small differences in the algorithm presented here compared to the original paper by Vrugt et al. (2009). Mainly -#' the algorithm implemented here does not have an automatic stopping criterion. Hence, it will +#' The algorithm implemented here does not have an automatic stopping criterion. Hence, it will #' always run the number of iterations specified by the user. Also, convergence is not #' monitored and left to the user. This can easily be done with coda::gelman.diag(chain). -#' Further the proposed delayed rejectio step in Vrugt et al. (2009) is not implemented here.\cr\cr +#' Furthermore, the delayed rejection step proposed in Vrugt et al. (2009) is not implemented here.\cr\cr #' #' During the adaptation phase DREAM is running two mechanisms to enhance the sampler's efficiency. -#' First the disribution of crossover values is tuned to favor large jumps in the parameter space. +#' First, the disribution of crossover values is tuned to favor large jumps in the parameter space. #' The crossover probabilities determine how many parameters are updated simultaneously. -#' Second outlier chains are replanced as they can largely deteriorate the sampler's performance. +#' Second, outlier chains are replaced as they can largely deteriorate the sampler's performance. #' However, these steps destroy the detailed balance of the chain. Consequently these parts of the chain #' should be discarded when summarizing posterior moments. This can be done automatically during the -#' sampling process (i.e. burnin > adaptation) or subsequently by the user. We chose to distinguish between -#' the burnin and adaptation phase to allow the user more flexibility in the sampler's settings. +#' sampling process (i.e. burn-in > adaptation) or subsequently by the user. We chose to distinguish between +#' the burn-in and adaptation phase to allow the user more flexibility in the sampler's settings. #' #' #' @example /inst/examples/DEfamilyHelp.R diff --git a/BayesianTools/R/mcmcDREAM_helperFunctions.R b/BayesianTools/R/mcmcDREAM_helperFunctions.R index a798bef..e0b4b4c 100644 --- a/BayesianTools/R/mcmcDREAM_helperFunctions.R +++ b/BayesianTools/R/mcmcDREAM_helperFunctions.R @@ -1,8 +1,6 @@ - - ##' Generates matrix of CR values based on pCR -##' @param pCR Vector of crossover probabilities. Needs to be of length nCR. -##' @param settings settings list +##' @param pCR vector of crossover probabilities. Needs to be of length nCR. +##' @param settings list of settings ##' @param Npop number of chains ##' @return Matrix with CR values #' @keywords internal @@ -35,10 +33,9 @@ generateCRvalues <- function(pCR,settings, Npop){ - #' Adapts pCR values -#' @param CR Vector of crossover probabilities. Needs to be of length nCR. -#' @param settings settings list +#' @param CR vector of crossover probabilities. Needs to be of length nCR. +#' @param settings list of settings #' @param delta vector with differences #' @param lCR values to weight delta #' @param Npop number of chains. diff --git a/BayesianTools/R/mcmcDREAMzs.R b/BayesianTools/R/mcmcDREAMzs.R index 0467da3..ae513be 100644 --- a/BayesianTools/R/mcmcDREAMzs.R +++ b/BayesianTools/R/mcmcDREAMzs.R @@ -1,47 +1,48 @@ + ### DREAMzs algorithm #' DREAMzs #' @author Stefan Paul -#' @param bayesianSetup Object of class 'bayesianSetup' or 'bayesianOuput'. +#' @param bayesianSetup object of class 'bayesianSetup' or 'bayesianOuput'. #' @param settings list with parameter values -#' @param iterations Number of model evaluations -#' @param nCR parameter determining the number of cross-over proposals. If nCR = 1 all parameters are updated jointly. -#' @param updateInterval determining the intervall for the pCR (crossover probabilities) update -#' @param gamma Kurtosis parameter Bayesian Inference Scheme. +#' @param iterations number of model evaluations +#' @param nCR parameter determining the number of cross-over proposals. If nCR = 1 all parameters are updated jointly. +#' @param updateInterval determines the interval for the pCR (crossover probabilities) update +#' @param gamma kurtosis parameter Bayesian Inference Scheme. #' @param eps Ergodicity term #' @param e Ergodicity term -#' @param pCRupdate Update of crossover probabilities +#' @param pCRupdate update of crossover probabilities #' @param burnin number of iterations treated as burn-in. These iterations are not recorded in the chain. -#' @param thin thin thinning parameter. Determines the interval in which values are recorded. -#' @param adaptation Number or percentage of samples that are used for the adaptation in DREAM (see Details) -#' @param DEpairs Number of pairs used to generate proposal +#' @param thin thinning parameter. Determines the interval in which values are recorded. +#' @param adaptation number or percentage of samples that are used for the adaptation in DREAM (see Details) +#' @param DEpairs number of pairs used to generate proposal #' @param ZupdateFrequency frequency to update Z matrix #' @param pSnooker probability of snooker update #' @param Z starting matrix for Z -#' @param startValue eiter a matrix containing the start values (see details), an integer to define the number of chains that are run, a function to sample the start values or NUll, in which case the values are sampled from the prior. -#' @param consoleUpdates Intervall in which the sampling progress is printed to the console -#' @param message logical determines whether the sampler's progress should be printed +#' @param startValue either a matrix containing the start values (see details), an integer to define the number of chains to be run, a function to sample the start values or NUll - in which case the values are sampled from the prior. +#' @param consoleUpdates interval in which the sampling progress is printed to the console +#' @param message logical, determines whether the sampler's progress should be printed #' @return mcmc.object containing the following elements: chains, X, pCR, Z #' @references Vrugt, Jasper A., et al. "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 (2009): 273-290. #' @references ter Braak C. J. F., and Vrugt J. A. (2008). Differential Evolution Markov Chain with snooker updater and fewer chains. Statistics and Computing http://dx.doi.org/10.1007/s11222-008-9104-9 -#' @details Insted of a bayesianSetup, the function can take the output of a previous run to restart the sampler +#' @details Instead of a bayesianSetup, the function can take the output of a previous run to restart the sampler #' from the last iteration. Due to the sampler's internal structure you can only use the output #' of DREAMzs. -#' If you provide a matrix with start values the number of rows detemines the number of chains that are run. -#' The number of coloumns must be equivalent to the number of parameters in your bayesianSetup. \cr\cr +#' If you provide a matrix with start values, the number of rows determines the number of chains that will be run. +#' The number of columns must be equivalent to the number of parameters in your bayesianSetup. \cr\cr #' There are several small differences in the algorithm presented here compared to the original paper by Vrugt et al. (2009). Mainly -#' the algorithm implemented here does not have an automatic stopping criterion. Hence, it will +#' The algorithm implemented here does not have an automatic stopping criterion. Hence, it will #' always run the number of iterations specified by the user. Also, convergence is not #' monitored and left to the user. This can easily be done with coda::gelman.diag(chain). -#' Further the proposed delayed rejectio step in Vrugt et al. (2009) is not implemented here.\cr\cr +#' Furthermore, the delayed rejection step proposed in Vrugt et al. (2009) is not implemented here.\cr\cr #' During the adaptation phase DREAM is running two mechanisms to enhance the sampler's efficiency. -#' First the disribution of crossover values is tuned to favor large jumps in the parameter space. +#' First, the distribution of crossover values is tuned to favor large jumps in the parameter space. #' The crossover probabilities determine how many parameters are updated simultaneously. -#' Second outlier chains are replanced as they can largely deteriorate the sampler's performance. +#' Second, outlier chains are replaced as they can largely deteriorate the sampler's performance. #' However, these steps destroy the detailed balance of the chain. Consequently these parts of the chain #' should be discarded when summarizing posterior moments. This can be done automatically during the -#' sampling process (i.e. burnin > adaptation) or subsequently by the user. We chose to distinguish between -#' the burnin and adaptation phase to allow the user more flexibility in the sampler's settings. +#' sampling process (i.e. burn-in > adaptation) or subsequently by the user. We chose to distinguish between +#' the burn-in and adaptation phase to allow the user more flexibility in the sampler's settings. #' @example /inst/examples/DEfamilyHelp.R #' @seealso \code{\link{DREAM}} #' @export diff --git a/BayesianTools/R/mcmcFrancesco.R b/BayesianTools/R/mcmcFrancesco.R index be874ea..982e505 100644 --- a/BayesianTools/R/mcmcFrancesco.R +++ b/BayesianTools/R/mcmcFrancesco.R @@ -1,14 +1,15 @@ + #' The Metropolis Algorithm #' @author Francesco Minunno #' @description The Metropolis Algorithm (Metropolis et al. 1953) -#' @param startValue vector with the start values for the algorithm. Can be NULL if FUN is of class BayesianSetup. In this case startValues are sampled from the prior. -#' @param iterations iterations to run -#' @param nBI number of burnin +#' @param startValue vector with the start values for the algorithm. Can be NULL if FUN is of class BayesianSetup. In this case, startValues are sampled from the prior. +#' @param iterations number of iterations to run +#' @param nBI number of burn-in #' @param parmin minimum values for the parameter vector or NULL if FUN is of class BayesianSetup #' @param parmax maximum values for the parameter vector or NULL if FUN is of class BayesianSetup #' @param f scaling factor #' @param FUN function to be sampled from or object of class bayesianSetup -#' @param consoleUpdates interger, determines the frequency with which sampler progress is printed to the console +#' @param consoleUpdates integer, determines the frequency with which sampler progress is printed to the console #' @references Metropolis, Nicholas, et al. "Equation of state calculations by fast computing machines." The journal of chemical physics 21.6 (1953): 1087-1092. #' @keywords internal # #' @export diff --git a/BayesianTools/R/mcmcMetropolis.R b/BayesianTools/R/mcmcMetropolis.R index 3a6a4bc..4230eca 100644 --- a/BayesianTools/R/mcmcMetropolis.R +++ b/BayesianTools/R/mcmcMetropolis.R @@ -1,21 +1,22 @@ + #' Creates a Metropolis-type MCMC with options for covariance adaptatin, delayed rejection, Metropolis-within-Gibbs, and tempering #' @author Florian Hartig #' @param bayesianSetup either an object of class bayesianSetup created by \code{\link{createBayesianSetup}} (recommended), or a log target function -#' @param settings a list of settings - possible options follow below +#' @param settings a list of settings - possible options follow #' @param startValue startValue for the MCMC and optimization (if optimize = T). If not provided, the sampler will attempt to obtain the startValue from the bayesianSetup #' @param optimize logical, determines whether an optimization for start values and proposal function should be run before starting the sampling -#' @param proposalGenerator optional proposalgenerator object (see \code{\link{createProposalGenerator}}) +#' @param proposalGenerator optional, proposalgenerator object (see \code{\link{createProposalGenerator}}) #' @param proposalScaling additional scaling parameter for the proposals that controls the different scales of the proposals after delayed rejection (typical, after a rejection, one would want to try a smaller scale). Needs to be as long as DRlevels. Defaults to 0.5^(- 0:(mcmcSampler$settings$DRlevels -1) #' @param burnin number of iterations treated as burn-in. These iterations are not recorded in the chain. #' @param thin thinning parameter. Determines the interval in which values are recorded. #' @param consoleUpdates integer, determines the frequency with which sampler progress is printed to the console -#' @param adapt logical, determines wheter an adaptive algorithm should be implemented. Default is TRUE. +#' @param adapt logical, determines whether an adaptive algorithm should be implemented. Default is TRUE. #' @param adaptationInterval integer, determines the interval of the adaption if adapt = TRUE. #' @param adaptationNotBefore integer, determines the start value for the adaption if adapt = TRUE. #' @param DRlevels integer, determines the number of levels for a delayed rejection sampler. Default is 1, which means no delayed rejection is used. #' @param temperingFunction function to implement simulated tempering in the algorithm. The function describes how the acceptance rate will be influenced in the course of the iterations. -#' @param gibbsProbabilities vector that defines the relative probabilities of the number of parameters to be changes simultaniously. -#' @param message logical determines whether the sampler's progress should be printed +#' @param gibbsProbabilities vector that defines the relative probabilities of the number of parameters to be changed simultaneously. +#' @param message logical, determines whether the sampler's progress should be printed #' @details The 'Metropolis' function is the main function for all Metropolis based samplers in this package. To call the derivatives from the basic Metropolis-Hastings MCMC, you can either use the corresponding function (e.g. \code{\link{AM}} for an adaptive Metropolis sampler) or use the parameters to adapt the basic Metropolis-Hastings. The advantage of the latter case is that you can easily combine different properties (e.g. adapive sampling and delayed rejection sampling) without changing the function. #' @import coda #' @example /inst/examples/MetropolisHelp.R diff --git a/BayesianTools/R/mcmcMultipleChains.R b/BayesianTools/R/mcmcMultipleChains.R index 84fa49c..1ebdfc2 100644 --- a/BayesianTools/R/mcmcMultipleChains.R +++ b/BayesianTools/R/mcmcMultipleChains.R @@ -1,5 +1,6 @@ + #' Run multiple chains -#' @param bayesianSetup Object of class "BayesianSetup" +#' @param bayesianSetup object of class "BayesianSetup" #' @param settings list with settings for sampler #' @param sampler character, either "Metropolis" or "DE" #' @return list containing the single runs ($sampler) and the chains in a coda::mcmc.list ($mcmc.list) diff --git a/BayesianTools/R/mcmcRun.R b/BayesianTools/R/mcmcRun.R index b273a90..db51f84 100644 --- a/BayesianTools/R/mcmcRun.R +++ b/BayesianTools/R/mcmcRun.R @@ -1,3 +1,4 @@ + #' Main wrapper function to start MCMCs, particle MCMCs and SMCs #' @author Florian Hartig #' @param bayesianSetup either a BayesianSetup (see \code{\link{createBayesianSetup}}), a function, or a BayesianOutput created by runMCMC. The latter allows to continue a previous MCMC run. See details for how to restart a sampler. @@ -24,7 +25,7 @@ #' #' Note that even if you specify parallel = T, this will only turn on internal parallelization of the samplers. The independent samplers controlled by nrChains are not evaluated in parallel, so if time is an issue it will be better to run the MCMCs individually and then combine them via \code{\link{createMcmcSamplerList}} into one joint object. #' -#' Note that DE and DREAM variants as well as SMC and T-walk require a population to start, which should be provided as a matrix. Default (NULL) sets the population size for DE to 3 x dimensions of parameters, for DREAM to 2 x dimensions of parameters and for DEzs and DREAMzs to three, sampled from the prior. Note also that the zs variants of DE and DREAM require two populations, the current population and the z matrix (a kind of memory) - if you want to set both, provide a list with startvalue$X and startvalue$Z. +#' Note that, DE and DREAM variants as well as SMC and T-walk require a population to start, which should be provided as a matrix. Default (NULL) sets the population size for DE to 3 x dimensions of parameters, for DREAM to 2 x dimensions of parameters and for DEzs and DREAMzs to three, sampled from the prior. Note also that the zs variants of DE and DREAM require two populations, the current population and the z matrix (a kind of memory) - if you want to set both, provide a list with startvalue$X and startvalue$Z. #' #' setting startValue for sampling with nrChains > 1 : if you want to provide different start values for the different chains, provide them as a list #' diff --git a/BayesianTools/R/mcmcTwalk.R b/BayesianTools/R/mcmcTwalk.R index ffceb46..7ab1c5d 100644 --- a/BayesianTools/R/mcmcTwalk.R +++ b/BayesianTools/R/mcmcTwalk.R @@ -1,19 +1,20 @@ + #' T-walk MCMC #' @author Stefan Paul -#' @param bayesianSetup Object of class 'bayesianSetup' or 'bayesianOuput'. +#' @param bayesianSetup object of class 'bayesianSetup' or 'bayesianOuput'. #' @param settings list with parameter values. -#' @param iterations Number of model evaluations +#' @param iterations number of model evaluations #' @param at "traverse" move proposal parameter. Default to 6 #' @param aw "walk" move proposal parameter. Default to 1.5 -#' @param pn1 Probability determining the number of parameters that are changed -#' @param Ptrav Move probability of "traverse" moves, default to 0.4918 -#' @param Pwalk Move probability of "walk" moves, default to 0.4918 -#' @param Pblow Move probability of "traverse" moves, default to 0.0082 +#' @param pn1 probability determining the number of parameters that are changed +#' @param Ptrav move probability of "traverse" moves, default to 0.4918 +#' @param Pwalk move probability of "walk" moves, default to 0.4918 +#' @param Pblow move probability of "traverse" moves, default to 0.0082 #' @param burnin number of iterations treated as burn-in. These iterations are not recorded in the chain. #' @param thin thinning parameter. Determines the interval in which values are recorded. -#' @param startValue Matrix with start values -#' @param consoleUpdates Intervall in which the sampling progress is printed to the console -#' @param message logical determines whether the sampler's progress should be printed +#' @param startValue matrix with start values +#' @param consoleUpdates intervall in which the sampling progress is printed to the console +#' @param message logical, determines whether the sampler's progress should be printed #' @details ##' The probability of "hop" moves is 1 minus the sum of all other probabilities. #' @return Object of class bayesianOutput. diff --git a/BayesianTools/R/mcmcTwalk_helperFunctions.R b/BayesianTools/R/mcmcTwalk_helperFunctions.R index 8aaaf41..438bc22 100644 --- a/BayesianTools/R/mcmcTwalk_helperFunctions.R +++ b/BayesianTools/R/mcmcTwalk_helperFunctions.R @@ -2,9 +2,10 @@ # Twalk helper functions ###### + #' Wrapper for step function -#' @param Npar Number of parameters -#' @param FUN Log posterior density +#' @param Npar number of parameters +#' @param FUN log posterior density #' @param x parameter vector of chain 1 #' @param Eval last evaluation of x #' @param x2 parameter vector of chain 2 diff --git a/BayesianTools/R/plotCorrelationDensity.r b/BayesianTools/R/plotCorrelationDensity.r index 9a87d65..3f4a816 100644 --- a/BayesianTools/R/plotCorrelationDensity.r +++ b/BayesianTools/R/plotCorrelationDensity.r @@ -1,3 +1,4 @@ + #' Flexible function to create correlation density plots #' @author Florian Hartig #' @param mat object of class "bayesianOutput" or a matrix or data frame of variables @@ -5,8 +6,8 @@ #' @param thin thinning of the matrix to make things faster. Default is to thin to 5000 #' @param method method for calculating correlations. Possible choices are "pearson" (default), "kendall" and "spearman" #' @param whichParameters indices of parameters that should be plotted -#' @param scaleCorText should the text to display correlation be scaled to the strength of the correlation -#' @param ... additional parameters to pass on to the \code{\link{getSample}}, for example parametersOnly =F, or start = 1000 +#' @param scaleCorText should the text to display correlation be scaled to the strength of the correlation? +#' @param ... additional parameters to pass on to the \code{\link{getSample}}, for example parametersOnly = F, or start = 1000 #' @references The code for the correlation density plot originates from Hartig, F.; Dislich, C.; Wiegand, T. & Huth, A. (2014) Technical Note: Approximate Bayesian parameterization of a process-based tropical forest model. Biogeosciences, 11, 1261-1272. #' @export #' @seealso \code{\link{marginalPlot}} \cr diff --git a/BayesianTools/R/plotDiagnostic.R b/BayesianTools/R/plotDiagnostic.R index 6178c14..5381c65 100644 --- a/BayesianTools/R/plotDiagnostic.R +++ b/BayesianTools/R/plotDiagnostic.R @@ -5,17 +5,16 @@ #' @param start start value for calculating DIC, WAIC, mPSRF and PSRF, default = 50 #' @param numSamples for calculating WAIC, default = 10 because of high computational costs #' @param window plot range to show, vector of percents or only one value as start value for the window -#' @param plotWAIC whether to calculate WAIC or not, default = T -#' @param plotPSRF calculate and plot mPSRF/PSRF or not, default = T -#' @param plotDIC calculate and plot DICor not, default = T -#' @param plotTrace show trace plots or not, default = T +#' @param plotWAIC logical, whether to calculate WAIC or not, default = T +#' @param plotPSRF logical, whether to calculate and plot mPSRF/PSRF or not, default = T +#' @param plotDIC logical, whether to calculate and plot DIC or not, default = T +#' @param plotTrace logical, whether to show trace plots or not, default = T #' @param graphicParameters graphic parameters as list for plot function #' @param ... parameters to give to getSample #' @example /inst/examples/plotDiagnosticHelp.R #' @export - plotDiagnostic <- function(out, start = 50, numSamples = 100, window = 0.2, plotWAIC = F, plotPSRF = T, plotDIC = T, plotTrace = T, graphicParameters = NULL, ...){ oldpar = NULL diff --git a/BayesianTools/R/plotMarginals.R b/BayesianTools/R/plotMarginals.R index ca829a4..91d71c7 100644 --- a/BayesianTools/R/plotMarginals.R +++ b/BayesianTools/R/plotMarginals.R @@ -1,13 +1,14 @@ #' @export marginalPlot <- function(x, ...) UseMethod("marginalPlot") + #' Plot MCMC marginals -#' @param x bayesianOutput, or matrix or data.frame containing with samples as rows and parameters as columns -#' @param prior if x is a bayesianOutput, T/F will determine if the prior is drawn (default = T). If x is matrix oder data.frame, a prior can be drawn if a matrix of prior draws with values as rows and parameters as columns can be provided here. -#' @param xrange vector or matrix of plotting ranges for the x axis. If matrix, the rows must be parameters and the columns min and max values. -#' @param type character determining the plot type. Either 'd' for density plot, or 'v' for violin plot -#' @param singlePanel logical, determining whether the parameter should be plotted in a single panel or each in its own panel -#' @param settings optional list of additional settings for \code{\link{marginalPlotDensity}}, and \code{\link{marginalPlotViolin}}, respectively +#' @param x bayesianOutput, or matrix or data.frame with samples as rows and parameters as columns +#' @param prior if x is a bayesianOutput, T/F will determines whether the prior is drawn (default = T). If x is matrix or data.frame, a prior can be drawn if a matrix of prior draws with values as rows and parameters as columns can be provided here. +#' @param xrange vector or matrix of plot ranges for the x-axis. If matrix, the rows must be parameters and the columns must be min and max values. +#' @param type character, determes the plot type. Either 'd' for density plot, or 'v' for violin plot +#' @param singlePanel logical, determines whether the parameter should be plotted in a single panel or each in its own panel +#' @param settings optional, list of additional settings for \code{\link{marginalPlotDensity}}, and \code{\link{marginalPlotViolin}}, respectively #' @param nPriorDraws number of draws from the prior, if x is bayesianOutput #' @param ... additional arguments passed to \code{\link{getSample}}. If you have a high number of draws from the posterior it is advised to set numSamples (to e.g. 5000) for performance reasons. #' @example /inst/examples/marginalPlotHelp.R diff --git a/BayesianTools/R/plotSensitivityOAT.R b/BayesianTools/R/plotSensitivityOAT.R index 1c2b060..66a3c4a 100644 --- a/BayesianTools/R/plotSensitivityOAT.R +++ b/BayesianTools/R/plotSensitivityOAT.R @@ -1,8 +1,9 @@ + #' Performs a one-factor-at-a-time sensitivity analysis for the posterior of a given bayesianSetup within the prior range. #' @author Florian Hartig -#' @param bayesianSetup An object of class BayesianSetup +#' @param bayesianSetup an object of class BayesianSetup #' @param selection indices of selected parameters -#' @param equalScale if T, y axis of all plots will have the same scale +#' @param equalScale if T, y-axis of all plots will have the same scale #' @note This function can also be used for sensitivity analysis of an arbitrary output - just create a BayesianSetup with this output. #' @example /inst/examples/plotSensitivityHelp.R #' @export diff --git a/BayesianTools/R/plotTrace.R b/BayesianTools/R/plotTrace.R index b61a3e2..45f2216 100644 --- a/BayesianTools/R/plotTrace.R +++ b/BayesianTools/R/plotTrace.R @@ -1,7 +1,8 @@ + #' Trace plot for MCMC class #' @param sampler an object of class MCMC sampler -#' @param thin determines the thinning intervall of the chain -#' @param ... additional parameters to pass on to the \code{\link{getSample}}, for example parametersOnly =F, or start = 1000 +#' @param thin determines the thinning interval of the chain +#' @param ... additional parameters to pass on to the \code{\link{getSample}}, for example parametersOnly = F, or start = 1000 #' @export #' @seealso \code{\link{marginalPlot}} \cr #' \code{\link{plotTimeSeries}} \cr diff --git a/BayesianTools/R/proposalGenerator.R b/BayesianTools/R/proposalGenerator.R index f4abae0..a69262f 100644 --- a/BayesianTools/R/proposalGenerator.R +++ b/BayesianTools/R/proposalGenerator.R @@ -1,11 +1,12 @@ + #' Factory that creates a proposal generator #' @author Florian Hartig #' @param covariance covariance matrix. Can also be vector of the sqrt of diagonal elements --> standard deviation -#' @param gibbsProbabilities optional probabilities for the number of parameters to vary in a Metropolis within gibbs style - for 4 parameters, c(1,1,0.5,0) means that at most 3 parameters will be varied, and it is double as likely to vary one or two than varying 3 -#' @param gibbsWeights optional probabilities for parameters to be varied in a Metropolis within gibbs style - default ist equal weight for all parameters - for 4 parameters, c(1,1,1,100) would mean that if 2 parameters would be selected, parameter 4 would be 100 times more likely to be picked than the others. If 4 is selected, the remaining parameters have equal probability. -#' @param otherDistribution optional additinal distribution to be mixed with the default multivariate normal. The distribution needs to accept a parameter vector (to allow for the option of making the distribution dependend on the parameter values), but it is still assumed that the change from the current values is returned, not the new absolute values. +#' @param gibbsProbabilities optional, probabilities for the number of parameters to vary in a Metropolis within Gibbs style - for 4 parameters, c(1,1,0.5,0) means that at most 3 parameters will be varied, and it is twice as likely to vary one or two than to vary 3 +#' @param gibbsWeights optional, probabilities for parameters to be varied in a Metropolis within Gibbs style - default is equal weight for all parameters - for 4 parameters, c(1,1,1,100) would mean that if 2 parameters were selected, parameter 4 would be 100 times more likely to be picked than the others. If 4 is selected, the remaining parameters have equal probability. +#' @param otherDistribution optional, additional distribution to be mixed with the default multivariate normal. The distribution needs to accept a parameter vector (to allow the option of making the distribution dependent on the parameter values), but it is still assumed that the change from the current values is returned, not the new absolute values. #' @param otherDistributionLocation a vector with 0 and 1, denoting which parameters are modified by the otherDistribution -#' @param otherDistributionScaled should the other distribution be scaled if gibbs updates are calculated? +#' @param otherDistributionScaled logical, should the other distribution be scaled if Gibbs updates are calculated? #' @param message print out parameter settings #' @param method method for covariance decomposition #' @param scalingFactor scaling factor for the proposals diff --git a/BayesianTools/R/testFunctions.R b/BayesianTools/R/testFunctions.R index c898120..cb31b63 100644 --- a/BayesianTools/R/testFunctions.R +++ b/BayesianTools/R/testFunctions.R @@ -1,9 +1,10 @@ + #' Multivariate normal likelihood #' @author Florian Hartig #' @description Generates a 3 dimensional multivariate normal likelihood function. #' @param mean vector with the three mean values of the distribution #' @param sigma either a correlation matrix, or "strongcorrelation", or "no correlation" -#' @param sample should the function create samples +#' @param sample logical, should the function create samples? #' @param n number of samples to create #' @param throwErrors parameter for test purpose. Between 0 and 1 for proportion of errors #' @details 3-d multivariate normal density function with mean 2,4,0 and either strong correlation (default), or no correlation. diff --git a/BayesianTools/R/utils-Numerics.R b/BayesianTools/R/utils-Numerics.R index 125cbe3..e3bb9d2 100644 --- a/BayesianTools/R/utils-Numerics.R +++ b/BayesianTools/R/utils-Numerics.R @@ -1,3 +1,4 @@ + # inspired from https://gist.github.com/doobwa/941125 # maybe replace with logSumExp {matrixStats} which might be faster? diff --git a/BayesianTools/R/utils.R b/BayesianTools/R/utils.R index c65a633..fd9444f 100644 --- a/BayesianTools/R/utils.R +++ b/BayesianTools/R/utils.R @@ -10,6 +10,7 @@ getSetup <- function(x) { else stop('Can not get setup from x') } + #' Function to thin matrices #' @param mat matrix to thin #' @param thin thinning parameter @@ -32,7 +33,7 @@ thinMatrix <- function(mat, thin = "auto"){ #' @param mat matrix to scale #' @param min minimum value #' @param max maximum value -#' @return sclaed matrix +#' @return scaled matrix #' @keywords internal scaleMatrix <- function(mat, min, max){ if(class(mat)[1] %in% c("matrix", "data.frame")){ @@ -130,7 +131,7 @@ sampleEquallySpaced <- function(x, numSamples) { #' Checks if thin is consistent with nTotalSamples samples and if not corrects it. #' @author Tankred Ott #' @param nTotalSamples total number of rows/samples -#' @param thin thinning +#' @param thin thinning parameter #' @param autoThinFraction fraction of the data that will be sampled when thin is set to "auto". E.g. 0.5 means thin will be nTotalSamples * 0.5. The resulting thin value is rounded down to the next integer. #' @details Checks if the thin argument is consistent with the data consisting of nTotalSamples samples/rows and corrects thin if not. #' @author Tankred Ott @@ -155,7 +156,7 @@ correctThin <- function(nTotalSamples, thin, autoThinFraction = 0.001) { #' @title Rescale #' @description Rescales values in the interval "from" (lower, upper) to the new interval "to" (lower, upper). -#' @param x vector of values tp be scaled +#' @param x vector of values to be scaled #' @param from vector of length 2, original interval (lower, upper) #' @param to vector of length 2, target interval (lower, upper) #' diff --git a/BayesianTools/man/AdaptpCR.Rd b/BayesianTools/man/AdaptpCR.Rd index 3a7bfb4..1801699 100644 --- a/BayesianTools/man/AdaptpCR.Rd +++ b/BayesianTools/man/AdaptpCR.Rd @@ -7,13 +7,13 @@ AdaptpCR(CR, delta, lCR, settings, Npop) } \arguments{ -\item{CR}{Vector of crossover probabilities. Needs to be of length nCR.} +\item{CR}{vector of crossover probabilities. Needs to be of length nCR.} \item{delta}{vector with differences} \item{lCR}{values to weight delta} -\item{settings}{settings list} +\item{settings}{list of settings} \item{Npop}{number of chains.} } diff --git a/BayesianTools/man/DE.Rd b/BayesianTools/man/DE.Rd index a55b88f..2fcb7bf 100644 --- a/BayesianTools/man/DE.Rd +++ b/BayesianTools/man/DE.Rd @@ -17,7 +17,7 @@ DE( \item{settings}{list with parameter settings} -\item{startValue}{(optional) eiter a matrix with start population, a number to define the number of chains that are run or a function that samples a starting population.} +\item{startValue}{(optional) either a matrix with start population, a number defining the number of chains to be run or a function that samples a starting population.} \item{iterations}{number of function evaluations.} @@ -31,7 +31,7 @@ DE( \item{blockUpdate}{list determining whether parameters should be updated in blocks. For possible settings see Details.} -\item{message}{logical determines whether the sampler's progress should be printed} +\item{message}{logical, Specifies whether to print the progress of the sampler.} } \description{ Differential-Evolution MCMC @@ -45,18 +45,18 @@ Possible choices are \item{"random"} { random blocking. Using k (see below)} \item{"user"} { user defined groups. Using groups (see below)} } -Further seven parameters can be specified. "k" determnined the number of groups, "h" the strength -of the correlation used to group parameter and "groups" is used for user defined groups. +Further, seven parameters can be specified. "k" defines the number of groups, "h" the strength +of the correlation used to group the parameters and "groups" is used for user defined groups. "groups" is a vector containing the group number for each parameter. E.g. for three parameters with the first two in one group, "groups" would be c(1,1,2). -Further pSel and pGroup can be used to influence the choice of groups. In the sampling process -a number of groups is randomly drawn and updated. pSel is a vector containing relative probabilities -for an update of the respective number of groups. E.g. for always updating only one group pSel = 1. +Moreover, pSel and pGroup can be used to influence the choice of groups. In the sampling process +a number of groups are drawn at random and updated. pSel is a vector containing relative probabilities +for updating the respective number of groups. E.g. To update one group at a time pSel = 1. For updating one or two groups with the same probability pSel = c(1,1). By default all numbers have the same probability. -The same principle is used in pGroup. Here the user can influence the probability of each group +The same principle is used for pGroup. Here the user can influence the probability of each group to be updated. By default all groups have the same probability. -Finally "groupStart" defines the starting point of the groupUpdate and "groupIntervall" the intervall +Finally, "groupStart" defines the starting point of the groupUpdate and "groupIntervall" - the interval in which the groups are evaluated. } \examples{ diff --git a/BayesianTools/man/DEzs.Rd b/BayesianTools/man/DEzs.Rd index df53820..37bc139 100644 --- a/BayesianTools/man/DEzs.Rd +++ b/BayesianTools/man/DEzs.Rd @@ -18,11 +18,11 @@ DEzs( \item{settings}{list with parameter settings} -\item{startValue}{(optional) eiter a matrix with start population, a number to define the number of chains that are run or a function that samples a starting population.} +\item{startValue}{(optional) either a matrix with start population, a number to define the number of chains that are run or a function that samples a starting population.} \item{Z}{starting Z population} -\item{iterations}{iterations to run} +\item{iterations}{number of iterations to run} \item{pSnooker}{probability of Snooker update} @@ -44,13 +44,13 @@ DEzs( \item{blockUpdate}{list determining whether parameters should be updated in blocks. For possible settings see Details.} -\item{message}{logical determines whether the sampler's progress should be printed} +\item{message}{logical, specifies whether to print the progress of the sampler.} } \description{ Differential-Evolution MCMC zs } \details{ -For parallel computing, the likelihood density in the bayesianSetup needs to be parallelized, i.e. needs to be able to operate on a matrix of proposals +For parallel computing, the likelihood density in the bayesianSetup needs to be parallelized, i.e., it needs to be able to operate on a matrix of proposals For blockUpdate the first element in the list determines the type of blocking. Possible choices are @@ -60,18 +60,18 @@ Possible choices are \item{"random"} { random blocking. Using k (see below)} \item{"user"} { user defined groups. Using groups (see below)} } -Further seven parameters can be specified. "k" determnined the number of groups, "h" the strength +Further, seven parameters can be specified. "k" defines the number of groups, "h" the strength of the correlation used to group parameter and "groups" is used for user defined groups. "groups" is a vector containing the group number for each parameter. E.g. for three parameters with the first two in one group, "groups" would be c(1,1,2). -Further pSel and pGroup can be used to influence the choice of groups. In the sampling process -a number of groups is randomly drawn and updated. pSel is a vector containing relative probabilities -for an update of the respective number of groups. E.g. for always updating only one group pSel = 1. +Moreover, pSel and pGroup can be used to influence the choice of groups. In the sampling process +a number of groups is drawn at random and updated. pSel is a vector containing relative probabilities +for updating the respective number of groups. E.g. To update one group at a time pSel = 1. For updating one or two groups with the same probability pSel = c(1,1). By default all numbers have the same probability. -The same principle is used in pGroup. Here the user can influence the probability of each group +The same principle is used in pGroup. Here, the user can influence the probability of each group to be updated. By default all groups have the same probability. -Finally "groupStart" defines the starting point of the groupUpdate and "groupIntervall" the intervall +Finally, "groupStart" defines the starting point of the groupUpdate and "groupIntervall" - the interval in which the groups are evaluated. } \examples{ diff --git a/BayesianTools/man/DREAM.Rd b/BayesianTools/man/DREAM.Rd index e6da437..7146f27 100644 --- a/BayesianTools/man/DREAM.Rd +++ b/BayesianTools/man/DREAM.Rd @@ -13,15 +13,15 @@ DREAM( ) } \arguments{ -\item{bayesianSetup}{Object of class 'bayesianSetup' or 'bayesianOuput'.} +\item{bayesianSetup}{object of class 'bayesianSetup' or 'bayesianOuput'.} \item{settings}{list with parameter values} -\item{iterations}{Number of model evaluations} +\item{iterations}{number of model evaluations} \item{nCR}{parameter determining the number of cross-over proposals. If nCR = 1 all parameters are updated jointly.} -\item{updateInterval}{determining the intervall for the pCR update} +\item{updateInterval}{determines the interval for the pCR update} \item{gamma}{Kurtosis parameter Bayesian Inference Scheme} @@ -29,21 +29,21 @@ DREAM( \item{e}{Ergodicity term} -\item{pCRupdate}{If T, crossover probabilities will be updated} +\item{pCRupdate}{logical, if T, crossover probabilities will be updated} \item{burnin}{number of iterations treated as burn-in. These iterations are not recorded in the chain.} -\item{thin}{thin thinning parameter. Determines the interval in which values are recorded.} +\item{thin}{thinning parameter. Determines the interval in which values are recorded.} -\item{adaptation}{Number or percentage of samples that are used for the adaptation in DREAM (see Details).} +\item{adaptation}{number or percentage of samples that are used for the adaptation in DREAM (see Details).} -\item{DEpairs}{Number of pairs used to generate proposal} +\item{DEpairs}{number of pairs used to generate proposal} -\item{startValue}{eiter a matrix containing the start values (see details), an integer to define the number of chains that are run, a function to sample the start values or NUll, in which case the values are sampled from the prior.} +\item{startValue}{either a matrix containing the start values (see details), an integer to define the number of chains to be run, a function to sample the start values or NUll - in which case the values are sampled from the prior.} -\item{consoleUpdates}{Intervall in which the sampling progress is printed to the console} +\item{consoleUpdates}{interval at which the sampling progress is printed to the console} -\item{message}{logical determines whether the sampler's progress should be printed} +\item{message}{logical, determines whether the sampler's progress should be printed} } \value{ mcmc.object containing the following elements: chains, X, pCR @@ -52,25 +52,25 @@ mcmc.object containing the following elements: chains, X, pCR DREAM } \details{ -Insted of a bayesianSetup, the function can take the output of a previous run to restart the sampler +Instead of a bayesianSetup, the function can take the output of a previous run to restart the sampler from the last iteration. Due to the sampler's internal structure you can only use the output of DREAM. -If you provide a matrix with start values the number of rows determines the number of chains that are run. +If you provide a matrix with start values, the number of rows determines the number of chains that will be run. The number of coloumns must be equivalent to the number of parameters in your bayesianSetup. \cr\cr There are several small differences in the algorithm presented here compared to the original paper by Vrugt et al. (2009). Mainly -the algorithm implemented here does not have an automatic stopping criterion. Hence, it will +The algorithm implemented here does not have an automatic stopping criterion. Hence, it will always run the number of iterations specified by the user. Also, convergence is not monitored and left to the user. This can easily be done with coda::gelman.diag(chain). -Further the proposed delayed rejectio step in Vrugt et al. (2009) is not implemented here.\cr\cr +Furthermore, the delayed rejection step proposed in Vrugt et al. (2009) is not implemented here.\cr\cr During the adaptation phase DREAM is running two mechanisms to enhance the sampler's efficiency. -First the disribution of crossover values is tuned to favor large jumps in the parameter space. +First, the disribution of crossover values is tuned to favor large jumps in the parameter space. The crossover probabilities determine how many parameters are updated simultaneously. -Second outlier chains are replanced as they can largely deteriorate the sampler's performance. +Second, outlier chains are replaced as they can largely deteriorate the sampler's performance. However, these steps destroy the detailed balance of the chain. Consequently these parts of the chain should be discarded when summarizing posterior moments. This can be done automatically during the -sampling process (i.e. burnin > adaptation) or subsequently by the user. We chose to distinguish between -the burnin and adaptation phase to allow the user more flexibility in the sampler's settings. +sampling process (i.e. burn-in > adaptation) or subsequently by the user. We chose to distinguish between +the burn-in and adaptation phase to allow the user more flexibility in the sampler's settings. } \examples{ library(BayesianTools) diff --git a/BayesianTools/man/DREAMzs.Rd b/BayesianTools/man/DREAMzs.Rd index 80f1805..97fc4b6 100644 --- a/BayesianTools/man/DREAMzs.Rd +++ b/BayesianTools/man/DREAMzs.Rd @@ -13,31 +13,31 @@ DREAMzs( ) } \arguments{ -\item{bayesianSetup}{Object of class 'bayesianSetup' or 'bayesianOuput'.} +\item{bayesianSetup}{object of class 'bayesianSetup' or 'bayesianOuput'.} \item{settings}{list with parameter values} -\item{iterations}{Number of model evaluations} +\item{iterations}{number of model evaluations} -\item{nCR}{parameter determining the number of cross-over proposals. If nCR = 1 all parameters are updated jointly.} +\item{nCR}{parameter determining the number of cross-over proposals. If nCR = 1 all parameters are updated jointly.} -\item{updateInterval}{determining the intervall for the pCR (crossover probabilities) update} +\item{updateInterval}{determines the interval for the pCR (crossover probabilities) update} -\item{gamma}{Kurtosis parameter Bayesian Inference Scheme.} +\item{gamma}{kurtosis parameter Bayesian Inference Scheme.} \item{eps}{Ergodicity term} \item{e}{Ergodicity term} -\item{pCRupdate}{Update of crossover probabilities} +\item{pCRupdate}{update of crossover probabilities} \item{burnin}{number of iterations treated as burn-in. These iterations are not recorded in the chain.} -\item{thin}{thin thinning parameter. Determines the interval in which values are recorded.} +\item{thin}{thinning parameter. Determines the interval in which values are recorded.} -\item{adaptation}{Number or percentage of samples that are used for the adaptation in DREAM (see Details)} +\item{adaptation}{number or percentage of samples that are used for the adaptation in DREAM (see Details)} -\item{DEpairs}{Number of pairs used to generate proposal} +\item{DEpairs}{number of pairs used to generate proposal} \item{ZupdateFrequency}{frequency to update Z matrix} @@ -45,11 +45,11 @@ DREAMzs( \item{Z}{starting matrix for Z} -\item{startValue}{eiter a matrix containing the start values (see details), an integer to define the number of chains that are run, a function to sample the start values or NUll, in which case the values are sampled from the prior.} +\item{startValue}{either a matrix containing the start values (see details), an integer to define the number of chains to be run, a function to sample the start values or NUll - in which case the values are sampled from the prior.} -\item{consoleUpdates}{Intervall in which the sampling progress is printed to the console} +\item{consoleUpdates}{interval in which the sampling progress is printed to the console} -\item{message}{logical determines whether the sampler's progress should be printed} +\item{message}{logical, determines whether the sampler's progress should be printed} } \value{ mcmc.object containing the following elements: chains, X, pCR, Z @@ -58,24 +58,24 @@ mcmc.object containing the following elements: chains, X, pCR, Z DREAMzs } \details{ -Insted of a bayesianSetup, the function can take the output of a previous run to restart the sampler +Instead of a bayesianSetup, the function can take the output of a previous run to restart the sampler from the last iteration. Due to the sampler's internal structure you can only use the output of DREAMzs. -If you provide a matrix with start values the number of rows detemines the number of chains that are run. -The number of coloumns must be equivalent to the number of parameters in your bayesianSetup. \cr\cr +If you provide a matrix with start values, the number of rows determines the number of chains that will be run. +The number of columns must be equivalent to the number of parameters in your bayesianSetup. \cr\cr There are several small differences in the algorithm presented here compared to the original paper by Vrugt et al. (2009). Mainly -the algorithm implemented here does not have an automatic stopping criterion. Hence, it will +The algorithm implemented here does not have an automatic stopping criterion. Hence, it will always run the number of iterations specified by the user. Also, convergence is not monitored and left to the user. This can easily be done with coda::gelman.diag(chain). -Further the proposed delayed rejectio step in Vrugt et al. (2009) is not implemented here.\cr\cr +Furthermore, the delayed rejection step proposed in Vrugt et al. (2009) is not implemented here.\cr\cr During the adaptation phase DREAM is running two mechanisms to enhance the sampler's efficiency. -First the disribution of crossover values is tuned to favor large jumps in the parameter space. +First, the distribution of crossover values is tuned to favor large jumps in the parameter space. The crossover probabilities determine how many parameters are updated simultaneously. -Second outlier chains are replanced as they can largely deteriorate the sampler's performance. +Second, outlier chains are replaced as they can largely deteriorate the sampler's performance. However, these steps destroy the detailed balance of the chain. Consequently these parts of the chain should be discarded when summarizing posterior moments. This can be done automatically during the -sampling process (i.e. burnin > adaptation) or subsequently by the user. We chose to distinguish between -the burnin and adaptation phase to allow the user more flexibility in the sampler's settings. +sampling process (i.e. burn-in > adaptation) or subsequently by the user. We chose to distinguish between +the burn-in and adaptation phase to allow the user more flexibility in the sampler's settings. } \examples{ library(BayesianTools) diff --git a/BayesianTools/man/M.Rd b/BayesianTools/man/M.Rd index d365647..d138c9e 100644 --- a/BayesianTools/man/M.Rd +++ b/BayesianTools/man/M.Rd @@ -16,11 +16,11 @@ M( ) } \arguments{ -\item{startValue}{vector with the start values for the algorithm. Can be NULL if FUN is of class BayesianSetup. In this case startValues are sampled from the prior.} +\item{startValue}{vector with the start values for the algorithm. Can be NULL if FUN is of class BayesianSetup. In this case, startValues are sampled from the prior.} -\item{iterations}{iterations to run} +\item{iterations}{number of iterations to run} -\item{nBI}{number of burnin} +\item{nBI}{number of burn-in} \item{parmin}{minimum values for the parameter vector or NULL if FUN is of class BayesianSetup} @@ -30,7 +30,7 @@ M( \item{FUN}{function to be sampled from or object of class bayesianSetup} -\item{consoleUpdates}{interger, determines the frequency with which sampler progress is printed to the console} +\item{consoleUpdates}{integer, determines the frequency with which sampler progress is printed to the console} } \description{ The Metropolis Algorithm (Metropolis et al. 1953) diff --git a/BayesianTools/man/MAP.Rd b/BayesianTools/man/MAP.Rd index ce4490a..113de9b 100644 --- a/BayesianTools/man/MAP.Rd +++ b/BayesianTools/man/MAP.Rd @@ -15,7 +15,7 @@ MAP(bayesianOutput, ...) calculates the Maxiumum APosteriori value (MAP) } \details{ -Currently, this function simply returns the parameter combination with the highest posterior in the chain. A more refined option would be to take the MCMC sample and do additional calculations, e.g. use an optimizer, a kerne delnsity estimator, or some other tool to search / interpolate around the best value in the chain +Currently, this function simply returns the parameter combination with the highest posterior in the chain. A more refined option would be to take the MCMC sample and do additional calculations, e.g. use an optimizer, a kernel density estimator, or some other tool to search / interpolate around the best value in the chain. } \seealso{ \code{\link{WAIC}}, \code{\link{DIC}}, \code{\link{marginalLikelihood}} diff --git a/BayesianTools/man/Metropolis.Rd b/BayesianTools/man/Metropolis.Rd index d17408d..cff88af 100644 --- a/BayesianTools/man/Metropolis.Rd +++ b/BayesianTools/man/Metropolis.Rd @@ -16,13 +16,13 @@ Metropolis( \arguments{ \item{bayesianSetup}{either an object of class bayesianSetup created by \code{\link{createBayesianSetup}} (recommended), or a log target function} -\item{settings}{a list of settings - possible options follow below} +\item{settings}{a list of settings - possible options follow} \item{startValue}{startValue for the MCMC and optimization (if optimize = T). If not provided, the sampler will attempt to obtain the startValue from the bayesianSetup} \item{optimize}{logical, determines whether an optimization for start values and proposal function should be run before starting the sampling} -\item{proposalGenerator}{optional proposalgenerator object (see \code{\link{createProposalGenerator}})} +\item{proposalGenerator}{optional, proposalgenerator object (see \code{\link{createProposalGenerator}})} \item{proposalScaling}{additional scaling parameter for the proposals that controls the different scales of the proposals after delayed rejection (typical, after a rejection, one would want to try a smaller scale). Needs to be as long as DRlevels. Defaults to 0.5^(- 0:(mcmcSampler$settings$DRlevels -1)} @@ -32,7 +32,7 @@ Metropolis( \item{consoleUpdates}{integer, determines the frequency with which sampler progress is printed to the console} -\item{adapt}{logical, determines wheter an adaptive algorithm should be implemented. Default is TRUE.} +\item{adapt}{logical, determines whether an adaptive algorithm should be implemented. Default is TRUE.} \item{adaptationInterval}{integer, determines the interval of the adaption if adapt = TRUE.} @@ -42,9 +42,9 @@ Metropolis( \item{temperingFunction}{function to implement simulated tempering in the algorithm. The function describes how the acceptance rate will be influenced in the course of the iterations.} -\item{gibbsProbabilities}{vector that defines the relative probabilities of the number of parameters to be changes simultaniously.} +\item{gibbsProbabilities}{vector that defines the relative probabilities of the number of parameters to be changed simultaneously.} -\item{message}{logical determines whether the sampler's progress should be printed} +\item{message}{logical, determines whether the sampler's progress should be printed} } \description{ Creates a Metropolis-type MCMC with options for covariance adaptatin, delayed rejection, Metropolis-within-Gibbs, and tempering diff --git a/BayesianTools/man/Twalk.Rd b/BayesianTools/man/Twalk.Rd index c32caf6..098c150 100644 --- a/BayesianTools/man/Twalk.Rd +++ b/BayesianTools/man/Twalk.Rd @@ -12,33 +12,33 @@ Twalk( ) } \arguments{ -\item{bayesianSetup}{Object of class 'bayesianSetup' or 'bayesianOuput'.} +\item{bayesianSetup}{object of class 'bayesianSetup' or 'bayesianOuput'.} \item{settings}{list with parameter values.} -\item{iterations}{Number of model evaluations} +\item{iterations}{number of model evaluations} \item{at}{"traverse" move proposal parameter. Default to 6} \item{aw}{"walk" move proposal parameter. Default to 1.5} -\item{pn1}{Probability determining the number of parameters that are changed} +\item{pn1}{probability determining the number of parameters that are changed} -\item{Ptrav}{Move probability of "traverse" moves, default to 0.4918} +\item{Ptrav}{move probability of "traverse" moves, default to 0.4918} -\item{Pwalk}{Move probability of "walk" moves, default to 0.4918} +\item{Pwalk}{move probability of "walk" moves, default to 0.4918} -\item{Pblow}{Move probability of "traverse" moves, default to 0.0082} +\item{Pblow}{move probability of "traverse" moves, default to 0.0082} \item{burnin}{number of iterations treated as burn-in. These iterations are not recorded in the chain.} \item{thin}{thinning parameter. Determines the interval in which values are recorded.} -\item{startValue}{Matrix with start values} +\item{startValue}{matrix with start values} -\item{consoleUpdates}{Intervall in which the sampling progress is printed to the console} +\item{consoleUpdates}{intervall in which the sampling progress is printed to the console} -\item{message}{logical determines whether the sampler's progress should be printed} +\item{message}{logical, determines whether the sampler's progress should be printed} } \value{ Object of class bayesianOutput. diff --git a/BayesianTools/man/TwalkMove.Rd b/BayesianTools/man/TwalkMove.Rd index 8639ad0..06ffc78 100644 --- a/BayesianTools/man/TwalkMove.Rd +++ b/BayesianTools/man/TwalkMove.Rd @@ -21,9 +21,9 @@ TwalkMove( ) } \arguments{ -\item{Npar}{Number of parameters} +\item{Npar}{number of parameters} -\item{FUN}{Log posterior density} +\item{FUN}{log posterior density} \item{x}{parameter vector of chain 1} diff --git a/BayesianTools/man/VSEM.Rd b/BayesianTools/man/VSEM.Rd index 84571d0..d5c70dd 100644 --- a/BayesianTools/man/VSEM.Rd +++ b/BayesianTools/man/VSEM.Rd @@ -19,7 +19,7 @@ VSEM( \item{C}{switch to choose whether to use the C or R version of the model. C is much faster.} } \value{ -a matrix with colums NEE, CV, CR and CS units and explanations see details +a matrix with columns NEE, CV, CR and CS units and explanations see details } \description{ A very simple ecosystem model, based on three carbon pools and a basic LUE model @@ -31,7 +31,7 @@ The model determines the accumulation of carbon in the plant and soil from the g The model calculates Gross Primary Productivity (GPP) using a very simple light-use efficiency (LUE) formulation multiplied by light interception. Light interception is calculated via Beer's law with a constant light extinction coefficient operating on Leaf Area Index (LAI). -A parameter (GAMMA) determines the fraction of GPP that is autotrophic respiration. The Net Primary Productivity (NPP) is then allocated to above and below-ground vegetation via a fixed allocation fraction. Carbon is lost from the plant pools to a single soil pool via fixed turnover rates. Heterotropic respiration in the soil is determined via a soil turnover rate. +A parameter (GAMMA) determines the fraction of GPP that is autotrophic respiration. The Net Primary Productivity (NPP) is then allocated to above and below-ground vegetation via a fixed allocation fraction. Carbon is lost from the plant pools to a single soil pool via fixed turnover rates. Heterotrophic respiration in the soil is determined via a soil turnover rate. The model equations are diff --git a/BayesianTools/man/VSEMcreateLikelihood.Rd b/BayesianTools/man/VSEMcreateLikelihood.Rd index 0f29233..31999cf 100644 --- a/BayesianTools/man/VSEMcreateLikelihood.Rd +++ b/BayesianTools/man/VSEMcreateLikelihood.Rd @@ -7,9 +7,9 @@ VSEMcreateLikelihood(likelihoodOnly = F, plot = F, selection = c(1:6, 12)) } \arguments{ -\item{likelihoodOnly}{switch to devide whether to create only a likelihood, or a full bayesianSetup with uniform priors.} +\item{likelihoodOnly}{logical, decides whether to create only a likelihood, or a full bayesianSetup with uniform priors.} -\item{plot}{switch to decide whether data should be plotted} +\item{plot}{logical, decides whether data should be plotted} \item{selection}{vector containing the indices of the selected parameters} } diff --git a/BayesianTools/man/WAIC.Rd b/BayesianTools/man/WAIC.Rd index a22446a..0435901 100644 --- a/BayesianTools/man/WAIC.Rd +++ b/BayesianTools/man/WAIC.Rd @@ -34,7 +34,7 @@ Method 2 is defined as, where \eqn{V_{s=1}^{S}} is the sample variance. } \note{ -The function requires that the likelihood passed on to BayesianSetup contains the option sum = T/F, with defaul F. If set to true, the likelihood for each data point must be returned. +The function requires that the likelihood passed on to BayesianSetup contains the option sum = T/F, with default F. If set to true, the likelihood for each data point must be returned. } \examples{ bayesianSetup <- createBayesianSetup(likelihood = testDensityNormal, diff --git a/BayesianTools/man/calibrationTest.Rd b/BayesianTools/man/calibrationTest.Rd index c5b03fc..30c4836 100644 --- a/BayesianTools/man/calibrationTest.Rd +++ b/BayesianTools/man/calibrationTest.Rd @@ -7,9 +7,9 @@ calibrationTest(posteriorList, priorDraws, ...) } \arguments{ -\item{posteriorList}{a list with posterior samples. List items must be of a class that is supported by \code{\link{getSample}}. This includes BayesianTools objects, but also matrix and data.frame} +\item{posteriorList}{a list of posterior samples. List items must be of a class that is supported by \code{\link{getSample}}. This includes BayesianTools objects, but also matrix and data.frame objects.} -\item{priorDraws}{a matrix with parameter values, drawn from the prior, that were used to simulate the data underlying the posteriorList. If colnames are provided, these will be used in the plots} +\item{priorDraws}{a matrix of parameter values, drawn from the prior, that were used to simulate the data underlying the posteriorList. If colnames are provided, they are used in the plots} \item{...}{arguments to be passed to \code{\link{getSample}}. Consider in particular the thinning option.} } diff --git a/BayesianTools/man/combineChains.Rd b/BayesianTools/man/combineChains.Rd index 85fcedb..600523c 100644 --- a/BayesianTools/man/combineChains.Rd +++ b/BayesianTools/man/combineChains.Rd @@ -9,7 +9,7 @@ combineChains(x, merge = T) \arguments{ \item{x}{a list of MCMC chains} -\item{merge}{logical determines whether chains should be merged} +\item{merge}{should chains be merged? (T or F)} } \value{ combined chains diff --git a/BayesianTools/man/convertCoda.Rd b/BayesianTools/man/convertCoda.Rd index 6009f3b..e4213b0 100644 --- a/BayesianTools/man/convertCoda.Rd +++ b/BayesianTools/man/convertCoda.Rd @@ -7,22 +7,19 @@ convertCoda(sampler, names = NULL, info = NULL, likelihood = NULL) } \arguments{ -\item{sampler}{An object of class mcmc or mcmc.list} +\item{sampler}{an object of class mcmc or mcmc.list} -\item{names}{vector giving the parameter names (optional)} +\item{names}{a vector with parameter names (optional)} -\item{info}{matrix (or list with matrices for mcmc.list objects) with three coloumns containing log posterior, log likelihood and log prior of the sampler for each time step (optional; but see Details)} +\item{info}{a matrix (or list with matrices for mcmc.list objects) with three columns containing log posterior, log likelihood and log prior of the sampler for each time step (optional; but see Details)} -\item{likelihood}{likelihood function used in the sampling (see Details)} +\item{likelihood}{likelihood function used for sampling (see Details)} } \description{ -Function is used to make the plot and diagnostic functions -available for coda::mcmc objects +Function to support plotting and diagnostic functions for coda::mcmc objects. } \details{ -The parameter 'likelihood' is optional for most functions but can be needed e.g for -using the \code{\link{DIC}} function. +The parameter 'likelihood' is optional for most functions but can be needed e.g for \code{\link{DIC}} function. -Also the parameter info is optional for most uses. However for some functions (e.g. \code{\link{MAP}}) -the matrix or single coloumns (e.g. log posterior) are necessary for the diagnostics. +Also, the parameter information is typically optional for most uses. However, for certain functions (e.g. \code{\link{MAP}}), the matrix or single columns (e.g. log posterior) are necessary for diagnostics. } diff --git a/BayesianTools/man/correctThin.Rd b/BayesianTools/man/correctThin.Rd index 368dc30..e77c2f1 100644 --- a/BayesianTools/man/correctThin.Rd +++ b/BayesianTools/man/correctThin.Rd @@ -9,7 +9,7 @@ correctThin(nTotalSamples, thin, autoThinFraction = 0.001) \arguments{ \item{nTotalSamples}{total number of rows/samples} -\item{thin}{thinning} +\item{thin}{thinning parameter} \item{autoThinFraction}{fraction of the data that will be sampled when thin is set to "auto". E.g. 0.5 means thin will be nTotalSamples * 0.5. The resulting thin value is rounded down to the next integer.} } diff --git a/BayesianTools/man/correlationPlot.Rd b/BayesianTools/man/correlationPlot.Rd index 11d51b4..40add9b 100644 --- a/BayesianTools/man/correlationPlot.Rd +++ b/BayesianTools/man/correlationPlot.Rd @@ -25,9 +25,9 @@ correlationPlot( \item{whichParameters}{indices of parameters that should be plotted} -\item{scaleCorText}{should the text to display correlation be scaled to the strength of the correlation} +\item{scaleCorText}{should the text to display correlation be scaled to the strength of the correlation?} -\item{...}{additional parameters to pass on to the \code{\link{getSample}}, for example parametersOnly =F, or start = 1000} +\item{...}{additional parameters to pass on to the \code{\link{getSample}}, for example parametersOnly = F, or start = 1000} } \description{ Flexible function to create correlation density plots diff --git a/BayesianTools/man/createBayesianSetup.Rd b/BayesianTools/man/createBayesianSetup.Rd index 3225342..c87b551 100644 --- a/BayesianTools/man/createBayesianSetup.Rd +++ b/BayesianTools/man/createBayesianSetup.Rd @@ -37,9 +37,9 @@ createBayesianSetup( \item{names}{optional vector with parameter names} -\item{parallelOptions}{list containing three lists. First "packages" determines the R packages necessary to run the likelihood function. Second "variables" the objects in the global environment needed to run the likelihood function and third "dlls" the DLLs needed to run the likelihood function (see Details and Examples).} +\item{parallelOptions}{list containing three lists.\itemize{ \item First, "packages" determines the R packages necessary to run the likelihood function.\item Second, "variables" - the objects in the global environment needed to run the likelihood function and \item Third, "dlls" is needed to run the likelihood function (see Details and Examples).}} -\item{catchDuplicates}{Logical, determines whether unique parameter combinations should only be evaluated once. Only used when the likelihood accepts a matrix with parameter as columns.} +\item{catchDuplicates}{logical, determines whether unique parameter combinations should only be evaluated once. Only used when the likelihood accepts a matrix with parameter as columns.} \item{plotLower}{vector with lower limits for plotting} @@ -53,14 +53,14 @@ Creates a standardized collection of prior, likelihood and posterior functions, \details{ If prior is of class prior (e.g. create with \code{\link{createPrior}}), priorSampler, lower, upper and best will be ignored.\cr If prior is a function (log prior density), priorSampler (custom sampler), or lower/upper (uniform sampler) is required.\cr If prior is NULL, and lower and upper are passed, a uniform prior (see \code{\link{createUniformPrior}}) will be created with boundaries lower and upper. -For parallelization, Bayesiantools requies that the likelihood can evaluate several parameter vectors (supplied as a matrix) in parallel. +For parallelization, Bayesiantools requires that the likelihood can evaluate multiple parameter vectors (supplied as a matrix) in parallel. \itemize{ -\item parallel = T means that an automatic parallelization of the likelihood via a standard R socket cluster is attempted, using the function \code{\link{generateParallelExecuter}}. By default, of the N cores detected on the computer, N-1 cores are requested. Alternatively, you can provide a integer number to parallel, specifying the cores reserved for the cluster. When the cluster is cluster is created, a copy of your workspace, including DLLs and objects are exported to the cluster workers. Because this can be very inefficient, you can explicitly specify the packages, objects and DLLs that are to be exported via parallelOptions. Using parallel = T requires that the function to be parallelized is well encapsulate, i.e. can run on a shared memory / shared hard disk machine in parallel without interfering with each other. +\item parallel = T attempts to parallelize likelihood via a standard R socket cluster using the \code{\link{generateParallelExecuter}} function. By default, of the N cores detected on the computer, N-1 cores are requested. Alternatively, you can provide a integer number to parallel, specifying the cores reserved for the cluster. When the cluster is created, a copy of your workspace, including DLLs and objects are exported to the cluster workers. As this approach can be highly inefficient, it is recommended to explicitly specify the packages, objects and DLLs to export using parallelOptions. Using parallel = T requires that the function to be parallelized is well encapsulated, i.e. can run in parallel on a shared memory / shared hard disk machine in parallel without interfering with each other. } -If automatic parallelization cannot be done (e.g. because dlls are not thread-safe or write to shared disk), and only in this case, you should specify parallel = "external". In this case, it is assumed that the likelihood is programmed such that it accepts a matrix with parameters as columns and the different model runs as rows. It is then up to the user if and how to parallelize this function. This option gives most flexibility to the user, in particular for complicated parallel architecture or shared memory problems. +If automatic parallelization is not possible (e.g., because dlls are not thread-safe or write to shared disk), and only in this case, you should specify parallel = "external". In this case, it is assumed that the likelihood is programmed to accept a matrix with parameters as columns and the different model runs as rows. The user can then choose whether and how to parallelize this function. This option provides optimal flexibility for the user, especially regarding complicated parallel architectures or shared memory issues. -For more details on parallelization, make sure to read both vignettes, in particular the section on the likelihood in the main vignette, and the section on parallelization in the vignette on interfacing models. +For more details on parallelization, make sure to read both vignettes, especially the section on likelihood in the main vignette and the section on parallelization in the vignette on interfacing models. } \examples{ ll <- function(x) sum(dnorm(x, log = TRUE)) diff --git a/BayesianTools/man/createLikelihood.Rd b/BayesianTools/man/createLikelihood.Rd index 9b9d33b..b9ad678 100644 --- a/BayesianTools/man/createLikelihood.Rd +++ b/BayesianTools/man/createLikelihood.Rd @@ -14,17 +14,17 @@ createLikelihood( ) } \arguments{ -\item{likelihood}{Log likelihood density} +\item{likelihood}{log likelihood density} -\item{names}{Parameter names (optional)} +\item{names}{parameter names (optional)} -\item{parallel}{parallelization , either i) no parallelization --> F, ii) native R parallelization --> T / "auto" will select n-1 of your available cores, or provide a number for how many cores to use, or iii) external parallelization --> "external". External means that the likelihood is already able to execute parallel runs in form of a matrix with} +\item{parallel}{parallelization , either i) no parallelization --> F, ii) native R parallelization --> T / "auto" will select n-1 of your available cores, or provide a number for how many cores to use, or iii) external parallelization --> "external". External means that the likelihood is already able to execute parallel runs in the form of a matrix.} -\item{catchDuplicates}{Logical, determines whether unique parameter combinations should only be evaluated once. Only used when the likelihood accepts a matrix with parameter as columns.} +\item{catchDuplicates}{logical, determines whether unique parameter combinations should only be evaluated once. This is only applicable when the likelihood accepts a matrix with parameters as columns.} \item{sampler}{sampler} -\item{parallelOptions}{list containing two lists. First "packages" determines the R packages necessary to run the likelihood function. Second "objects" the objects in the global envirnment needed to run the likelihood function (for details see \code{\link{createBayesianSetup}}).} +\item{parallelOptions}{a list containing two lists. First, "packages" specifies the R packages necessary to run the likelihood function. Second, "objects" contains the objects in the global environment needed to run the likelihood function (for details see \code{\link{createBayesianSetup}}).} } \description{ Creates a standardized likelihood class#' diff --git a/BayesianTools/man/createMcmcSamplerList.Rd b/BayesianTools/man/createMcmcSamplerList.Rd index a81dc76..5f3ebde 100644 --- a/BayesianTools/man/createMcmcSamplerList.Rd +++ b/BayesianTools/man/createMcmcSamplerList.Rd @@ -7,10 +7,10 @@ createMcmcSamplerList(mcmcList) } \arguments{ -\item{mcmcList}{a list with each object being an mcmcSampler} +\item{mcmcList}{list of objects, each of which is an mcmcSampler} } \value{ -Object of class "mcmcSamplerList" +object of class "mcmcSamplerList" } \description{ Convenience function to create an object of class mcmcSamplerList from a list of mcmc samplers diff --git a/BayesianTools/man/createPosterior.Rd b/BayesianTools/man/createPosterior.Rd index d197c47..7686af3 100644 --- a/BayesianTools/man/createPosterior.Rd +++ b/BayesianTools/man/createPosterior.Rd @@ -9,13 +9,13 @@ createPosterior(prior, likelihood) \arguments{ \item{prior}{prior class} -\item{likelihood}{Log likelihood density} +\item{likelihood}{log likelihood density} } \description{ Creates a standardized posterior class } \details{ -Function is internally used in \code{\link{createBayesianSetup}} to create a standarized posterior class. +Function is internally used in \code{\link{createBayesianSetup}} to create a standardized posterior class. } \author{ Florian Hartig diff --git a/BayesianTools/man/createPrior.Rd b/BayesianTools/man/createPrior.Rd index 666dd9b..4718810 100644 --- a/BayesianTools/man/createPrior.Rd +++ b/BayesianTools/man/createPrior.Rd @@ -13,7 +13,7 @@ createPrior( ) } \arguments{ -\item{density}{Prior density} +\item{density}{prior density} \item{sampler}{Sampling function for density (optional)} @@ -27,7 +27,7 @@ createPrior( Creates a standardized prior class } \details{ -This is the general prior generator. It is highly recommended to not only implement the density, but also the sampler function. If this is not done, the user will have to provide explicit starting values for many of the MCMC samplers. Note the existing, more specialized prior function. If your prior can be created by those, they are preferred. Note also that priors can be created from an existing MCMC output from BT, or another MCMC sample, via \code{\link{createPriorDensity}}. +This is the general prior generator. It is highly recommended to implement both the density and sampler function. If not, the user will have to provide explicit starting values for many of the MCMC samplers. Note the existing, more specialized prior functions. It is recommended to use those specialized prior functions, if possible. Also note that priors can be created from an existing MCMC output from BT, or another MCMC sample, via \code{\link{createPriorDensity}}. } \note{ min and max truncate, but not re-normalize the prior density (so, if a pdf that integrated to one is truncated, the integral will in general be smaller than one). For MCMC sampling, this doesn't make a difference, but if absolute values of the prior density are a concern, one should provide a truncated density function for the prior. diff --git a/BayesianTools/man/createProposalGenerator.Rd b/BayesianTools/man/createProposalGenerator.Rd index f0e28d4..b7970ce 100644 --- a/BayesianTools/man/createProposalGenerator.Rd +++ b/BayesianTools/man/createProposalGenerator.Rd @@ -19,15 +19,15 @@ createProposalGenerator( \arguments{ \item{covariance}{covariance matrix. Can also be vector of the sqrt of diagonal elements --> standard deviation} -\item{gibbsProbabilities}{optional probabilities for the number of parameters to vary in a Metropolis within gibbs style - for 4 parameters, c(1,1,0.5,0) means that at most 3 parameters will be varied, and it is double as likely to vary one or two than varying 3} +\item{gibbsProbabilities}{optional, probabilities for the number of parameters to vary in a Metropolis within Gibbs style - for 4 parameters, c(1,1,0.5,0) means that at most 3 parameters will be varied, and it is twice as likely to vary one or two than to vary 3} -\item{gibbsWeights}{optional probabilities for parameters to be varied in a Metropolis within gibbs style - default ist equal weight for all parameters - for 4 parameters, c(1,1,1,100) would mean that if 2 parameters would be selected, parameter 4 would be 100 times more likely to be picked than the others. If 4 is selected, the remaining parameters have equal probability.} +\item{gibbsWeights}{optional, probabilities for parameters to be varied in a Metropolis within Gibbs style - default is equal weight for all parameters - for 4 parameters, c(1,1,1,100) would mean that if 2 parameters were selected, parameter 4 would be 100 times more likely to be picked than the others. If 4 is selected, the remaining parameters have equal probability.} -\item{otherDistribution}{optional additinal distribution to be mixed with the default multivariate normal. The distribution needs to accept a parameter vector (to allow for the option of making the distribution dependend on the parameter values), but it is still assumed that the change from the current values is returned, not the new absolute values.} +\item{otherDistribution}{optional, additional distribution to be mixed with the default multivariate normal. The distribution needs to accept a parameter vector (to allow the option of making the distribution dependent on the parameter values), but it is still assumed that the change from the current values is returned, not the new absolute values.} \item{otherDistributionLocation}{a vector with 0 and 1, denoting which parameters are modified by the otherDistribution} -\item{otherDistributionScaled}{should the other distribution be scaled if gibbs updates are calculated?} +\item{otherDistributionScaled}{logical, should the other distribution be scaled if Gibbs updates are calculated?} \item{message}{print out parameter settings} diff --git a/BayesianTools/man/createSmcSamplerList.Rd b/BayesianTools/man/createSmcSamplerList.Rd index 11208b2..735ce36 100644 --- a/BayesianTools/man/createSmcSamplerList.Rd +++ b/BayesianTools/man/createSmcSamplerList.Rd @@ -10,7 +10,7 @@ createSmcSamplerList(...) \item{...}{a list of MCMC samplers} } \value{ -a list of class smcSamplerList with each object being an smcSampler +a list of class smcSamplerList with objects of smcSampler } \description{ Convenience function to create an object of class SMCSamplerList from a list of mcmc samplers diff --git a/BayesianTools/man/generateCRvalues.Rd b/BayesianTools/man/generateCRvalues.Rd index 41e6302..6f0a81c 100644 --- a/BayesianTools/man/generateCRvalues.Rd +++ b/BayesianTools/man/generateCRvalues.Rd @@ -7,9 +7,9 @@ generateCRvalues(pCR, settings, Npop) } \arguments{ -\item{pCR}{Vector of crossover probabilities. Needs to be of length nCR.} +\item{pCR}{vector of crossover probabilities. Needs to be of length nCR.} -\item{settings}{settings list} +\item{settings}{list of settings} \item{Npop}{number of chains} } diff --git a/BayesianTools/man/generateTestDensityMultiNormal.Rd b/BayesianTools/man/generateTestDensityMultiNormal.Rd index 3c72972..3a57034 100644 --- a/BayesianTools/man/generateTestDensityMultiNormal.Rd +++ b/BayesianTools/man/generateTestDensityMultiNormal.Rd @@ -17,7 +17,7 @@ generateTestDensityMultiNormal( \item{sigma}{either a correlation matrix, or "strongcorrelation", or "no correlation"} -\item{sample}{should the function create samples} +\item{sample}{logical, should the function create samples?} \item{n}{number of samples to create} diff --git a/BayesianTools/man/getBlockSettings.Rd b/BayesianTools/man/getBlockSettings.Rd index 6c29a25..a0bd314 100644 --- a/BayesianTools/man/getBlockSettings.Rd +++ b/BayesianTools/man/getBlockSettings.Rd @@ -13,6 +13,6 @@ getBlockSettings(blockUpdate) list with block settings } \description{ -Transforms the original settings in settings used in the model runs +Transforms the original settings to settings used in the model runs } \keyword{internal} diff --git a/BayesianTools/man/getSample.Rd b/BayesianTools/man/getSample.Rd index 900847f..d72d774 100644 --- a/BayesianTools/man/getSample.Rd +++ b/BayesianTools/man/getSample.Rd @@ -148,15 +148,15 @@ getSample( \item{parametersOnly}{for a BT output, if F, likelihood, posterior and prior values are also provided in the output} -\item{coda}{works only for mcmc classes - provides output as a coda object. Note: if mcmcSamplerList contains mcmc samplers such as DE that have several chains, the internal chains will be collapsed. This may not be the desired behavior for all applications.} +\item{coda}{works only for mcmc classes - returns output as a coda object. Note: if mcmcSamplerList contains mcmc samplers such as DE that have several chains, the internal chains will be collapsed. This may not be desired for all applications.} -\item{start}{for mcmc samplers start value in the chain. For SMC samplers, start particle} +\item{start}{for mcmc samplers, start value in the chain. For SMC samplers, start particle} \item{end}{for mcmc samplers end value in the chain. For SMC samplers, end particle} -\item{thin}{thinning parameter. Either an integer determining the thinning intervall (default is 1) or "auto" for automatic thinning.} +\item{thin}{thinning parameter. Either an integer determining the thinning interval (default is 1) or "auto" for automatic thinning.} -\item{numSamples}{sample size (only used if thin = 1). If you want to use numSamples set thin to 1.} +\item{numSamples}{sample size (only used if thin = 1). If you want to use numSamples, set thin to 1.} \item{whichParameters}{possibility to select parameters by index} @@ -168,9 +168,9 @@ getSample( Extracts the sample from a bayesianOutput } \details{ -If thin is greater than the total number of samples in the sampler object the first and the last element (of each chain if a sampler with multiples chains is used) are sampled. If numSamples is greater than the total number of samples all samples are selected. In both cases a warning is displayed. +If thin is greater than the total number of samples in the sampler object, the first and the last element (of each chain if a sampler with multiples chains is used) are sampled. If numSamples is greater than the total number of samples all samples are selected. A warning will be displayed in both cases. -If thin and numSamples is passed, the function will use the thin argument if it is valid and greater than 1, else numSamples will be used. +If both thin and numSamples are provided, the function will use thin only if it is valid and greater than 1; otherwise, numSamples will be used. } \examples{ ll = function(x) sum(dnorm(x, log = TRUE)) diff --git a/BayesianTools/man/getVolume.Rd b/BayesianTools/man/getVolume.Rd index 9d63ed9..55e4659 100644 --- a/BayesianTools/man/getVolume.Rd +++ b/BayesianTools/man/getVolume.Rd @@ -7,9 +7,9 @@ getVolume(sampler, prior = F, method = "MVN", ...) } \arguments{ -\item{sampler}{an object of superclass bayesianOutput or any other class that has the getSample function implemented (e.g. Matrix)} +\item{sampler}{an object of superclass bayesianOutput or any other class that has implemented the getSample function (e.g. Matrix)} -\item{prior}{schould also prior volume be calculated} +\item{prior}{logical, should prior volume be calculated?} \item{method}{method for volume estimation. Currently, the only option is "MVN"} @@ -19,7 +19,7 @@ getVolume(sampler, prior = F, method = "MVN", ...) Calculate posterior volume } \details{ -The idea of this function is to provide an estimate of the "posterior volume", i.e. how "broad" the posterior is. One potential application is to the overall reduction of parametric uncertainty between different data types, or between prior and posterior. +The idea of this function is to provide an estimate of the "posterior volume", i.e. how "broad" the posterior is. One potential application is the overall reduction of parametric uncertainty between different data types, or between prior and posterior. Implemented methods for volume estimation: diff --git a/BayesianTools/man/makeObjectClassCodaMCMC.Rd b/BayesianTools/man/makeObjectClassCodaMCMC.Rd index ccabf2c..d442a60 100644 --- a/BayesianTools/man/makeObjectClassCodaMCMC.Rd +++ b/BayesianTools/man/makeObjectClassCodaMCMC.Rd @@ -9,14 +9,14 @@ makeObjectClassCodaMCMC(chain, start = 1, end = numeric(0), thin = 1) \arguments{ \item{chain}{mcmc Chain} -\item{start}{for mcmc samplers start value in the chain. For SMC samplers, start particle} +\item{start}{For MCMC samplers, the initial value in the chain. For SMC samplers, initial particle} -\item{end}{for mcmc samplers end value in the chain. For SMC samplers, end particle} +\item{end}{For MCMC samplers, the end value in the chain. For SMC samplers, end particle.} \item{thin}{thinning parameter} } \value{ -object of class coda::mcmc +object an object of class coda::mcmc } \description{ Helper function to change an object to a coda mcmc class, diff --git a/BayesianTools/man/marginalLikelihood.Rd b/BayesianTools/man/marginalLikelihood.Rd index dabc68e..7efabf0 100644 --- a/BayesianTools/man/marginalLikelihood.Rd +++ b/BayesianTools/man/marginalLikelihood.Rd @@ -16,7 +16,7 @@ marginalLikelihood(sampler, numSamples = 1000, method = "Chib", ...) \item{...}{further arguments passed to \code{\link{getSample}}} } \value{ -A list with log of the marginal likelihood, as well as other diagnostics depending on the chose method +A list with log of the marginal likelihood, as well as other diagnostics depending on the chosen method } \description{ Calcluated the marginal likelihood from a set of MCMC samples @@ -32,11 +32,11 @@ Given that MLs are calculated for each model, you can get posterior weights (for In BT, we return the log ML, so you will have to exp all values for this formula. -It is well-known that the ML is VERY dependent on the prior, and in particular the choice of the width of uninformative priors may have major impacts on the relative weights of the models. It has therefore been suggested to not use the ML for model averaging / selection on uninformative priors. If you have no informative priors, and option is to split the data into two parts, use one part to generate informative priors for the model, and the second part for the model selection. See help for an example. +It is well-known that the ML is strongly dependent on the prior, and in particular the choice of the width of uninformative priors may have major impacts on the relative weights of the models. It has therefore been suggested to not use the ML for model averaging / selection on uninformative priors. If you have no informative priors, and option is to split the data into two parts, use one part to generate informative priors for the model, and the second part for the model selection. See help for an example. The marginalLikelihood function currently implements four ways to calculate the marginal likelihood. Be aware that marginal likelihood calculations are notoriously prone to numerical stability issues. Especially in high-dimensional parameter spaces, there is no guarantee that any of the implemented algorithms will converge reasonably fast. The recommended (and default) method is the method "Chib" (Chib and Jeliazkov, 2001), which is based on MCMC samples, with a limited number of additional calculations. Despite being the current recommendation, note there are some numeric issues with this algorithm that may limit reliability for larger dimensions. -The harmonic mean approximation, is implemented only for comparison. Note that the method is numerically unrealiable and usually should not be used. +The harmonic mean approximation, is implemented only for comparison. Note that the method is numerically unreliable and usually should not be used. The third method is simply sampling from the prior. While in principle unbiased, it will only converge for a large number of samples, and is therefore numerically inefficient. diff --git a/BayesianTools/man/marginalPlot.Rd b/BayesianTools/man/marginalPlot.Rd index 3c35ef3..5d7d762 100644 --- a/BayesianTools/man/marginalPlot.Rd +++ b/BayesianTools/man/marginalPlot.Rd @@ -16,17 +16,17 @@ marginalPlot( ) } \arguments{ -\item{x}{bayesianOutput, or matrix or data.frame containing with samples as rows and parameters as columns} +\item{x}{bayesianOutput, or matrix or data.frame with samples as rows and parameters as columns} -\item{prior}{if x is a bayesianOutput, T/F will determine if the prior is drawn (default = T). If x is matrix oder data.frame, a prior can be drawn if a matrix of prior draws with values as rows and parameters as columns can be provided here.} +\item{prior}{if x is a bayesianOutput, T/F will determines whether the prior is drawn (default = T). If x is matrix or data.frame, a prior can be drawn if a matrix of prior draws with values as rows and parameters as columns can be provided here.} -\item{xrange}{vector or matrix of plotting ranges for the x axis. If matrix, the rows must be parameters and the columns min and max values.} +\item{xrange}{vector or matrix of plot ranges for the x-axis. If matrix, the rows must be parameters and the columns must be min and max values.} -\item{type}{character determining the plot type. Either 'd' for density plot, or 'v' for violin plot} +\item{type}{character, determes the plot type. Either 'd' for density plot, or 'v' for violin plot} -\item{singlePanel}{logical, determining whether the parameter should be plotted in a single panel or each in its own panel} +\item{singlePanel}{logical, determines whether the parameter should be plotted in a single panel or each in its own panel} -\item{settings}{optional list of additional settings for \code{\link{marginalPlotDensity}}, and \code{\link{marginalPlotViolin}}, respectively} +\item{settings}{optional, list of additional settings for \code{\link{marginalPlotDensity}}, and \code{\link{marginalPlotViolin}}, respectively} \item{nPriorDraws}{number of draws from the prior, if x is bayesianOutput} diff --git a/BayesianTools/man/mcmcMultipleChains.Rd b/BayesianTools/man/mcmcMultipleChains.Rd index 8cbdcec..d6ad683 100644 --- a/BayesianTools/man/mcmcMultipleChains.Rd +++ b/BayesianTools/man/mcmcMultipleChains.Rd @@ -7,7 +7,7 @@ mcmcMultipleChains(bayesianSetup, settings, sampler) } \arguments{ -\item{bayesianSetup}{Object of class "BayesianSetup"} +\item{bayesianSetup}{object of class "BayesianSetup"} \item{settings}{list with settings for sampler} diff --git a/BayesianTools/man/plotDiagnostic.Rd b/BayesianTools/man/plotDiagnostic.Rd index a2394e6..471fcd8 100644 --- a/BayesianTools/man/plotDiagnostic.Rd +++ b/BayesianTools/man/plotDiagnostic.Rd @@ -26,13 +26,13 @@ plotDiagnostic( \item{window}{plot range to show, vector of percents or only one value as start value for the window} -\item{plotWAIC}{whether to calculate WAIC or not, default = T} +\item{plotWAIC}{logical, whether to calculate WAIC or not, default = T} -\item{plotPSRF}{calculate and plot mPSRF/PSRF or not, default = T} +\item{plotPSRF}{logical, whether to calculate and plot mPSRF/PSRF or not, default = T} -\item{plotDIC}{calculate and plot DICor not, default = T} +\item{plotDIC}{logical, whether to calculate and plot DIC or not, default = T} -\item{plotTrace}{show trace plots or not, default = T} +\item{plotTrace}{logical, whether to show trace plots or not, default = T} \item{graphicParameters}{graphic parameters as list for plot function} diff --git a/BayesianTools/man/plotSensitivity.Rd b/BayesianTools/man/plotSensitivity.Rd index 4546ed4..53830e9 100644 --- a/BayesianTools/man/plotSensitivity.Rd +++ b/BayesianTools/man/plotSensitivity.Rd @@ -7,11 +7,11 @@ plotSensitivity(bayesianSetup, selection = NULL, equalScale = T) } \arguments{ -\item{bayesianSetup}{An object of class BayesianSetup} +\item{bayesianSetup}{an object of class BayesianSetup} \item{selection}{indices of selected parameters} -\item{equalScale}{if T, y axis of all plots will have the same scale} +\item{equalScale}{if T, y-axis of all plots will have the same scale} } \description{ Performs a one-factor-at-a-time sensitivity analysis for the posterior of a given bayesianSetup within the prior range. diff --git a/BayesianTools/man/rescale.Rd b/BayesianTools/man/rescale.Rd index 3bea259..d2a3988 100644 --- a/BayesianTools/man/rescale.Rd +++ b/BayesianTools/man/rescale.Rd @@ -7,7 +7,7 @@ rescale(x, from, to) } \arguments{ -\item{x}{vector of values tp be scaled} +\item{x}{vector of values to be scaled} \item{from}{vector of length 2, original interval (lower, upper)} diff --git a/BayesianTools/man/runMCMC.Rd b/BayesianTools/man/runMCMC.Rd index 16f4f02..eacee0f 100644 --- a/BayesianTools/man/runMCMC.Rd +++ b/BayesianTools/man/runMCMC.Rd @@ -44,7 +44,7 @@ The MCMC samplers will have a number of additional settings, which are described Note that even if you specify parallel = T, this will only turn on internal parallelization of the samplers. The independent samplers controlled by nrChains are not evaluated in parallel, so if time is an issue it will be better to run the MCMCs individually and then combine them via \code{\link{createMcmcSamplerList}} into one joint object. -Note that DE and DREAM variants as well as SMC and T-walk require a population to start, which should be provided as a matrix. Default (NULL) sets the population size for DE to 3 x dimensions of parameters, for DREAM to 2 x dimensions of parameters and for DEzs and DREAMzs to three, sampled from the prior. Note also that the zs variants of DE and DREAM require two populations, the current population and the z matrix (a kind of memory) - if you want to set both, provide a list with startvalue$X and startvalue$Z. +Note that, DE and DREAM variants as well as SMC and T-walk require a population to start, which should be provided as a matrix. Default (NULL) sets the population size for DE to 3 x dimensions of parameters, for DREAM to 2 x dimensions of parameters and for DEzs and DREAMzs to three, sampled from the prior. Note also that the zs variants of DE and DREAM require two populations, the current population and the z matrix (a kind of memory) - if you want to set both, provide a list with startvalue$X and startvalue$Z. setting startValue for sampling with nrChains > 1 : if you want to provide different start values for the different chains, provide them as a list } diff --git a/BayesianTools/man/scaleMatrix.Rd b/BayesianTools/man/scaleMatrix.Rd index cdab189..c807aeb 100644 --- a/BayesianTools/man/scaleMatrix.Rd +++ b/BayesianTools/man/scaleMatrix.Rd @@ -14,7 +14,7 @@ scaleMatrix(mat, min, max) \item{max}{maximum value} } \value{ -sclaed matrix +scaled matrix } \description{ Function to scale matrices diff --git a/BayesianTools/man/smcSampler.Rd b/BayesianTools/man/smcSampler.Rd index 31382f1..a1da4bb 100644 --- a/BayesianTools/man/smcSampler.Rd +++ b/BayesianTools/man/smcSampler.Rd @@ -22,13 +22,13 @@ smcSampler( \item{iterations}{number of iterations} -\item{resampling}{if new particles should be created at each iteration} +\item{resampling}{logical, specifies whether new particles should be created at each iteration} \item{resamplingSteps}{how many resampling (MCMC) steps between the iterations} -\item{proposal}{optional proposal class} +\item{proposal}{optional, proposal class} -\item{adaptive}{should the covariance of the proposal be adapted during sampling} +\item{adaptive}{logical, should the covariance of the proposal be adapted during sampling?} \item{proposalScale}{scaling factor for the proposal generation. Can be adapted if there is too much / too little rejection} } diff --git a/BayesianTools/man/tracePlot.Rd b/BayesianTools/man/tracePlot.Rd index 50afc14..c4d0eb4 100644 --- a/BayesianTools/man/tracePlot.Rd +++ b/BayesianTools/man/tracePlot.Rd @@ -9,9 +9,9 @@ tracePlot(sampler, thin = "auto", ...) \arguments{ \item{sampler}{an object of class MCMC sampler} -\item{thin}{determines the thinning intervall of the chain} +\item{thin}{determines the thinning interval of the chain} -\item{...}{additional parameters to pass on to the \code{\link{getSample}}, for example parametersOnly =F, or start = 1000} +\item{...}{additional parameters to pass on to the \code{\link{getSample}}, for example parametersOnly = F, or start = 1000} } \description{ Trace plot for MCMC class diff --git a/BayesianTools/man/updateGroups.Rd b/BayesianTools/man/updateGroups.Rd index 2067ea3..b41d85c 100644 --- a/BayesianTools/man/updateGroups.Rd +++ b/BayesianTools/man/updateGroups.Rd @@ -9,7 +9,7 @@ updateGroups(chain, blockSettings) \arguments{ \item{chain}{MCMC chain including only the parameters (not logP,ll, logP)} -\item{blockSettings}{list with settings} +\item{blockSettings}{a list with settings} } \value{ groups