do_global_all_women_run: Do Complete Run of FPEM
In FPcounts/FPEMglobal: Estimation of Contraceptive Use for All Women

do_global_all_women_run

R Documentation

Do Complete Run of FPEM

Description

Do married and unmarried runs of the global model, and produce results. Then combine to produce all women results.

Usage

do_global_all_women_run(
  run_desc = "",
  age_group = "15-49",
  estimation_iterations = 3,
  burn_in_iterations = 1,
  steps_before_progress_report = 4,
  thinning = 2,
  chain_nums = 1:3,
  set_seed_chains = 1,
  run_in_parallel = isTRUE(length(chain_nums) > 1),
  input_data_folder_path = system.file("extdata", package = "FPEMglobal"),
  data_csv_filename = paste0("data_cp_model_all_women_", age_group, ".csv"),
  region_information_csv_filename = "country_and_area_classification.csv",
  denominator_counts_csv_filename = paste0("number_of_women_", age_group, ".csv"),
  countries_for_aggregates_csv_filename = "countries_mwra_195.csv",
  countries_in_CI_plots_csv_filename = "countries_mwra_195.csv",
  special_aggregates_name = NULL,
  start_year = 1970.5,
  end_year = 2030.5,
  years_change = matrix(c(1990.5, 2000.5, 2000.5, 2018.5, 2018.5, 2030.5, 2012.5, 2018.5,
    2012.5, 2020.5, 2012.5, 2017.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), ncol = 3, byrow =
    TRUE),
  plot_barchart_years = c(floor(start_year), floor(median(c(start_year, end_year))),
    floor(end_year)),
  plot_CI_changes_years = c(floor(start_year), floor(end_year)),
  make_any_aggregates = TRUE,
  make_all_bar_charts = TRUE,
  plot_maps_shapefile_folder = NULL,
  plot_maps_years = floor(median(c(start_year, end_year))),
  data_info_plot_years = c(1990, 2000, 2010),
  adjust_medians = TRUE,
  run_name_override_married = NULL,
  run_name_override_unmarried = NULL,
  run_name_override_all_women = NULL,
  model_diagnostics = TRUE,
  include_AR = TRUE,
  age_ratios_age_total_run_name_prefix = NULL,
  age_ratios_age_total_married_run_name = NULL,
  age_ratios_age_total_unmarried_run_name = NULL,
  age_ratios_age_total_all_women_run_name = NULL,
  age_ratios_age_total_married_output_folder_path = NULL,
  age_ratios_age_total_unmarried_output_folder_path = NULL,
  age_ratios_age_total_all_women_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_desc`	Character. Brief note to be appended to the auto-generated `run_name`. Ignored if `run_name_override` is non-`NULL`.
`age_group`	Character. The age group for which a run of the model is desired, specified in the format “xx-yy”, where “xx” is the start age, “yy” is the end age, e.g., `"15-49"` or `"15-19"`. This is used to form the run name if `run_name_override` is `NULL`, to name of the file containing prevalence data if `data_csv_filename` is `NULL`, and to select rows from the denominator counts file if post-processing is done (see `post_process_mcmc`).
`estimation_iterations`	Numeric. Number of MCMC iterations that should be saved. This is before `thinning`.
`burn_in_iterations`	Numeric. Number of MCMC iterations that should be run as burn-in before starting to save them.
`steps_before_progress_report`	Numeric. The number of times progress should reported during MCMC sampling.
`thinning`	Numeric. The actual number of iterations saved is `\frac{\code{estimation_iterations}}{\code{thinning}}`.
`chain_nums`	Numeric. The number of MCMC chains to run, as a sequence. E.g., for three chains use `1:3`. You need to run at least two chains for post-processing to be successful.
`set_seed_chains`	Set the random seed passed to `JAGS`. For multiple chains, the seed for each is `set_seed_chains` multiplied by the chain number.
`run_in_parallel`	Logical. Determines if MCMC chains are run in parallel. Parallel running requires package doParallel or doMC. Defaults to serial running if `run_in_parallel = TRUE` but the package is not available.
`input_data_folder_path`	File path to folder containing all input data (except any map shapefiles). If `NULL` the value of `data_csv_filename`, etc., will be passed to `file.path` as-is. Otherwise, `file.path(input_data_folder_path, data_csv_filename)` will be passed. The default value points to the data directory supplied with the package.
`data_csv_filename`	Filename of the ‘.csv’ file containing country-level prevalence data. See “Details”.
`region_information_csv_filename`	Filename of the ‘.csv’ file containing classifications of countries in sub-regions, regions, etc. See “Details”.
`denominator_counts_csv_filename`	File path. Filepath to ‘.csv’ file with denominator counts (married and unmarried) for this `age_group`. If `NULL`, defaults to `paste0("women_", age_group, ".csv")`.
`countries_for_aggregates_csv_filename`	Name of the ‘.csv’ file listing countries that will be used in constructing country aggregates.
`countries_in_CI_plots_csv_filename`	Name of ‘.csv’ file that lists the countries to be included in the main country-level indicator plots. These are the plots saved in ‘`output_folder_path`/fig/`[run name]`CIs.pdf’. The format is the same as `countries_for_aggregates_csv_filename`. The file is looked for in `input_data_folder_path`. Countries appear in the ‘.pdf’ in the same order as they are listed in `countries_in_CI_plots_csv_filename`.
`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”.
`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.
`plot_barchart_years`	Vector of years for which bar charts should be produced. These are saved to ‘`output_folder_path`/fig/barchart’. These must be in the range of `start_year` and `end_year` passed to `post_process_mcmc`.
`plot_CI_changes_years`	Vector of length two (if longer, only the first and last elements are used). Declares the years to be used to make the “fish bone” plots, i.e., the plots appearing in files ‘`output_folder_path`/fig/`[run name]`_CIspropsubregional_modern_UNPD.pdf’. These must be in the range of `start_year` and `end_year` passed to `post_process_mcmc`.
`make_any_aggregates`	Logical. Should country aggregates of any kind (including default aggregates) be produced?
`make_all_bar_charts`	Logical. Produce barcharts? If `NULL` but `plot_barchart_years` is non-`NULL`, is reset to `TRUE`.
`plot_maps_shapefile_folder`	Path to directory containing shapefiles for maps. Only needed if `plot_maps` is `TRUE`. This is not looked for in `input_data_folder_path`; it should be a full path to the shape files.
`plot_maps_years`	Vector of years for which maps are desired; the full set of maps are produced for each of the years listed. These must be in the range of `start_year` and `end_year` passed to `post_process_mcmc`.
`adjust_medians`	Logical. Should adjusted medians outputs be produced in addition to unadjusted outputs?
`model_diagnostics`	Logical; should convergence diagnostics and WAIC be computed? These are not re-done if the folder ‘`output_folder_path`/convergence’ exists.
`include_AR`	Logical; should the auto-regressive component of the model be estimated. Used mainly for testing.
`age_ratios_age_total_run_name_prefix`	Run name prefix for married, unmarried, and all women runs. Results will be searched for in ‘output/`age_ratios_age_total_run_name_prefix`_`[marital_group]`_15-49’.
`age_ratios_age_total_married_run_name`	Run name of the married 15–49 run to use as the denominator for age ratios.
`age_ratios_age_total_unmarried_run_name`	Run name of the unmarried 15–49 run to use as the denominator for age ratios.
`age_ratios_age_total_all_women_run_name`	Run name of the all women 15–49 run to use as the denominator for age ratios.
`age_ratios_age_total_married_output_folder_path`	File path to output directory of the married 15–49 run to use to make age ratios.
`age_ratios_age_total_unmarried_output_folder_path`	File path to output directory of the unmarried 15–49 run to use to make age ratios.
`age_ratios_age_total_all_women_output_folder_path`	File path to output directory of the all women 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

A “run name” is assigned to each run of the model to identify it. The run name is used to name the directory in which outputs are stored and the filenames of certain results such as tables and plots. By default, it is auto-generated by concatenating the date-time (via format(Sys.time(), "%y%m%d_%H%M%S")), marital group, age group and (optionally) run_desc. If run_desc does not afford enough control, run_name_override can be used to completely override auto-generation. The function returns the run name as a character string.

See system.file("extdata", "data_cp_model_all_women_15-49.csv") for how the prevalence data input should be formatted. Assume all columns are required.

See system.file("extdata", "country_and_area_classification.csv") for how the country classification file should be formatted. Assume all columns are required.

Typical values of the MCMC control parameters for a “full” model run are:

estimation_iterations: ceiling(5e5 / nchains), where nchains is the number of chains (i.e., length(chain_nums)).
burn_in_iterations: 2e4
thinning: 30