fit_u5mr: Fit U5MR model in TMB

In taylorokonek/stbench: Fully Bayesian Benchmarking for spatio-temporal models

Fit U5MR model in TMB

Description

Fit U5MR model in TMB. Optionally include age-specific intercepts, IID random effects in time, BYM2 spatial random effects, area-specific random slopes in time, RWs in time for each age group, and Type IV Knorr-Held interactions. Can fit benchmarked models, unbenchmarked models, or both. Simultaneous benchmarking is performed via a second likelihood for national level estimates at each time point. Produces posterior samples for fitted values, hyperparameters, random effects, and fixed effects. All models use either a lono-binomial likelihood, described in Dong and Wakefield (2021) or a betabinomial likelihood at the cluster level.

Usage

fit_u5mr(
  binom_df,
  terms = c("intercepts", "iid_time", "bym2_space", "area_slopes", "rw2s_time",
    "typeiv"),
  cluster = "cluster",
  y = "y",
  Ntrials = "N",
  region = "admin1",
  time = NULL,
  survey = NULL,
  years_predict = NULL,
  age = "age_id",
  age_n = c(1, 11, 12, 12, 12, 12),
  age_group = "age_group_id",
  hiv_adj = NA,
  natl = NULL,
  natl_sd = NULL,
  pop_weights = NULL,
  Q_struct_space = NULL,
  nsamp = 1000,
  benched = "unbenched",
  family = "binomial"
)

Arguments

binom_df	a dataframe containing binomial counts, and the following columns: cluster: cluster ID y: deaths Ntrials: total number of person-months in this age, cluster, and region region: area time: year survey: survey id. Only needs to be in binom_df if you want a survey random effect in your model age: id for each age group (must be numeric) you want intercepts for age_group: id for each age group you want RW2s for age_n: the number of months in each age
terms	a character vector containing the names of terms to include in the linear predictor. Options include: "intercepts": age-specific intercepts. If this is not included in terms, a model will be fit with a global intercept. A model with no intercepts is not currently implemented. "iid_time": an iid random effect in time "bym2_space": a BYM2 random effect in space. This is the only option for a spatial random effect at this time. "area_slopes": area-specific random slopes in time "rw2s_time": rw2s in time for each age group specified in age_group "rw1s_time": To Do "typei": To Do. A Type I Knorr-Held space-time interaction, with RW1 in time "typeii": To Do. A Type II Knorr-Held space-time interaction, with RW1 in time "typeiii": To Do. A Type III Knorr-Held space-time interaction, with RW1 in time "typeiv": A Type IV Knorr-Held space-time interaction, with RW1 in time Current default is terms = c("intercepts", "iid_time", "bym2_space", "area_slopes", "rw2s_time", "typeiv").
cluster	the column in binom_df corresponding to cluster id
y	the column in binom_df corresponding to deaths
Ntrials	the column in binom_df corresponding to total number of person-months
region	the column in binom_df corresponding to region/area. Must be numeric and start from 1.
time	the column in binom_df corresponding to year. Must be numeric and start from 1.
survey	the column in binom_df corresponding to survey id. Must be numeric and start from 1.
years_predict	a numeric sequence containing the years in which we want to make predictions. Must start at 1, and the max year must be greater than or equal to the maximum value in time. Defaults to 1 through the maximum value in time.
age	the column in binom_df corresponding to age id, used for age-specific intercepts. Must be numeric and start from 1.
age_n	the number of months in each age group specified by the age column in binom_df. The length of age_n must be equal to the number of unique age groups specified in age.
age_group	the column in binom_df corresponding to age group id, used for age-group-specific RWs in time. Must be numeric and start from 1.
hiv_adj	An optional log offset in time to include in the linear predictor. Defaults to no log offset. If included, the length of hiv_adj must be equal to the number of unique time points specified in years_predict times the number of surveys present in your dataset, in order arrange(survey, time).
natl	a vector of national level estimates, arranged in order of time
natl_sd	a vector of standard deviations for national level estimates, arranged in order of time
pop_weights	a vector of population weights for use in the benchmarking constraint. Must sum to one at each time point, and be in order arrange(region, time)
Q_struct_space	An ICAR precision matrix. Should be unscaled, as scaling will happen internally.
nsamp	Number of posterior samples to take from joint posterior. Defaults to 1000
benched	A string, either "benched", "unbenched", or "both", determining whether to fit a benchmarked model, and unbenchmarked model, or both. Defaults to "unbenched".
family	A string, either "binomial" or "betabinomial", specifying which likelihood to use for the clustered observations. If "binomial" is specified, does the lono-binomial correction, as described in Dong and Wakefield (2021). Defaults to "binomial".

Value

A list containing:

• fitted_mat: a matrix of posterior samples of fitted values in order arrange(region, time)

• re_list: a list contaning matrices of posterior samples for each random effect term

• param_list: a list containing matrices of posterior samples for fixed effects and hyperparameters

• runtime: the time it took to fit the model in TMB and get samples from the joint posterior

If benched = "both", a list of two will be returned containing the above list for both benchmarked and unbenchmarked models.

Author(s)

Taylor Okonek

taylorokonek/stbench documentation built on Jan. 7, 2025, 11:13 p.m.