Package 'runMCMCbtadjust'

R object of type mcmc.list that contains the MCMC output

character: designates the kind of correlation calculated among "pearson" (the default, for linear relationships), "spearman" (for monotone relationships) or "hoeffd" (for general associations - i.e. dependencies - between parameters)

double, between 0 and 1: minimum level of (absolute) correlation to report.

R object (can be a vector, matrix, array, list...) all components of which must be of character type: will remove parameters whose names partially match one of tghese components.

R object: code for the model that will be used to build the MCMC when MCMC_language is "Nimble" or "Jags". If "Nimble", must be the name (in R) of the object which is the result of the function nimbleCode. If "Jags", should be either: (i) a character string which is the name of a txt file that contains the code of the model (as used in the function jags.model): should then end up by ".txt"; or (ii) a character string that contains the text of the Jags code.

R list: a list that will contain the data when MCMC_language is "Nimble" or "Jags". If "Nimble", will be sent to the data argument of the nimbleModel function in nimble package, i.e. the data that have a random distribution in the model. If MCMC_language is "Greta", can be used just to document the summary of data in the output.

R list: a list that will contain the rest of the data (in addition to data) when MCMC_language is "Nimble". Will be sent to the constants argument of the nimbleModel function in nimble package, i.e. the data that do not have a random distribution in the model. If MCMC_language is "Greta", can be used just to document the summary of other data in the output.

R object: should be the result of the model command of Greta when MCMC_language is "Greta".

character value: designates the MCMC_language used to write & fit the Bayesian model in R. Current choices are "Nimble" - the default-, "Greta" or "Jags". Note that in case it is "Nimble", package nimble should be loaded in your search list if not using parallelization.

integer value : the number of Markov chains to run in the MCMC.

either NULL, a function or an R list, with Nchains components. Each component is then a named list that contains the initial values of the parameters for the MCMC. In case MCMC_language=="Greta", each component should be the result of the initials function in greta package. If a function, it will generate values for one chain.

character vector: contains the names of the parameters to save at the end of the MCMC and to monitor for convergence and effective sample size; inactive for convergence/effective sample size if params.conv is specified; inactive for saving if params.save is specified.

character vector: contains the names of the parameters to monitor for convergence and effective sample size.

character vector: contains the names of the parameters to be saved at the end of the MCMC.

integer value: the minimum number of iterations in each chain of the MCMC.

integer value: the maximum number of iterations in each chain of the MCMC. Will stop the MCMC once the number of iterations will reach this limit.

integer value: the minimum number of burn-in (=transitory) iterations in each chain of the MCMC.

integer value: the maximum number of burn-in (=transitory) iterations in each chain of the MCMC. Will stay at this burn-in value once this limit is reached.

integer value: the minimum value of the thin parameter of the MCMC.

integer value: the maximum value of the thin parameter of the MCMC. Will stay at this thin value once this limit is reached.

positive real number: minimum effective sample size - over parameters used to diagnose convergence & effective sample size- , as calculated with neff.method (specified in Control). The algorithm will not stop if the minimum number of effective values is not above this value (unless another limit - e.g. niter.max - is reached).

positive real number: median effective sample size - over parameters used to diagnose convergence & effective sample size- , as calculated with neff.method (specified in Control). The algorithm will not stop if the median number of effective values is not above this value (unless another limit - e.g. niter.max - is reached).

positive real number: mean effective sample size - over parameters used to diagnose convergence & effective sample size-, as calculated with neff.method (specified in Control). The algorithm will not stop if the mean number of effective values is not above this value (unless another limit - e.g. niter.max - is reached).

positive real number: maximum - over parameters used to diagnose convergence & effective sample size - convergence diagnostic, as calculated with convtype method (specified in Control). The algorithm will not stop if the maximum convergence diagnostic is not below this value (unless another limit - e.g. niter.max - is reached).

positive real number: median - over parameters used to diagnose convergence & effective sample size - convergence diagnostic, as calculated with convtype method(specified in Control). The algorithm will not stop if the median convergence diagnostic is not below this value (unless another limit - e.g. niter.max - is reached).

positive real number: mean - over parameters used to diagnose convergence & effective sample size - convergence diagnostic, as calculated with convtype method (specified in Control). The algorithm will not stop if the mean convergence diagnostic is not below this value (unless another limit - e.g. niter.max - is reached).

list of runMCMC_btadjust control parameters: with the following components:

• time.max: positive number (units: seconds): maximum time of the process in seconds, not including WAIC calculations and extra.calculations; the program will organize itself to stop (not including WAIC calculation and extra calculations as specified in control.MCMC$extraCalculations) before roughly time.max. Default to NULL, corresponding to no time constraint except in case of parallelization (see below).

