Function collection class

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

BayesianTools/R/classBayesianOutput.R

@@ -1,21 +1,22 @@
 # 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")
 

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

BayesianTools/R/classLikelihood.R

@@ -1,10 +1,11 @@
+
 #' 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

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.

BayesianTools/R/classPosterior.R

@@ -1,8 +1,9 @@
+
 #' 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){
 

BayesianTools/R/classPrior.R

@@ -1,11 +1,12 @@
+
 #' 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

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(...)

BayesianTools/R/codaFunctions.R

@@ -1,7 +1,6 @@
 #' 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 +43,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){

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){