fit_all_MAPC: Fit all configurations of MAPC models using INLA
In MAPCtools: Multivariate Age-Period-Cohort (MAPC) Modeling for Health Data

fit_all_MAPC

R Documentation

Fit all configurations of MAPC models using INLA

Description

Fits all configurations of shared vs. stratum-specific time effects:

APc: Shared age and period effects, stratum-specific cohort effects.
ApC: Shared age and cohort effects, stratum-specific period effects.
aPC: Shared period and cohort effects, stratum-specific age effects.
Apc: Shared age effects, stratum-specific period and cohort effects.
aPc: Shared period effects, stratum-specific age and cohort effects.
apC: Shared cohort effects, stratum-specific age and period effects.

Uses the fit_MAPC function. The multivariate APC model is based on Riebler and Held (2010) \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1093/biostatistics/kxp037")}. For handling complex survey data, we follow Mercer et al. (2014) \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.spasta.2013.12.001")}, implemented using the survey package.

Usage

fit_all_MAPC(
  data,
  response,
  family,
  stratify_by,
  reference_strata = NULL,
  age = "age",
  period = "period",
  grid.factor = 1,
  all_models = c("apC", "aPc", "Apc", "aPC", "ApC", "APc"),
  extra.fixed = NULL,
  extra.random = NULL,
  extra.models = NULL,
  extra.hyper = NULL,
  apc_prior = "rw1",
  include.random = FALSE,
  binomial.n = NULL,
  poisson.offset = NULL,
  apc_hyperprior = NULL,
  survey.design = NULL,
  control.compute = list(dic = TRUE, waic = TRUE, cpo = TRUE),
  track.progress = FALSE,
  verbose = FALSE
)

Arguments

