Package 'mcmsupply'

Title: Estimating Public and Private Sector Contraceptive Market Supply Shares
Description: Family Planning programs and initiatives typically use nationally representative surveys to estimate key indicators of a country’s family planning progress. However, in recent years, routinely collected family planning services data (Service Statistics) have been used as a supplementary data source to bridge gaps in the surveys. The use of service statistics comes with the caveat that adjustments need to be made for missing private sector contributions to the contraceptive method supply chain. Evaluating the supply source of modern contraceptives often relies on Demographic Health Surveys (DHS), where many countries do not have recent data beyond 2015/16. Fortunately, in the absence of recent surveys we can rely on statistical model-based estimates and projections to fill the knowledge gap. We present a Bayesian, hierarchical, penalized-spline model with multivariate-normal spline coefficients, to account for across method correlations, to produce country-specific,annual estimates for the proportion of modern contraceptive methods coming from the public and private sectors. This package provides a quick and convenient way for users to access the DHS modern contraceptive supply share data at national and subnational administration levels, estimate, evaluate and plot annual estimates with uncertainty for a sample of low- and middle-income countries. Methods for the estimation of method supply shares at the national level are described in Comiskey, Alkema, Cahill (2022) <arXiv:2212.03844>.
Authors: Hannah Comiskey [aut, cre], Niamh Cahill [aut], Leontine Alkema [aut]
Maintainer: Hannah Comiskey <[email protected]>
License: MIT + file LICENSE
Version: 1.1.1
Built: 2024-11-14 06:42:13 UTC
Source: CRAN

Help Index

The Country and area classification according to the United Nations Standaistical Division, Standard country or area codes for statistical use (M49). Adapted for use in FP2030 by the Track20 project. A subset of data from the United Nations country classifications

Description

The Country and area classification according to the United Nations Standaistical Division, Standard country or area codes for statistical use (M49). Adapted for use in FP2030 by the Track20 project. A subset of data from the United Nations country classifications

Usage

Country_and_area_classification

Format

A data frame with 231 rows and 8 columns:

Country or area

Country name

ISO Code

1, 2 & 3 number ISO country codes

Major area

Continent

Region

Sub-continent

Developed region

Binary indicator for development status

Least developed country

Binary indicator for least developed status

Sub-Saharan Africa

Binary indicator for whether country is in Sub-Saharan Africa

FP2020

Binary indicator for FP2020 participation status

Source

https://unstats.un.org/unsd/methodology/m49/

The names of the countries with national and subnational administration level data stored

Description

The names of the countries with national and subnational administration level data stored

Usage

country_names

Format

A data frame with 30 rows and 3 columns:

Country names

Country name

National level data available

Indicator for whether data at the national administration level is available in the package

Subnational level data available

Indicator for whether data at the subnational administration level is available in the package

DEFT_DHS_database A database of the design effects for some of the DHS surveys in the national and subnational datasets. Due to due to multistage and clustering of the DHS sample, the average standard error is increased by a design effect (DEFT) factor over that in an equivalent simple random sample.

Description

DEFT_DHS_database A database of the design effects for some of the DHS surveys in the national and subnational datasets. Due to due to multistage and clustering of the DHS sample, the average standard error is increased by a design effect (DEFT) factor over that in an equivalent simple random sample.

Usage

DEFT_DHS_database

Format

A dataframe of Country names, survey year and design effects for DHS surveys

Source

DHS final reports Appendix B, 'ESTIMATES OF SAMPLING ERRORS'.

Wrapper function that retrieves the DHS data used for modelling the proportion of modern contraceptives supplied by the public and private sectors at the national and subnational administration levels.

Description

Wrapper function that retrieves the DHS data used for modelling the proportion of modern contraceptives supplied by the public and private sectors at the national and subnational administration levels.

Usage

get_data(
  national = TRUE,
  local = FALSE,
  mycountry = NULL,
  fp2030 = TRUE,
  surveydata_filepath = NULL
)

Arguments

national

TRUE/FALSE. Default is TRUE for national administration level data. FALSE retrieves subnational level data.
local

TRUE/FALSE. Default is FALSE for global runs. Decides if this is a single-country or global run.
mycountry

The name of country of interest. Default is NULL. For the names of potential countries, review vigentte.
fp2030

Default is TRUE. Filter raw data to only include the Family Planning 2030 focus countries discussed in the Comiskey et al. paper.
surveydata_filepath

Path to survey data. Default is NULL. Survey data should be a .xlsx with the following format national_FPsource_data.

Value

returns a list containing the DHS data set used for inputs into the model and the arguments that specify the data set up.

Examples

raw_data <- get_data(national=FALSE, local=TRUE, mycountry="Nepal")

Function to pull the complete posterior sample for the national method-supply share estimates. Functionality for the subnational models is still under development.

