fit.StMoMo: Fit a Stochastic Mortality Model

Description Usage Arguments Details Value Examples

View source: R/fitStMoMo.R

Description

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

Usage

1
2
3
4
5
6
## S3 method for class '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 α_x.

start.bx

optional matrix with starting values for β_x^{(i)}.

start.kt

optional matrix with starting values for κ_t^{(i)}.

start.b0x

optional vector with starting values for β_x^{(0)}.

start.gc

optional vector with starting values for γ_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.

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.

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 α_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 β_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 κ_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 β_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 γ_{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

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
   

# 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)

## End(Not run)

Example output

Loading required package: gnm
Loading required package: forecast
Registered S3 method overwritten by 'quantmod':
  method            from
  as.zoo.data.frame zoo 
StMoMo: Start fitting with gnm
Initialising
Running start-up iterations..
Running main iterations.....
Done
StMoMo: Finish fitting with gnm
StMoMo: Start fitting with gnm
Initialising
Running start-up iterations..
Running main iterations.....
Done
StMoMo: Finish fitting with gnm
StMoMo: The following cohorts have been zero weigthed: 1861 1862 1863 2009 2010 2011 
StMoMo: Start fitting with gnm
StMoMo: Finish fitting with gnm
StMoMo: Start fitting with gnm
Initialising
Running start-up iterations..
Running main iterations.....
Done
StMoMo: Finish fitting with gnm

StMoMo documentation built on May 2, 2019, 11:42 a.m.