post_process_mcmc: Post process MCMC chains from a global run of FPEM
In FPcounts/FPEMglobal: Estimation of Contraceptive Use for All Women

post_process_mcmc

R Documentation

Post process MCMC chains from a global run of FPEM

Description

MCMC chains from a global run of FPEM for either married or unmarried women (via do_global_mcmc) must be post-processed before summary results (tables, plots) can be produced. This function does the post-processing and saves the results in output_folder_path. You need at least two chains for post-processing to work. This function does not apply to all women runs; see combine_runs.

Usage

post_process_mcmc(
  run_name = NULL,
  output_folder_path = file.path("output", run_name),
  input_data_folder_path = NULL,
  denominator_counts_csv_filename = NULL,
  countries_for_aggregates_csv_filename = "countries_mwra_195.csv",
  start_year = 1970.5,
  end_year = 2030.5,
  years_change = matrix(c(1990.5, 2000.5, 2000.5, 2019.5, 2019.5, 2030.5, 2012.5, 2019.5,
    2012.5, 2019.5, 2012.5, 2020.5), ncol = 2, byrow = TRUE),
  years_change2 = matrix(c(2005.5, 2010.5, 2015.5, 2000.5, 2005.5, 2010.5, 1995.5,
    2000.5, 2005.5, 1990.5, 1995.5, 2000.5, 1990.5, 2000.5, 2010.5, 2000.5, 2010.5,
    2019.5), ncol = 3, byrow = TRUE),
  model_diagnostics = TRUE,
  make_any_aggregates = TRUE,
  special_aggregates_name = NULL,
  summarize_global_run = TRUE,
  age_ratios_age_total_run_name = NULL,
  age_ratios_age_total_output_folder_path = NULL,
  age_ratios_age_total_denominator_counts_csv_filename = "number_of_women_15-49.csv",
  age_ratios_age_total_denominator_counts_folder_path = NULL,
  verbose = FALSE
)

Arguments

`run_name`	The name of the run to post-process.
`output_folder_path`	Filepath to directory where outputs should be saved. If `NULL`, defaults to `file.path("output", run_name)`.
`input_data_folder_path`	File path to folder containing all input data (except any map shapefiles). If `NULL` the value is taken from `file.path(output_folder_path, "global_mcmc_args.RData")` if that file exists, otherwise `file.path(output_folder_path, "data")`.
`denominator_counts_csv_filename`	Name of the ‘.csv’ file containing estimates and projections of the number of women by marital status, age, and year. See “Details”.
`countries_for_aggregates_csv_filename`	Name of the ‘.csv’ file listing countries that will be used in constructing country aggregates.
`start_year`	Estimates and projections are produced for a specified time interval. This is the start year of that interval.
`end_year`	Estimates and projections are produced for a specified time interval. This is the end year of that interval.
`years_change`	A two-column matrix giving the year pairs (as rows) between which probabilistic estimates of changes in the indicators are desired.
`years_change2`	A three-column matrix giving the year triples (as rows) among which to compute probabilistic estimates of change-in-changes.
`model_diagnostics`	Logical; should convergence diagnostics and WAIC be computed? These are not re-done if the folder ‘`output_folder_path`/convergence’ exists.
`make_any_aggregates`	Logical. Should country aggregates of any kind (including default aggregates) be produced?
`special_aggregates_name`	Character vector of names (not filenames) of any speical aggregates desired. There must be a corresponding file with name ‘`special_aggregates_name`.csv’ in `input_data_folder_path` that defines the special aggregates. See “Details”.
`summarize_global_run`	Logical; should the model summary for one-country runs be produced?
`age_ratios_age_total_run_name`	Run name of the 15–49 run to use as the denominator for age ratios. Calculate ratios of users in a subset age range (e.g., 15–19) to users in the total age range (15–49) from this run. Requires a completed 15–49 run.
`age_ratios_age_total_output_folder_path`	Alternative way of specifying the run to use to make age ratios (see `age_ratios_age_total_run_name`. File path to output directory of the 15–49 run to use to make age ratios.
`age_ratios_age_total_denominator_counts_csv_filename`	Name of the ‘.csv’ file containing estimates and projections of the number of women by marital status, age, and year, for the age group 15–49. Only used if `make_age_ratios` is `TRUE`. Searched for in `age_ratios_age_total_denominator_counts_folder_path`.
`age_ratios_age_total_denominator_counts_folder_path`	Path to `age_ratios_age_total_denominator_counts_csv_filename`. If `NULL`, defaults to `file.path(age_ratios_age_total_output_folder_path, "data")`.
`verbose`	Logical; print lots and lots of messages about progress?

Details

The counts of women by marital status, age, and year in denominator_counts_csv_filename are used to convert prevalence proportions to counts of women by contraceptive use status. See system.file("extdata", "data_cp_model_all_women_15-49.csv", package = "FPEMglobal") for an example of how the file should be formatted. Assume all columns are required.

By default, results are produced at the country level and for geographic country aggregates. These are the sub-regions and regions of the UN M49 classification (UN DESA Statistics Division, 2017). For additional aggregates, argument special_aggregates_name may be used. The argument takes the name of the aggregate. There must be a corresponding ‘.csv’ file in input_data_folder_path. The aggregate “WHO_regions” is included with the package; see system.file("extdata", "WHO_regions.csv", package = "FPEMglobal") for the required format. Assum all columns are required.

Value

The run name (invisibly). The function is mainly called for its side effects.

Author(s)

Mark Wheldon, Andrew Tait

References

UN DESA Statistics Division, (2017) Standard Country or Area Codes for Statistical Use (M49). United Nations, Department of Economic and Social Affairs. https://unstats.un.org/unsd/methodology/m49/