run.tfr3.mcmc {bayesTFR}R Documentation

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.

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)

[Package bayesTFR version 7.0-4 Index]