StMoMo (version 0.4.1)

fit.rh: Fit a Renshaw and Haberman (Lee-Carter with cohorts) mortality model

Description

Fit a Renshaw and Haberman (Lee-Carter with cohorts) mortality model using the iterative Newton-Raphson procedure presented in Algorithm 1 of Hunt and Villegas (2015). This approach helps solve the well-known robustness and converges issues of the Lee-Carter model with cohort-effects.

Usage

# S3 method for rh
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,
  tolerance = 1e-04, iterMax = 10000, ...)

Arguments

object

an object of class "rh" created with function rh.

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.

tolerance

a positive numeric value specifying the tolerance level for convergence.

iterMax

a positive integer specifying the maximum number of iterations to perform.

...

arguments to be passed to or from other methods.

Value

model

the object of class "rh" 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 iterative fitting algorithm.

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.

References

Hunt, A., & Villegas, A. M. (2015). Robustness and convergence in the Lee-Carter model with cohorts. Insurance: Mathematics and Economics, 64, 186-202.

Examples

# NOT RUN {
LCfit <-  fit(lc(), data = EWMaleData, ages.fit = 55:89)
wxt <- genWeightMat(55:89,  EWMaleData$years, clip = 3)
RHfit <- fit(rh(), data = EWMaleData, ages.fit = 55:89, 
             wxt = wxt, start.ax = LCfit$ax,
             start.bx = LCfit$bx, start.kt = LCfit$kt)
plot(RHfit)
 
#Impose approximate constraint as in Hunt and Villegas (2015)    
# }
# NOT RUN {
RHapprox <- rh(approxConst = TRUE)
RHapproxfit <- fit(RHapprox, data = EWMaleData, ages.fit = 55:89, 
                    wxt = wxt)
plot(RHapproxfit) 
# }
# NOT RUN {
# }