StMoMo (version 0.4.1)

fit.StMoMo: Fit a Stochastic Mortality Model

Description

Fit a Stochastic Mortality Model to a given data set. The fitting is done using package gnm.

Usage

# S3 method for StMoMo
fit(object, data = NULL, Dxt = NULL, Ext = NULL,
  ages = NULL, years = NULL, ages.fit = NULL, years.fit = NULL,
  oxt = NULL, wxt = NULL, start.ax = NULL, start.bx = NULL,
  start.kt = NULL, start.b0x = NULL, start.gc = NULL, verbose = TRUE,
  ...)

Arguments

object

an object of class "StMoMo" defining the stochastic mortality model.

data

an optional object of type StMoMoData containing information on deaths and exposures to be used for fitting the model. This is typically created with function StMoMoData. If this is not provided then the fitting data is taken from arguments, Dxt, Ext, ages, years.

Dxt

optional matrix of deaths data.

Ext

optional matrix of observed exposures of the same dimension of Dxt.

ages

optional vector of ages corresponding to rows of Dxt and Ext.

years

optional vector of years corresponding to rows of Dxt and Ext.

ages.fit

optional vector of ages to include in the fit. Must be a subset of ages.

years.fit

optional vector of years to include in the fit. Must be a subset of years.

oxt

optional matrix/vector or scalar of known offset to be used in fitting the model. This can be used to specify any a priori known component to be added to the predictor during fitting.

wxt

optional matrix of 0-1 weights to be used in the fitting process. This can be used, for instance, to zero weight some cohorts in the data. See genWeightMat which is a helper function for defining weighting matrices.

start.ax

optional vector with starting values for \(\alpha_x\).

start.bx

optional matrix with starting values for \(\beta_x^{(i)}\).

start.kt

optional matrix with starting values for \(\kappa_t^{(i)}\).

start.b0x

optional vector with starting values for \(\beta_x^{(0)}\).

start.gc

optional vector with starting values for \(\gamma_c\).

verbose

a logical value. If TRUE progress indicators are printed as the model is fitted. Set verbose = FALSE to silent the fitting and avoid progress messages.

...

arguments to be passed to or from other methods. This can be used to control the fitting parameters of gnm. See gnm.

Value

A list with class "fitStMoMo" with components:

model

the object of class "StMoMo" defining the fitted stochastic mortality model.

ax

vector with the fitted values of the static age function \(\alpha_x\). If the model does not have a static age function or failed to fit this is set to NULL.

bx

matrix with the values of the period age-modulating functions \(\beta_x^{(i)}, i=1, ..., N\). If the \(i\)-th age-modulating function is non-parametric (e.g. as in the Lee-Carter model) bx[, i] contains the estimated values. If the model does not have any age-period terms (i.e. \(N=0\)) or failed to fit this is set to NULL.

kt

matrix with the values of the fitted period indexes \(\kappa_t^{(i)}, i=1, ..., N\). kt[i, ] contains the estimated values of the \(i\)-th period index. If the model does not have any age-period terms (i.e. \(N=0\)) or failed to fit this is set to NULL.

b0x

vector with the values of the cohort age-modulating function \(\beta_x^{(0)}\). If the age-modulating function is non-parametric b0x contains the estimated values. If the model does not have a cohort effect or failed to fit this is set to NULL.

gc

vector with the fitted cohort index \(\gamma_{c}\). If the model does not have a cohort effect or failed to fit this is set to NULL.

data

StMoMoData object provided for fitting the model.

Dxt

matrix of deaths used in the fitting.

Ext

matrix of exposures used in the fitting.

oxt

matrix of known offset values used in the fitting.

wxt

matrix of 0-1 weights used in the fitting.

ages

vector of ages used in the fitting.

years

vector of years used in the fitting.

cohorts

vector of cohorts used in the fitting.

fittingModel

output from the call to gnm used to fit the model. If the fitting failed to converge this is set to NULL.

loglik

log-likelihood of the model. If the fitting failed to converge this is set to NULL.

deviance

deviance of the model. If the fitting failed to converge this is set to NULL.

npar

effective number of parameters in the model. If the fitting failed to converge this is set to NULL.

nobs

number of observations in the model fit. If the fitting failed to converge this is set to NULL.

fail

TRUE if a model could not be fitted and FALSE otherwise.

conv

TRUE if the model fitting converged and FALSE if it didn't.

@seealso StMoMoData, genWeightMat, plot.fitStMoMo, EWMaleData

Details

Fitting is done using function gnm within package gnm. This is equivalent to minimising (maximising) the deviance (log-likelihood) of the model. Ages and years in the data should be of type numeric. Data points with zero exposure are assigned a zero weight and are ignored in the fitting process. Similarly, NA are assigned a zero weight and ignored in the fitting process. Parameter estimates can be plotted using function plot.fitStMoMo.

Examples

# NOT RUN {
   

# Lee-Carter model only for older ages
LCfit <- fit(lc(), data = EWMaleData, ages.fit = 55:89)
plot(LCfit)

# Use arguments Dxt, Ext, ages, years to pass fitting data
LCfit <- fit(lc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, 
             ages = EWMaleData$ages, years = EWMaleData$years, 
             ages.fit = 55:89)
plot(LCfit)

# APC model weigthing out the 3 first and last cohorts
wxt <- genWeightMat(EWMaleData$ages,  EWMaleData$years, clip = 3)
APCfit <- fit(apc(), data = EWMaleData, wxt = wxt)
plot(APCfit, parametricbx = FALSE, nCol = 3)

# Set verbose = FALSE for silent fitting
APCfit <- fit(apc(), data = EWMaleData,  wxt = wxt, 
              verbose = FALSE)
# }
# NOT RUN {
  # Poisson Lee-Carter model with the static age function set to  
  # the mean over time of the log-death rates
  constLCfix_ax <- function(ax, bx, kt, b0x, gc, wxt, ages){  
    c1 <- sum(bx, na.rm = TRUE)
    bx <- bx / c1
    kt <- kt * c1  
    list(ax = ax, bx = bx, kt = kt, b0x = b0x, gc = gc)  
  }  
  LCfix_ax <- StMoMo(link = "log", staticAgeFun = FALSE, 
                     periodAgeFun = "NP", constFun =  constLCfix_ax)
  LCfix_axfit <- fit(LCfix_ax, data= EWMaleData, 
                     oxt = rowMeans(log(EWMaleData$Dxt / EWMaleData$Ext)))
  plot(LCfix_axfit)
# }