run.tfr.mcmc.extra: Run MCMC for Extra Countries, Areas or Regions

In PPgp/bayesTFR: Bayesian Fertility Projection

Run MCMC for Extra Countries, Areas or Regions

Description

Run MCMC for extra countries, areas or regions. It uses the posterior distribution of model hyperparameters from an existing simulation to generate country-specific parameters.

Usage

run.tfr.mcmc.extra(sim.dir = file.path(getwd(), "bayesTFR.output"), 
    countries = NULL, my.tfr.file = NULL, 
    iter = NULL, thin = 1, thin.extra = 1, burnin = 2000,
    parallel = FALSE, nr.nodes = NULL,  my.locations.file = NULL,
    uncertainty = FALSE, my.tfr.raw.file = NULL, 
    use.wpp.data = TRUE, iso.unbiased = NULL, 
    covariates = c('source', 'method'), cont_covariates = NULL, 
    source.col.name = "source", average.gammas.cov = TRUE, 
    verbose = FALSE, verbose.iter = 100, ...)

Arguments

sim.dir	Directory with an existing simulation.
countries	Vector of country codes. These include codes of areas and regions (see column country_code in UNlocations).
my.tfr.file	File name containing user-specified TFR time series for countries for which the simulation should run (see Details below).
iter	Number of iterations to be used for sampling from the posterior distribution of the hyperparameters. By default, the number of iterations used in the existing simulation is taken.
thin	Thinning interval for sampling from the posterior distribution of the hyperparameters.
thin.extra	Thinning interval for the MCMC run for extra countries.
burnin	Number of iterations discarded before sampling from the posterior distribution of the hyperparameters. It is also used when computing proposal of gamma covariance matrices (see get.cov.gammas).
parallel	Logical determining if the simulation should run multiple chains in parallel.
nr.nodes	Relevant only if parallel is TRUE. It gives the number of nodes for running the simulation in parallel. By default it equals to the number of chains contained in the existing simulation.
my.locations.file	File name containing user-specified locations. See Details below.
uncertainty	Whether past TFR uncertainty is considered. If TRUE, countries listed in countries will be re-simulated with the model that accounts for past TFR estimation. It will take observations either from rawTFR (default) or from a file given by my.tfr.raw.file, and estimate the distribution of these observations with respect to the true TFR. Then instead of treating the observed data as true data, it assumes the true TFR are unknown and includes an extra step for estimating past TFR.
my.tfr.raw.file	File name of the raw TFR used when uncertainty is TRUE. See details in run.tfr.mcmc.
use.wpp.data	Logical indicating if default WPP data should be used, i.e. if my.tfr.file will be matched with the WPP data in terms of time periods and locations. If FALSE, it is assumed that the my.tfr.file contains all locations and time periods to be included in the simulation.
iso.unbiased	Codes of countries for which the vital registration TFR estimates are considered unbiased. See details in run.tfr.mcmc.
covariates, cont_covariates	Categorical and continuous features used in estimating bias and standard deviation if uncertainty is TRUE. See details in run.tfr.mcmc.
source.col.name	If uncertainty is TRUE this is a column name within the given covariates that determines the data source. It is used if iso.unbiased is given to identify the vital registration records.
average.gammas.cov	Set this to FALSE if the processed country has been included in the main simulation. In such a case the proposal gamma covariance matrix is taken from the proposal_cov_gammas_cii dataset. By default, the matrix is taken as an average from all countries.
verbose	Logical switching log messages on and off.
verbose.iter	Integer determining how often (in number of iterations) log messages are outputted during the estimation.
...	Additional parameters to be passed to the function performParallel, if parallel is TRUE.

Details

The function can be used to make predictions for countries, areas or regions (further denoted as ‘countries’) that were not included in the MCMC estimation (invoked by run.tfr.mcmc). It creates MCMC traces for country-specific parameters. The purpose of this function is to have country-specific parameters available in order to be able to generate projections for additional countries or their aggregations, without having to re-run the often time-expensive MCMC simulation.

The set of countries to be considered by this function can be given either by their codes, using the argument countries, in which case the countries must be included in the UN WPP tfr dataset. Or, it can be given by a user-specific TFR file, using the argument my.tfr.file. The countries argument haas a priority over my.tfr.file.

In the default case of uncertainty = FALSE, the function will ignore all countries that were used in the existing MCMC simulation for estimating the hyperparameters. However, countries that already own country-specific parameters (e.g. because they were included in my.tfr.file passed to run.tfr.mcmc with include_code = 1, or from a previous pass of the run.tfr.mcmc.extra function) get their parameters recomputed. In case of uncertainty = TRUE, all specified countries, regardless if they were included in the existing world simulation or not, get their parameters recomputed. It is therefore advisable to make a backup copy of the exisiting MCMC simulation, as there is a no easy way to revert the parameters to their original values.

Note that all affected countries should be included in the UNlocations dataset, but unlike in run.tfr.mcmc, their include_code is ignored. As in the case of run.tfr.mcmc, the default dataset of locations UNlocations can be overwritten using a file of the same structure as UNlocations passed via the my.locations.file argument. This file should be especially used, if TFR is simulated for new locations that are not included in UNlocations.

Value

An object of class bayesTFR.mcmc.set.

Note

If there is an existing projection for the directory sim.dir, use tfr.predict.extra to obtain projections for the extra countries used in this function.

Author(s)

Hana Sevcikova, Leontine Alkema, Peiran Liu

See Also

run.tfr.mcmc, tfr.predict.extra

Examples

## Not run: 
sim.dir <- tempfile()
m <- run.tfr.mcmc(nr.chains = 1, iter = 20, output.dir = sim.dir, verbose = TRUE)
m <- run.tfr.mcmc.extra(sim.dir = sim.dir, countries = c(908, 924), 
  burnin = 10, verbose = TRUE)
summary(m, country = 924)
pred <- tfr.predict(m, burnin = 10, use.tfr3 = FALSE, verbose = TRUE)
summary(pred, country = 908)
unlink(sim.dir, recursive = TRUE)
## End(Not run)

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