do_global_run: Run the global FPEM model for married or unmarried women
In FPcounts/FPEMglobal: Estimation of Contraceptive Use for All Women

do_global_run

R Documentation

Run the global FPEM model for married or unmarried women

Description

This generates the MCMC chains using do_global_mcmc, post-processes them using post_process_mcmc and produces plots and tables using make_results.

Usage

do_global_run(
  run_desc = "",
  marital_group = c("married", "unmarried"),
  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,
  output_folder_path = 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),
  make_any_results = 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_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),
  make_any_aggregates = TRUE,
  adjust_medians = 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,
  run_name_override = NULL,
  model_diagnostics = TRUE,
  include_AR = TRUE,
  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`.
`marital_group`	Character. The marital group for which a run of the model is desired.
`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`	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.
`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”.
`output_folder_path`	Filepath to directory where outputs should be saved. If `NULL`, defaults to `file.path("output", run_name)`.
`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.
`make_any_results`	Logical. Should tables and plots be produced? If `FALSE`, the arguments that pertain to specific plots or tables are ineffective.
`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_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`.
`make_any_aggregates`	Logical. Should country aggregates of any kind (including default aggregates) be produced?
`adjust_medians`	Logical. Should adjusted medians outputs be produced in addition to unadjusted outputs?
`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")`.
`run_name_override`	Character. User defined run name to override default generation. `run_desc` is ignored if this is non-`NULL`.
`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.
`verbose`	Logical; print lots and lots of messages about progress?

Details

See “Details” in the help file for do_global_all_women_run.

Value

A name for the run, run_name, returned invisibly as a character string.

Author(s)

Mark Wheldon, Andrew Tait

References

Kettunen, J. et al. (2012) Genome-wide association study identifies multiple loci influencing human serum metabolite levels. Nat Genet advance online publication. http://dx.doi.org/10.1038/ng.1073.