popReconstruct_fit: Implement the Bayesian hierarchical PopReconstruct model

In ihmeuw-demographics/popMethods: Methods for Population Estimation

Description

The popReconstruct model embeds the cohort component method of population projection (ccmpp) in a Bayesian hierarchical model. It reconciles ccmpp input preliminary estimates of sex-ratio at birth, fertility, mortality, migration, and a baseline population with population data while accounting for measurement error in these initial estimates.

popReconstruct_fit() fits the model using Stan or TMB.

popReconstruct_posterior_draws() produces draws from the posterior distribution.

popReconstruct_prior_draws() produces draws from the prior distribution.

popReconstruct_count_space_parameters() uses draws from the popReconstruct model to derive count space parameters. For most of the parameters this is calculated as count = rate * population. Maternal age-specific live births are also split into child sex-specific live births using the sex ratio at birth. male_proportion = srb / (srb + 1) & female_proportion = 1 / (srb + 1).

popReconstruct_summarize_draws() produces summary statistics of draws from the popReconstruct model using demUtils::summarize_dt(). The summarize_cols parameter should include 'chain', 'chain_draw' and 'draw' when the model was fit with stan and just 'draw' when the model was fit with tmb.

Usage

popReconstruct_fit(
  inputs,
  data,
  hyperparameters,
  settings,
  value_col,
  software,
  ...
)

popReconstruct_posterior_draws(
  fit,
  inputs,
  settings,
  value_col,
  software,
  method_name
)

popReconstruct_count_space_parameters(
  draws,
  settings,
  parameters = c("live_births", "deaths", "net_migrants"),
  value_col = "value",
  quiet = FALSE
)

popReconstruct_prior_draws(
  inputs,
  hyperparameters,
  settings,
  value_col,
  method_name,
  chunk_size = 100
)

popReconstruct_summarize_draws(
  draws,
  summarize_cols = c("chain", "chain_draw", "draw"),
  value_col = "value",
  ...
)

Arguments

inputs	[list()] [data.table()] for each ccmpp input. Requires 'srb', 'asfr', 'baseline'; mortality estimates provided as just 'survival' or two of 'mx', 'ax', and 'qx'; and migration estimates provided as just 'net_migration' or both 'immigration' and 'emigration'. See Section: Inputs for more information on each of the required inputs.
data	[list()] [data.table()] for each type of data input for the model (currently only 'population'). See Section: Data for more information.
hyperparameters	[list()] List for each model component ('srb', 'asfr', ...) that itself contains a list specifying the alpha (shape) and beta (scale) hyperparameters for the variance of each model component.
settings	[list()] Named list of settings for running the popReconstruct model with. The required settings are the same as those required for demCore::ccmpp(), see Section: Settings for these. The optional settings specific to popReconstruct are described in Section: Optional popReconstruct Settings
value_col	[character(1)] Name of the column containing the value of interest in each of the inputs. Default is 'value'.
software	[character()] Statistical modeling software to fit popReconstruct with. Either 'stan' or 'tmb' are available.
...	For popReconstruct_fit() additional arguments to pass to rstan::sampling() if fitting the model with 'stan' or optimx::optimx() if fitting the model with 'tmb'. For popReconstruct_summarize_draws() additional arguments to pass to demUtils::summarize_dt().
fit	[stanfit(1)] or [sdreport(1)] Model fit object returned by popReconstruct_fit().
method_name	[character(1)] Description to assign to column 'method' in each returned data.table.
draws	[list()] of [data.table()] Draws from the posterior distribution of the popReconstruct model as returned by popReconstruct_posterior_draws().
parameters	[character()] Count space parameters to derive. Can be a combination of 'live_births', 'deaths', 'net_migrants', 'immigrants', 'emigrants'. Default is 'live_births', 'deaths', & 'net_migrants'.
quiet	[logical(1)] Should progress messages be suppressed as the function is run? Default is False.
chunk_size	[integer(1)] number of draws to sample from the prior at once.
summarize_cols	[character()] The id_cols that should be collapsed and to calculate summary statistics over.

Optional popReconstruct Settings

