From 1c6f691afec1ffdc3f5e4366e54a2bc343f65cef Mon Sep 17 00:00:00 2001 From: Andres Villegas Date: Wed, 10 Feb 2016 04:59:37 +1100 Subject: [PATCH] Update roxygen2 --- DESCRIPTION | 23 +-- NAMESPACE | 3 +- man/StMoMo.Rd | 146 ++++++++++---------- man/apc.Rd | 32 +++-- man/binomRes2q.Rd | 10 +- man/bootstrap.Rd | 12 +- man/bootstrap.fitStMoMo.Rd | 67 ++++----- man/cbd.Rd | 26 ++-- man/coef.fitStMoMo.Rd | 48 +++---- man/computeDevianceBinomial.Rd | 2 +- man/computeDeviancePoisson.Rd | 2 +- man/computeLogLikBinomial.Rd | 2 +- man/computeLogLikPoisson.Rd | 2 +- man/extractCoefficientsFromGnm.Rd | 8 +- man/fit.Rd | 12 +- man/fit.StMoMo.Rd | 145 +++++++++---------- man/fitted.fitStMoMo.Rd | 16 +-- man/forecast.fitStMoMo.Rd | 98 ++++++------- man/forecast.mrwd.Rd | 13 +- man/genBinomialResBootSamples.Rd | 10 +- man/genBinomialSemiparametricBootSamples.Rd | 8 +- man/genPoissonResBootSamples.Rd | 8 +- man/genPoissonSemiparametricBootSamples.Rd | 6 +- man/genWeightMat.Rd | 19 +-- man/getMinimalFitStMoMo.Rd | 50 +++---- man/invlogit.Rd | 2 +- man/lc.Rd | 36 ++--- man/logLik.fitStMoMo.Rd | 4 +- man/logit.Rd | 2 +- man/m6.Rd | 42 +++--- man/m7.Rd | 48 ++++--- man/m8.Rd | 30 ++-- man/mrwd.Rd | 10 +- man/plot.bootStMoMo.Rd | 17 +-- man/plot.fitStMoMo.Rd | 16 ++- man/plot.forStMoMo.Rd | 14 +- man/plot.resStMoMo.Rd | 60 ++++---- man/plotParameterFan.Rd | 6 +- man/poissonRes2death.Rd | 6 +- man/predict.fitStMoMo.Rd | 63 ++++----- man/predictLink.Rd | 2 +- man/print.StMoMo.Rd | 2 +- man/print.bootStMoMo.Rd | 2 +- man/print.fitStMoMo.Rd | 2 +- man/print.forStMoMo.Rd | 2 +- man/print.simStMoMo.Rd | 2 +- man/processStartValues.Rd | 4 +- man/residuals.fitStMoMo.Rd | 14 +- man/rh.Rd | 54 ++++---- man/scatterplotAPC.Rd | 8 +- man/simulate.bootStMoMo.Rd | 97 ++++++------- man/simulate.fitStMoMo.Rd | 128 ++++++++--------- man/simulate.mrwd.Rd | 8 +- 53 files changed, 737 insertions(+), 712 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 621680d..f6a4d9e 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -5,26 +5,29 @@ Author: Andres Villegas , Pietro Millossovich , Vladimir Kaishev Maintainer: Andres Villegas -Description: Implementation of the family of generalised age-period-cohort - stochastic mortality models. This family of models encompasses many models - proposed in the actuarial and demographic literature including the Lee-Carter model - and the Cairns-Blake-Dowd model. It includes functions for fitting mortality models, - analysing their goodness-of-fit and performing mortality projections and - simulations. +Description: Implementation of the family of generalised age-period-cohort + stochastic mortality models. This family of models encompasses many models + proposed in the actuarial and demographic literature including the Lee-Carter + model and the Cairns-Blake-Dowd model. It includes functions for fitting + mortality models, analysing their goodness-of-fit and performing mortality + projections and simulations. URL: http://github.com/amvillegas/StMoMo BugReports: http://github.com/amvillegas/StMoMo/issues -Imports: +Imports: MASS, rootSolve (>= 1.6.5.1), fanplot (>= 3.4), reshape2 (>= 1.4.1), fields (>= 8.2), RColorBrewer -Depends: +Depends: R (>= 3.2.0), - gnm (>= 1.0), + gnm (>= 1.0), forecast(>= 6.1) License: GPL (>= 2) LazyData: true -Suggests: knitr, xtable +Suggests: + knitr, + xtable VignetteBuilder: knitr +RoxygenNote: 5.0.1 diff --git a/NAMESPACE b/NAMESPACE index 2dd54ee..c0a7de6 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,11 +1,10 @@ -# Generated by roxygen2 (4.1.1): do not edit by hand +# Generated by roxygen2: do not edit by hand S3method(bootstrap,fitStMoMo) S3method(coef,fitStMoMo) S3method(fit,StMoMo) S3method(fitted,fitStMoMo) S3method(forecast,fitStMoMo) -S3method(forecast,mrwd) S3method(logLik,fitStMoMo) S3method(plot,bootStMoMo) S3method(plot,fitStMoMo) diff --git a/man/StMoMo.Rd b/man/StMoMo.Rd index 0d8ab14..89ac3b1 100644 --- a/man/StMoMo.Rd +++ b/man/StMoMo.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/StMoMo.R, R/docStMoMo.R \docType{package} \name{StMoMo} @@ -11,97 +11,97 @@ StMoMo(link = c("log", "logit"), staticAgeFun = TRUE, periodAgeFun = "NP", list(ax = ax, bx = bx, kt = kt, b0x = b0x, gc = gc)) } \arguments{ -\item{link}{defines the link function and random component associated with - the mortality model. \code{"log"} would assume that deaths follow a - Poisson distribution and use a log link while \code{"logit"} would assume - that deaths follow a Binomial distribution and a logit link.} - -\item{staticAgeFun}{logical value indicating if a static age function - \eqn{\alpha_x} is to be included.} - -\item{periodAgeFun}{a list of length \eqn{N} with the definitions of the - period age modulating parameters \eqn{\beta_x^{(i)}}. Each entry can take - values: \code{"NP"} for non-parametric age terms, \code{"1"} for - \eqn{\beta_x^{(i)}=1} or a predefined parametric function of - age (see details). Set this to \code{NULL} if there are no period terms - in the model.} - -\item{cohortAgeFun}{defines the cohort age modulating parameter - \eqn{\beta_x^{(0)}}. It can take values: \code{"NP"} for non-parametric - age terms, \code{"1"} for \eqn{\beta_x^{(0)}=1}, a predefined parametric - function of age (see details) or \code{NULL} if there is no cohort effect.} - -\item{constFun}{function defining the identifiability constraints of the - model. It must be a function of the form - \code{constFun <- function(ax, bx, kt, b0x, gc, wxt, ages)} taking a set - of fitted model parameters and returning a list - \code{list(ax = ax, bx = bx, kt = kt, b0x = b0x, gc = gc)} - of the model parameters with the identifiability constraints applied. If - omitted no identifiability constraints are applied to the model.} +\item{link}{defines the link function and random component associated with +the mortality model. \code{"log"} would assume that deaths follow a +Poisson distribution and use a log link while \code{"logit"} would assume +that deaths follow a Binomial distribution and a logit link.} + +\item{staticAgeFun}{logical value indicating if a static age function +\eqn{\alpha_x} is to be included.} + +\item{periodAgeFun}{a list of length \eqn{N} with the definitions of the +period age modulating parameters \eqn{\beta_x^{(i)}}. Each entry can take +values: \code{"NP"} for non-parametric age terms, \code{"1"} for +\eqn{\beta_x^{(i)}=1} or a predefined parametric function of +age (see details). Set this to \code{NULL} if there are no period terms +in the model.} + +\item{cohortAgeFun}{defines the cohort age modulating parameter +\eqn{\beta_x^{(0)}}. It can take values: \code{"NP"} for non-parametric +age terms, \code{"1"} for \eqn{\beta_x^{(0)}=1}, a predefined parametric +function of age (see details) or \code{NULL} if there is no cohort effect.} + +\item{constFun}{function defining the identifiability constraints of the +model. It must be a function of the form +\code{constFun <- function(ax, bx, kt, b0x, gc, wxt, ages)} taking a set +of fitted model parameters and returning a list +\code{list(ax = ax, bx = bx, kt = kt, b0x = b0x, gc = gc)} +of the model parameters with the identifiability constraints applied. If +omitted no identifiability constraints are applied to the model.} } \value{ A list with class \code{"StMoMo"} with components: - + \item{link}{a character string defining the link function of the model.} - - \item{staticAgeFun}{a logical value indicating if the model has a static + + \item{staticAgeFun}{a logical value indicating if the model has a static age function.} - + \item{periodAgeFun}{a list defining the period age modulating parameters.} - - \item{cohortAgeFun}{an object defining the cohort age modulating + + \item{cohortAgeFun}{an object defining the cohort age modulating parameters.} - + \item{constFun}{a function defining the identifiability constraints.} - - \item{N}{an integer specifying The number of age-period terms in the + + \item{N}{an integer specifying The number of age-period terms in the model.} - + \item{textFormula}{a character string of the model formula.} - - \item{gnmFormula}{a formula that can be used for fitting the model with + + \item{gnmFormula}{a formula that can be used for fitting the model with package \pkg{gnm}.} } \description{ -Initialises a StMoMo object which represents a Generalised +Initialises a StMoMo object which represents a Generalised Age-Period-Cohort Stochastic Mortality Model. StMoMo. } \details{ -R implementation of the family of Generalised Age-Period-Cohort +R implementation of the family of Generalised Age-Period-Cohort stochastic mortality models. This family of models encompasses many models proposed in the literature including the well-known -Lee-Carter model, CBD model and APC model. +Lee-Carter model, CBD model and APC model. -\code{StMoMo} defines an abstract representation of a Generalised -Age-Period-Cohort (GAPC) Stochastic model that fits within the -general class of generalised non-linear models defined as follows -\deqn{D_{xt} \sim Poisson(E_{xt}\mu_{xt}), D_{xt} \sim -Binomial(E_{xt},q_{xt})} +\code{StMoMo} defines an abstract representation of a Generalised +Age-Period-Cohort (GAPC) Stochastic model that fits within the +general class of generalised non-linear models defined as follows +\deqn{D_{xt} \sim Poisson(E_{xt}\mu_{xt}), D_{xt} \sim +Binomial(E_{xt},q_{xt})} \deqn{\eta_{xt} = \log \mu_{xt}, \eta_{xt} = \mathrm{logit}\, q_{xt}} \deqn{\eta_{xt} = \alpha_x + \sum_{i=1}^N \beta_x^{(i)}\kappa_t^{(i)} -+ \beta_x^{(0)}\gamma_{t-x}} \deqn{v: \{\alpha_{x}, \beta_x^{(1)},..., -\beta_x^{(N)}, \kappa_t^{(1)},..., \kappa_t^{(N)}, \beta_x^{(0)}, \gamma_{t-x}\} \mapsto -\{\alpha_{x}, \beta_x^{(1)},..., \beta_x^{(N)}, \kappa_t^{(1)},..., \kappa_t^{(N)}, -\beta_x^{(0)}, \gamma_{t-x}\},} where ++ \beta_x^{(0)}\gamma_{t-x}} \deqn{v: \{\alpha_{x}, \beta_x^{(1)},..., +\beta_x^{(N)}, \kappa_t^{(1)},..., \kappa_t^{(N)}, \beta_x^{(0)}, \gamma_{t-x}\} \mapsto +\{\alpha_{x}, \beta_x^{(1)},..., \beta_x^{(N)}, \kappa_t^{(1)},..., \kappa_t^{(N)}, +\beta_x^{(0)}, \gamma_{t-x}\},} where \itemize{ - \item \eqn{\alpha_x} is a static age function; - \item \eqn{\beta_x^{(i)}\kappa_t^{(i)}, i = 1,..N}, are age/period terms; - \item \eqn{\beta_x^{(0)}\gamma_{t-x}} is the age/cohort term; and - \item \eqn{v} is a function defining the identifiability constraints of - the model. + \item \eqn{\alpha_x} is a static age function; + \item \eqn{\beta_x^{(i)}\kappa_t^{(i)}, i = 1,..N}, are age/period terms; + \item \eqn{\beta_x^{(0)}\gamma_{t-x}} is the age/cohort term; and + \item \eqn{v} is a function defining the identifiability constraints of + the model. } Most Stochastic mortality models proposed in the literature can be cast to this representation (See Hunt and Blake (2015)). -Parametric age functions should be scalar functions of the form -\code{f <- function(x, ages)} taking a scalar age \code{x} and a vector +Parametric age functions should be scalar functions of the form +\code{f <- function(x, ages)} taking a scalar age \code{x} and a vector of model fitting \code{ages} (see examples below). -Do to limitation of functions \code{\link[gnm]{gnm}} within package -\pkg{gnm}, which is used for fitting \code{"StMoMo"} objects to data -(see \code{\link{fit.StMoMo}}), models combining parametric and +Do to limitation of functions \code{\link[gnm]{gnm}} within package +\pkg{gnm}, which is used for fitting \code{"StMoMo"} objects to data +(see \code{\link{fit.StMoMo}}), models combining parametric and non-parametric age-modulating functions are not supported at the moment. } \examples{ @@ -114,17 +114,17 @@ constLC <- function(ax, bx, kt, b0x, gc, wxt, ages) { LC <- StMoMo(link = "log", staticAgeFun = TRUE, periodAgeFun = "NP", constFun = constLC) -plot(fit(LC, Dxt = EWMaleData$Dxt,Ext = EWMaleData$Ext, +plot(fit(LC, Dxt = EWMaleData$Dxt,Ext = EWMaleData$Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89)) -#CBD model +#CBD model f2 <- function(x, ages) x - mean(ages) CBD <- StMoMo(link = "logit", staticAgeFun = FALSE, periodAgeFun = c("1", f2)) -plot(fit(CBD, Dxt = EWMaleData$Dxt,Ext = EWMaleData$Ext, - ages = EWMaleData$ages, years = EWMaleData$years, +plot(fit(CBD, Dxt = EWMaleData$Dxt,Ext = EWMaleData$Ext, + ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89)) #Reduced Plat model (Plat, 2009) @@ -153,8 +153,8 @@ PLAT <- StMoMo(link = "log", staticAgeFun = TRUE, periodAgeFun = c("1", f2), cohortAgeFun = "1", constFun = constPlat) -plot(fit(PLAT, Dxt = EWMaleData$Dxt,Ext = EWMaleData$Ext, - ages = EWMaleData$ages, years = EWMaleData$years, +plot(fit(PLAT, Dxt = EWMaleData$Dxt,Ext = EWMaleData$Ext, + ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89)) #Models not supported @@ -164,16 +164,16 @@ MnotSup1 <- StMoMo(periodAgeFun = f2, cohortAgeFun = "NP") } } \references{ -Plat, R. (2009). On stochastic mortality modeling. Insurance: Mathematics - and Economics, 45(3), 393-404. +Plat, R. (2009). On stochastic mortality modeling. Insurance: Mathematics + and Economics, 45(3), 393-404. -Hunt, A., & Blake, D. (2015). On the Structure and Classification of +Hunt, A., & Blake, D. (2015). On the Structure and Classification of Mortality Models Mortality Models. Pension Institute Working Paper. \url{http://www.pensions-institute.org/workingpapers/wp1506.pdf}. } \seealso{ -\code{\link{fit.StMoMo}}, \code{\link{lc}}, \code{\link{cbd}}, -\code{\link{apc}}, \code{\link{rh}}, \code{\link{m6}}, \code{\link{m7}}, +\code{\link{fit.StMoMo}}, \code{\link{lc}}, \code{\link{cbd}}, +\code{\link{apc}}, \code{\link{rh}}, \code{\link{m6}}, \code{\link{m7}}, \code{\link{m8}} } diff --git a/man/apc.Rd b/man/apc.Rd index 89ccd14..e4e3490 100644 --- a/man/apc.Rd +++ b/man/apc.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/standardModels.R \name{apc} \alias{apc} @@ -7,39 +7,41 @@ apc(link = c("log", "logit")) } \arguments{ -\item{link}{defines the link function and random component associated with - the mortality model. \code{"log"} would assume that deaths follow a - Poisson distribution and use a log link while \code{"logit"} would assume - that deaths follow a Binomial distribution and a logit link.} +\item{link}{defines the link function and random component associated with +the mortality model. \code{"log"} would assume that deaths follow a +Poisson distribution and use a log link while \code{"logit"} would assume +that deaths follow a Binomial distribution and a logit link.} } \value{ An object of class \code{"StMoMo"}. } \description{ -Utility function to initialise a \code{StMoMo} object representing an +Utility function to initialise a \code{StMoMo} object representing an Age-Period-Cohort mortality model. } \details{ -The created model is either a log-Poisson or a logit-Binomial version of -the classical age-period-cohort mortality model which has predictor -structure +The created model is either a log-Poisson or a logit-Binomial version of +the classical age-period-cohort mortality model which has predictor +structure \deqn{\eta_{xt} = \alpha_x + \kappa_t + \gamma_{t-x}.} -To ensure identifiability we follow Cairns et al. (2009) and impose +To ensure identifiability we follow Cairns et al. (2009) and impose constraints \deqn{\sum_c \gamma_c = 0} and \deqn{\sum_c c\gamma_c = 0} } \examples{ + APC <- apc() wxt <- genWeightMat(EWMaleData$ages, EWMaleData$years, clip = 3) -APCfit <- fit(APC, Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, - ages = EWMaleData$ages, years = EWMaleData$years, +APCfit <- fit(APC, Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, + ages = EWMaleData$ages, years = EWMaleData$years, wxt = wxt) plot(APCfit, parametricbx = FALSE, nCol = 3) + } \references{ -Cairns, A. J. G., Blake, D., Dowd, K., Coughlan, G. D., Epstein, D., -Ong, A., & Balevich, I. (2009). A quantitative comparison of stochastic -mortality models using data from England and Wales and the United States. +Cairns, A. J. G., Blake, D., Dowd, K., Coughlan, G. D., Epstein, D., +Ong, A., & Balevich, I. (2009). A quantitative comparison of stochastic +mortality models using data from England and Wales and the United States. North American Actuarial Journal, 13(1), 1-35. } \seealso{ diff --git a/man/binomRes2q.Rd b/man/binomRes2q.Rd index da0686d..ae0177a 100644 --- a/man/binomRes2q.Rd +++ b/man/binomRes2q.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/bootstrapfitStMoMo.R \name{binomRes2q} \alias{binomRes2q} @@ -17,13 +17,13 @@ binomRes2q(dhat, e, res) matching observed deaths } \description{ -This funciont uses the procedure described in +This funciont uses the procedure described in Debon et al. (2010, section 3) } \references{ -Debon, A., Martinez-Ruiz, F., & Montes, F. (2010). A geostatistical -approach for dynamic life tables: The effect of mortality on remaining -lifetime and annuities. Insurance: Mathematics and Economics, +Debon, A., Martinez-Ruiz, F., & Montes, F. (2010). A geostatistical +approach for dynamic life tables: The effect of mortality on remaining +lifetime and annuities. Insurance: Mathematics and Economics, 47(3), 327-336. } \keyword{internal} diff --git a/man/bootstrap.Rd b/man/bootstrap.Rd index 64f3e30..3b58c89 100644 --- a/man/bootstrap.Rd +++ b/man/bootstrap.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/bootstrapfitStMoMo.R \name{bootstrap} \alias{bootstrap} @@ -7,7 +7,7 @@ bootstrap(object, nBoot, ...) } \arguments{ -\item{object}{an object used to select a method. Typically of class +\item{object}{an object used to select a method. Typically of class \code{fitStMoMo} or an extension of this class.} \item{nBoot}{number of bootstrap samples to produce.} @@ -15,13 +15,13 @@ bootstrap(object, nBoot, ...) \item{...}{arguments to be passed to or from other methods.} } \description{ -\code{bootstrap} is a generic function for bootstrapping Stochastic -Mortality Models. The function invokes particular methods which depend on +\code{bootstrap} is a generic function for bootstrapping Stochastic +Mortality Models. The function invokes particular methods which depend on the class of the first argument. } \details{ -\code{bootstrap} is a generic function which means that new fitting -strategies can be added for particular stochastic mortality models. See +\code{bootstrap} is a generic function which means that new fitting +strategies can be added for particular stochastic mortality models. See for instance \code{\link{bootstrap.fitStMoMo}}. } diff --git a/man/bootstrap.fitStMoMo.Rd b/man/bootstrap.fitStMoMo.Rd index bb96e1e..b606662 100644 --- a/man/bootstrap.fitStMoMo.Rd +++ b/man/bootstrap.fitStMoMo.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/bootstrapfitStMoMo.R \name{bootstrap.fitStMoMo} \alias{bootstrap.fitStMoMo} @@ -8,19 +8,19 @@ "residual"), deathType = c("observed", "fitted"), ...) } \arguments{ -\item{object}{an object of class \code{"fitStMoMo"} with the fitted +\item{object}{an object of class \code{"fitStMoMo"} with the fitted parameters of a stochastic mortality model.} \item{nBoot}{number of bootstrap samples to produce.} -\item{type}{type of bootstrapping approach to be applied. -\code{"semiparametric"}(default) uses the assumed distribution of the -deaths to generate bootstrap samples. \code{"residual"} resamples the +\item{type}{type of bootstrapping approach to be applied. +\code{"semiparametric"}(default) uses the assumed distribution of the +deaths to generate bootstrap samples. \code{"residual"} resamples the deviance residuals of the model to generate bootstrap samples.} -\item{deathType}{type of deaths to sample in the semiparametric bootstrap. -\code{"observed"} (default) resamples the observed deaths. \code{"fitted"} -resamples the fitted deaths. This parameter is only used if \code{type} is +\item{deathType}{type of deaths to sample in the semiparametric bootstrap. +\code{"observed"} (default) resamples the observed deaths. \code{"fitted"} +resamples the fitted deaths. This parameter is only used if \code{type} is \code{"semiparametric"}.} \item{...}{arguments to be passed to or from other methods.} @@ -28,59 +28,60 @@ resamples the fitted deaths. This parameter is only used if \code{type} is \value{ A list with class \code{"bootStMoMo"} with components: -\item{bootParameters}{ a list of of length \code{nBoot} with the fitted -parameters for each bootstrap replication.} +\item{bootParameters}{ a list of of length \code{nBoot} with the fitted +parameters for each bootstrap replication.} \item{model}{ the model fit that has been bootstrapped.} \item{type}{ type of bootstrapping approach applied.} -\item{deathType}{ type of deaths sampled in case of semiparametric +\item{deathType}{ type of deaths sampled in case of semiparametric bootstrap.} } \description{ -Produce bootstrap parameters of a Stochastic Mortality Model to account for +Produce bootstrap parameters of a Stochastic Mortality Model to account for parameter uncertainty. } \details{ -When \code{type} is \code{"residual"} the residual bootstrapping approach -described in Renshaw and Haberman (2008) is applied, which is an -adaptation of the approach of Koissi et al (2006). In the case of a -\code{"logit"} link with Binomial responses the adaptation described in +When \code{type} is \code{"residual"} the residual bootstrapping approach +described in Renshaw and Haberman (2008) is applied, which is an +adaptation of the approach of Koissi et al (2006). In the case of a +\code{"logit"} link with Binomial responses the adaptation described in Debon et al, (2010, section 3) is used. -When \code{type} is \code{"semiparametric"} the semiparametric approach -described in Brouhns et al.(2005) is used. In the case of a \code{"logit"} -link with Binomial responses a suitable adaptation is applied. If -\code{deathType} is \code{"observed"} then the observed deaths are used in -the sampling as in Brouhns et al. (2005) while if \code{deathType} is -\code{"fitted"} the fitted deaths are used in the sampling as in +When \code{type} is \code{"semiparametric"} the semiparametric approach +described in Brouhns et al.(2005) is used. In the case of a \code{"logit"} +link with Binomial responses a suitable adaptation is applied. If +\code{deathType} is \code{"observed"} then the observed deaths are used in +the sampling as in Brouhns et al. (2005) while if \code{deathType} is +\code{"fitted"} the fitted deaths are used in the sampling as in Renshaw and Haberman (2008). } \examples{ #Long computing times \dontrun{ -LCfit <- fit(lc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, +LCfit <- fit(lc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, ages = EWMaleData$ages, years = EWMaleData$years) LCResBoot <- bootstrap(LCfit, nBoot = 500, type = "residual") plot(LCResBoot) LCSemiObsBoot <- bootstrap(LCfit, nBoot = 500, type = "semiparametric") plot(LCSemiObsBoot) -LCSemiFitBoot <- bootstrap(LCfit, nBoot = 500, type = "semiparametric", +LCSemiFitBoot <- bootstrap(LCfit, nBoot = 500, type = "semiparametric", deathType = "fitted") plot(LCSemiFitBoot) } + } \references{ -Brouhns, N., Denuit M., & Van Keilegom, I. (2005). Bootstrapping the -Poisson log-bilinear model for mortality forecasting. -Scandinavian Actuarial Journal, 2005(3), 212-224. +Brouhns, N., Denuit M., & Van Keilegom, I. (2005). Bootstrapping the +Poisson log-bilinear model for mortality forecasting. +Scandinavian Actuarial Journal, 2005(3), 212-224. -Debon, A., Martinez-Ruiz, F., & Montes, F. (2010). A geostatistical -approach for dynamic life tables: The effect of mortality on remaining -lifetime and annuities. Insurance: Mathematics and Economics, 47(3), -327-336. +Debon, A., Martinez-Ruiz, F., & Montes, F. (2010). A geostatistical +approach for dynamic life tables: The effect of mortality on remaining +lifetime and annuities. Insurance: Mathematics and Economics, 47(3), +327-336. -Renshaw, A. E., & Haberman, S. (2008). On simulation-based approaches to -risk measurement in mortality with specific reference to Poisson Lee-Carter +Renshaw, A. E., & Haberman, S. (2008). On simulation-based approaches to +risk measurement in mortality with specific reference to Poisson Lee-Carter modelling. Insurance: Mathematics and Economics, 42(2), 797-816. } \seealso{ diff --git a/man/cbd.Rd b/man/cbd.Rd index 53d875d..d1df0b2 100644 --- a/man/cbd.Rd +++ b/man/cbd.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/standardModels.R \name{cbd} \alias{cbd} @@ -7,41 +7,43 @@ cbd(link = c("logit", "log")) } \arguments{ -\item{link}{defines the link function and random component associated with -the mortality model. \code{"log"} would assume that deaths follow a -Poisson distribution and use a log link while \code{"logit"} would -assume that deaths follow a Binomial distribution and a logit link. +\item{link}{defines the link function and random component associated with +the mortality model. \code{"log"} would assume that deaths follow a +Poisson distribution and use a log link while \code{"logit"} would +assume that deaths follow a Binomial distribution and a logit link. Note that the default is the logit link.} } \value{ An object of class \code{"StMoMo"}. } \description{ -Utility function to initialise a \code{StMoMo} object representing a +Utility function to initialise a \code{StMoMo} object representing a Cairns-Blake-Dowd mortality model. } \details{ -The created model is either a logit-Binomial or a log-Poisson version of -the Cairns-Blake-Dowd mortality model which has predictor structure +The created model is either a logit-Binomial or a log-Poisson version of +the Cairns-Blake-Dowd mortality model which has predictor structure \deqn{\eta_{xt} = \kappa_t^{(1)} + (x-\bar{x})\kappa_t^{(2)},} where \eqn{\bar{x}} is the average age in the data. } \examples{ + CBD <- cbd() Dxt <- EWMaleData$Dxt Ext <- EWMaleData$Ext + 0.5 * EWMaleData$Dxt -CBDfit <- fit(CBD, Dxt = Dxt, Ext = Ext, +CBDfit <- fit(CBD, Dxt = Dxt, Ext = Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) plot(CBDfit, parametricbx = FALSE) + } \references{ -Cairns, A. J. G., Blake, D., & Dowd, K. (2006). A Two-Factor Model for -Stochastic Mortality with Parameter Uncertainty: Theory and Calibration. +Cairns, A. J. G., Blake, D., & Dowd, K. (2006). A Two-Factor Model for +Stochastic Mortality with Parameter Uncertainty: Theory and Calibration. Journal of Risk and Insurance, 73(4), 687-718. } \seealso{ -\code{\link{StMoMo}}, \code{\link{m6}}, \code{\link{m7}}, +\code{\link{StMoMo}}, \code{\link{m6}}, \code{\link{m7}}, \code{\link{m8}} } diff --git a/man/coef.fitStMoMo.Rd b/man/coef.fitStMoMo.Rd index 7327397..8fd1885 100644 --- a/man/coef.fitStMoMo.Rd +++ b/man/coef.fitStMoMo.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/coeffitStMoMo.R \name{coef.fitStMoMo} \alias{coef.fitStMoMo} @@ -7,46 +7,46 @@ \method{coef}{fitStMoMo}(object, ...) } \arguments{ -\item{object}{an object of class \code{"fitStMoMo"} with the fitted +\item{object}{an object of class \code{"fitStMoMo"} with the fitted parameters of a stochastic mortality model.} \item{...}{other arguments.} } \value{ A list of model parameters with components: - - \item{ax}{ Vector with the fitted values of the static age function - \eqn{\alpha_x}. If the model does not have a static age function or failed + + \item{ax}{ Vector with the fitted values of the static age function + \eqn{\alpha_x}. If the model does not have a static age function or failed to fit this is set to \code{NULL}.} - - \item{bx}{ Matrix with the values of the period age-modulating functions - \eqn{\beta_x^{(i)}, i=1, ..., N}. If the \eqn{i}-th age-modulating - function is non-parametric (e.g., as in the Lee-Carter model) - \code{bx[, i]} contains the estimated values. If the model does not have - any age-period terms (i.e. \eqn{N=0}) or failed to fit this is set to + + \item{bx}{ Matrix with the values of the period age-modulating functions + \eqn{\beta_x^{(i)}, i=1, ..., N}. If the \eqn{i}-th age-modulating + function is non-parametric (e.g., as in the Lee-Carter model) + \code{bx[, i]} contains the estimated values. If the model does not have + any age-period terms (i.e. \eqn{N=0}) or failed to fit this is set to \code{NULL}.} - - \item{kt}{ Matrix with the values of the fitted period indexes - \eqn{\kappa_t^{(i)}, i=1, ..., N}. \code{kt[i, ]} contains the estimated - values of the \eqn{i}-th period index. If the model does not have any - age-period terms (i.e. \eqn{N=0}) or failed to fit this is set to + + \item{kt}{ Matrix with the values of the fitted period indexes + \eqn{\kappa_t^{(i)}, i=1, ..., N}. \code{kt[i, ]} contains the estimated + values of the \eqn{i}-th period index. If the model does not have any + age-period terms (i.e. \eqn{N=0}) or failed to fit this is set to \code{NULL}.} - - \item{b0x}{ Vector with the values of the cohort age-modulating function - \eqn{\beta_x^{(0)}}. If the age-modulating function is non-parametric - \code{b0x} contains the estimated values. If the model does not have a + + \item{b0x}{ Vector with the values of the cohort age-modulating function + \eqn{\beta_x^{(0)}}. If the age-modulating function is non-parametric + \code{b0x} contains the estimated values. If the model does not have a cohort effect or failed to fit this is set to \code{NULL}.} - + \item{gc}{ Vector with the fitted cohort index \eqn{\gamma_{c}}. - If the model does not have a cohort effect or failed to fit this is set + If the model does not have a cohort effect or failed to fit this is set to \code{NULL}.} } \description{ Extract coefficients from a fitted Stochastic Mortality Model } \examples{ -APCfit <- fit(apc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, +APCfit <- fit(apc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, ages = EWMaleData$ages, years = EWMaleData$years) -coef(APCfit) +coef(APCfit) } diff --git a/man/computeDevianceBinomial.Rd b/man/computeDevianceBinomial.Rd index 07487c8..cb2e37a 100644 --- a/man/computeDevianceBinomial.Rd +++ b/man/computeDevianceBinomial.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/internalUtils.R \name{computeDevianceBinomial} \alias{computeDevianceBinomial} diff --git a/man/computeDeviancePoisson.Rd b/man/computeDeviancePoisson.Rd index c3cd074..f0ee68c 100644 --- a/man/computeDeviancePoisson.Rd +++ b/man/computeDeviancePoisson.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/internalUtils.R \name{computeDeviancePoisson} \alias{computeDeviancePoisson} diff --git a/man/computeLogLikBinomial.Rd b/man/computeLogLikBinomial.Rd index 1779ec0..971502b 100644 --- a/man/computeLogLikBinomial.Rd +++ b/man/computeLogLikBinomial.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/internalUtils.R \name{computeLogLikBinomial} \alias{computeLogLikBinomial} diff --git a/man/computeLogLikPoisson.Rd b/man/computeLogLikPoisson.Rd index b45d000..641be54 100644 --- a/man/computeLogLikPoisson.Rd +++ b/man/computeLogLikPoisson.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/internalUtils.R \name{computeLogLikPoisson} \alias{computeLogLikPoisson} diff --git a/man/extractCoefficientsFromGnm.Rd b/man/extractCoefficientsFromGnm.Rd index 0cf5354..9e2521d 100644 --- a/man/extractCoefficientsFromGnm.Rd +++ b/man/extractCoefficientsFromGnm.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/fitStMoMo.R \name{extractCoefficientsFromGnm} \alias{extractCoefficientsFromGnm} @@ -19,13 +19,13 @@ mortality model.} \item{cohorts}{cohorts in the fitting data.} -\item{zeroWeigthAges}{character vector of years whose parameters cannot +\item{zeroWeigthAges}{character vector of years whose parameters cannot be estimated because all data is zero weighted} -\item{zeroWeigthYears}{character vector of years whose parameters cannot +\item{zeroWeigthYears}{character vector of years whose parameters cannot be estimated because all data is zero weighted} -\item{zeroWeigthCohorts}{character vector of cohort whose parameters +\item{zeroWeigthCohorts}{character vector of cohort whose parameters cannot be estimated because all data is zero weighted} } \value{ diff --git a/man/fit.Rd b/man/fit.Rd index c357305..a63c42a 100644 --- a/man/fit.Rd +++ b/man/fit.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/fitStMoMo.R \name{fit} \alias{fit} @@ -7,19 +7,19 @@ fit(object, ...) } \arguments{ -\item{object}{an object used to select a method. Typically of class +\item{object}{an object used to select a method. Typically of class \code{StMoMo} or an extension of this class.} \item{...}{arguments to be passed to or from other methods.} } \description{ -\code{fit} is a generic function for fitting Stochastic Mortality Models. -The function invokes particular methods which depend on the class of the +\code{fit} is a generic function for fitting Stochastic Mortality Models. +The function invokes particular methods which depend on the class of the first argument. } \details{ -\code{fit} is a generic function which means that new fitting strategies -can be added for particular stochastic mortality models. See for instance +\code{fit} is a generic function which means that new fitting strategies +can be added for particular stochastic mortality models. See for instance \code{\link{fit.StMoMo}}. } diff --git a/man/fit.StMoMo.Rd b/man/fit.StMoMo.Rd index 8be5dac..67bfbe2 100644 --- a/man/fit.StMoMo.Rd +++ b/man/fit.StMoMo.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/fitStMoMo.R \name{fit.StMoMo} \alias{fit.StMoMo} @@ -21,19 +21,19 @@ mortality model.} \item{years}{vector of years corresponding to rows of \code{Dxt} and \code{Ext}.} -\item{ages.fit}{optional vector of ages to include in the fit. Must be a +\item{ages.fit}{optional vector of ages to include in the fit. Must be a subset of \code{ages}.} -\item{years.fit}{optional vector of years to include in the fit. Must be a +\item{years.fit}{optional vector of years to include in the fit. Must be a subset of \code{years}.} \item{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 model. This can be used to specify any a priori known component to be added to the predictor during fitting.} -\item{wxt}{optional matrix of 0-1 weights to be used in the fitting process. +\item{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 \code{\link{genWeightMat}} which is a helper function for defining +See \code{\link{genWeightMat}} which is a helper function for defining weighting matrices.} \item{start.ax}{optional vector with starting values for \eqn{\alpha_x}.} @@ -46,129 +46,130 @@ weighting matrices.} \item{start.gc}{optional vector with starting values for \eqn{\gamma_c}.} -\item{verbose}{a logical value. If \code{TRUE} progress indicators are -printed as the model is fitted. Set \code{verbose = FALSE} to silent the +\item{verbose}{a logical value. If \code{TRUE} progress indicators are +printed as the model is fitted. Set \code{verbose = FALSE} to silent the fitting and avoid progress messages.} -\item{...}{arguments to be passed to or from other methods. This can be -used to control the fitting parameters of \code{gnm}. See +\item{...}{arguments to be passed to or from other methods. This can be +used to control the fitting parameters of \code{gnm}. See \code{\link[gnm]{gnm}}.} } \value{ A list with class \code{"fitStMoMo"} with components: - - \item{model}{ the object of class \code{"StMoMo"} defining the fitted + + \item{model}{ the object of class \code{"StMoMo"} defining the fitted stochastic mortality model.} - - \item{ax}{ vector with the fitted values of the static age function - \eqn{\alpha_x}. If the model does not have a static age function or + + \item{ax}{ vector with the fitted values of the static age function + \eqn{\alpha_x}. If the model does not have a static age function or failed to fit this is set to \code{NULL}.} - - \item{bx}{ matrix with the values of the period age-modulating functions - \eqn{\beta_x^{(i)}, i=1, ..., N}. If the \eqn{i}-th age-modulating - function is non-parametric (e.g. as in the Lee-Carter model) - \code{bx[, i]} contains the estimated values. If the model does not have - any age-period terms (i.e. \eqn{N=0}) or failed to fit this is set to + + \item{bx}{ matrix with the values of the period age-modulating functions + \eqn{\beta_x^{(i)}, i=1, ..., N}. If the \eqn{i}-th age-modulating + function is non-parametric (e.g. as in the Lee-Carter model) + \code{bx[, i]} contains the estimated values. If the model does not have + any age-period terms (i.e. \eqn{N=0}) or failed to fit this is set to \code{NULL}.} - - \item{kt}{ matrix with the values of the fitted period indexes - \eqn{\kappa_t^{(i)}, i=1, ..., N}. \code{kt[i, ]} contains the estimated - values of the \eqn{i}-th period index. If the model does not have any - age-period terms (i.e. \eqn{N=0}) or failed to fit this is set to + + \item{kt}{ matrix with the values of the fitted period indexes + \eqn{\kappa_t^{(i)}, i=1, ..., N}. \code{kt[i, ]} contains the estimated + values of the \eqn{i}-th period index. If the model does not have any + age-period terms (i.e. \eqn{N=0}) or failed to fit this is set to \code{NULL}.} - \item{b0x}{ vector with the values of the cohort age-modulating function - \eqn{\beta_x^{(0)}}. If the age-modulating function is non-parametric - \code{b0x} contains the estimated values. If the model does not have a + \item{b0x}{ vector with the values of the cohort age-modulating function + \eqn{\beta_x^{(0)}}. If the age-modulating function is non-parametric + \code{b0x} contains the estimated values. If the model does not have a cohort effect or failed to fit this is set to \code{NULL}.} - + \item{gc}{ vector with the fitted cohort index \eqn{\gamma_{c}}. If the model does not have a cohort effect or failed to fit this is set to \code{NULL}.} - + \item{Dxt}{ matrix of deaths used in the fitting.} - + \item{Ext}{ matrix of exposures used in the fitting.} - + \item{oxt}{ matrix of known offset values used in the fitting.} - + \item{wxt}{ matrix of 0-1 weights used in the fitting.} - + \item{ages}{ vector of ages used in the fitting.} - + \item{years}{ vector of years used in the fitting.} - + \item{cohorts}{ vector of cohorts used in the fitting.} - - \item{fittingModel}{ output from the call to \code{gnm} used to fit the + + \item{fittingModel}{ output from the call to \code{gnm} used to fit the model. If the fitting failed to converge this is set to \code{NULL}.} - - \item{loglik}{ log-likelihood of the model. If the fitting failed to + + \item{loglik}{ log-likelihood of the model. If the fitting failed to converge this is set to \code{NULL}.} - - \item{deviance}{ deviance of the model. If the fitting failed to + + \item{deviance}{ deviance of the model. If the fitting failed to converge this is set to \code{NULL}.} - + \item{npar}{ effective number of parameters in the model. If the fitting failed to converge this is set to \code{NULL}.} - + \item{nobs}{ number of observations in the model fit. If the fitting failed to converge this is set to \code{NULL}.} - \item{fail}{ \code{TRUE} if a model could not be fitted and - \code{FALSE} otherwise.} - - \item{conv}{ \code{TRUE} if the model fitting converged and + \item{fail}{ \code{TRUE} if a model could not be fitted and + \code{FALSE} otherwise.} + + \item{conv}{ \code{TRUE} if the model fitting converged and \code{FALSE} if it didn't.} + + @seealso \code{\link{genWeightMat}}, \code{\link{plot.fitStMoMo}} } \description{ -Fit a Stochastic Mortality Model to a given data set. The fitting is done +Fit a Stochastic Mortality Model to a given data set. The fitting is done using package \code{gnm}. } \details{ -Fitting is done using function \code{\link[gnm]{gnm}} within package -\code{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 +Fitting is done using function \code{\link[gnm]{gnm}} within package +\code{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, \code{NA} are assigned a -zero weight and ignored in the fitting process. Parameter estimates can be +zero weight and ignored in the fitting process. Parameter estimates can be plotted using function \code{\link{plot.fitStMoMo}}. } \examples{ + + # CBD model only to older ages -CBDfit <- fit(cbd(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, - ages = EWMaleData$ages, years = EWMaleData$years, +CBDfit <- fit(cbd(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, + ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) plot(CBDfit, parametricbx = FALSE) # APC model weigthing out the 3 first and last cohorts wxt <- genWeightMat(EWMaleData$ages, EWMaleData$years, clip = 3) -APCfit <- fit(apc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, - ages = EWMaleData$ages, years = EWMaleData$years, +APCfit <- fit(apc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, + ages = EWMaleData$ages, years = EWMaleData$years, wxt = wxt) plot(APCfit, parametricbx = FALSE, nCol = 3) # Set verbose = FALSE for silent fitting -APCfit <- fit(apc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, - ages = EWMaleData$ages, years = EWMaleData$years, +APCfit <- fit(apc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, + ages = EWMaleData$ages, years = EWMaleData$years, wxt = wxt, verbose = FALSE) \dontrun{ -# Poisson Lee-Carter model with the static age function set to +# 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){ +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, + 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, Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, - ages = EWMaleData$ages, years = EWMaleData$years, +LCfix_axfit <- fit(LCfix_ax, Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, + ages = EWMaleData$ages, years = EWMaleData$years, oxt = rowMeans(log(EWMaleData$Dxt / EWMaleData$Ext))) plot(LCfix_axfit) } } -\seealso{ -\code{\link{genWeightMat}}, \code{\link{plot.fitStMoMo}} -} diff --git a/man/fitted.fitStMoMo.Rd b/man/fitted.fitStMoMo.Rd index ed8b7b3..9d168d6 100644 --- a/man/fitted.fitStMoMo.Rd +++ b/man/fitted.fitStMoMo.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/fittedfitStMoMo.R \name{fitted.fitStMoMo} \alias{fitted.fitStMoMo} @@ -7,11 +7,11 @@ \method{fitted}{fitStMoMo}(object, type = c("link", "rates", "deaths"), ...) } \arguments{ -\item{object}{an object of class \code{"fitStMoMo"} with the fitted +\item{object}{an object of class \code{"fitStMoMo"} with the fitted parameters of a stochastic mortality model.} -\item{type}{the type of the fitted values that should be returned. The -alternatives are \code{"link"}(default), \code{"rates"}, and +\item{type}{the type of the fitted values that should be returned. The +alternatives are \code{"link"}(default), \code{"rates"}, and \code{"deaths"}.} \item{...}{other arguments.} @@ -20,15 +20,15 @@ alternatives are \code{"link"}(default), \code{"rates"}, and A matrix with the fitted values. } \description{ -Returns fitted values for the data used in fitting a Stochastic Mortality +Returns fitted values for the data used in fitting a Stochastic Mortality Model. } \examples{ -LCfit <- fit(lc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, +LCfit <- fit(lc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) -matplot(LCfit$ages, fitted(LCfit), type = "l", lty = 1, - col = rainbow(length(LCfit$years)), xlab = "year", +matplot(LCfit$ages, fitted(LCfit), type = "l", lty = 1, + col = rainbow(length(LCfit$years)), xlab = "year", ylab = "log death rate", main = "Fitted rates") qxthat <- fitted(LCfit, type = "rates") diff --git a/man/forecast.fitStMoMo.Rd b/man/forecast.fitStMoMo.Rd index 3945495..dc6dd8d 100644 --- a/man/forecast.fitStMoMo.Rd +++ b/man/forecast.fitStMoMo.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/forecastfitStMoMo.R \name{forecast.fitStMoMo} \alias{forecast.fitStMoMo} @@ -9,40 +9,40 @@ "actual"), kt.lookback = NULL, gc.lookback = NULL, ...) } \arguments{ -\item{object}{an object of class \code{"fitStMoMo"} with the fitted +\item{object}{an object of class \code{"fitStMoMo"} with the fitted parameters of a stochastic mortality model.} \item{h}{number of years ahead to forecast.} -\item{level}{confidence level for prediction intervals of the +\item{level}{confidence level for prediction intervals of the period and cohort indices.} -\item{oxt}{optional matrix/vector or scalar of known offset to be -added in the forecasting. This can be used to specify any a priori +\item{oxt}{optional matrix/vector or scalar of known offset to be +added in the forecasting. This can be used to specify any a priori known component to be added to the forecasted predictor.} -\item{gc.order}{a specification of the ARIMA model: the three components -\eqn{(p, d, q)} are the AR order, the degree of differencing, and the MA +\item{gc.order}{a specification of the ARIMA model: the three components +\eqn{(p, d, q)} are the AR order, the degree of differencing, and the MA order. The default is an ARIMA\eqn{(1, 1, 0)}.} \item{gc.include.constant}{a logical value indicating if the ARIMA model should include a constant value. The default is \code{TRUE}.} -\item{jumpchoice}{option to select the jump-off rates, i.e. the rates -from the final year of observation, to use in projections of mortality -rates. \code{"fit"}(default) uses the fitted rates and \code{"actual"} +\item{jumpchoice}{option to select the jump-off rates, i.e. the rates +from the final year of observation, to use in projections of mortality +rates. \code{"fit"}(default) uses the fitted rates and \code{"actual"} uses the actual rates from the final year.} \item{kt.lookback}{optional argument to specify the look-back window to use -in the estimation of the MRWD for period indexes. By default all the -estimated values are used in estimating the MRWD. If -\code{kt.lookback} is provided then the last \code{kt.lookback} +in the estimation of the MRWD for period indexes. By default all the +estimated values are used in estimating the MRWD. If +\code{kt.lookback} is provided then the last \code{kt.lookback} years of \eqn{\kappa_t^{(i)}, i = 1,..N,} are used.} \item{gc.lookback}{optional argument to specify the look-back window to use -in the estimation of the ARIMA model for the cohort effect. By -default all the estimated values are used in estimating the ARIMA -model. If \code{gc.lookback} is provided then the last +in the estimation of the ARIMA model for the cohort effect. By +default all the estimated values are used in estimating the ARIMA +model. If \code{gc.lookback} is provided then the last \code{gc.lookback} years of \eqn{\gamma_{t-x}} are used.} \item{...}{other arguments.} @@ -54,27 +54,27 @@ A list of class \code{"forStMoMo"} with components: \item{ages}{ vector of ages corresponding to the rows of \code{rates}.} \item{years}{vector of years for which a forecast has been produced. This corresponds to the columns of \code{rates}.} - -\item{kt.f}{ forecasts of period indexes of the model. This is a list with -the \code{model} fitted to \eqn{\kappa_t}; the \code{mean}(central) -forecast, the \code{lower} and \code{upper} limits of the prediction -interval; the confidence \code{level} associated with the prediction -interval; and the \code{years} for which a forecast was produced. If the -model does not have any age-period terms (i.e. \eqn{N=0}) this is set to + +\item{kt.f}{ forecasts of period indexes of the model. This is a list with +the \code{model} fitted to \eqn{\kappa_t}; the \code{mean}(central) +forecast, the \code{lower} and \code{upper} limits of the prediction +interval; the confidence \code{level} associated with the prediction +interval; and the \code{years} for which a forecast was produced. If the +model does not have any age-period terms (i.e. \eqn{N=0}) this is set to \code{NULL}.} - -\item{gc.f}{ forecasts of cohort index of the model. This is a list with + +\item{gc.f}{ forecasts of cohort index of the model. This is a list with the \code{model} fitted to \eqn{\gamma_c}; the \code{mean}(point) forecast, the \code{lower} and \code{upper} limits of the prediction interval; the -confidence \code{level} associated with the prediction interval; and the +confidence \code{level} associated with the prediction interval; and the \code{cohorts} for which a forecast was produced. If the mortality model -does not have a cohort effect this is set to \code{NULL}.} +does not have a cohort effect this is set to \code{NULL}.} \item{oxt.f}{ the offset used in the forecast.} -\item{fitted}{ a matrix with the fitted in-sample rates of the model for +\item{fitted}{ a matrix with the fitted in-sample rates of the model for the years for which the mortality model was fitted.} - + \item{model}{the model fit from which the forecast was produced.} \item{jumpchoice}{Jump-off method used in the forecast.} @@ -82,7 +82,7 @@ the years for which the mortality model was fitted.} \description{ Forecast mortality rates using a Stochastic Mortality Model fit. The period indexes \eqn{\kappa_t^{(i)}, i = 1,..N,} are forecasted -using a Multivariate Random Walk with Drift (MRWD). The cohort index +using a Multivariate Random Walk with Drift (MRWD). The cohort index \eqn{\gamma_{t-x}} is forecasted using an ARIMA\eqn{(p, d, q)}. By default an ARIMA\eqn{(1, 1, 0)} with a constant is used. } @@ -90,26 +90,26 @@ an ARIMA\eqn{(1, 1, 0)} with a constant is used. Fitting and forecasting of the Multivariate Random Walk with Drift for the period indexes use the function \code{\link{mrwd}}. Fitting and forecasting of the ARIMA model for the cohort index -is done with function \code{\link[forecast]{Arima}} from package -\pkg{forecast}. See the latter function for further details on -input arguments \code{gc.order} and \code{gc.include.constant}. +is done with function \code{\link[forecast]{Arima}} from package +\pkg{forecast}. See the latter function for further details on +input arguments \code{gc.order} and \code{gc.include.constant}. -Note that in some cases forecast of the +Note that in some cases forecast of the cohort effects may be needed for a horizon longer than \code{h}. -This is the case when in the fitted model the most recent cohorts -have been zero weighted. The forecasted cohorts can be seen in +This is the case when in the fitted model the most recent cohorts +have been zero weighted. The forecasted cohorts can be seen in \code{gc.f$cohorts}. } \examples{ #Lee-Carter -LCfit <- fit(lc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, +LCfit <- fit(lc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) LCfor <- forecast(LCfit) plot(LCfor) #CBD -CBDfit <- fit(cbd(),Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, +CBDfit <- fit(cbd(),Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) CBDfor <- forecast(CBDfit) @@ -117,29 +117,29 @@ plot(CBDfor, parametricbx = FALSE) #APC: Compare forecast with different models for the cohort index wxt <- genWeightMat(55:89, EWMaleData$years, clip = 3) -APCfit <- fit(apc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, - ages = EWMaleData$ages, years = EWMaleData$years, +APCfit <- fit(apc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, + ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89, wxt = wxt) APCfor1 <- forecast(APCfit) plot(APCfor1, parametricbx = FALSE, nCol = 3) APCfor2 <- forecast(APCfit, gc.order = c(0, 2, 2)) plot(APCfor2, only.gc = TRUE) -plot(c(APCfit$years, APCfor1$years), - cbind(APCfor1$fitted, APCfor1$rates)["65", ], - type = "l", xlab = "year", ylab = "Mortality rate at age 65", +plot(c(APCfit$years, APCfor1$years), + cbind(APCfor1$fitted, APCfor1$rates)["65", ], + type = "l", xlab = "year", ylab = "Mortality rate at age 65", main = "Forecasts with different models for gc") lines(APCfor2$years, APCfor2$rates["65", ], col = "blue") -points(APCfit$years, (APCfit$Dxt / APCfit$Ext)["65", ], pch = 19) +points(APCfit$years, (APCfit$Dxt / APCfit$Ext)["65", ], pch = 19) -#Compare Lee-Carter forecast using: +#Compare Lee-Carter forecast using: # 1. Fitted jump-off rates and all history for kt # 2. Actual jump-off rates and all history for kt -# 3. Fitted jump-off rates and only history for +# 3. Fitted jump-off rates and only history for # the past 30 years of kt (i.e 1982-2011) LCfor1 <- forecast(LCfit) LCfor2 <- forecast(LCfit, jumpchoice = "actual") -LCfor3 <- forecast(LCfit, kt.lookback = 30) +LCfor3 <- forecast(LCfit, kt.lookback = 30) plot(LCfit$years, (LCfit$Dxt / LCfit$Ext)["60", ], xlim = range(LCfit$years, LCfor1$years), @@ -151,8 +151,8 @@ lines(LCfit$years, fitted(LCfit, type = "rates")["60", ]) lines(LCfor1$years, LCfor1$rates["60", ], lty = 2) lines(LCfor2$years, LCfor2$rates["60", ], lty = 3, col = "blue") lines(LCfor3$years, LCfor3$rates["60", ], lty = 4, col = "red") -legend("topright",legend = c("Fitted jump-off", "Actual jump-off", - "Fitted jump-off, 30 year look-back"), +legend("topright",legend = c("Fitted jump-off", "Actual jump-off", + "Fitted jump-off, 30 year look-back"), lty = 1:3, col = c("black", "blue", "red")) } diff --git a/man/forecast.mrwd.Rd b/man/forecast.mrwd.Rd index 97798bc..a3af53e 100644 --- a/man/forecast.mrwd.Rd +++ b/man/forecast.mrwd.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/mrwd.R \name{forecast.mrwd} \alias{forecast.mrwd} @@ -14,7 +14,7 @@ \item{level}{confidence level for prediction intervals.} -\item{fan}{if \code{TRUE}, level is set to \code{seq(50, 99, by = 1)}. +\item{fan}{if \code{TRUE}, level is set to \code{seq(50, 99, by = 1)}. This is suitable for fan plots.} \item{...}{other arguments.} @@ -23,15 +23,16 @@ This is suitable for fan plots.} An object of class \code{"mrwdForecast"} with components: \item{model}{a list containing information about the fitted model.} \item{mean}{ array with the central forecast.} -\item{lower}{ three dimensional array with lower limits for prediction +\item{lower}{ three dimensional array with lower limits for prediction intervals.} -\item{upper}{ three dimensional array with upper limits for prediction +\item{upper}{ three dimensional array with upper limits for prediction intervals.} - \item{level}{ the confidence values associated with the prediction + \item{level}{ the confidence values associated with the prediction intervals.} + @export } \description{ -Returns forecasts and other information for a Multivariate +Returns forecasts and other information for a Multivariate Random Walk with Drift model. } diff --git a/man/genBinomialResBootSamples.Rd b/man/genBinomialResBootSamples.Rd index 778d9c9..00430cc 100644 --- a/man/genBinomialResBootSamples.Rd +++ b/man/genBinomialResBootSamples.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/bootstrapfitStMoMo.R \name{genBinomialResBootSamples} \alias{genBinomialResBootSamples} @@ -16,7 +16,7 @@ genBinomialResBootSamples(devRes, dhat, E, nBoot) \item{nBoot}{number of bootstrap samples to produce.} } \value{ -a list of length \code{nBoot} of matrices with matching sampled +a list of length \code{nBoot} of matrices with matching sampled deaths } \description{ @@ -24,9 +24,9 @@ Generate Binomial bootstrap samples using the procedure described in Debon et al. (2010, section 3) } \references{ -Debon, A., Martinez-Ruiz, F., & Montes, F. (2010). A geostatistical -approach for dynamic life tables: The effect of mortality on remaining -lifetime and annuities. Insurance: Mathematics and Economics, 47(3), +Debon, A., Martinez-Ruiz, F., & Montes, F. (2010). A geostatistical +approach for dynamic life tables: The effect of mortality on remaining +lifetime and annuities. Insurance: Mathematics and Economics, 47(3), 327-336. } \keyword{internal} diff --git a/man/genBinomialSemiparametricBootSamples.Rd b/man/genBinomialSemiparametricBootSamples.Rd index 499923a..b0b4868 100644 --- a/man/genBinomialSemiparametricBootSamples.Rd +++ b/man/genBinomialSemiparametricBootSamples.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/bootstrapfitStMoMo.R \name{genBinomialSemiparametricBootSamples} \alias{genBinomialSemiparametricBootSamples} @@ -17,12 +17,12 @@ genBinomialSemiparametricBootSamples(D, E, nBoot) a list of length \code{nBoot} of matrices with sampled deaths } \description{ -Generate Binomial semiparametric bootstrap samples using a suitable +Generate Binomial semiparametric bootstrap samples using a suitable adaptation of the Poisson procedure described in Brouhns et al (2005). } \references{ -Brouhns, N., Denuit M., & Van Keilegom, I. (2005). Bootstrapping the -Poisson log-bilinear model for mortality forecasting. +Brouhns, N., Denuit M., & Van Keilegom, I. (2005). Bootstrapping the +Poisson log-bilinear model for mortality forecasting. Scandinavian Actuarial Journal, 2005(3), 212-224. } \keyword{internal} diff --git a/man/genPoissonResBootSamples.Rd b/man/genPoissonResBootSamples.Rd index 18dd717..1042d60 100644 --- a/man/genPoissonResBootSamples.Rd +++ b/man/genPoissonResBootSamples.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/bootstrapfitStMoMo.R \name{genPoissonResBootSamples} \alias{genPoissonResBootSamples} @@ -14,7 +14,7 @@ genPoissonResBootSamples(devRes, dhat, nBoot) \item{nBoot}{number of bootstrap samples to produce.} } \value{ -a list of length \code{nBoot} of marices with matching sampled +a list of length \code{nBoot} of marices with matching sampled deaths } \description{ @@ -22,8 +22,8 @@ Generate poisson bootstrap samples using the procedure described in Renshaw and Haberman (2008) } \references{ -Renshaw, A. E., & Haberman, S. (2008). On simulation-based approaches to -risk measurement in mortality with specific reference to Poisson Lee-Carter +Renshaw, A. E., & Haberman, S. (2008). On simulation-based approaches to +risk measurement in mortality with specific reference to Poisson Lee-Carter modelling. Insurance: Mathematics and Economics, 42(2), 797-816. } \keyword{internal} diff --git a/man/genPoissonSemiparametricBootSamples.Rd b/man/genPoissonSemiparametricBootSamples.Rd index 64aff7a..5f61fa2 100644 --- a/man/genPoissonSemiparametricBootSamples.Rd +++ b/man/genPoissonSemiparametricBootSamples.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/bootstrapfitStMoMo.R \name{genPoissonSemiparametricBootSamples} \alias{genPoissonSemiparametricBootSamples} @@ -19,8 +19,8 @@ Generate Poisson semiparametric bootstrap samples using the procedure described in Brouhns et al (2005). } \references{ -Brouhns, N., Denuit M., & Van Keilegom, I. (2005). Bootstrapping the -Poisson log-bilinear model for mortality forecasting. +Brouhns, N., Denuit M., & Van Keilegom, I. (2005). Bootstrapping the +Poisson log-bilinear model for mortality forecasting. Scandinavian Actuarial Journal, 2005(3), 212-224. } \keyword{internal} diff --git a/man/genWeightMat.Rd b/man/genWeightMat.Rd index 2f78cbb..39ab2e8 100644 --- a/man/genWeightMat.Rd +++ b/man/genWeightMat.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/exportUtils.R \name{genWeightMat} \alias{genWeightMat} @@ -11,8 +11,8 @@ genWeightMat(ages, years, clip = 0, zeroCohorts = NULL) \item{years}{vector of years.} -\item{clip}{number of cohorts in the boundary to assign a zero -weight. This can be be used to zero weigh some of the first and +\item{clip}{number of cohorts in the boundary to assign a zero +weight. This can be be used to zero weigh some of the first and last cohorts in the data.} \item{zeroCohorts}{other cohort for which a zero weight is to be assigned.} @@ -23,24 +23,25 @@ A 0-1 matrix with 0 for the zero-weighed cohorts. \description{ Generates a weight matrix given a group of ages and years and a set of cohorts which are to be given zero weight. This -is useful for excluding some data points when fitting a +is useful for excluding some data points when fitting a Stochastic Mortality Model (see \code{\link{fit.StMoMo}}). } \examples{ #Zero-weight the first three and last three cohorts wxt1 <- genWeightMat(55:89, EWMaleData$years, clip = 3) -APCfit1 <- fit(apc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, - ages = EWMaleData$ages, years = EWMaleData$years, +APCfit1 <- fit(apc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, + ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89, wxt = wxt1) plot(APCfit1, parametricbx = FALSE, nCol = 3) #Also Zero-weight the 1886 cohort -wxt2 <- genWeightMat(55:89, EWMaleData$years, clip = 3, +wxt2 <- genWeightMat(55:89, EWMaleData$years, clip = 3, zeroCohorts = 1886) -APCfit2 <- fit(apc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, - ages = EWMaleData$ages, years = EWMaleData$years, +APCfit2 <- fit(apc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, + ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89, wxt = wxt2) plot(APCfit2, parametricbx = FALSE, nCol = 3) + } \seealso{ \code{\link{fit.StMoMo}} diff --git a/man/getMinimalFitStMoMo.Rd b/man/getMinimalFitStMoMo.Rd index b96194a..25b9311 100644 --- a/man/getMinimalFitStMoMo.Rd +++ b/man/getMinimalFitStMoMo.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/internalUtils.R \name{getMinimalFitStMoMo} \alias{getMinimalFitStMoMo} @@ -7,58 +7,58 @@ getMinimalFitStMoMo(object) } \arguments{ -\item{object}{an object of class \code{"fitStMoMo"} with the fitted +\item{object}{an object of class \code{"fitStMoMo"} with the fitted parameters of a stochastic mortality model.} } \value{ A list with class \code{"fitStMoMo"} with components - - \item{model}{ The \code{StMoMo} defining the fitted stochastic + + \item{model}{ The \code{StMoMo} defining the fitted stochastic mortality model.} - + \item{ax}{ Vector with the fitted values of the static age function - \eqn{\alpha_x}. If the model does not have a static age function or + \eqn{\alpha_x}. If the model does not have a static age function or failed to fit this is set to \code{NULL}.} - + \item{bx}{ Matrix with the values of the period age-modulating functions - \eqn{\beta_x^{(i)}, i=1, ..., N}. If the \eqn{i}-th age-modulating - function is non-parametric (e.g. as in the Lee-Carter model) + \eqn{\beta_x^{(i)}, i=1, ..., N}. If the \eqn{i}-th age-modulating + function is non-parametric (e.g. as in the Lee-Carter model) \code{bx[, i]} contains the estimated values. If the model does not have any age-period terms (i.e. \eqn{N=0}) or failed to fit this is set to \code{NULL}.} - + \item{kt}{ Matrix with the values of the fitted period indexes \eqn{\kappa_t^{(i)}, i=1, ..., N}. \code{kt[i, ]} contains the estimated - values of the \eqn{i}-th period index. If the model does not have any - age-period terms (i.e. \eqn{N=0}) or failed to fit this is set to + values of the \eqn{i}-th period index. If the model does not have any + age-period terms (i.e. \eqn{N=0}) or failed to fit this is set to \code{NULL}.} - + \item{b0x}{ Vector with the values of the cohort age-modulating function - \eqn{\beta_x^{(0)}}. If the age-modulating function is non-parametric - \code{b0x} contains the estimated values. If the model does not have a + \eqn{\beta_x^{(0)}}. If the age-modulating function is non-parametric + \code{b0x} contains the estimated values. If the model does not have a cohort effect or failed to fit this is set to \code{NULL}.} - + \item{gc}{ Vector with the fitted cohort index \eqn{\gamma_{c}}. If the - model does not have a cohort effect or failed to fit this is set to + model does not have a cohort effect or failed to fit this is set to \code{NULL}.} - + \item{Dxt}{ Matrix of deaths used in the fitting.} - + \item{Ext}{ Matrix of exposures used in the fitting.} - + \item{oxt}{ Matrix of known offset values used in the fitting.} - + \item{wxt}{ Matrix of 0-1 weights used in the fitting.} - + \item{ages}{ Vector of ages in the data.} - + \item{years}{ Vector of years in the data.} - + \item{cohorts}{ Vector of cohorts in the data.} } \description{ Obtain a lighter version of a fitted Stochastic Mortality Model -with the essential information for plotting, forecasting, +with the essential information for plotting, forecasting, and simulation. } \keyword{internal} diff --git a/man/invlogit.Rd b/man/invlogit.Rd index 461e929..acc05a5 100644 --- a/man/invlogit.Rd +++ b/man/invlogit.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/internalUtils.R \name{invlogit} \alias{invlogit} diff --git a/man/lc.Rd b/man/lc.Rd index 5b03e60..4b40e01 100644 --- a/man/lc.Rd +++ b/man/lc.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/standardModels.R \name{lc} \alias{lc} @@ -7,27 +7,27 @@ lc(link = c("log", "logit"), const = c("sum", "last", "first")) } \arguments{ -\item{link}{defines the link function and random component associated with - the mortality model. \code{"log"} would assume that deaths follow a - Poisson distribution and use a log link while \code{"logit"} would assume - that deaths follow a Binomial distribution and a logit link.} +\item{link}{defines the link function and random component associated with +the mortality model. \code{"log"} would assume that deaths follow a +Poisson distribution and use a log link while \code{"logit"} would assume +that deaths follow a Binomial distribution and a logit link.} \item{const}{defines the constraint to impose to the period index of the - model to ensure identifiability. The alternatives are - \code{"sum"}(default), \code{"last"} and \code{"first"} which apply - constraints \eqn{\sum_t\kappa_t = 0}, \eqn{\kappa_n = 0} and - \eqn{\kappa_1 = 0}, respectively.} +model to ensure identifiability. The alternatives are +\code{"sum"}(default), \code{"last"} and \code{"first"} which apply +constraints \eqn{\sum_t\kappa_t = 0}, \eqn{\kappa_n = 0} and +\eqn{\kappa_1 = 0}, respectively.} } \value{ An object of class \code{"StMoMo"}. } \description{ -Utility function to initialise a \code{StMoMo} object representing a +Utility function to initialise a \code{StMoMo} object representing a Lee-Carter model. } \details{ -The created model is either a log-Poisson (see Brouhns et al (2002)) or a -logit-Binomial version of the Lee-Carter model which has predictor structure +The created model is either a log-Poisson (see Brouhns et al (2002)) or a +logit-Binomial version of the Lee-Carter model which has predictor structure \deqn{\eta_{xt} = \alpha_x + \beta_x\kappa_t.} To ensure identifiability one of the following constraints is imposed \deqn{\sum_t\kappa_t = 0,\,\kappa_1 = 0,\, \kappa_n = 0} @@ -35,33 +35,35 @@ depending on the value of \code{const}, and \deqn{\sum_x\beta_x = 1.} } \examples{ + #sum(kt) = 0 and log link LC1 <- lc() -LCfit1<-fit(LC1, Dxt = EWMaleData$Dxt,Ext = EWMaleData$Ext, +LCfit1<-fit(LC1, Dxt = EWMaleData$Dxt,Ext = EWMaleData$Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) plot(LCfit1) #kt[1] = 0 and log link LC2 <- lc(const = "first") -LCfit2<-fit(LC2, Dxt = EWMaleData$Dxt,Ext = EWMaleData$Ext, +LCfit2<-fit(LC2, Dxt = EWMaleData$Dxt,Ext = EWMaleData$Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) plot(LCfit2) #kt[n] = 0 and logit link LC3 <- lc("logit", "last") -LCfit3<-fit(LC3, Dxt = EWMaleData$Dxt,Ext = EWMaleData$Ext, +LCfit3<-fit(LC3, Dxt = EWMaleData$Dxt,Ext = EWMaleData$Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) plot(LCfit3) + } \references{ -Brouhns, N., Denuit, M., & Vermunt, J. K. (2002). A Poisson log-bilinear +Brouhns, N., Denuit, M., & Vermunt, J. K. (2002). A Poisson log-bilinear regression approach to the construction of projected lifetables. Insurance: Mathematics and Economics, 31(3), 373-393. -Lee, R. D., & Carter, L. R. (1992). Modeling and forecasting U.S. mortality. +Lee, R. D., & Carter, L. R. (1992). Modeling and forecasting U.S. mortality. Journal of the American Statistical Association, 87(419), 659-671. } \seealso{ diff --git a/man/logLik.fitStMoMo.Rd b/man/logLik.fitStMoMo.Rd index 09fb892..b604c9a 100644 --- a/man/logLik.fitStMoMo.Rd +++ b/man/logLik.fitStMoMo.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/logLikfitStMoMo.R \name{logLik.fitStMoMo} \alias{logLik.fitStMoMo} @@ -7,7 +7,7 @@ \method{logLik}{fitStMoMo}(object, ...) } \arguments{ -\item{object}{an object of class \code{fitStMoMo} representing a +\item{object}{an object of class \code{fitStMoMo} representing a Stochastic Mortality Model fitted to some data.} \item{...}{other arguments.} diff --git a/man/logit.Rd b/man/logit.Rd index 8dc3e66..b540d23 100644 --- a/man/logit.Rd +++ b/man/logit.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/internalUtils.R \name{logit} \alias{logit} diff --git a/man/m6.Rd b/man/m6.Rd index ff8b8e3..cd4d278 100644 --- a/man/m6.Rd +++ b/man/m6.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/standardModels.R \name{m6} \alias{m6} @@ -7,54 +7,56 @@ m6(link = c("logit", "log")) } \arguments{ -\item{link}{defines the link function and random component associated with -the mortality model. \code{"log"} would assume that deaths follow a -Poisson distribution and use a log link while \code{"logit"} would -assume that deaths follow a Binomial distribution and a logit link. +\item{link}{defines the link function and random component associated with +the mortality model. \code{"log"} would assume that deaths follow a +Poisson distribution and use a log link while \code{"logit"} would +assume that deaths follow a Binomial distribution and a logit link. Note that the default is the logit link.} } \value{ An object of class \code{"StMoMo"}. } \description{ -Utility function to initialise a \code{StMoMo} object representing the -M6 (CBD with cohorts) extension of the Cairns-Blake-Dowd mortality model +Utility function to initialise a \code{StMoMo} object representing the +M6 (CBD with cohorts) extension of the Cairns-Blake-Dowd mortality model introduced in Cairns et al (2009). } \details{ -The created model is either a logit-Binomial or a log-Poisson version of the -M6 model which has predictor structure -\deqn{\eta_{xt} = \kappa_t^{(1)} + (x-\bar{x})\kappa_t^{(2)} + \gamma_{t-x},} +The created model is either a logit-Binomial or a log-Poisson version of the +M6 model which has predictor structure +\deqn{\eta_{xt} = \kappa_t^{(1)} + (x-\bar{x})\kappa_t^{(2)} + \gamma_{t-x},} where \eqn{\bar{x}} is the average age in the data. -Identifiability of the model is accomplished by applying parameters +Identifiability of the model is accomplished by applying parameters constraints \deqn{\sum_c\gamma_c = 0, \sum_c c\gamma_c = 0} -which ensure that the cohort effect fluctuates around zero and has no -linear trend. These constraints are applied using the strategy discussed +which ensure that the cohort effect fluctuates around zero and has no +linear trend. These constraints are applied using the strategy discussed in Appendix A of Haberman and Renshaw (2011). } \examples{ + M6 <- m6() Dxt <- EWMaleData$Dxt Ext <- EWMaleData$Ext + 0.5 * EWMaleData$Dxt wxt <- genWeightMat(55:89, EWMaleData$years, clip = 3) -M6fit <- fit(M6, Dxt = Dxt, Ext = Ext, ages = EWMaleData$ages, +M6fit <- fit(M6, Dxt = Dxt, Ext = Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) plot(M6fit, parametricbx = FALSE) + } \references{ -Cairns, A. J. G., Blake, D., Dowd, K., Coughlan, G. D., Epstein, D., -Ong, A., & Balevich, I. (2009). A quantitative comparison of stochastic -mortality models using data from England and Wales and the United States. +Cairns, A. J. G., Blake, D., Dowd, K., Coughlan, G. D., Epstein, D., +Ong, A., & Balevich, I. (2009). A quantitative comparison of stochastic +mortality models using data from England and Wales and the United States. North American Actuarial Journal, 13(1), 1-35. -Haberman, S., & Renshaw, A. (2011). A comparative study of parametric -mortality projection models. Insurance: Mathematics and Economics, +Haberman, S., & Renshaw, A. (2011). A comparative study of parametric +mortality projection models. Insurance: Mathematics and Economics, 48(1), 35-55. } \seealso{ -\code{\link{StMoMo}}, \code{\link{cbd}}, \code{\link{m7}}, +\code{\link{StMoMo}}, \code{\link{cbd}}, \code{\link{m7}}, \code{\link{m8}} } diff --git a/man/m7.Rd b/man/m7.Rd index cbeafd7..5dc13da 100644 --- a/man/m7.Rd +++ b/man/m7.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/standardModels.R \name{m7} \alias{m7} @@ -7,56 +7,58 @@ m7(link = c("logit", "log")) } \arguments{ -\item{link}{defines the link function and random component associated with -the mortality model. \code{"log"} would assume that deaths follow a -Poisson distribution and use a log link while \code{"logit"} would -assume that deaths follow a Binomial distribution and a logit link. +\item{link}{defines the link function and random component associated with +the mortality model. \code{"log"} would assume that deaths follow a +Poisson distribution and use a log link while \code{"logit"} would +assume that deaths follow a Binomial distribution and a logit link. Note that the default is the logit link.} } \value{ An object of class \code{"StMoMo"}. } \description{ -Utility function to initialise a \code{StMoMo} object representing the +Utility function to initialise a \code{StMoMo} object representing the M7 extension of the Cairns-Blake-Dowd mortality model introduced in Cairns et al (2009). } \details{ -The created model is either a logit-Binomial or a log-Poisson version of -the M7 model which has predictor structure -\deqn{\eta_{xt} = \kappa_t^{(1)} + (x-\bar{x})\kappa_t^{(2)} + - ((x-\bar{x})^2 - \hat{\sigma}^2_x)\kappa_t^{(2)} + \gamma_{t-x},} -where \eqn{\bar{x}} is the average age in the data and \eqn{\hat{\sigma}^2_x} +The created model is either a logit-Binomial or a log-Poisson version of +the M7 model which has predictor structure +\deqn{\eta_{xt} = \kappa_t^{(1)} + (x-\bar{x})\kappa_t^{(2)} + + ((x-\bar{x})^2 - \hat{\sigma}^2_x)\kappa_t^{(2)} + \gamma_{t-x},} +where \eqn{\bar{x}} is the average age in the data and \eqn{\hat{\sigma}^2_x} is the average value of \eqn{(x-\bar{x})^2}. - -Identifiability of the model is accomplished by applying parameters -constraints \deqn{\sum_c\gamma_c = 0, \sum_c c\gamma_c = 0, -\sum_c c^2\gamma_c = 0} which ensure that the cohort effect fluctuates -around zero and has no linear or quadratic trend. These constraints are -applied using the strategy discussed in Appendix A of + +Identifiability of the model is accomplished by applying parameters +constraints \deqn{\sum_c\gamma_c = 0, \sum_c c\gamma_c = 0, +\sum_c c^2\gamma_c = 0} which ensure that the cohort effect fluctuates +around zero and has no linear or quadratic trend. These constraints are +applied using the strategy discussed in Appendix A of Haberman and Renshaw (2011). } \examples{ + M7 <- m7() Dxt <- EWMaleData$Dxt Ext <- EWMaleData$Ext + 0.5 * EWMaleData$Dxt wxt <- genWeightMat(55:89, EWMaleData$years, clip = 3) -M7fit <- fit(M7, Dxt = Dxt, Ext = Ext, ages = EWMaleData$ages, +M7fit <- fit(M7, Dxt = Dxt, Ext = Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) plot(M7fit, parametricbx = FALSE) + } \references{ Cairns, A. J. G., Blake, D., Dowd, K., Coughlan, G. D., Epstein, D., -Ong, A., & Balevich, I. (2009). A quantitative comparison of stochastic -mortality models using data from England and Wales and the United States. +Ong, A., & Balevich, I. (2009). A quantitative comparison of stochastic +mortality models using data from England and Wales and the United States. North American Actuarial Journal, 13(1), 1-35. -Haberman, S., & Renshaw, A. (2011). A comparative study of parametric -mortality projection models. Insurance: Mathematics and Economics, +Haberman, S., & Renshaw, A. (2011). A comparative study of parametric +mortality projection models. Insurance: Mathematics and Economics, 48(1), 35-55. } \seealso{ -\code{\link{StMoMo}}, \code{\link{cbd}}, \code{\link{m6}}, +\code{\link{StMoMo}}, \code{\link{cbd}}, \code{\link{m6}}, \code{\link{m8}} } diff --git a/man/m8.Rd b/man/m8.Rd index 533c317..7b82c93 100644 --- a/man/m8.Rd +++ b/man/m8.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/standardModels.R \name{m8} \alias{m8} @@ -7,10 +7,10 @@ m8(link = c("logit", "log"), xc) } \arguments{ -\item{link}{defines the link function and random component associated with -the mortality model. \code{"log"} would assume that deaths follow a -Poisson distribution and use a log link while \code{"logit"} would -assume that deaths follow a Binomial distribution and a logit link. +\item{link}{defines the link function and random component associated with +the mortality model. \code{"log"} would assume that deaths follow a +Poisson distribution and use a log link while \code{"logit"} would +assume that deaths follow a Binomial distribution and a logit link. Note that the default is the logit link.} \item{xc}{constant defining the cohort age-modulating parameter.} @@ -19,37 +19,39 @@ Note that the default is the logit link.} An object of class \code{"StMoMo"}. } \description{ -Utility function to initialise a \code{StMoMo} object representing the +Utility function to initialise a \code{StMoMo} object representing the M8 extension of the Cairns-Blake-Dowd mortality model introduced in Cairns et al (2009). } \details{ -The created model is either a logit-Binomial or a log-Poisson version of -the M8 model which has predictor structure +The created model is either a logit-Binomial or a log-Poisson version of +the M8 model which has predictor structure \deqn{\eta_{xt} = \kappa_t^{(1)} + (x-\bar{x})\kappa_t^{(2)} + (x_c-x)\gamma_{t-x}} where \eqn{\bar{x}} is the average age in the data and \eqn{x_c} is a -predefined constant. -Identifiability of the model is accomplished by applying parameters +predefined constant. +Identifiability of the model is accomplished by applying parameters constraint \deqn{\sum_c\gamma_c = 0.} } \examples{ + M8 <- m8(xc = 89) Dxt <- EWMaleData$Dxt Ext <- EWMaleData$Ext + 0.5 * EWMaleData$Dxt wxt <- genWeightMat(55:89, EWMaleData$years, clip = 3) -M8fit <- fit(M8, Dxt = Dxt, Ext = Ext, ages = EWMaleData$ages, +M8fit <- fit(M8, Dxt = Dxt, Ext = Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) plot(M8fit, parametricbx = FALSE) + } \references{ -Cairns, A. J. G., Blake, D., Dowd, K., Coughlan, G. D., Epstein, D., +Cairns, A. J. G., Blake, D., Dowd, K., Coughlan, G. D., Epstein, D., Ong, A., & Balevich, I. (2009). A quantitative comparison of stochastic -mortality models using data from England and Wales and the United States. +mortality models using data from England and Wales and the United States. North American Actuarial Journal, 13(1), 1-35. } \seealso{ -\code{\link{StMoMo}}, \code{\link{cbd}}, \code{\link{m6}}, +\code{\link{StMoMo}}, \code{\link{cbd}}, \code{\link{m6}}, \code{\link{m7}} } diff --git a/man/mrwd.Rd b/man/mrwd.Rd index eb8d476..6e2dc07 100644 --- a/man/mrwd.Rd +++ b/man/mrwd.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/mrwd.R \name{mrwd} \alias{mrwd} @@ -13,10 +13,10 @@ Series are arranged in rows with columns representing time.} \value{ an object of class \code{"mrwd"} with components: \item{drift}{ a vector with the estimated drift.} -\item{sigma}{ a matrix with the estimated variance covariance +\item{sigma}{ a matrix with the estimated variance covariance matrix.} \item{fitted}{ fitted values.} -\item{residuals}{ residuals from the fitted model. That is +\item{residuals}{ residuals from the fitted model. That is observed minus fitted values.} \item{x}{the original time series.} } @@ -29,8 +29,8 @@ For further information on the Multivariate Random Walk with drift see Appendix B in Haberman and Renshaw (2011). } \references{ -Haberman, S., & Renshaw, A. (2011). A comparative study of parametric -mortality projection models. Insurance: Mathematics and Economics, +Haberman, S., & Renshaw, A. (2011). A comparative study of parametric +mortality projection models. Insurance: Mathematics and Economics, 48(1), 35-55. } diff --git a/man/plot.bootStMoMo.Rd b/man/plot.bootStMoMo.Rd index 9825078..0b13687 100644 --- a/man/plot.bootStMoMo.Rd +++ b/man/plot.bootStMoMo.Rd @@ -1,44 +1,45 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/plotbootStMoMo.R \name{plot.bootStMoMo} \alias{plot.bootStMoMo} \title{Plot bootstrapped parameters of a Stochastic Mortality Model} \usage{ -\method{plot}{bootStMoMo}(x, nCol = 2, parametricbx = TRUE, - colour = rgb(0, 0, 0), +\method{plot}{bootStMoMo}(x, nCol = 2, parametricbx = TRUE, + colour = rgb(0, 0, 0), probs = c(2.5, 10, 25, 50, 75, 90, 97.5), ...) } \arguments{ -\item{x}{an object of class \code{"bootStMoMo"} with the bootstrapped +\item{x}{an object of class \code{"bootStMoMo"} with the bootstrapped parameters of a stochastic mortality model.} \item{nCol}{number of columns to use in the plot.} -\item{parametricbx}{if \code{FALSE} parametric age-modulating terms, +\item{parametricbx}{if \code{FALSE} parametric age-modulating terms, which don't need to be estimated, are not plotted.} \item{colour}{colour to use in the fans.} \item{probs}{probabilities related to percentiles to plot in the fan chart. -The default \code{c(2.5,10,25,50,75,90,97.5)} plots the 50\%, 80\% and +The default \code{c(2.5,10,25,50,75,90,97.5)} plots the 50\%, 80\% and 95\% confidence intervals of the parameters.} \item{...}{other arguments.} } \description{ -Plot fancharts of bootstrapped parameters of a Stochastic Mortality Model +Plot fancharts of bootstrapped parameters of a Stochastic Mortality Model stored in an object of class \code{"bootStMoMo"}. } \examples{ #Long computing times \dontrun{ -CBDfit <- fit(cbd(),Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, +CBDfit <- fit(cbd(),Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) CBDResBoot <- bootstrap(CBDfit, nBoot = 500) plot(CBDResBoot) plot(CBDResBoot, parametricbx = FALSE, probs = seq(2.5, 97.5, 2.5)) } + } \seealso{ \code{\link{plot.fitStMoMo}} diff --git a/man/plot.fitStMoMo.Rd b/man/plot.fitStMoMo.Rd index dd562de..26971e1 100644 --- a/man/plot.fitStMoMo.Rd +++ b/man/plot.fitStMoMo.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/plotfitStMoMo.R \name{plot.fitStMoMo} \alias{plot.fitStMoMo} @@ -7,38 +7,40 @@ \method{plot}{fitStMoMo}(x, nCol = 2, parametricbx = TRUE, type = "l", ...) } \arguments{ -\item{x}{an object of class \code{"fitStMoMo"} with the fitted +\item{x}{an object of class \code{"fitStMoMo"} with the fitted parameters of a stochastic mortality model.} \item{nCol}{number of columns to use in the plot.} -\item{parametricbx}{if \code{FALSE} parametric age-modulating terms, +\item{parametricbx}{if \code{FALSE} parametric age-modulating terms, which don't need to be estimated, are not plotted.} -\item{type}{what type of plot should be drawn. See +\item{type}{what type of plot should be drawn. See \code{\link[graphics]{plot}}.} \item{...}{additional arguments to control graphical appearance. See \code{\link[graphics]{plot}}.} } \description{ -Plot fitted parameters of a stochastic mortality model of class +Plot fitted parameters of a stochastic mortality model of class \code{"fitStMoMo"}. } \examples{ + #Fit and plot a Lee-Carter model -LCfit <- fit(lc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, +LCfit <- fit(lc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) plot(LCfit) plot(LCfit, type = "p", pch = 19) #Fit and plot a CBD model -CBDfit <- fit(cbd(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, +CBDfit <- fit(cbd(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) plot(CBDfit) plot(CBDfit, parametricbx = FALSE) plot(CBDfit, nCol = 1, parametricbx = FALSE, lwd = 2) + } diff --git a/man/plot.forStMoMo.Rd b/man/plot.forStMoMo.Rd index f9201f3..1665199 100644 --- a/man/plot.forStMoMo.Rd +++ b/man/plot.forStMoMo.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/plotforStMoMo.R \name{plot.forStMoMo} \alias{plot.forStMoMo} @@ -8,18 +8,18 @@ only.gc = FALSE, ...) } \arguments{ -\item{x}{an object of class \code{"forStMoMo"} with the forecast +\item{x}{an object of class \code{"forStMoMo"} with the forecast of a stochastic mortality model.} \item{nCol}{number of columns to use in the plot.} -\item{parametricbx}{if \code{FALSE} parametric age-modulating terms, +\item{parametricbx}{if \code{FALSE} parametric age-modulating terms, which don't need to be estimated, are not plotted.} -\item{only.kt}{If \code{TRUE} only the period indexes of the model are +\item{only.kt}{If \code{TRUE} only the period indexes of the model are plotted.} -\item{only.gc}{If \code{TRUE} only the cohort index of the model is +\item{only.gc}{If \code{TRUE} only the cohort index of the model is plotted. This argument is ignored if \code{only.kt} is \code{TRUE}.} \item{...}{additional arguments to control graphical appearance. @@ -30,8 +30,8 @@ Plot a forecasted Stochastic Mortality Model of class \code{"forStMoMo"}. } \examples{ wxt <- genWeightMat(55:89, EWMaleData$years, clip = 3) -APCfit <- fit(apc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, - ages = EWMaleData$ages, years = EWMaleData$years, +APCfit <- fit(apc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, + ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89, wxt = wxt) APCfor <- forecast(APCfit) plot(APCfor) diff --git a/man/plot.resStMoMo.Rd b/man/plot.resStMoMo.Rd index c946013..7fd9bca 100644 --- a/man/plot.resStMoMo.Rd +++ b/man/plot.resStMoMo.Rd @@ -1,78 +1,78 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/residualsfitStMoMo.R \name{plot.resStMoMo} \alias{plot.resStMoMo} \title{Plot the residuals of a Stochastic Mortality Model} \usage{ -\method{plot}{resStMoMo}(x, type = c("scatter", "colourmap", - "signplot"), - reslim = NULL, plotAge = TRUE, - plotYear = TRUE, plotCohort = TRUE, +\method{plot}{resStMoMo}(x, type = c("scatter", "colourmap", + "signplot"), + reslim = NULL, plotAge = TRUE, + plotYear = TRUE, plotCohort = TRUE, pch = 20, col = NULL, ...) } \arguments{ -\item{x}{an object of class \code{resStMoMo} with the residuals of a +\item{x}{an object of class \code{resStMoMo} with the residuals of a Stochastic Mortality Model.} -\item{type}{the type of the plot. The alternatives are +\item{type}{the type of the plot. The alternatives are \code{"scatter"}(default), \code{"colourmap"}, and \code{"signplot"}.} -\item{reslim}{optional numeric vector of length 2, giving the range of the +\item{reslim}{optional numeric vector of length 2, giving the range of the residuals.} -\item{plotAge}{logical value indicating if the age scatter plot should be +\item{plotAge}{logical value indicating if the age scatter plot should be produced. This is only used when \code{type = "scatter"}.} -\item{plotYear}{logical value indicating if the calendar year scatter plot +\item{plotYear}{logical value indicating if the calendar year scatter plot should be produced. This is only used when \code{type = "scatter"}.} -\item{plotCohort}{logical value indicating if the cohort scatter plot +\item{plotCohort}{logical value indicating if the cohort scatter plot should be produced. This is only used when \code{type = "scatter"}.} -\item{pch}{optional symbol to use for the points in a scatterplot. -This is only used when \code{type = "scatter"}. See +\item{pch}{optional symbol to use for the points in a scatterplot. +This is only used when \code{type = "scatter"}. See \code{\link[graphics]{plot}}.} -\item{col}{optional colours to use in plotting. If +\item{col}{optional colours to use in plotting. If \code{type = "scatter"} this is a single colour to use in the points in the scatter plots, while if \code{type = "colourmap"} this should -be a list of colours (see help in \code{\link[fields]{image.plot}} +be a list of colours (see help in \code{\link[fields]{image.plot}} for details). This argument is ignored if \code{type = "signplot"}.} -\item{...}{other plotting parameters to be passed to the plotting +\item{...}{other plotting parameters to be passed to the plotting functions. This can be used to control the appearance of the plots.} } \description{ -Plots the deviance residuals of a Stochastic Mortality Model which are +Plots the deviance residuals of a Stochastic Mortality Model which are of class \code{"resStMoMo"}. Three types of plots are available: scatter plot of residuals by age, period and cohort, -colour map (heatmap) of the residuals, and a black and white signplot +colour map (heatmap) of the residuals, and a black and white signplot of the residuals. } \details{ -When \code{type = "scatter"} scatter plots of the residuals against age, -calendar year and cohort (year of birth) are produced. +When \code{type = "scatter"} scatter plots of the residuals against age, +calendar year and cohort (year of birth) are produced. -When \code{type = "colourmap"} a two dimensional colour map of the -residuals is plotted. This is produced using function -\code{\link[fields]{image.plot}}. See \code{\link[fields]{image.plot}} +When \code{type = "colourmap"} a two dimensional colour map of the +residuals is plotted. This is produced using function +\code{\link[fields]{image.plot}}. See \code{\link[fields]{image.plot}} for further parameters that can be passed to this type of plots. When \code{type = "signplot"} a two dimensional black and white map of the - residuals is plotted with dark grey representing negative residuals and - light grey representing positive residuals. This is produced using - function \code{\link[graphics]{image.default}}. + residuals is plotted with dark grey representing negative residuals and + light grey representing positive residuals. This is produced using + function \code{\link[graphics]{image.default}}. + + @seealso \code{\link{residuals.fitStMoMo}} } \examples{ -CBDfit <- fit(cbd(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, +CBDfit <- fit(cbd(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) CBDres <- residuals(CBDfit) plot(CBDres) plot(CBDres, type = "signplot") plot(CBDres, type = "colourmap") -} -\seealso{ -\code{\link{residuals.fitStMoMo}} + } diff --git a/man/plotParameterFan.Rd b/man/plotParameterFan.Rd index 210aa63..41edf23 100644 --- a/man/plotParameterFan.Rd +++ b/man/plotParameterFan.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/plotbootStMoMo.R \name{plotParameterFan} \alias{plotParameterFan} @@ -29,8 +29,8 @@ plotParameterFan(x, y, yBoot, main, xlab, ylab, probs, fan.col, n.fan, ...) Plot fanchart of the parameters } \details{ -In order for the plotting to look appropiately the intervals of -the data with non missing values need to be found. Otherwise fanplot::fan +In order for the plotting to look appropiately the intervals of +the data with non missing values need to be found. Otherwise fanplot::fan doesn't work. } \keyword{internal} diff --git a/man/poissonRes2death.Rd b/man/poissonRes2death.Rd index 2d40b94..86f76ae 100644 --- a/man/poissonRes2death.Rd +++ b/man/poissonRes2death.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/bootstrapfitStMoMo.R \name{poissonRes2death} \alias{poissonRes2death} @@ -18,8 +18,8 @@ matching observed deaths This funciont uses the procedure described in Renshaw and Haberman (2008) } \references{ -Renshaw, A. E., & Haberman, S. (2008). On simulation-based approaches to -risk measurement in mortality with specific reference to Poisson Lee-Carter +Renshaw, A. E., & Haberman, S. (2008). On simulation-based approaches to +risk measurement in mortality with specific reference to Poisson Lee-Carter modelling. Insurance: Mathematics and Economics, 42(2), 797-816. } \keyword{internal} diff --git a/man/predict.fitStMoMo.Rd b/man/predict.fitStMoMo.Rd index c6235de..0993ed6 100644 --- a/man/predict.fitStMoMo.Rd +++ b/man/predict.fitStMoMo.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/predictfitStMoMo.R \name{predict.fitStMoMo} \alias{predict.fitStMoMo} @@ -8,31 +8,31 @@ oxt = NULL, type = c("link", "rates"), ...) } \arguments{ -\item{object}{an object of class \code{"fitStMoMo"} with the fitted +\item{object}{an object of class \code{"fitStMoMo"} with the fitted parameters of a stochastic mortality model.} \item{years}{vector of years for which a prediction is required.} -\item{kt}{matrix of values of the period indexes to use for the prediction. -If the model has any age-period term this argument needs to be provided and -the number of rows in \code{kt} must be equal to the number of age-period -terms in the model and the number of columns in \code{kt} must correspond -to the length of \code{years}. If the Stochastic Mortality Model doesn't -have any age-period terms this argument is ignored and needs not be +\item{kt}{matrix of values of the period indexes to use for the prediction. +If the model has any age-period term this argument needs to be provided and +the number of rows in \code{kt} must be equal to the number of age-period +terms in the model and the number of columns in \code{kt} must correspond +to the length of \code{years}. If the Stochastic Mortality Model doesn't +have any age-period terms this argument is ignored and needs not be provided.} -\item{gc}{vector of values of the cohort indexes to use for the prediction. -If the model has a cohort effect this argument needs to be provided. -In this case the length of \code{gc} must be equal to the number of cohorts -for which a prediction is being produced, namely, -\code{length(object$ages) + length(years) - 1}. If the Stochastic Mortality -Model doesn't have a cohort effect this argument is ignored and needs not +\item{gc}{vector of values of the cohort indexes to use for the prediction. +If the model has a cohort effect this argument needs to be provided. +In this case the length of \code{gc} must be equal to the number of cohorts +for which a prediction is being produced, namely, +\code{length(object$ages) + length(years) - 1}. If the Stochastic Mortality +Model doesn't have a cohort effect this argument is ignored and needs not be provided.} -\item{oxt}{optional matrix/vector or scalar of known offset to be used in +\item{oxt}{optional matrix/vector or scalar of known offset to be used in the prediction.} -\item{type}{the type of the predicted values that should be returned. The +\item{type}{the type of the predicted values that should be returned. The alternatives are \code{"link"}(default) and \code{"rates"}.} \item{...}{other arguments.} @@ -45,48 +45,49 @@ Obtain predictions from a Stochastic Mortality Model fit. } \details{ -This function evaluates -\deqn{\hat{\eta}_{xt} = o_{xt} + \alpha_x + +This function evaluates +\deqn{\hat{\eta}_{xt} = o_{xt} + \alpha_x + \sum_{i=1}^N \beta_x^{(i)}\kappa_t^{(i)} + \beta_x^{(0)}\gamma_{t-x}} for a fitted Stochastic Mortality model. In producing a prediction the static age function, \eqn{\alpha_x}, and the age-modulating parameters, \eqn{\beta_x^{(i)}, i=0, ..., N}, are taken from -the fitted model in \code{object} while the period indexes, -\eqn{\kappa_t^{(i)}, i=1,..., N}, and cohort index, \eqn{\gamma_{t-x}}, +the fitted model in \code{object} while the period indexes, +\eqn{\kappa_t^{(i)}, i=1,..., N}, and cohort index, \eqn{\gamma_{t-x}}, are taken from the function arguments. -This function can be useful, for instance, in producing forecasts of -mortality rates using time series models different to those available +This function can be useful, for instance, in producing forecasts of +mortality rates using time series models different to those available in \code{\link{forecast.fitStMoMo}} (See examples below). } \examples{ library(forecast) #Lee-Carter forecast using auto.arima -LCfit <- fit(lc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, +LCfit <- fit(lc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) -ktForLC <- forecast(auto.arima(as.vector(LCfit$kt)), h = 30) -mxtForLC <- predict(LCfit, years = 2012:2041, kt = ktForLC$mean, +ktForLC <- forecast(auto.arima(as.vector(LCfit$kt)), h = 30) +mxtForLC <- predict(LCfit, years = 2012:2041, kt = ktForLC$mean, type = "rates") mxthatLC <- fitted(LCfit, type = "rates") mxt <- LCfit$Dxt / LCfit$Ext -plot(1961:2041, (cbind(mxthatLC, mxtForLC))["80", ], type = "l", - xlab = "year", ylab = "death rate", +plot(1961:2041, (cbind(mxthatLC, mxtForLC))["80", ], type = "l", + xlab = "year", ylab = "death rate", main = "Fitted vs. Observed rates at age 80") points(1961:2011, mxt["80", ]) #Age-Period-Cohort forecast using auto.arima -APCfit <- fit(apc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, +APCfit <- fit(apc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) ktForAPC <- forecast(auto.arima(as.vector(APCfit$kt)), h = 30) gcForAPC <- forecast(auto.arima(as.vector(APCfit$gc), max.d = 1), h = 30) -mxtForAPC <- predict(APCfit, years = 2012:2041, kt = ktForAPC$mean, - gc = c(tail(APCfit$gc, 34), gcForAPC$mean), +mxtForAPC <- predict(APCfit, years = 2012:2041, kt = ktForAPC$mean, + gc = c(tail(APCfit$gc, 34), gcForAPC$mean), type = "rates") mxthatAPC <- fitted(APCfit, type = "rates") -lines(1961:2041 , (cbind(mxthatAPC, mxtForAPC))["80", ], type = "l", +lines(1961:2041 , (cbind(mxthatAPC, mxtForAPC))["80", ], type = "l", col = "blue") + } \seealso{ \code{\link{forecast.fitStMoMo}} diff --git a/man/predictLink.Rd b/man/predictLink.Rd index 56b4baa..fad07aa 100644 --- a/man/predictLink.Rd +++ b/man/predictLink.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/internalUtils.R \name{predictLink} \alias{predictLink} diff --git a/man/print.StMoMo.Rd b/man/print.StMoMo.Rd index c518e7d..4c1e1b7 100644 --- a/man/print.StMoMo.Rd +++ b/man/print.StMoMo.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/StMoMo.R \name{print.StMoMo} \alias{print.StMoMo} diff --git a/man/print.bootStMoMo.Rd b/man/print.bootStMoMo.Rd index ca1fef2..a6180f5 100644 --- a/man/print.bootStMoMo.Rd +++ b/man/print.bootStMoMo.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/bootstrapfitStMoMo.R \name{print.bootStMoMo} \alias{print.bootStMoMo} diff --git a/man/print.fitStMoMo.Rd b/man/print.fitStMoMo.Rd index aec8e23..b2ee24c 100644 --- a/man/print.fitStMoMo.Rd +++ b/man/print.fitStMoMo.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/fitStMoMo.R \name{print.fitStMoMo} \alias{print.fitStMoMo} diff --git a/man/print.forStMoMo.Rd b/man/print.forStMoMo.Rd index 8ca3a53..4d8eb96 100644 --- a/man/print.forStMoMo.Rd +++ b/man/print.forStMoMo.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/forecastfitStMoMo.R \name{print.forStMoMo} \alias{print.forStMoMo} diff --git a/man/print.simStMoMo.Rd b/man/print.simStMoMo.Rd index 94ba995..9b4ab57 100644 --- a/man/print.simStMoMo.Rd +++ b/man/print.simStMoMo.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/simulatefitStMoMo.R \name{print.simStMoMo} \alias{print.simStMoMo} diff --git a/man/processStartValues.Rd b/man/processStartValues.Rd index 4b4804a..4a6bb34 100644 --- a/man/processStartValues.Rd +++ b/man/processStartValues.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/fitStMoMo.R \name{processStartValues} \alias{processStartValues} @@ -32,7 +32,7 @@ mortality model.} a vector of intitial parameter estimates } \description{ -Convert the initial parameters supplied by the user into parameters +Convert the initial parameters supplied by the user into parameters suitable for use within \code{gnm} } \keyword{internal} diff --git a/man/residuals.fitStMoMo.Rd b/man/residuals.fitStMoMo.Rd index d2f38f2..5f29c00 100644 --- a/man/residuals.fitStMoMo.Rd +++ b/man/residuals.fitStMoMo.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/residualsfitStMoMo.R \name{residuals.fitStMoMo} \alias{residuals.fitStMoMo} @@ -7,28 +7,28 @@ \method{residuals}{fitStMoMo}(object, scale = TRUE, ...) } \arguments{ -\item{object}{an object of class \code{"fitStMoMo"} with the fitted +\item{object}{an object of class \code{"fitStMoMo"} with the fitted parameters of a stochastic mortality model.} -\item{scale}{logical indicating whether the residuals should be scaled -or not by dividing the deviance by the overdispersion of the model. +\item{scale}{logical indicating whether the residuals should be scaled +or not by dividing the deviance by the overdispersion of the model. Default is \code{TRUE}.} \item{...}{other arguments.} } \value{ -An object of class \code{"resStMoMo"} with the residuals. This +An object of class \code{"resStMoMo"} with the residuals. This object has components: \item{residuals}{ a matrix with the residuals.} \item{ages}{ ages corresponding to the rows in \code{residuals}.} \item{years}{ years corresponding to the columns in \code{residuals}.} } \description{ -Compute deviance residuals of a fitted Stochastic Mortality Model. +Compute deviance residuals of a fitted Stochastic Mortality Model. These residuals can be plotted using \code{\link{plot.resStMoMo}}. } \examples{ -CBDfit <- fit(cbd(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, +CBDfit <- fit(cbd(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) CBDres <- residuals(CBDfit) diff --git a/man/rh.Rd b/man/rh.Rd index 0fcecc7..70d8e68 100644 --- a/man/rh.Rd +++ b/man/rh.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/standardModels.R \name{rh} \alias{rh} @@ -7,32 +7,32 @@ rh(link = c("log", "logit"), cohortAgeFun = c("1", "NP")) } \arguments{ -\item{link}{defines the link function and random component associated with - the mortality model. \code{"log"} would assume that deaths follow a - Poisson distribution and use a log link while \code{"logit"} would assume - that deaths follow a Binomial distribution and a logit link.} +\item{link}{defines the link function and random component associated with +the mortality model. \code{"log"} would assume that deaths follow a +Poisson distribution and use a log link while \code{"logit"} would assume +that deaths follow a Binomial distribution and a logit link.} -\item{cohortAgeFun}{defines the cohort age modulating parameter - \eqn{\beta_x^{(0)}}. It can take values: \code{"NP"} for a non-parametric age - term or \code{"1"} for \eqn{\beta_x^{(0)}=1} (the default).} +\item{cohortAgeFun}{defines the cohort age modulating parameter +\eqn{\beta_x^{(0)}}. It can take values: \code{"NP"} for a non-parametric age +term or \code{"1"} for \eqn{\beta_x^{(0)}=1} (the default).} } \value{ An object of class \code{"StMoMo"}. } \description{ -Utility function to initialise a \code{StMoMo} object representing a +Utility function to initialise a \code{StMoMo} object representing a Renshaw and Haberman (Lee-Carter with cohorts) mortality model introduced in Renshaw and Haberman (2006). } \details{ -The created model is either a log-Poisson or a -logit-Binomial version of the Renshaw and Haberman model which has -predictor structure +The created model is either a log-Poisson or a +logit-Binomial version of the Renshaw and Haberman model which has +predictor structure \deqn{\eta_{xt} = \alpha_x + \beta^{(1)}_x\kappa_t + \beta^{(0)} \gamma_{t-x}.} or \deqn{\eta_{xt} = \alpha_x + \beta^{(1)}_x\kappa_t + \gamma_{t-x}.} depending on the value of argument \code{cohortAgeFun}. - + To ensure identifiability the following constraints are imposed \deqn{\sum_t\kappa_t = 0, \sum_x\beta^{(1)}_x = 1, \sum_c\gamma_c = 0} plus @@ -43,27 +43,29 @@ By default \eqn{\beta^{(0)}_x = 1} as this model has shown to be more stable (see Haberman and Renshaw (2011) and Hunt and Villegas (2015)). } \examples{ -LCfit <- fit(lc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, - ages = EWMaleData$ages, years = EWMaleData$years, + +LCfit <- fit(lc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, + ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) wxt <- genWeightMat(55:89, EWMaleData$years, clip = 3) -RHfit <- fit(rh(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, - ages = EWMaleData$ages, years = EWMaleData$years, - ages.fit = 55:89, wxt = wxt, start.ax = LCfit$ax, +RHfit <- fit(rh(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, + ages = EWMaleData$ages, years = EWMaleData$years, + ages.fit = 55:89, wxt = wxt, start.ax = LCfit$ax, start.bx = LCfit$bx, start.kt = LCfit$kt) plot(RHfit) + } \references{ -Haberman, S., & Renshaw, A. (2011). A comparative study of parametric -mortality projection models. Insurance: Mathematics and Economics, -48(1), 35-55. +Haberman, S., & Renshaw, A. (2011). A comparative study of parametric +mortality projection models. Insurance: Mathematics and Economics, +48(1), 35-55. -Hunt, A., & Villegas, A. M. (2015). Robustness and convergence in the -Lee-Carter model with cohorts. Insurance: Mathematics and Economics, -64, 186-202. +Hunt, A., & Villegas, A. M. (2015). Robustness and convergence in the +Lee-Carter model with cohorts. Insurance: Mathematics and Economics, +64, 186-202. -Renshaw, A. E., & Haberman, S. (2006). A cohort-based extension to the -Lee-Carter model for mortality reduction factors. +Renshaw, A. E., & Haberman, S. (2006). A cohort-based extension to the +Lee-Carter model for mortality reduction factors. Insurance: Mathematics and Economics, 38(3), 556-570. } \seealso{ diff --git a/man/scatterplotAPC.Rd b/man/scatterplotAPC.Rd index 85d883b..3e5f0a4 100644 --- a/man/scatterplotAPC.Rd +++ b/man/scatterplotAPC.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/residualsfitStMoMo.R \name{scatterplotAPC} \alias{scatterplotAPC} @@ -14,13 +14,13 @@ scatterplotAPC(mat, ages, years, plotAge = TRUE, plotYear = TRUE, \item{years}{years corresponding to the columns in \code{mat}.} -\item{plotAge}{logical value indicating if the age scatter plot should be +\item{plotAge}{logical value indicating if the age scatter plot should be produced.} -\item{plotYear}{logical value indicating if the calendar year scatter plot +\item{plotYear}{logical value indicating if the calendar year scatter plot should be produced.} -\item{plotCohort}{logical value indicating if the cohort scatter plot +\item{plotCohort}{logical value indicating if the cohort scatter plot should be produced.} \item{zeroLine}{logical valae indicating if a horizontal line at zero diff --git a/man/simulate.bootStMoMo.Rd b/man/simulate.bootStMoMo.Rd index 7379d0e..31eb751 100644 --- a/man/simulate.bootStMoMo.Rd +++ b/man/simulate.bootStMoMo.Rd @@ -1,8 +1,8 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/simulatebootStMoMo.R \name{simulate.bootStMoMo} \alias{simulate.bootStMoMo} -\title{Simulate future sample paths from a Bootstrapped Stochastic +\title{Simulate future sample paths from a Bootstrapped Stochastic Mortality Model} \usage{ \method{simulate}{bootStMoMo}(object, nsim = 1, seed = NULL, h = 50, @@ -11,45 +11,45 @@ Mortality Model} ...) } \arguments{ -\item{object}{an object of class \code{"bootStMoMo"} with the bootstrapped +\item{object}{an object of class \code{"bootStMoMo"} with the bootstrapped parameters of a stochastic mortality model.} -\item{nsim}{number of sample paths to simulate from each bootstrapped -sample. Thus if there are \code{nBoot} bootstrapped samples the total +\item{nsim}{number of sample paths to simulate from each bootstrapped +sample. Thus if there are \code{nBoot} bootstrapped samples the total number of paths will be \code{nsim * nBoot}.} -\item{seed}{either \code{NULL} or an integer that will be used in a -call to \code{\link{set.seed}} before simulating the time series. +\item{seed}{either \code{NULL} or an integer that will be used in a +call to \code{\link{set.seed}} before simulating the time series. The default, \code{NULL} will not change the random generator state.} \item{h}{number of years ahead to forecast.} -\item{oxt}{optional array/matrix/vector or scalar of known offset to be -added in the simulations. This can be used to specify any a priori known +\item{oxt}{optional array/matrix/vector or scalar of known offset to be +added in the simulations. This can be used to specify any a priori known component to be added to the simulated predictor.} -\item{gc.order}{a specification of the ARIMA model: the three components -\eqn{(p, d, q)} are the AR order, the degree of differencing, and the MA +\item{gc.order}{a specification of the ARIMA model: the three components +\eqn{(p, d, q)} are the AR order, the degree of differencing, and the MA order. The default is an ARIMA\eqn{(1, 1, 0)}.} \item{gc.include.constant}{a logical value indicating if the ARIMA model should include a constant value. The default is \code{TRUE}.} -\item{jumpchoice}{option to select the jump-off rates, i.e. the rates -from the final year of observation, to use in projections of mortality -rates. \code{"fit"}(default) uses the fitted rates and \code{"actual"} +\item{jumpchoice}{option to select the jump-off rates, i.e. the rates +from the final year of observation, to use in projections of mortality +rates. \code{"fit"}(default) uses the fitted rates and \code{"actual"} uses the actual rates from the final year.} \item{kt.lookback}{optional argument to specify the look-back window to use -in the estimation of the MRWD for period indexes. By default all the -estimated values are used in estimating the MRWD. If -\code{kt.lookback} is provided then the last \code{kt.lookback} +in the estimation of the MRWD for period indexes. By default all the +estimated values are used in estimating the MRWD. If +\code{kt.lookback} is provided then the last \code{kt.lookback} years of \eqn{\kappa_t^{(i)}, i = 1,..N,} are used.} \item{gc.lookback}{optional argument to specify the look-back window to use -in the estimation of the ARIMA model for the cohort effect. By -default all the estimated values are used in estimating the ARIMA -model. If \code{gc.lookback} is provided then the last +in the estimation of the ARIMA model for the cohort effect. By +default all the estimated values are used in estimating the ARIMA +model. If \code{gc.lookback} is provided then the last \code{gc.lookback} years of \eqn{\gamma_{t-x}} are used.} \item{...}{other arguments.} @@ -59,40 +59,40 @@ A list of class \code{"simStMoMo"} with components \item{rates}{ a three dimensional array with the future simulated rates.} -\item{ages}{ vector of ages corresponding to the first dimension of +\item{ages}{ vector of ages corresponding to the first dimension of \code{rates}.} -\item{years}{ vector of years for which a simulations has been produced. -This corresponds to the second dimension of \code{rates}.} - -\item{kt.s}{ information on the simulated paths of the period indices of +\item{years}{ vector of years for which a simulations has been produced. +This corresponds to the second dimension of \code{rates}.} + +\item{kt.s}{ information on the simulated paths of the period indices of the model. This is a list with the simulated paths of \eqn{\kappa_t} - (\code{sim}) and the \code{years} for which simulations were produced. + (\code{sim}) and the \code{years} for which simulations were produced. If the mortality model does not have any age-period terms (i.e. \eqn{N=0}) this is set to \code{NULL}.} - + \item{gc.s}{ information on the simulated paths of the cohort index of the - model. This is a list with the simulated paths of \eqn{\gamma_c} - (\code{sim}) and the \code{cohorts} for which simulations were produced. - If the mortality model does not have a cohort effect this is set to - \code{NULL}.} - -\item{oxt.s}{ a three dimensional array with the offset used in the + model. This is a list with the simulated paths of \eqn{\gamma_c} + (\code{sim}) and the \code{cohorts} for which simulations were produced. + If the mortality model does not have a cohort effect this is set to + \code{NULL}.} + +\item{oxt.s}{ a three dimensional array with the offset used in the simulations.} -\item{fitted}{ a three dimensional array with the in-sample rates of the -model for the years for which the mortality model was fitted +\item{fitted}{ a three dimensional array with the in-sample rates of the +model for the years for which the mortality model was fitted (and bootstrapped).} - + \item{jumpchoice}{Jump-off method used in the simulation.} - - \item{model}{the bootstrapped model from which the simulations were + + \item{model}{the bootstrapped model from which the simulations were produced.} } \description{ Simulate future sample paths from a Bootstrapped Stochastic Mortality Model. The period indexes \eqn{\kappa_t^{(i)}, i = 1,..N,} are modelled -using a Multivariate Random Walk with Drift. The cohort index +using a Multivariate Random Walk with Drift. The cohort index \eqn{\gamma_{t-x}} is modelled using an ARIMA\eqn{(p, d, q)}. By default an ARIMA\eqn{(1, 1, 0)} with a constant is used. } @@ -104,25 +104,26 @@ For further details see \code{\link{simulate.fitStMoMo}}. \dontrun{ #Lee-Carter: Compare projection with and without parameter uncertainty library(fanplot) -LCfit <- fit(lc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, +LCfit <- fit(lc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, ages = EWMaleData$ages, years = EWMaleData$years) LCResBoot <- bootstrap(LCfit, nBoot = 500) LCResBootsim <- simulate(LCResBoot) -LCsim <- simulate(LCfit, nsim = 500)#' -plot(LCfit$years, log(LCfit$Dxt / LCfit$Ext)["10", ], +LCsim <- simulate(LCfit, nsim = 500)#' +plot(LCfit$years, log(LCfit$Dxt / LCfit$Ext)["10", ], xlim = range(LCfit$years, LCsim$years), - ylim = range(log(LCfit$Dxt / LCfit$Ext)["10", ], + ylim = range(log(LCfit$Dxt / LCfit$Ext)["10", ], log(LCsim$rates["10", , ])), - type = "l", xlab = "year", ylab = "log rate", - main = "Mortality rate projection at age 10 with and without parameter uncertainty") -fan(t(log(LCResBootsim$rates["10", , ])),start = LCResBootsim$years[1], - probs = c(2.5, 10, 25, 50, 75, 90, 97.5), n.fan = 4, + type = "l", xlab = "year", ylab = "log rate", + main = "Mortality rate projection at age 10 with and without parameter uncertainty") +fan(t(log(LCResBootsim$rates["10", , ])),start = LCResBootsim$years[1], + probs = c(2.5, 10, 25, 50, 75, 90, 97.5), n.fan = 4, fan.col = colorRampPalette(c(rgb(0, 0, 1), rgb(1, 1, 1))), ln = NULL) fan(t(log(LCsim$rates["10", 1:(length(LCsim$years) - 3), ])), start = LCsim$years[1], probs = c(2.5, 10, 25, 50, 75, 90, 97.5), - n.fan = 4, fan.col = colorRampPalette(c(rgb(1, 0, 0), rgb(1, 1, 1))), + n.fan = 4, fan.col = colorRampPalette(c(rgb(1, 0, 0), rgb(1, 1, 1))), ln = NULL) } + } \seealso{ \code{\link{bootstrap.fitStMoMo}}, \code{\link{simulate.fitStMoMo}} diff --git a/man/simulate.fitStMoMo.Rd b/man/simulate.fitStMoMo.Rd index 43bbedc..58ff786 100644 --- a/man/simulate.fitStMoMo.Rd +++ b/man/simulate.fitStMoMo.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/simulatefitStMoMo.R \name{simulate.fitStMoMo} \alias{simulate.fitStMoMo} @@ -10,43 +10,43 @@ ...) } \arguments{ -\item{object}{an object of class \code{"fitStMoMo"} with the fitted +\item{object}{an object of class \code{"fitStMoMo"} with the fitted parameters of a stochastic mortality model.} \item{nsim}{number of sample paths to simulate.} -\item{seed}{either \code{NULL} or an integer that will be used in a -call to \code{\link{set.seed}} before simulating the time series. +\item{seed}{either \code{NULL} or an integer that will be used in a +call to \code{\link{set.seed}} before simulating the time series. The default, \code{NULL} will not change the random generator state.} \item{h}{number of years ahead to forecast.} -\item{oxt}{optional matrix/vector or scalar of known offset to be -added in the simulations. This can be used to specify any a priori +\item{oxt}{optional matrix/vector or scalar of known offset to be +added in the simulations. This can be used to specify any a priori known component to be added to the simulated predictor.} -\item{gc.order}{a specification of the ARIMA model: the three components -\eqn{(p, d, q)} are the AR order, the degree of differencing, and the MA +\item{gc.order}{a specification of the ARIMA model: the three components +\eqn{(p, d, q)} are the AR order, the degree of differencing, and the MA order. The default is an ARIMA\eqn{(1, 1, 0)}.} \item{gc.include.constant}{a logical value indicating if the ARIMA model should include a constant value. The default is \code{TRUE}.} -\item{jumpchoice}{option to select the jump-off rates, i.e. the rates -from the final year of observation, to use in projections of mortality -rates. \code{"fit"}(default) uses the fitted rates and \code{"actual"} +\item{jumpchoice}{option to select the jump-off rates, i.e. the rates +from the final year of observation, to use in projections of mortality +rates. \code{"fit"}(default) uses the fitted rates and \code{"actual"} uses the actual rates from the final year.} \item{kt.lookback}{optional argument to specify the look-back window to use -in the estimation of the MRWD for period indexes. By default all the -estimated values are used in estimating the MRWD. If -\code{kt.lookback} is provided then the last \code{kt.lookback} +in the estimation of the MRWD for period indexes. By default all the +estimated values are used in estimating the MRWD. If +\code{kt.lookback} is provided then the last \code{kt.lookback} years of \eqn{\kappa_t^{(i)}, i = 1,..N,} are used.} \item{gc.lookback}{optional argument to specify the look-back window to use -in the estimation of the ARIMA model for the cohort effect. By -default all the estimated values are used in estimating the ARIMA -model. If \code{gc.lookback} is provided then the last +in the estimation of the ARIMA model for the cohort effect. By +default all the estimated values are used in estimating the ARIMA +model. If \code{gc.lookback} is provided then the last \code{gc.lookback} years of \eqn{\gamma_{t-x}} are used.} \item{...}{other arguments.} @@ -56,38 +56,38 @@ A list of class \code{"simStMoMo"} with components: \item{rates}{ a three dimensional array with the future simulated rates.} -\item{ages}{ vector of ages corresponding to the first dimension of +\item{ages}{ vector of ages corresponding to the first dimension of \code{rates}.} -\item{years}{vector of years for which a simulations has been produced. -This corresponds to the second dimension of \code{rates}.} +\item{years}{vector of years for which a simulations has been produced. +This corresponds to the second dimension of \code{rates}.} -\item{kt.s}{ information on the simulated paths of the period indexes -of the model. This is a list with the \code{model} fitted to -\eqn{\kappa_t}; the simulated paths (\code{sim}); and the \code{years} -for which simulations were produced. If the mortality model does not +\item{kt.s}{ information on the simulated paths of the period indexes +of the model. This is a list with the \code{model} fitted to +\eqn{\kappa_t}; the simulated paths (\code{sim}); and the \code{years} +for which simulations were produced. If the mortality model does not have any age-period terms (i.e. \eqn{N=0}) this is set to \code{NULL}.} - -\item{gc.s}{ information on the simulated paths of the cohort index of -the model. This is a list with the \code{model} fitted to \eqn{\gamma_c}; -the simulated paths (\code{sim}); and the \code{cohorts} for which -simulations were produced. If the mortality model does not have a cohort -effect this is set to \code{NULL}.} - -\item{oxt.s}{ a three dimensional array with the offset used in the + +\item{gc.s}{ information on the simulated paths of the cohort index of +the model. This is a list with the \code{model} fitted to \eqn{\gamma_c}; +the simulated paths (\code{sim}); and the \code{cohorts} for which +simulations were produced. If the mortality model does not have a cohort +effect this is set to \code{NULL}.} + +\item{oxt.s}{ a three dimensional array with the offset used in the simulations.} -\item{fitted}{ a three dimensional array with the in-sample rates of +\item{fitted}{ a three dimensional array with the in-sample rates of the model for the years for which the mortality model was fitted.} - + \item{jumpchoice}{Jump-off method used in the simulation.} - + \item{model}{ the model fit from which the simulations were produced.} } \description{ Simulate future sample paths from a Stochastic Mortality Model. The period indexes \eqn{\kappa_t^{(i)}, i = 1,..N,} are modelled -using a Multivariate Random Walk with Drift. The cohort index +using a Multivariate Random Walk with Drift. The cohort index \eqn{\gamma_{t-x}} is modelled using an ARIMA\eqn{(p, d, q)}. By default an ARIMA\eqn{(1, 1, 0)} with a constant is used. } @@ -95,81 +95,81 @@ an ARIMA\eqn{(1, 1, 0)} with a constant is used. Fitting and simulation of the Multivariate Random Walk with Drift for the period indexes is done using the function \code{\link{mrwd}}. Fitting and simulation of the ARIMA model for the cohort index -is done with function \code{\link[forecast]{Arima}} from package -\pkg{forecast}. See the latter function for further details on -input arguments \code{gc.order} and \code{gc.include.constant}. +is done with function \code{\link[forecast]{Arima}} from package +\pkg{forecast}. See the latter function for further details on +input arguments \code{gc.order} and \code{gc.include.constant}. -Note that in some cases simulations of the +Note that in some cases simulations of the cohort effects may be needed for a horizon longer than \code{h}. -This is the case when in the fitted model the most recent cohorts -have been zero weighted. The simulated cohorts can be seen in +This is the case when in the fitted model the most recent cohorts +have been zero weighted. The simulated cohorts can be seen in \code{gc.s$cohorts}. } \examples{ #Lee-Carter -LCfit <- fit(lc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, +LCfit <- fit(lc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89) LCsim <- simulate(LCfit, nsim = 100) par(mfrow=c(1, 2)) plot(LCfit$years, LCfit$kt[1, ], xlim = range(LCfit$years, LCsim$kt.s$years), - ylim = range(LCfit$kt, LCsim$kt.s$sim), type = "l", - xlab = "year", ylab = "kt", + ylim = range(LCfit$kt, LCsim$kt.s$sim), type = "l", + xlab = "year", ylab = "kt", main = "Lee-Carter: Simulated paths of the period index kt") matlines(LCsim$kt.s$years, LCsim$kt.s$sim[1, , ], type = "l", lty = 1) -plot(LCfit$years, (LCfit$Dxt / LCfit$Ext)["65", ], +plot(LCfit$years, (LCfit$Dxt / LCfit$Ext)["65", ], xlim = range(LCfit$years, LCsim$years), - ylim = range((LCfit$Dxt / LCfit$Ext)["65", ], LCsim$rates["65", , ]), - type = "l", xlab = "year", ylab = "rate", + ylim = range((LCfit$Dxt / LCfit$Ext)["65", ], LCsim$rates["65", , ]), + type = "l", xlab = "year", ylab = "rate", main = "Lee-Carter: Simulated mortality rates at age 65") matlines(LCsim$years, LCsim$rates["65", , ], type = "l", lty = 1) #APC par(mfrow=c(1, 3)) wxt <- genWeightMat(55:89, EWMaleData$years, clip = 3) -APCfit <- fit(apc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, - ages = EWMaleData$ages, years = EWMaleData$years, +APCfit <- fit(apc(), Dxt = EWMaleData$Dxt, Ext = EWMaleData$Ext, + ages = EWMaleData$ages, years = EWMaleData$years, ages.fit = 55:89, wxt = wxt) APCsim <- simulate(APCfit, nsim = 100, gc.order = c(1, 1, 0)) -plot(APCfit$years, APCfit$kt[1, ], +plot(APCfit$years, APCfit$kt[1, ], xlim = range(APCfit$years, APCsim$kt.s$years), ylim = range(APCfit$kt, APCsim$kt.s$sim), type = "l", xlab = "year", ylab = "kt", main = "APC: Simulated paths of the period index kt") matlines(APCsim$kt.s$years, APCsim$kt.s$sim[1, , ], type = "l", lty = 1) -plot(APCfit$cohorts, APCfit$gc, +plot(APCfit$cohorts, APCfit$gc, xlim = range(APCfit$cohorts, APCsim$gc.s$cohorts), ylim = range(APCfit$gc, APCsim$gc.s$sim, na.rm = TRUE), type = "l", - xlab = "year", ylab = "kt", + xlab = "year", ylab = "kt", main = "APC: Simulated paths of the cohort index (ARIMA(1,1,0))") matlines(APCsim$gc.s$cohorts, APCsim$gc.s$sim, type = "l", lty = 1) -plot(APCfit$years, (APCfit$Dxt / APCfit$Ext)["65", ], +plot(APCfit$years, (APCfit$Dxt / APCfit$Ext)["65", ], xlim = range(APCfit$years, APCsim$years), - ylim = range((APCfit$Dxt/APCfit$Ext)["65", ], APCsim$rates["65", , ]), - type = "l", xlab = "year", ylab = "rate", + ylim = range((APCfit$Dxt/APCfit$Ext)["65", ], APCsim$rates["65", , ]), + type = "l", xlab = "year", ylab = "rate", main = "APC: Simulated of mortality rates at age 65") matlines(APCsim$years, APCsim$rates["65", , ], type = "l", lty = 1) #Compare LC and APC library(fanplot) par(mfrow=c(1, 1)) -plot(LCfit$years, (LCfit$Dxt / LCfit$Ext)["65", ], +plot(LCfit$years, (LCfit$Dxt / LCfit$Ext)["65", ], xlim = range(LCfit$years, LCsim$years), - ylim = range((LCfit$Dxt / LCfit$Ext)["65", ], LCsim$rates["65", , ], - APCsim$rates["65", , ]), type = "l", xlab = "year", ylab = "rate", + ylim = range((LCfit$Dxt / LCfit$Ext)["65", ], LCsim$rates["65", , ], + APCsim$rates["65", , ]), type = "l", xlab = "year", ylab = "rate", main = "Fan chart of mortality rates at age 65 (LC vs. APC)") -fan(t(LCsim$rates["65", , ]), start = LCsim$years[1], +fan(t(LCsim$rates["65", , ]), start = LCsim$years[1], probs = c(2.5, 10, 25, 50, 75, 90, 97.5), n.fan = 4, fan.col = colorRampPalette(c(rgb(1, 0, 0), rgb(1, 1, 1))), ln = NULL) -fan(t(APCsim$rates["65", 1:(length(APCsim$years) - 3), ]), - start = APCsim$years[1], probs = c(2.5, 10, 25, 50, 75, 90, 97.5), - n.fan = 4, fan.col = colorRampPalette(c(rgb(0, 0, 1), rgb(1, 1, 1))), - ln = NULL) +fan(t(APCsim$rates["65", 1:(length(APCsim$years) - 3), ]), + start = APCsim$years[1], probs = c(2.5, 10, 25, 50, 75, 90, 97.5), + n.fan = 4, fan.col = colorRampPalette(c(rgb(0, 0, 1), rgb(1, 1, 1))), + ln = NULL) } \seealso{ \code{\link{forecast.fitStMoMo}} diff --git a/man/simulate.mrwd.Rd b/man/simulate.mrwd.Rd index d7022cb..acd3701 100644 --- a/man/simulate.mrwd.Rd +++ b/man/simulate.mrwd.Rd @@ -1,4 +1,4 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand +% Generated by roxygen2: do not edit by hand % Please edit documentation in R/mrwd.R \name{simulate.mrwd} \alias{simulate.mrwd} @@ -11,14 +11,14 @@ \item{nsim}{number of periods for the simulated series.} -\item{seed}{either \code{NULL} or an integer that will be used in a -call to \code{\link{set.seed}} before simulating the time series. +\item{seed}{either \code{NULL} or an integer that will be used in a +call to \code{\link{set.seed}} before simulating the time series. The default, \code{NULL} will not change the random generator state.} \item{...}{other arguments.} } \description{ -Returns one simulated path of the Multivariate +Returns one simulated path of the Multivariate Random Walk with Drift model in \code{object}. }