Description

Function to pull the complete posterior sample for the national method-supply share estimates. Functionality for the subnational models is still under development.

Usage

get_posterior_P_samps(jagsdata, model_output, nposterior)

Arguments

jagsdata

The inputs for the JAGS model
model_output

The output of the mcmsupply::run_jags_model() function.
nposterior

The number of posterior samples you wish to pull.

Value

A dataframe containing the posterior samples of national method-supply share estimates.

Examples

## Not run: 
raw_data <- get_data(national=TRUE, local=TRUE, mycountry="Nepal")
jagsdata <- get_modelinputs(startyear=1990, endyear=2025.5, nsegments=12, raw_data)
mod <- run_jags_model(jagsdata = jagsdata, jagsparams = NULL, n_iter = 5, n_burnin = 1, n_thin = 1)
post_samps <- get_posterior_P_samps(jagsdata = jagsdata, model_output = mod, nposterior=4)

## End(Not run)

Get JAGS model inputs

Description

Get JAGS model inputs

Usage

get_modelinputs(
  startyear = 1990,
  endyear = 2030.5,
  nsegments = 12,
  raw_data,
  varcov_array_filepath = NULL
)

Arguments

startyear

The year you wish to begin your predictions from. Default is 1990.
endyear

The year you wish to finish your predictions. Default is 2030.5.
nsegments

The number of knots you wish to use in your basis functions. Default is 12.
raw_data

The list of arguments and family planning source data from the 'get_data' function.
varcov_array_filepath

Path to calculated variance-covariance array associated with the custom supplied FP source data. Default is NULL. Covariance data should be a .RDS file.

Value

A list of modelling inputs for the JAGS model.

  1. Tstar is the year index for the most recent survey in each province.

  2. Kstar is the knot index that aligns with Tstar.

  3. B.ik are the basis functions.

  4. n_years are total number of years

  5. n_obs are the total number of observations

  6. K are the number of knots.

  7. H is K-1. Used in the calculation of first order differences of spline coefficients.

  8. P_count is the number of subnational provinces/regions.

  9. M_count is the number of modern contraceptive methods.

  10. matchsubnat is the subnational province indexing to match the observed data to the predictions.

  11. matchcountry is the country indexing to match the observed data to the predictions.

  12. matchmethod is the method indexing to match the observed data to the predictions.

  13. matchyears is the year indexing to match the observed data to the predictions.

Examples

raw_data <- get_data(national=FALSE, local=TRUE, mycountry="Nepal")
jagsdata <- get_modelinputs(startyear=1990, endyear=2030.5, nsegments=12, raw_data)

The estimated national-level correlations between the rates of change in methods

Description

The estimated national-level correlations between the rates of change in methods

Usage

national_estimated_correlations_bivarlogitnormal

Format

A array of 2 matrices with 5 rows and 5 columns:

row

Contraceptive method the correlation estimate refers to

column

Contraceptive method the correlation estimate refers to

public_cor

The estimated correlation between the rates of change in methods supplied by the public sector

private_cor

The estimated correlation between the rates of change in methods supplied by the private sector

DHS survey observations for the proportion of modern contraceptives supplied by the public and private sectors at the national level

Description

DHS survey observations for the proportion of modern contraceptives supplied by the public and private sectors at the national level

Usage

national_FPsource_data

Format

national_FPsource_data

A data frame with 562 rows and 15 columns:

Country

Country names

Method

Contraceptive method name

average_year

Average year of the survey

year

Year of the survey

country_code

ISO country codes

Public

Proportion supplied by the Public sector

se.Public

Standard error of proportion supplied by the Public sector

Public_n

Sample size used to calculate proportion supplied by the Public sector

Commercial_medical

Proportion supplied by the private Commercial medical sector

se.Commercial_medical

Standard error of proportion supplied by the private Commercial medical sector

Commercial_medical_n

Sample size used to calculate proportion supplied by the private Commercial medical sector

Other

Proportion supplied by the private Other sector

se.Other

Standard error of proportion supplied by the private Other sector

Other_n

Sample size used to calculate proportion supplied by the private Other sector

check_sum

Check to see if proportions sum to 1

Source

On request from DHS microdata - using the womens individuals recode file. Contact details found at https://dhsprogram.com/data/dataset_admin/login_main.cfm

A checklist for ensuring national-level custom data is appropriate to be used for estimation

Description

A checklist for ensuring national-level custom data is appropriate to be used for estimation

Usage

national_FPsource_format

Format

A list of requirements for custom data to meet before being accepted into the model

Country

Country name variable classification

Method

Method name variable classification

average_year

average_year variable classification

sector_category

sector_category name variable classification

proportion

proportion variable classification

SE.proportion

SE.proportion variable classification

n

n variable classification

