\documentclass[nojss]{jss}
\usepackage{lifecon}
\usepackage{graphicx}
\usepackage{amsmath}
%\usepackage{hyperref}
\usepackage[utf8]{inputenc}
\usepackage{draftwatermark}
\SetWatermarkText{Draft}
\SetWatermarkScale{1.5}

%\usepackage{myVignette}
%\VignetteIndexEntry{Multiple decrements tables with lifecontingencies package}
%%\VignetteDepends{lifecontingencies}
%%\VignetteKeywords{multiple decrements tables, lifecontingencies, R}
%%\VignettePackage{lifecontingencies}
% need no \usepackage{Sweave.sty}
%\SweaveOpts{prefix.string=Figures/fig}

\author{Giorgio Alfredo Spedicato, ACAS}


\title{Multiple decrements tables with \pkg{lifecontingencies} package}

\Plainauthor{Giorgio Alfredo Spedicato, Gian Paolo Clemente}
\Plaintitle{Multiple decrements tables with lifecontingencies packages}
\Shorttitle{Multiple decrements tables}
\Keywords{multiple decrements tables, lifecontingencies, \proglang{R}}
\Plainkeywords{multiple decrements tables, lifecontingencies, R}



\Abstract{
This paper introduces the \code{mdt} class within \pkg{lifecontingencies}
\proglang{R} package, that handles multiple decrements models for actuarial applications. Applied examples will show how to perform demographic and actuarial calculation with the package.}

\Keywords{actuarial mathematics, multiple decrement models,
\pkg{lifecontingencies}} \Plainkeywords{actuarial mathematics, multiple
decrement models, lifecontingencies}