• fixed_parameters: [character()]
  Names of demCore::ccmpp() input components that should be fixed in the model, corresponds to the names of the input list. Defaults to empty if fitting the model for both sexes, if only 'female' then defaults to 'srb'.

• n_draws: [character()]
  The number of draws to take from the output posterior distribution. If fitting the model with stan then the number of draws is dictated by chains, iterations, burn-in, thin arguments to rstan::sampling; n_draws can then be used to subsample down.

• k_years_input_name: [integer()]
  The start of each calendar year interval that will be knots in the B-spline linear basis functions for the year-specific input estimates, so not relevant for 'baseline'. Defaults to the setting for 'years' which is equal to the original popReconstruct model without linear B-splines to reduce year-specific parameters.

• k_ages_input_name: [integer()]
  The start of each age-group interval that will be knots in the B-spline linear basis functions for the age-specific input estimates, so not relevant for 'srb'. Defaults to the setting for 'ages' (or 'ages_input_name') which is equal to the original popReconstruct model without linear B-splines to reduce age-specific parameters.

Data

population: [data.table()]

• year: [integer()] year of population data.

• sex: [character()] either 'female', 'male', or 'both'. If 'sexes' setting is 'female' can only have 'female' input data.

• age_start: [integer()] start of the age group (inclusive). Corresponds to 'ages' setting. Age groups included must not overlap.

• age_end: [integer()] end of the age group (exclusive).

• value_col: [numeric()] population count, must be greater than zero.

popReconstruct_fit Value

If fit using 'stan' an object of class stanfit and if fit using 'tmb' an object of class sdreport. Either represents the fitted results that can be extracted using popReconstruct_posterior_draws(). Stan has helper packages that can be used to explore the model fit through shinystan, bayesplot, etc.

popReconstruct_posterior_draws and popReconstruct_prior_draws Value

popReconstruct_posterior_draws() and popReconstruct_prior_draws() return a named [list()] of [data.table()] for draws from the posterior and prior distribution respectively for each ccmpp input component along with the associated offset and spline offset parameters. Draws for the 'variance' and projected 'population' are also included.

The returned [data.table()]s will include columns related to the draw number:

• draw: the draw index.

• chain: if using stan to fit the model, the chain the draw came from.

• chain_draw: if using stan to fit the model, the draw index for that chain.

population: [data.table()]

• year: [integer()] mid-year for population estimate. Corresponds to 'years' setting plus an extra interval.

• sex: [character()] either 'female' or 'male'. Corresponds to 'sexes' setting.

• age_start: [integer()] start of the age group (inclusive). Corresponds to 'ages' setting.

• age_end: [integer()] end of the age group (exclusive).

• draw: [integer()] draw index.

• value_col: [numeric()] projected population count estimates.

variance: [data.table()]

• parameter: [character()] the ccmpp component the variance term corresponds to.

• draw: [integer()] draw index.

• value_col: [numeric()] estimated variance value..

For each ccmpp component ('srb', 'asfr', etc.) there will be three [data.table()] outputs included in the returned [list()]. These will each have the same columns as described in the Section: Inputs but with additional draw related columns as described above.

1. The offset parameters representing the values of the piecewise linear function at the year- and age-specific knots. These are the estimated deviations from the initial ccmpp input estimates at the exact knots. The estimated values are in the transformed modeling space (log transformed for 'srb', logit transformed for 'survival', etc.).

2. The spline offset values calculated by multiplying the fixed B-spline linear basis functions by the offset parameters. These are the estimated deviations from the initial ccmpp input estimates at all years and ages. The estimated values are in the transformed modeling space.

3. The actual ccmpp input posterior draws after combining the spline offset values with the initial ccmpp input estimates and after applying the inverse of the transformation used to model each component.

popReconstruct_count_space_parameters Value

Returns the same named [list()] of [data.table()] returned by popReconstruct_posterior_draws() or popReconstruct_prior_draws() with additional list elements for each of the specified count space parameters requested.

popReconstruct_summarize_draws Value

Returns a named [list()] of [data.table()] for summary statistics of the input draws. Each data.table() will have the id_cols for each component (minus the summarize_cols) plus summary statistic columns. The summary statistic columns have the same name as each function specified in summary_fun and the quantiles are named like 'q_(probs * 100)'. See [demUtils::summarize_dt()] for more information.

