make_results: Summarize a post-processed global run of FPEM
In FPcounts/FPEMglobal: Estimation of Contraceptive Use for All Women

make_results

R Documentation

Summarize a post-processed global run of FPEM

Description

Once post-processed, a global model can be used to generate results in the form of summary figures and tables of key indicators. Summaries are in the form of quantiles of posterior marginal distributions, and means for some indicators.

Usage

make_results(
  run_name = NULL,
  output_folder_path = file.path("output", run_name),
  input_data_folder_path = NULL,
  countries_in_CI_plots_csv_filename = "countries_mwra_195.csv",
  CI_plots_years = NULL,
  plot_diagnostic_CI_plots = FALSE,
  make_all_bar_charts = NULL,
  plot_barchart_years = NULL,
  data_info_plot_years = c(1990, 2000, 2010),
  plot_CI_changes_years = NULL,
  plot_maps_shapefile_folder = NULL,
  plot_maps_years = NULL,
  plot_prior_post = NULL,
  plot_parameters = NULL,
  tabulate_changes = TRUE,
  adjust_medians = TRUE,
  make_any_aggregates = TRUE,
  special_aggregates_name = NULL,
  make_age_ratios = NULL,
  validation_keep_all = TRUE,
  validation_return_res_as_df = FALSE,
  all_women = 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 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.
`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`.
`plot_diagnostic_CI_plots`	Logical. Produce diagnostic versions of the main country-level indicator plots. These have zoomed y-axes.
`make_all_bar_charts`	Logical. Produce barcharts? If `NULL` but `plot_barchart_years` is non-`NULL`, is reset to `TRUE`.
`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`.
`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`.
`plot_parameters`	Logical. Should posterior quantiles of model parameters be added to the plots in legend boxes?
`adjust_medians`	Logical. Should adjusted medians outputs be produced in addition to unadjusted outputs?
`make_any_aggregates`	Logical. Should country aggregates of any kind (including default aggregates) be produced?
`special_aggregates_name`	name for special aggregates, if any. The default, `NULL`, means no special aggregates are produced. Note: this is not a filename, although a corresponding file named ‘`special_aggregates_name`.csv’ must be present in `input_data_folder_path`.
`make_age_ratios`	Logical. Should results for age-ratios be made? If `NULL` this is set based on the presence of files “res.country.age.ratio.rda” or “res.country.all.women.age.ratio.rda” in `output_folder_path`.
`validation_keep_all`	Logical. Should validation results be saved? If `TRUE`, a list with elements `CI.df` and `Error.df` is saved to ‘`output_folder_path`/validn_repts/validation.results.rda’.
`validation_return_res_as_df`	Logical; should the validation results be returned as a data frame? If `FALSE` the function returns the `run_name` invisibly as a character string.
`verbose`	Logical; print lots and lots of messages about progress?
`married_women_run_name`	Run name of a married women run. Relevant if `make_results` is being run on an all women run and age ratios for country aggregates are wanted. If this argument is `NULL` (default), and `all_women` is `TRUE` (explicitly or implicitly), an attempt is made to find this folder by substituting “all_women” with “married” in the `run_name`.
`unmarried_women_run_name`	Run name of a unmarried women run. See `married_women_run_name`.
`married_women_output_folder_path`	Path to directory containing outputs for a married women run. See `married_women_run_name`.
`unmarried_women_output_folder_path`	Path to directory containing outputs for a unmarried women run. See `married_women_output_folder_path`.

Details

The indicators for which these summaries are generated are, by country and country aggregate, by year:

Contraceptive prevalence, any method (CP)
Contraceptive prevalence, traditional methods (CP modern)
Contraceptive prevalence, modern methods (CP traditional)
Unmet need for (modern) contraception (unmet need)
CP + Unmet need
Met demand for any method of contraception
Met demand for modern methods of contraception
Ratio of CP modern to CP
Probability that met demand for modern methods is greater than 75 percent

Value

Either run_name invisibly as a character string or, if isTRUE(validation_return_res_as_df), a data frame (non-invisibly) containing validation results.

Age ratios for aggregates

post_process_mcmc generates trajectories for the age ratios for countries for married, unmarried, and all women. However, combine_runs, not post_process_mcmc, produces the trajectories for age ratios for country aggregates, including those for married and unmarried women. When make_results is applied to an all women run, an attempt is made to find the corresponding