`data`	A data frame containing the age, period, response, and stratification variables. Age and period are assumed to be on the raw scale, not transformed to 1-indexed index columns. Factor/character columns are handled, as long as they are properly sorted by `sort(unique(data$age/period))` (e.g. values of the form "20-25" for age groups are handled).
`response`	A string naming the response (outcome) variable in `data`.
`family`	A string indicating the likelihood family. The default is `"gaussian"` with identity link.
`stratify_by`	The column in `data` to use for stratification.
`reference_strata`	Level of `stratify_by` to set as the reference level.
`age`	The age column in `data`.
`period`	The period column in `data`.
`grid.factor`	(Optional) Grid factor, defined as the ratio of age interval width to period interval width; defaults to 1.
`all_models`	(Optional) Character vectors of valid APC-formats (e.g. `c("ApC", "apC", "APc"))`, specifying the MAPC models to be estimated. Requirements for a valid APC-format (lowercase letter means stratum-specific, uppercase means shared): - Only one time effect: shared/stratum-specific both fine. - Two time effects: shared/stratum-specific both fine. - Three time effects: either one or two must be stratum-specific. Defaults to `c("apC", "aPc", "Apc", "aPC", "ApC", "APc")`.
`extra.fixed`	(Optional) If desired, the user can specify additional fixed effects to be added. This is passed as a character argument, specifying the name of the variable to be added. Multiple variables can be added by passing a character vector of names. Defaults to `NULL`.
`extra.random`	(Optional) If desired, the user can specify additional random effects to be added. This is passed as a character argument, specifying the name of the variable to be added. Multiple variables can be added by passing a character vector of names. Defaults to `NULL`.
`extra.models`	(Optional) If the user specifies one or more additional random effects to be added in `extra.random`, this argument can be used to specify the model to be used for the additional random effects. Either passed as a single string, in which case all extra random effects are assigned the same model, or a character vector matching the length of `extra.ranom`, mapping unique models to each variable in `extra.random`. If `NULL` and `extra.random` is non-empty, all extra random effects are assigned the "`iid`" model in `inla()`. Defaults to `NULL`.
`extra.hyper`	(Optional) If the user specifies one or more additional random effects to be added in `extra.random`, this argument can be used to specify the priors of the hyperparameters of the models used for the random effects. The hyperpriors are specified as strings that can be passed directly to the `hyper=...` argument in the formula passed to the `inla()`-function. See the argument `apc_prior` below for a concrete example. Defaults to `NULL`, in which case the default `INLA` priors are used.
`apc_prior`	(Optional) A string specifying the prior for the age, period, and cohort effects (e.g. `"rw1"`, `"rw2"`). Defaults to `"rw1"`.
`include.random`	(Optional) Logical; if `TRUE`, include an overall random effect in the APC model. Defaults to `FALSE`.
`binomial.n`	(Optional) For the `family=binomial` likelihood. Either an integer giving the number of trials for the binomial response, or the name of the column containing the number of trials for each observation.
`poisson.offset`	(Optional) For the `family=poisson` likelihood. Either an integer giving the denominator for the Poisson count response, or the name of the column containing the denominator for each observation.
`apc_hyperprior`	(Optional) If the user wants non-default hyperpriors for the time effects, this can be achieved by passing the entire prior specification as a string. If e.g. `hyper = list(theta = list(prior="pc.prec", param=c(0.5,0.01)))` is desired, pass the string "`list(theta = list(prior="pc.prec", param=c(0.5,0.01)))`" to this argument.
`survey.design`	(Optional) In the case of complex survey data, explicit handling of unequal sampling probabilities can be required. The user can pass a `survey.design` object created with the `svydesign` function from the survey package. In this case, a Gaussian model is fit for the survey adjusted estimates, based on the asymptotic normality of Hájek estimator. The argument `family` should still indicate the underlying distribution of the response, and based on this, an appropriate transformation is applied to the adjusted mean estimates.
`control.compute`	(Optional) A list of control variables passed to the `inla()`-function, that specifies what to be computed during model fitting. See options for `control.compute` in the `INLA` docs. Defaults to `list(dic=TRUE, waic=TRUE, cpo=TRUE)`. If posterior sampling is desired, `config=TRUE` must be passed as a control option inside `control.compute`.
`track.progress`	(Optional) Whether to report progress of the estimation of models in the console; defaults to `FALSE`.
`verbose`	(Optional) This is argument is passed along to the `inla()` function that estimates the MAPC model. If `verbose=TRUE`, the `inla`-program runs in verbose mode, which can provide more informative error messages.

Details

The returned object is of class all_mapc, which is a container for multiple mapc model fits (each typically fitted with a different APC formats). It also contains a model_selection element, which holds plots summarizing comparative fit metrics (DIC, WAIC and log-scores).

The following S3 methods are available:

print(): Prints a compact summary for each individual model fit.
summary(): Calls summary() on each contained mapc object, providing detailed posterior summaries.
plot(): Displays model comparison plots (DIC/WAIC/log-score comparisons).

These methods are intended to streamline multi-model workflows and allow quick comparison of results across model specifications.

Value

A named list of mapc objects, one for each configuration of shared vs. stratum-specific time effects: APc, ApC, aPC, Apc, aPc, apC.

References

Rue, H., Martino, S., & Chopin, N. (2009). Approximate Bayesian inference for latent Gaussian models by using Integrated Nested Laplace Approximations. Journal of the Royal Statistical Society: Series B (Statistical Methodology), 71(2), 319-392. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1111/j.1467-9868.2008.00700.x")} See also https://www.r-inla.org for more information about the INLA method and software.

Examples


data("toy_data")
fits <- fit_all_MAPC(
  data               = toy_data,
  response           = count,
  family             = "poisson",
  stratify_by        = education,
  reference_strata   = 1,
  age                = age,
  period             = period,
  apc_prior          = "rw2",
  include.random     = TRUE
)

# Print concise summary of the models and estimation procedure
print(fits)

# Plot comparison plots, based on comparative fit metrics
plot(fits)

# Optional: view full summary of all models (can be long)
# summary(fits)

MAPCtools documentation built on June 25, 2025, 5:09 p.m.