Settings

• years: [numeric()]
  The start of each calendar year interval to project in ccmpp(). Corresponds to the 'year_start' column in each of the year-specific inputs.

• sexes: [character()]
  The sexes being projected in ccmpp(), must be either just 'female', or 'female' and 'male'. Corresponds to the 'sex' column in each of the sex-specific inputs.

• ages: [numeric()]
  The ages being projected in ccmpp(). Corresponds to the 'age_start' column in each of the standard age-specific inputs.

• ages_mortality: [numeric()]
  The ages for which mortality parameter estimates are available, includes one extra age group compared to the 'ages' setting. Corresponds to the 'age_start' column in the mortality [data.table()] input(s).

• ages_asfr: [numeric()]
  The assumed female reproductive ages, subset of 'ages'. Corresponds to the 'age_start' column in the age-specific fertility rate (asfr) [data.table()] input.

Inputs

srb: [data.table()]

• year_start: [integer()] start of the calendar year interval (inclusive). Corresponds to 'years' setting.

• year_end: [integer()] end of the calendar year interval (exclusive).

• value_col: [numeric()] sex-ratio at birth estimates, must be greater than zero.

asfr: [data.table()]

• year_start: [integer()] start of the calendar year interval (inclusive). Corresponds to 'years' setting.

• year_end: [integer()] end of the calendar year interval (exclusive).

• age_start: [integer()] start of the age group (inclusive). Corresponds to 'ages_asfr' setting.

• age_end: [integer()] end of the age group (exclusive).

• value_col: [numeric()] annual age-specific fertility rate estimates, must be greater than zero.

baseline: [data.table()]

• year: [integer()] mid-year for population estimate. Corresponds to 'years' setting.

• sex: [character()] either 'female' or 'male'. Corresponds to 'sexes' setting.

• age_start: [integer()] start of the age group (inclusive). Corresponds to 'ages' setting.

• age_end: [integer()] end of the age group (exclusive).

• value_col: [numeric()] baseline year population count estimates, must be greater than zero.

survival: [data.table()]

• year_start: [integer()] start of the calendar year interval (inclusive). Corresponds to 'years' setting.

• year_end: [integer()] end of the calendar year interval (exclusive).

• sex: [character()] either 'female' or 'male'. Corresponds to 'sexes' setting.

• age_start: [integer()] start of the age group (inclusive). Corresponds to 'ages' setting.

• age_end: [integer()] end of the age group (exclusive).

• value_col: [numeric()] survivorship ratio estimates, must be greater than zero and less than one.

mx: [data.table()]

• year_start: [integer()] start of the calendar year interval (inclusive). Corresponds to 'years' setting.

• year_end: [integer()] end of the calendar year interval (exclusive).

• sex: [character()] either 'female' or 'male'. Corresponds to 'sexes' setting.

• age_start: [integer()] start of the age group (inclusive). Corresponds to 'ages' setting.

• age_end: [integer()] end of the age group (exclusive).

• value_col: [numeric()] mortality rate estimates, must be greater than zero.

ax: [data.table()]

• year_start: [integer()] start of the calendar year interval (inclusive). Corresponds to 'years' setting.

• year_end: [integer()] end of the calendar year interval (exclusive).

• sex: [character()] either 'female' or 'male'. Corresponds to 'sexes' setting.

• age_start: [integer()] start of the age group (inclusive). Corresponds to 'ages' setting.

• age_end: [integer()] end of the age group (exclusive).

• value_col: [numeric()] average years lived by those dying in the interval estimates, must be greater than zero and less than the age interval length.

qx: [data.table()]

• year_start: [integer()] start of the calendar year interval (inclusive). Corresponds to 'years' setting.

• year_end: [integer()] end of the calendar year interval (exclusive).

• sex: [character()] either 'female' or 'male'. Corresponds to 'sexes' setting.

• age_start: [integer()] start of the age group (inclusive). Corresponds to 'ages' setting.

• age_end: [integer()] end of the age group (exclusive).

• value_col: [numeric()] probability of death estimates, must be greater than zero and less than one.