An array of variance-covariance matrices corresponding to the DHS survey observations for the proportion of modern contraceptives supplied by the public and private sectors at the national level

Description

An array of variance-covariance matrices corresponding to the DHS survey observations for the proportion of modern contraceptives supplied by the public and private sectors at the national level

Usage

national_FPsource_VARCOV_bivarlogitnormal

Format

national_FPsource_VARCOV_bivarlogitnormal

An array of 2x2 matrices for each of the 558 observations in the national_FPsource_data. Each 2x2 array corresponds to the variance of the public and private sectors on the diagonal and their corresponding covariances on the off-diagonal.

Source

The variance-covariance matrices are calculated using the survey R package: prop_mat <- svyby(~I(sector_categories), ~I(modern_method_source), design=d.s, svymean, covmat=TRUE) vcov_matrix <- vcov(prop_mat) function.

The median estimate for the national-level variance-covariance matrix of the delta.k terms in the multi-country national model.

Description

The median estimate for the national-level variance-covariance matrix of the delta.k terms in the multi-country national model.

Usage

national_inv_sigma_delta_hat_bivarlogitnorm

Format

A array of 2 matrices with 5 rows and 5 columns:

Array 1

Estimated public sector variance-covaraince matrix

Array 2

Estimated private sector variance-covaraince matrix

The median estimates of the precision for the national-level country, sector-, method-specific intercepts in the multi-country national model. This vector is used to inform the precision in the Normal prior of the national-level intercept in single-country national models.

Description

The median estimates of the precision for the national-level country, sector-, method-specific intercepts in the multi-country national model. This vector is used to inform the precision in the Normal prior of the national-level intercept in single-country national models.

Usage

national_tau_alpha_cms_hat_bivarlogitnorm

Format

A vector of two precision estimates

The median estimates of the national-level sub-continental, sector-, method-specific intercepts in the multi-country national model. This array is used to inform the Normal prior of the country-level intercept in the single-country national model.

Description

The median estimates of the national-level sub-continental, sector-, method-specific intercepts in the multi-country national model. This array is used to inform the Normal prior of the country-level intercept in the single-country national model.

Usage

national_theta_rms_hat_bivarlogitnorm

Format

A array of 6 matrices with 2 rows and 5 columns

The order of observations to join the variance-covariance array data and the DHS survey observations for the proportion of modern contraceptives supplied by the public and private sectors at the national level

Description

The order of observations to join the variance-covariance array data and the DHS survey observations for the proportion of modern contraceptives supplied by the public and private sectors at the national level

Usage

national_varcov_order_bivarlogitnormal

Format

national_varcov_order_bivarlogitnormal

A data frame with 558 rows and 3 columns:

Country

Country names

average_year

Average year of the survey

Method

Contraceptive method name

Source

On request from DHS microdata - using the womens individuals recode file. Contact details found at https://dhsprogram.com/data/dataset_admin/login_main.cfm

Wrapper function to plot the JAGS estimates

Description

Wrapper function to plot the JAGS estimates

Usage

plot_estimates(jagsdata, model_output)

Arguments

jagsdata

Output of the mcmsupply::get_modelinputs() function.
model_output

The output of the mcmsupply::run_jags_model() function.

Value

A list of ggplot objects.

Examples

## Not run: 
raw_data <- get_data(national=TRUE, local=TRUE, mycountry="Nepal")
jagsdata <- get_modelinputs(startyear=1990, endyear=2030.5, nsegments=12, raw_data)
mod <- run_jags_model(jagsdata, n_iter=5, n_burnin=1, n_thin=1)
plots <- plot_estimates(jagsdata = jagsdata, model_output = mod)

## End(Not run)

Function to pull method-supply share median estimates and credible intervals for a given year and country.

Description

Function to pull method-supply share median estimates and credible intervals for a given year and country.

Usage

pull_estimates(model_output, year, country)

Arguments

model_output

The output of the mcmsupply::run_jags_model() function.
year

Numeric. The year of model estimated you wish to pull.
country

String. The name of the country you wish to inspect.

Value

A dataframe of model estimates for each method, with the median (50%), 80% and 95% credible intervals.

Examples

## Not run: 
raw_data <- get_data(national=TRUE, local=TRUE, mycountry="Nepal")
jagsdata <- get_modelinputs(startyear=1990, endyear=2025.5, nsegments=12, raw_data)
mod <- run_jags_model(jagsdata = jagsdata, jagsparams = NULL, n_iter = 5, n_burnin = 1, n_thin = 1)
estimates <- pull_estimates(model_output = mod, year=2018, country="Nepal")

## End(Not run)

Wrapper function to run the jags model for estimating the proportion of modern contraceptive methods supplied by the public & private Sectors using a Bayesian hierarchical penalized spline model for the national and subnational administration levels

Description

