Merge pull request #257 from TahminaMojumder/mcmc

Updated help files name starting with mcmc

Author: florianhartig

BayesianTools/R/MAP.R

@@ -1,8 +1,8 @@
-#' calculates the Maxiumum APosteriori value (MAP)
+#' Calculates the Maximum 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, ...){

BayesianTools/R/VSEM.R

@@ -141,7 +141,7 @@ VSEMgetDefaults <- function(){
 
 #' Allows to mix a given parameter vector with a default parameter vector
 #' @param pars vector with new parameter values
-#' @param defaults vector with defaukt parameter values
+#' @param defaults vector with default parameter values
 #' @param locations indices of the new parameter values
 #' @rdname package-deprecated
 #' @description This function is deprecated and will be removed by v0.2. 
@@ -166,7 +166,7 @@ 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 likelihoodOnly switch to decide whether to create only a likelihood, or a full bayesianSetup with uniform priors.
 #' @param plot switch to decide 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 

BayesianTools/R/blockUpdate.R

@@ -1,6 +1,6 @@
 #' Determine the groups of correlated parameters
 #' @author Stefan Paul
-#' @param chain MCMC chain including only the parameters (not logP,ll, logP)
+#' @param chain MCMC chain including only the parameters (not logP, ll, logP)
 #' @param blockSettings a list with settings
 #' @return groups
 #' @keywords internal
@@ -88,4 +88,3 @@ getBlockSettings <- function(blockUpdate){
               pGroup = pGroup, groups = groups))
   }
 
-

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

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
@@ -168,7 +168,7 @@ checkBayesianSetup <- function(bayesianSetup, parallel = F){
 #' Function to close cluster in BayesianSetup
 #' @author Stefan Paul
 #' @description Function closes 
-#' the parallel executer (if available)
+#' the parallel executor (if available)
 #' @param  bayesianSetup object of class BayesianSetup
 #' @export
 stopParallel <- function(bayesianSetup){

BayesianTools/R/classLikelihood.R

@@ -1,14 +1,14 @@
 #' 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
-#' @example /inst/examples/createLikelihoodHelp.R        
+#' @example /inst/examples/createLikelihoodHelp.R
 #' @export
 createLikelihood <- function(likelihood, names = NULL, parallel = F, catchDuplicates=T, 
                              sampler = NULL, parallelOptions = NULL){
@@ -106,7 +106,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
@@ -138,7 +137,7 @@ likelihoodAR1 <- function(predicted, observed, sd, a){
 
   res = predicted - observed
 
-  # this calculates the unconditiona LL for this data, see e.g. http://stat.unicas.it/downloadStatUnicas/seminari/2008/Julliard0708_1.pdf
+  # this calculates the unconditional LL for this data, see e.g. http://stat.unicas.it/downloadStatUnicas/seminari/2008/Julliard0708_1.pdf
 
   ll =  0.5 * (  - n * log(2*pi)
                  - n * log(sd^2) 

BayesianTools/R/classMcmcSamplerList.R

@@ -1,7 +1,7 @@
 #' 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.
@@ -12,6 +12,7 @@ createMcmcSamplerList <- function(mcmcList){
   return(mcmcList)
 }
 
+
 #' @author Stefan Paul
 #' @method summary mcmcSamplerList
 #' @export

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){
 
@@ -53,5 +53,4 @@ createPosterior <- function(prior, likelihood){
 # x$density(c(0.2,0.2))
 # prior$density(c(2,2))
 # 
-# 
 # x = c(0.2,0.2)