• check.convergence: logical value: should the program check convergence at all? Default to TRUE. See Details.

• check.convergence.firstrun: logical value: should we check convergence after the first run? Default to NULL in which case will depend on MCMC_language: if MCMC_language!="Greta" & control.MCMC$n.adapt<=0, will be FALSE otherwise will be TRUE because warmup phase separated from the rest in case of Greta.

• recheck.convergence: logical value: should the algorithm recheck convergence once convergence has been found in a previous run? Default to TRUE.

• convtype: character or NULL value: specifies the type of convergence diagnostic used. Currently implemented: "Gelman" for original Gelman-Rubin diagnostic (only possible if Nchains>=2), "Gelman_new" for the version of the Gelman-Rubin diagnostic in the second version of "Bayesian Data Analysis" (Gelman, Carlin, Stern and Rubin)(only possible if Nchains>=2), "Geweke" for Geweke diagnostic (at present applied only in case Nchains==1) and "Heidelberger" for the reciprocal of Heidelberger-Welch first part of convergence diagnostic based on the Cramer-von Mises test statistic. If NULL (the default), chooses "Geweke" in case Nchains==1 and "Gelman" in case Nchains>1.

• convtype.Gelman: integer value: when convtype=="Gelman", do we target the Point estimate diagnostic (value 1) or the Upper C.I. diagnostic (value 2). Default to 2.

• convtype.Geweke: real vector with two components between 0 and 1: (i) the fraction of samples to consider as the beginning of the chain (frac1 in geweke.diag); (ii) the fraction of samples to consider as the end of the chain (frac2 in gewke.diag). Default to c(0.1,0.5) as in geweke.diag.

• convtype.alpha: real value between 0 and 1: significance level used in case convtype=="Gelman" and convtype.Gelman==2, or convtype=="Heidelberger"

• props.conv: numeric vector: quantiles of number of iterations removed to recheck convergence and number of effective values (if not converged before or conv.thorough.check is TRUE). Values should be between 0 and 1.

• ip.nc: real value: inflexion point for log(scaleconvs-1); if (very) negative will tend to double the number of iterations in case of non convergence (i.e. add niter iterations) ; if (very) positive will tend to add niter/Ncycles iterations. Default to 0.

• conv.thorough.check: logical value: whether one goes through all the props.conv proportions to find the best one in terms first of convergence (just in terms of respecting the criterion) and then of neffs (if TRUE) or stops at the first props.conv corresponding to convergence or does not change if there is no convergence (if FALSE, the default).

• neff.method: character value: method used to calculate the effective sample sizes. Current choice between "Stan" (the default) and "Coda". If "Stan", uses the function monitor in package rstan. If "Coda", uses the function effectiveSize in package coda.

• Ncycles.target: integer value: targeted number of MCMC runs. Default to 2.

• min.Nvalues: integer value or expression giving an integer value or NULL: minimum number of values to diagnose convergence or level of autocorrelation. Default to NULL in which case is will be given the value neff.max calculated within the program.

• round.thinmult: logical value: should the thin multiplier be rounded to the nearest integer so that past values are precisely positioned on the modified iteration sequence? Default to TRUE. Value of FALSE may not be rigorous or may not converge well.

• thinmult.in.resetMV.temporary: logical value: should the thin multiplier be taken into account in resetting parameter collection in case MCMC_language is "Nimble". Important mainly if control.MCMC$WAIC is TRUE. If TRUE, resetting will be more frequent, and WAIC calculation will be longer and more rigorous. Default to TRUE.

• check.thinmult: integer value between 1, 2 and 3: how should we check thinmult value after thinmult calculation? If 3, it is tested whether thinmult meets specific criteria -relative to convergence reaching (i.e. if no convergence, no change), number of effective value reaching conservation, minimum number of output values - min.Nvalues- and proportional reduction of number of effective values - and if not decreased values are tested with the same criteria. If 2, the same checkings are done except the one on proportional reduction of effective values. If 1, only the min.Nvalues criterion is taken into account. Default to 2. A value of 3 should produce shorter MCMCs, more values in the output, with more autocorrelation, than a value of 1.

• decrease.thinmult.multiplier: positive number below 1: when adapting the proposed multiplier of thin (thinmult), the multiplier of the current thinmult used to propose a new - smaller - thinmult value, provided thinmult is above decrease.thinmult.threshold. Default to 0.8.

• decrease.thinmult.threshold: positive number above 3: when adapting the proposed multiplier of thin (thinmult), the threshold value for thinmult below which decreases of proposed thinmult are substractions of one unit. Default to 20.

• only.final.adapt.thin: logical value: should the thin parameter be adapted only at the end - so that during running of the MCMC we conserve a sufficient number of values - esp. with respect to min.Nvalues. Default to FALSE.