\Address{
  Giorgio Alfredo Spedicato\\
  Ph.D ACAS C.STAT\\
  Via Firenze 11
  20037 Italy\\
  E-mail: \email{spedygiorgio@gmail.com}\\
  URL: \url{https://github.com/spedygiorgio/lifecontingencies}
}


\begin{document}

<<echo=FALSE,print=FALSE,results=hide>>=
options(width=80, prompt='R> ')
@



\section{Introduction}

\subsection{Multiple Decrement Models within R}

As of 2014 no \proglang{R} package provides easy tools to manage multiple
decrement tables for actuarial appliocations. Multiple decrement tables are the basis of many applications, as demography, medicine and actuarial science.\\
Until now no \proglang{R} package provides a good tool to manage multiple
decrement tables, even if \cite{deshmukh2012multiple} provides an \proglang{R}
based focus on multiple decrement tables with applications in R. The topic is deeply related to multistate analysis of life histories on which \cite{willekens2014multistate} provide a very good introduction.\\

This paper introduces the \code{mdt} class that has been specifically engineered
to manage multiple decrements models with R. Applied examples will follows.\\

\subsection{A review of Discrete Multiple Decrement Mathematics}

Following notation in \cite{finanMLC}, we provide definitions of the key quantities that allow to understand the main concepts regarding Multiple Decrement (MD) theory. Be $l_x^{(\tau )} = \sum\limits_{j = 1 \ldots m} {l_x^{(j)}}$ survivors to age $x$ that will, at future ages, be fully depleted by $m$ causes of decrement. $d_{x}^{(j)}=l_{x}^{(j)}-l_{x+1}^{(j)}$ represents the expected number of lives exiting from the population between ages $x$ and $x + 1$ due to decrement $j$. Therefore it follows that $_nd_x^{(j)} = \sum\limits_{t = 0 \ldots n - 1} {d_{x + t}^{(j)}}$.\\
The probability that a life $x$ will leave the group within one year as a result of decrement $j$ is $_nq_x^{(j)} = \frac{{_nd_x^{(j)}}}{{l_x^{(\tau )}}}$. It follows that $q_x^{(\tau )} = \sum\limits_{j = 1}^m {q_x^{(j)}}$ and that $_tq_x^{(\tau )} = 1{ - _t}p_x^{(\tau )} = \sum\limits_j {_tq_x^{(\tau )}}$.


\section{Multiple Decrement Models within lifecontingencies Package}
\subsection{The mdt class}

Examples in this paper are worked on slides provided in \cite{valdezSlides}.
First of all, we load the R package.

<<load, keep.source=TRUE>>=
library(lifecontingencies)
@

Then  we create a \code{mdt} class object. We can use the first example found on
\cite[p. 4]{valdezSlide}.

<<mdt1,  keep.source=TRUE>>=
valdezDf<-data.frame(
		x=c(50:54),
		lx=c(4832555,4821937,4810206,4797185,4782737),
		hearth=c(5168, 5363, 5618, 5929, 6277),
		accidents=c(1157, 1206, 1443, 1679,2152),
		other=c(4293,5162,5960,6840,7631)
)
valdezMdt<-new("mdt",name="ValdezExample",table=valdezDf)
@

The \code{mdt} class is an S4 class object \citep{chambers2008software}
comprised by a character slot \code{name} and a \code{data.frame} slot
\code{table} that is composed by following columns:
\begin{enumerate}
  \item \code{x}: the age, from 0 to $\omega$.
  \item \code{lx}: the subject living (at risk) at the beginning of age.
  \item one or more colums for different causes of decrements.
 \end{enumerate}
 
 Values within \code{table} item represents absolute number of subjects at risk at the beginning of age $x$ and dying for cause $j$ during period $x$ - $x+1$.\\

Within the various methods defined within the \code{mdt} class,
\code{setValidity} performs consistency checks to properly create the \code{mdt}
object. In particular, it verifies whether:
\begin{enumerate}
  \item \code{x} and \code{lx} exist and that they are consistent. \code{x}
  should start from 0 and flows by increments of one. The first \code{lx} value should be
  equal to the sum of all decrements and that $l_{x}=l_{x-1}-\left( d_{x-1,1} +
  d_{x-1,2} + \ldots + d_{x-1,k} \right)$ for any $x$.
  \item If the decrements (or x and lx) have been provided only for partial
  ages, the table is completed below (from 0 to $l_{x-1}$) assuming a decrement
  rate of 0.01 for the first cause of death.
  \item if the decrements at last provided age, $\omega$, do not sum to
  $l_{\omega}$, the table is incremented by one row such as $lx_{\omega+1}=lx_{\omega}-\left( d_{\omega,1} + d_{\omega,2} + 
  \ldots + d_{\omega,j} \right)$.
 \end{enumerate}

As shown, when the table is sanitized the operations performed are reported on
logs.

 An internal function, \code{.tableSanitizer} tries to fix the limitations on
 the input table in order it to meet the class definition requirements.
 
 Table can be viewed thanks to a \code{print} and \code{show} method (output omitted for simplicity). Similarly, it is possible to export a \code{mdt} to a \code{data.frame} or to a \code{markovchainList} object (from \pkg{markovchain} package).
 
<<md3a, keep.source=TRUE, eval=FALSE>>=
print(valdezMdt)
@

 
<<md3b, keep.source=TRUE>>=
valdezDf<-as(valdezMdt,"data.frame")
require(markovchain)
valdezMarkovChainList<-as(valdezMdt,"markovchainList")
@

Two specific methods have been defined for \code{mdt} class objects:
\code{getOmega}, that returns the maximum attainable age (similar to the one of
\code{lifetable} class), and \code{getDecrements}, that returns the decrements (by means of the names within table 
slot different from x and lx).

<<mdt4, keep.source=TRUE>>=
getOmega(valdezMdt)
getDecrements(valdezMdt)
@

A \code{summary} method is available as well.

<<summary, keep.source=TRUE>>=
summary(valdezMdt)
@

\subsection{Decrement probabilities calculation}


The \pkg{lifecontingencies} package makes easy to compute $d_{x}^{(j)}$,
${}_{n}d_{x}^{(j)}$ as well as ${}_{n}d_{x}^{(\tau)}$ quantities thanks to
\code{dxt} function.

<<dx1, keep.source=TRUE>>=
dxt(valdezMdt,x=51,decrement="other")
dxt(valdezMdt,x=51,t=2, decrement="other")
dxt(valdezMdt,x=51)
@

Probabilities could be computed as well.

<<dx2, keep.source=TRUE>>=
dxt(valdezMdt,x=51,t=2, decrement="other")
pxt(valdezMdt,x=50,t=3)
qxt(valdezMdt,x=53,t=2,decrement=1)
@

It is possible to generate random traiectories of a life subject to multiple cause of decrements as the following code shows.

<<randomSamples, keep.source=TRUE>>=
rmdt(n = 2,object = valdezMdt,x = 50,t = 2)
@

\section{Actuarial Applications}

The package now offers limited capabilities to fit multiple decrement insurances, e.g. $(\lcterm{A}{x}{n})^{ (1)}$

The example in \cite[p. 674]{finanMLC}, cites: A 3-year term issued to (16) pays 20,000 at the end of year of death if death results from an accident. The \code{mdt} table is below created.

<<act1, keep.source=TRUE>>=
myTable<-data.frame(x=c(16,17,18),
  lx=c(20000,17600,14520),
  da=c(1300,1870,2380),
  doc=c(1100,1210,1331)
)
myMdt<-new("mdt",table=myTable,name="Sample")
@

The value of $(\lcterm{A}{16}{3})^{( a )}$ is below calculated

<<act2, keep.source=TRUE>>=
Axn.mdt(object=myMdt,x=16,i=.1,decrement="da")
@


\bibliography{lifecontingenciesBiblio}


\end{document}
