runBayesMoFo: A function to fit mortality models.

In BayesMoFo: Bayesian Mortality Forecasting

A function to fit mortality models.

Description

Carry out Bayesian estimation a selection of stochastic mortality models considered in the paper.
DIC (Spiegelhalter et al., 2002) is used to perform model selection in determining the best/worst model for the specified (stratified) mortality data.

Usage

runBayesMoFo(
  death,
  expo,
  models = NULL,
  family = "nb",
  forecast = FALSE,
  h = 5,
  n_iter = 1000,
  n.chain = 1,
  n.adapt = 1000,
  thin = 1,
  quiet = FALSE
)

Arguments

death	death data that has been formatted through the function preparedata_fn.
expo	expo data that has been formatted through the function preparedata_fn.
models	a vector of strings specifying the models to run. If not specified, a standard set of models is run. If we set models="all", all the possible models considered will be run.
family	a string of characters that defines the family function associated with the mortality model. "poisson" would assume that deaths follow a Poisson distribution and use a log family; "binomial" would assume that deaths follow a Binomial distribution and a logit family; "nb" (default) would assume that deaths follow a Negative-Binomial distribution and a log family.
forecast	a logical value indicating if forecast is to be performed (default is FALSE). See below for details.
h	a numeric value giving the number of years to forecast. Default is h=5.
n_iter	number of iterations to run. Default is n_iter=1000.
n.chain	number of parallel chains for the model. Default is n.chain=1.
n.adapt	the number of iterations for adaptation. See ?rjags::adapt for details.
thin	thinning interval for monitoring purposes.
quiet	if TRUE then messages generated during compilation will be suppressed, as well as the progress bar during adaptation.

Details

The standard set of models used (25 in total) is as follows:
M1A, M1M, M1U, M2A1, M2A2, M2Y1, M2Y2,
MLiLee, MLiLee_sharealpha,
CBD_M1,
CBD_M2, CBD_M2_sharegamma,
CBD_M3, CBD_M3_sharegamma,
CBD_M5,
CBD_M6, CBD_M6_sharegamma,
CBD_M7, CBD_M7_sharegamma,
CBD_M8, CBD_M8_sharegamma,
APCI, APCI_sharegamma,
PLAT, PLAT_sharegamma.

The full list of mortality models fitted (44 in total) is as follows:
M1A, M1M, M1U, M2A1, M2A2, M2Y1, M2Y2,
MLiLee, MLiLee_sharealpha,
CBD_M1, CBD_M1_sharealpha, CBD_M1_sharebeta, CBD_M1_shareall,
CBD_M2, CBD_M2_sharealpha, CBD_M2_sharebeta, CBD_M2_sharegamma, CBD_M2_sharealpha_sharebeta, CBD_M2_sharealpha_sharegamma, CBD_M2_sharebeta_sharegamma, CBD_M2_shareall,
CBD_M3, CBD_M3_sharealpha, CBD_M3_sharegamma, CBD_M3_shareall,
CBD_M5,
CBD_M6, CBD_M6_sharegamma,
CBD_M7, CBD_M7_sharegamma,
CBD_M8, CBD_M8_sharegamma,
APCI, APCI_sharealpha, APCI_sharebeta, APCI_sharegamma, APCI_sharealpha_sharebeta, APCI_sharealpha_sharegamma, APCI_sharebeta_sharegamma, APCI_shareall,
PLAT, PLAT_sharealpha, PLAT_sharegamma, PLAT_shareall.

Value

A list with components:

result

A list containing 2 lists, respectively called "best" ($result$best) and "worst" ($result$best). Both return the similar output as fit_result, with the former giving those of the best model while the latter giving those of the worst model.

DIC

A table containing the numeric values of the DIC of all mortality models fitted.

best_model

A character string indicating the best model (lowest DIC).

worst_model

A character string indicating the worst model (highest DIC). If only one model was specified, then this is the same as best_model.

BayesMoFo_obj

A logical value indicating whether the result has been generated using the functionrunBayesMoFo (default=TRUE).

References

Spiegelhalter, David J., Best, Nicola G., Carlin, Bradley P., and van der Linde, Angelika. (2002). "Bayesian measures of model complexity and fit (with discussion)". Journal of the Royal Statistical Society, Series B. 64 (4): 583–639.\Sexpr[results=rd]{tools:::Rd_expr_doi("https://doi.org/10.1111/1467-9868.00353")}

Examples

#load and prepare mortality data
data("dxt_array_product");data("Ext_array_product")
death<-preparedata_fn(dxt_array_product,strat_name = c("ACI","DB","SCI"),ages=35:65)
expo<-preparedata_fn(Ext_array_product,strat_name = c("ACI","DB","SCI"),ages=35:65)

##automatically find the best model from a standard set
runBayesMoFo_result<-runBayesMoFo(death=death,expo=expo,n_iter=50,n.adapt=50)
head(runBayesMoFo_result$result$best)
runBayesMoFo_result$DIC
runBayesMoFo_result$best_model

##if fit all the models
runBayesMoFo_result<-runBayesMoFo(death=death,expo=expo,models="all",
  n_iter=50,n.adapt=50)

# fit a subset of the models and forecast for 10 years 
runBayesMoFo_result<-runBayesMoFo(death=death,expo=expo,models=c("APCI","LC","PLAT"),
  n_iter=1000,n.adapt=1000,n.chain=2,forecast=TRUE,h=10)

##plot the best model
plot_rates_fn(runBayesMoFo_result)
plot_rates_fn(runBayesMoFo_result,plot_type="time",plot_ages=c(40,50,60))
plot_param_fn(runBayesMoFo_result)

##convergence diagnostics plots

#trace and density plots of death rates
converge_diag_rates_fn(runBayesMoFo_result)

#trace and density plots of parameters
converge_diag_param_fn(runBayesMoFo_result)

#ACF plots of death rates
converge_diag_rates_fn(runBayesMoFo_result, trace = FALSE, density = FALSE, acf_plot = TRUE)

#ACF plots of parameters
converge_diag_param_fn(runBayesMoFo_result, trace = FALSE, density = FALSE, acf_plot = TRUE)

#Some MCMC diagnostics (Gelman, Geweke, Heidel diagnostics etc.)
converge_diag_fn(runBayesMoFo_result)

BayesMoFo documentation built on Aug. 11, 2025, 1:07 a.m.