Wrapper function to run the jags model for estimating the proportion of modern contraceptive methods supplied by the public & private Sectors using a Bayesian hierarchical penalized spline model for the national and subnational administration levels

Usage

run_jags_model(
  jagsdata,
  jagsparams = NULL,
  n_iter = 80000,
  n_burnin = 10000,
  n_thin = 35,
  n_chain = 2,
  n_cores = NULL,
  ...
)

Arguments

jagsdata

The object from the mcmsupply::get_modelinputs() function.
jagsparams

The parameters of the JAGS model you wish to review
n_iter

Default is 80000. Number of itterations to do in JAGS model.
n_burnin

Default is 10000. Number of samples to burn-in in JAGS model.
n_thin

Default is 35. Number of samples to thin by in JAGS model.
n_chain

Default is 2. Number of chains to run in your MCMC sample.
n_cores

The number of cores to use for parallel execution in subnational estimation. If not specified, the number of cores is set to the value of options("cores"), if specified, or to approximately half the number of cores detected by the parallel package.
...

Arguments from the mcmsupply::get_modelinputs() function.

Value

returns the jags model object

Examples

raw_data <- get_data(national=TRUE, local=TRUE, mycountry="Nepal")
jagsdata <- get_modelinputs(startyear=1990, endyear=2025.5, nsegments=12, raw_data)
run_jags_model(jagsdata, n_iter=5, n_burnin=1, n_thin=1)

DHS survey observations for the proportion of modern contraceptives supplied by the public and private sectors at the subnational administration level.

Description

Elizabeth Heger Boyle, Miriam King and Matthew Sobek. IPUMS-Demographic and Health Surveys: Version 9 (dataset). IPUMS and ICF, 2022. https://doi.org/10.18128/D080.V9

Usage

subnat_FPsource_data

Format

subnat_FPsource_data

A data frame with 6940 rows and 8 columns:

Country

Country names

Region

Subnational region names

Method

Contraceptive method name

average_year

Average year of the survey

sector_categories

Name of sector

proportion

Proportion supplied by the sector

SE.proportion

Standard error associated with the proportion

n

Sample size associated with the observation

Source

On request from IPUMS - https://www.idhsdata.org/idhs/index.shtml

A checklist for ensuring subnational-level custom data is appropriate to be used for estimation

Description

A checklist for ensuring subnational-level custom data is appropriate to be used for estimation

Usage

subnat_FPsource_format

Format

A list of requirements for custom data to meet before being accepted into the model

Country

Country name variable classification

Region

Subnational region name variable classification

Method

Method name variable classification

average_year

average_year variable classification

sector_categories

sector_categories name variable classification

proportion

proportion variable classification

SE.proportion

SE.proportion variable classification

n

n variable classification

The median estimates of the subnational-level country, sector-, method-specific intercepts in the multi-country subnational model. This array is used to inform the Normal prior of the subnational-level intercept in the single-country subnational model.

Description

The median estimates of the subnational-level country, sector-, method-specific intercepts in the multi-country subnational model. This array is used to inform the Normal prior of the subnational-level intercept in the single-country subnational model.

Usage

subnational_alpha_cms_hat

Format

A array of 23 matrices with 2 rows and 5 columns

The estimated subnational-level correlations between the rates of change in methods

Description

The estimated subnational-level correlations between the rates of change in methods

Usage

subnational_estimated_correlations

Format

A array of 2 matrices with 5 rows and 5 columns:

row

Contraceptive method the correlation estimate refers to

column

Contraceptive method the correlation estimate refers to

public_cor

The estimated correlation between the rates of change in methods supplied by the public sector

private_cor

The estimated correlation between the rates of change in methods supplied by the private sector

The median estimate for the subnational-level precision matrix of the delta.k terms in the multi-country subnational model. This array is used to inform the multi-variate normal prior in the single-country subnational model.

Description

The median estimate for the subnational-level precision matrix of the delta.k terms in the multi-country subnational model. This array is used to inform the multi-variate normal prior in the single-country subnational model.

Usage

subnational_inv.sigma_delta_hat

Format

A array of 2 matrices with 5 rows and 5 columns:

Array 1

Estimated public sector precision matrix

Array 2

Estimated private sector precision matrix

subnational_tau_alpha_pms_hat The median estimates of the precision for the subnational-level country, sector-, method-specific intercepts in the multi-country subnational model. This vector is used to inform the precision in the Normal prior of the subnational-level intercept in single-country subnational models.

Description

subnational_tau_alpha_pms_hat The median estimates of the precision for the subnational-level country, sector-, method-specific intercepts in the multi-country subnational model. This vector is used to inform the precision in the Normal prior of the subnational-level intercept in single-country subnational models.

Usage

subnational_tau_alpha_pms_hat

Format

A vector of two precision estimates