• min.thinmult: numeric value: minimum value of thin multiplier: if diagnostics suggest to multiply by less than this, this multiplication is not done. Default to 1.1.

• force.niter.max: logical value: if TRUE, the number of iterations is forced to go to niter.max - except for time.max constraints. Default to FALSE.

• force.time.max: logical value: if TRUE, the number of iterations is forced to go to approximately time.max seconds - except for niter.max constraints. Default to FALSE.

• time.max.turns.off.niter.max: logical value: if TRUE, and if time.max is finite, the number of iterations can be greater than niter.max (except if we are only in the phase of force.niter.max or force.time.max). Default to FALSE.

• seed: integer number or NULL value: seed for the pseudo-random number generator inside runMCMC_btadjust. Default to NULL in which case here is no control of this seed.

• identifier.to.print: character string: printed each time an MCMC update is ran to identify the model (esp. if multiple successive calls to runMCMC_btadjust are made).

• safemultiplier.Nvals: positive number: number bigger than 1 used to multiply the targeted number of effective values in calculations of additional number of iterations. Default to 1.2.

• max.prop.decr.neff: number between 0 and 1 used, if check.thinmult==3, to decide if we accept dimension reduction - through augmentation of thin parameter with thinmult -: maximum acceptable Proportional Decrease of the number of effective values: guaranties that at least (1-max.prop.decr.neff) times the number of effective values estimated prior to dimension reduction are kept. Default to 0.1.

• print.diagnostics: logical value: should diagnostics be printed each time they are calculated? Default to FALSE.

• print.thinmult: logical value: should the raw multiplier of thin be printed each time it is calculated? Default to TRUE.

• innerprint: logical value: should printings be done inside the function monitor of rstan in case neff.method=="Stan"? Default to FALSE.

• remove.fixedchains: logical value: should we remove Markov chains that do not vary during the first cycle (i.e. whose all parameters have zero variances)? Default to TRUE. If so, those chains are removed from the diagnostics, from the output values and associated chains are no longer updated if MCMC_language=="Nimble".

• check.installation: logical value: should the function check installation of packages and programs? Default to TRUE.

• save.data: logical value: should the program save the entire data in the call.params section of the attributes? Default to FALSE, in which case only a summary of data is saved.

• conveff.final.allparams: logical value: should the final convergence/number of effective values calculations in final.diags be done on all parameters? Default to TRUE.

list of MCMC control parameters: with the following components - that depend on MCMC_language:

• confModel.expression.toadd (only for MCMC_language=="Nimble"): expression to add to confModel to specify samplers, remove nodes... confModel should be referred to by confModel[[i]]. See Details for an example.

• sampler (only for MCMC_language=="Greta"): expression used to specify the sampler used.

• warmup (only for MCMC_language=="Greta"): integer value used as warmup parameter in the mcmc.

• n.adapt (only for MCMC_language=="Jags" or MCMC_language=="Nimble"): integer value: number of iterations used for adaptation (in function jags.model in rjags package in case MCMC_language=="Jags" and otherwise in Nimble - added to burnin: first iterations that are not saved).

• RNG.names (only for MCMC_language=="Jags"): character vector: name of pseudo-random number generators for each chain. Each component of the vector should be among "base::Wichmann-Hill", "base::Marsaglia-Multicarry", "base::Super-Duper", "base::Mersenne-Twister". If less values than Nchains are provided, they are specified periodically.

• n_cores (only for MCMC_language=="Greta"): integer or NULL: maximum number of cores to use by each sampler.

• showCompilerOutput (only for MCMC_language=="Nimble"): logical value indicating whether details of C++ compilation should be printed. Default to FALSE to get default printings of limited size.

• buildDerivs (only for MCMC_language=="Nimble"): logical value indicating whether derivatives should be prepared when preparing Nimble model (will esp. allow to use HMC sampler). Default to FALSE.

