run.tfr3.mcmc: Running Markov Chain Monte Carlo for Parameters of Total...

In PPgp/bayesTFR: Bayesian Fertility Projection

Running Markov Chain Monte Carlo for Parameters of Total Fertility Rate in Phase III

Description

Runs (or continues running) MCMCs for simulating Phase III total fertility rate, using a Bayesian hierarchical version of an AR(1) model.

Usage

run.tfr3.mcmc(sim.dir, nr.chains = 3, iter = 50000, thin = 10, 
    replace.output = FALSE, my.tfr.file = NULL, buffer.size = 100, 
    use.extra.countries = FALSE, 
    mu.prior.range = c(0, 2.1), rho.prior.range = c(0, 1 - .Machine$double.xmin), 
    sigma.mu.prior.range = c(1e-05, 0.318), sigma.rho.prior.range = c(1e-05, 0.289), 
    sigma.eps.prior.range = c(1e-05, 0.5), 
    mu.ini = NULL, mu.ini.range = mu.prior.range, 
    rho.ini = NULL, rho.ini.range = rho.prior.range, 
    sigma.mu.ini = NULL, sigma.mu.ini.range = sigma.mu.prior.range, 
    sigma.rho.ini = NULL, sigma.rho.ini.range = sigma.rho.prior.range, 
    sigma.eps.ini = NULL, sigma.eps.ini.range = sigma.eps.prior.range, 
    seed = NULL, parallel = FALSE, nr.nodes = nr.chains, compression.type = "None", 
    auto.conf = list(max.loops = 5, iter = 50000, iter.incr = 20000, nr.chains = 3, 
                    thin = 60, burnin = 10000), 
    verbose = FALSE, verbose.iter = 1000, ...)
        
continue.tfr3.mcmc(sim.dir, iter, chain.ids=NULL, 
    parallel = FALSE, nr.nodes = NULL, auto.conf = NULL,
    verbose=FALSE, verbose.iter = 1000, ...)

Arguments

sim.dir	Directory with an existing simulation of phase II TFR (see run.tfr.mcmc).
nr.chains	Number of MCMC chains to run.
iter	Number of iterations to run in each chain. In addition to a single value, it can have the value ‘auto’ in which case the function runs for the number of iterations given in the auto.conf list (see below), then checks if the MCMCs converged (using the auto.conf settings). If it did not converge, the procedure is repeated until convergence is reached or the number of repetition exceeded auto.conf$max.loops.
thin	Thinning interval between consecutive observations to be stored on disk.
replace.output	If TRUE, previously stored results of a phase III simulation will be overwritten.
my.tfr.file	File name containing user-specified TFR time series for one or more countries. See description of this argument in run.tfr.mcmc.
buffer.size	Buffer size (in number of iterations) for keeping data in the memory.
use.extra.countries	By default, only countries are used in the MCMCs that were assigned for estimation (i.e. their ‘include_code’ is 2 in the include) dataset and are in phase III at present time (argument present.year in run.tfr.mcmc). If this argument is TRUE, countries that were added using run.tfr.mcmc.extra and are in phase III are also included.
mu.prior.range, rho.prior.range, sigma.mu.prior.range, sigma.rho.prior.range, sigma.eps.prior.range	Min and max for the prior (uniform) distribution of these paraemters.
mu.ini, rho.ini, sigma.mu.ini, sigma.rho.ini, sigma.eps.ini	Initial value(s) of the parameters. It can be a single value or an array of the size nr.chains. By default, if nr.chains is 1, it is the middle point of the corresponding range. Otherwise, it is uniformly randomly distributed within the range.
mu.ini.range, rho.ini.range, sigma.mu.ini.range, sigma.rho.ini.range, sigma.eps.ini.range	Min and max for the initial values.
seed	Seed of the random number generator. If NULL no seed is set.
parallel	Logical determining if the simulation should run multiple chains in parallel. If it is TRUE, the package snowFT is required.
nr.nodes	Relevant only if parallel is TRUE. It gives the number of nodes for running the simulation in parallel.
compression.type	One of ‘None’, ‘gz’, ‘xz’, ‘bz’, determining type of a compression of the MCMC files. Important: Do not use this option for a long MCMC simulation as this tends to cause very long run times due to slow reading!
auto.conf	List containing a configuration for an ‘automatic’ run (see description of argument iter). Item iter gives the number of iterations in the first chunk of the MCMC simulation; item iter.incr gives the number of iterations in the following chunks; nr.chains gives the number of chains in all chunks of the MCMC simulation; items thin and burnin are used in the convergence diagnostics following each chunk; max.loops controls the maximum number of chunks. All items must be integer values. This argument is only used if the function argument iter is set to ‘auto’.
verbose	Logical switching log messages on and off.
verbose.iter	Integer determining how often (in number of iterations) messages are outputted during the estimation.
...	Additional parameters to be passed to the function performParallel, if parallel is TRUE.
chain.ids	Array of chain identifiers that should be resumed. If it is NULL, all existing chains are resumed.

Details

The MCMCs are stored in sim.dir in a subdirectory called “phaseIII”. It has exactly the same structure as phase II MCMCs described in run.tfr.mcmc.

Value

An object of class bayesTFR.mcmc.set which is a list with two components:

meta	An object of class bayesTFR.mcmc.meta.
mcmc.list	A list of objects of class bayesTFR.mcmc, one for each MCMC.

Author(s)

Hana Sevcikova

References

Raftery, A.E., Alkema, L. and Gerland, P. (2014). Bayesian Population Projections for the United Nations. Statistical Science, Vol. 29, 58-68. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1214/13-STS419")}.

See Also

run.tfr.mcmc, get.tfr3.mcmc

Examples

## Not run: 
sim.dir <- tempfile()
# Runs Phase II MCMCs (must be run before Phase III)
m <- run.tfr.mcmc(nr.chains=1, iter=5, output.dir=sim.dir, verbose=TRUE)
# Runs Phase III MCMCs
m3 <- run.tfr3.mcmc(sim.dir=sim.dir, nr.chains=2, iter=50, thin=1, verbose=TRUE)
m3 <- continue.tfr3.mcmc(sim.dir=sim.dir, iter=10, verbose=TRUE)
summary(m3, burnin=10)
unlink(sim.dir, recursive=TRUE)
## End(Not run)

PPgp/bayesTFR documentation built on Nov. 5, 2024, 1:57 p.m.