fit.StMoMo: Fit a Stochastic Mortality Model
In StMoMo: Stochastic Mortality Modelling

Description Usage Arguments Details Value Examples

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

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

`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`.

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.

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

   

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

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