• resetMV (only for MCMC_language=="Nimble"): logical value to be passed to $run specifying whether previous parameter samples should be reset or not. Default to FALSE to speed up WAIC calculations. You can turn it to TRUE if you wish to speed up runs of MCMC (cf. https://groups.google.com/g/nimble-users/c/RHH9Ybh7bSI/m/Su40lgNRBgAJ).

• parallelize (only for MCMC_language=="Jags" and MCMC_language=="Nimble"): logical value specifying whether the MCMC should be parallelized within the runMCMC_btadjust function with the parallel package (and for the moment default settings of this package). Default to FALSE. If TRUE, library parallel should be loaded. If TRUE and control$time.max is unspecified or infinite, each parallelized process will have a maximum duration of 30 days. In case MCMC_language=="Greta", parallelization is managed directly by Greta.

• parallelizeInitExpr (only for MCMC_language=="Jags" and MCMC_language=="Nimble"): expression to add in each cluster created by parallelization. Default to expression(if(MCMC_language=="Nimble"){library(nimble);if(control.MCMC$APT) {library(nimbleAPT)}} else {NULL}).

• useConjugacy (only for MCMC_language=="Nimble"): logical value specifying whether Nimble should search for conjugate priors in the model. Default to FALSE. If TRUE, can render model configuration shorter (https://groups.google.com/g/nimble-users/c/a6DFCefYfjU/m/kqUWx9UXCgAJ) at the expense of not allowing any conjugate sampler

• WAIC (only for MCMC_language=="Nimble"): logical value specifying whether WAIC should be calculated online within Nimble. Default to FALSE.

• WAIC.Nsamples (only for MCMC_language=="Nimble"): integer number: number of (nearly independent) samples of parameters in the posterior distribution over which to calculate WAIC. If WAIC is calculated on more than one chain, this number will be required for each of these chains. Default to 2000.

• WAIC.control (only for MCMC_language=="Nimble"): named list or list of such named lists: list (or lists) specifying the control parameters to calculate WAIC online within Nimble. Default to list(online=TRUE,dataGroups=NULL,marginalizeNodes=NULL,niterMarginal=1000,convergenceSet=c(0.25,0.5,0.75),thin=TRUE,nburnin_extra=0). Given the way WAIC is here calculated (after convergence and over the last sample outputs for one chain by named list), components thin will be turned to TRUE and nburnin_extra to 0. If several lists are used, only at most the first Nchains - reduced by removal of fixed chains - lists will be taken into account to calculate WAICs in different ways on different Markov Chains.

• APT (only for MCMC_language=="Nimble"): logical value specifying whether NimbleAPT should be used to allow Adaptive Parallel Tempering for at least a subset of the model parameters. If so, the sampler_RW_tempered sampler is declared for all parameters. If wishing to change sampler, use confModel.expression.toadd. Default to FALSE.

• APT.NTemps (only for MCMC_language=="Nimble"): integer number: number of temperatures for NimbleAPT. Default to 7.

• APT.initTemps (only for MCMC_language=="Nimble"): NULL or double vector of length APT.NTemps: initial temperatures for Nimble APT. Default to NULL in which case initial temperatures will be 1:APT.NTemps. The values should be increasing with a first value of 1.

• APT.tuneTemps (only for MCMC_language=="Nimble"): numerical vector of length 2: values to feed the parameters tuneTemper1 and tuneTemper2 in NimbleAPT. See documentation of NimbleAPT. Default to c(10,0.7).

• APT.thinPrintTemps (only for MCMC_language=="Nimble"): expression or numerical value : thinning parameter for printing temperatures in case APT. Default to expression(niter/5).

• includeAllStochNodes (only for MCMC_language=="Nimble"): logical value specifying whether all stochastic nodes should be made available in runMCMC_btadjust. Default to FALSE. Maybe useful for the extraCalculations component of control.MCMC. Can include more parameters than includeParentNodes. Can be useful for example to calculate goodness-of-fit p-values.

• monitorAllStochNodes (only for MCMC_language=="Nimble"): logical value specifying whether all stochastic nodes should be monitored for convergence and number of effective values in runMCMC_btadjust. Default to FALSE.

• saveAllStochNodes (only for MCMC_language=="Nimble"): logical value specifying whether all stochastic nodes should be made available in runMCMC_btadjust and kept in the result of runMCMC_btadjust. Default to FALSE. Note that if TRUE, will change the content of params_saved.

• includeParentNodes (only for MCMC_language=="Nimble"): logical value specifying whether parent stochastic nodes of data should be made available in runMCMC_btadjust. Default to FALSE. Maybe useful for the extraCalculations component of control.MCMC - for example for "offline" calculations of WAIC or DIC (Deviance information criterion).

• monitorParentNodes (only for MCMC_language=="Nimble"): logical value specifying whether parent stochastic nodes of data should be monitored for convergence and number of effective values in runMCMC_btadjust. Default to FALSE.

• saveParentNodes (only for MCMC_language=="Nimble"): logical value specifying whether parent stochastic nodes of data should be made available in runMCMC_btadjust and kept in the result of runMCMC_btadjust. Default to FALSE. Note that if TRUE, will change the content of params_saved.

• extraCalculations (mainly useful for MCMC_language=="Nimble" but can be used with other languages as well): NULL value or expression that will be evaluated at the end of runMCMC_btadjust. The value of this expression will be saved in the extraResults component of the final.params component of the attributes of the result of runMCMC_btadjust. See the vignette devoted to the use of it. Default to NULL.