net_migration: [data.table()]

• year_start: [integer()] start of the calendar year interval (inclusive). Corresponds to 'years' setting.

• year_end: [integer()] end of the calendar year interval (exclusive).

• sex: [character()] either 'female' or 'male'. Corresponds to 'sexes' setting.

• age_start: [integer()] start of the age group (inclusive). Corresponds to 'ages' setting.

• age_end: [integer()] end of the age group (exclusive).

• value_col: [numeric()] annual net-migration proportion estimates.

immigration: [data.table()]

• year_start: [integer()] start of the calendar year interval (inclusive). Corresponds to 'years' setting.

• year_end: [integer()] end of the calendar year interval (exclusive).

• sex: [character()] either 'female' or 'male'. Corresponds to 'sexes' setting.

• age_start: [integer()] start of the age group (inclusive). Corresponds to 'ages' setting.

• age_end: [integer()] end of the age group (exclusive).

• value_col: [numeric()] annual immigration proportion estimates, must be greater than zero.

emigration: [data.table()]

• year_start: [integer()] start of the calendar year interval (inclusive). Corresponds to 'years' setting.

• year_end: [integer()] end of the calendar year interval (exclusive).

• sex: [character()] either 'female' or 'male'. Corresponds to 'sexes' setting.

• age_start: [integer()] start of the age group (inclusive). Corresponds to 'ages' setting.

• age_end: [integer()] end of the age group (exclusive).

• value_col: [numeric()] annual emigration proportion estimates, must be greater than zero.

References

Wheldon, Mark C., Adrian E. Raftery, Samuel J. Clark, and Patrick Gerland. 2013. “Reconstructing Past Populations With Uncertainty From Fragmentary Data.” Journal of the American Statistical Association 108 (501): 96–110. https://doi.org/10.1080/01621459.2012.737729.

popReconstruct R Package

Wheldon, Mark C., Adrian E. Raftery, Samuel J. Clark, and Patrick Gerland. 2015. “Bayesian Reconstruction of Two-Sex Populations by Age: Estimating Sex Ratios at Birth and Sex Ratios of Mortality.” Journal of the Royal Statistical Society. Series A: Statistics in Society 178 (4): 977–1007. https://doi.org/10.1111/rssa.12104.

markalava/Bayesian-Reconstruction github repo

See Also

demCore::ccmpp()

demUtils::summarize_dt()

rbindlist_dts()

vignette("popReconstruct")

vignette("popReconstruct_options")

Other popReconstruct: popReconstruct_hyperparameters(), rbindlist_dts()

Examples

# specify settings for this example
settings = list(
  years = seq(1960, 2000, 5),
  sexes = c("female"),
  ages = seq(0, 80, 5),
  ages_mortality = seq(0, 85, 5),
  ages_asfr = seq(15, 45, 5),

  n_draws = 10
)

# hyperparameters for the variance prior distribution, represents measurement error
hyperparameters <- list(asfr = list(alpha = 1, beta = 0.0109),
                        population = list(alpha = 1, beta = 0.0109),
                        survival = list(alpha = 1, beta = 0.0109),
                        net_migration = list(alpha = 1, beta = 0.0436))

fit_stan <- popMethods::popReconstruct_fit(
  inputs = demCore::burkina_faso_initial_estimates,
  data = demCore::burkina_faso_data,
  hyperparameters = hyperparameters,
  settings = settings,
  value_col = "value",
  software = "stan",
  chains = 1,
  iter = 200,
  warmup = 100,
  thin = 2
)

draws_stan <- popMethods::popReconstruct_posterior_draws(
  fit = fit_stan,
  inputs = demCore::burkina_faso_initial_estimates,
  settings = settings,
  value_col = "value",
  software = "stan",
  method_name = "original"
)

draws_stan <- popMethods::popReconstruct_count_space_parameters(
  draws = draws_stan,
  settings = settings,
  parameters = c("live_births", "net_migrants"),
  value_col = "value",
)

summary_stan <- popMethods::popReconstruct_summarize_draws(
  draws = draws_stan
)

ihmeuw-demographics/popMethods documentation built on Jan. 29, 2021, 12:39 p.m.