Add examples

CRAN requires examples for all functions => Start adding them.
Export and document deathProbabilitiesIndividual and periodDeathProbabilitiesIndividual

NAMESPACE

@@ -23,6 +23,7 @@ export(mortalityTables.load)
 export(pensionTable)
 export(pensionTables.list)
 export(pensionTables.load)
+export(periodDeathProbabilitiesIndividual)
 export(plotMortalityTableComparisons)
 export(plotMortalityTables)
 export(plotMortalityTrend)

R/deathProbabilities.R

@@ -7,6 +7,11 @@ NULL
 #' @param ... Other parameters (currently unused)
 #' @param YOB The birth year for which the death probabilities should be calculated
 #'
+#' @examples
+#' mortalityTables.load("Austria_Annuities")
+#' deathProbabilities(AVOe2005R.male, YOB = 1975)
+#' deathProbabilities(AVOe2005R.male, YOB = 2017)
+#'
 #' @exportMethod deathProbabilities
 setGeneric("deathProbabilities", function(object, ..., YOB = 1975) standardGeneric("deathProbabilities"));
 
@@ -73,4 +78,3 @@ setMethod("deathProbabilities","mortalityTable.mixed",
               mixedqx = (object@weight1 * qx1 + object@weight2 * qx2)/(object@weight1 + object@weight2) * (1 + object@loading);
               object@modification(mixedqx)
           })
-

R/getCohortTable.R

@@ -7,6 +7,12 @@ NULL
 #' @param YOB The birth year for which the life table should be calculated
 #' @param ... Other parameters (currently unused)
 #'
+#' @examples
+#' mortalityTables.load("Austria_Annuities")
+#' tb75 = getCohortTable(AVOe2005R.male, YOB = 1975)
+#' # The tb75 is a fixed table with no trend any more
+#' plot(AVOe2005R.male, tb75, Period = 2017)
+#'
 #' @exportMethod getCohortTable
 setGeneric("getCohortTable", function(object, YOB, ...) standardGeneric("getCohortTable"));
 

R/getPeriodTable.R

@@ -8,6 +8,12 @@ NULL
 #'        be determined
 #' @param ... Other parameters (currently unused)
 #'
+#' @examples
+#' mortalityTables.load("Austria_Annuities")
+#' tb17 = getPeriodTable(AVOe2005R.male, Period = 2017)
+#' # The tb17 is a fixed table with no trend any more
+#' plot(AVOe2005R.male, tb17, YOB = 1975)
+#'
 #' @exportMethod getPeriodTable
 setGeneric("getPeriodTable",
            function(object, Period, ...)

R/lifeTable.R

@@ -7,13 +7,20 @@ NULL
 #' @param ... Parameters to be passed to the \code{deathProbabilities} method
 #'            of the life table
 #'
+#' @examples
+#' library("lifecontingencies")
+#' mortalityTables.load("Austria_Annuities")
+#' lifeTable(AVOe2005R.male, YOB = 2017)
+#' axn(lifeTable(AVOe2005R.male, YOB = 1975), x = 65, i = 0.03)
+#' axn(lifeTable(AVOe2005R.male, YOB = 2017), x = 65, i = 0.03)
+#'
 #' @exportMethod lifeTable
 setGeneric("lifeTable", function(object, ...) standardGeneric("lifeTable"));
 
 #' @describeIn lifeTable Return the lifetable object (package lifecontingencies)
 #'             for the cohort life table
 setMethod("lifeTable","mortalityTable",
-          function (object,  ...) {
+          function(object,  ...) {
               qx = deathProbabilities(object, ...);
               if (qx[[length(qx)]] != 1) {
                   qx = c(qx, 1, 1);

R/makeQxDataFrame.R

@@ -13,6 +13,10 @@
 #'        probabilities (i.e. the q_x for all ages are divided by the
 #'        corresponding probabilities of the reference table)
 #'
+#' @examples
+#' mortalityTables.load("Austria_Annuities")
+#' makeQxDataFrame(AVOe2005R.male, AVOe2005R.female, YOB = 1975)
+#'
 #' @export
 makeQxDataFrame = function(..., YOB = 1972, Period = NA, reference = NULL) {
     # If reference is given, normalize all probabilities by that table!

R/mortalityComparisonTable.R

@@ -58,5 +58,3 @@ mortalityComparisonTable = function(table1, table2, years, ages, binsize = 5, ..
 
     averages
 }
-
-# mortalityComparisonTable(AVOe2008P.female.aa, AVOe2008P.male.aa, years = seq(1932, 2022, by = 10), ages = 15:119, binsize=10)

R/mortalityImprovement.R

 #' @include mortalityTable.R mortalityTable.period.R mortalityTable.ageShift.R mortalityTable.trendProjection.R mortalityTable.improvementFactors.R mortalityTable.mixed.R
 NULL
 
-#' Return the mortality trend / yearly log-mortality improvement of the given period or the given generation.
+#' Return the mortality trend (yearly log-death-probability improvement) of the given period or the given generation.
 #'
 #' @param object The life table object (class inherited from mortalityTable)
 #' @param ... Other parameters (currently unused)
 #' @param YOB The birth year for which the mortality improvement should be calculated
-#' @param Period The observation year for which the mortality improvement should be calculated. If both YOB and Period are given, YOB is ignored.
+#' @param Period The observation year for which the mortality improvement should
+#'               be calculated. If both YOB and Period are given, YOB is ignored.
+#'
+#' @examples
+#' mortalityTables.load("Austria_Annuities")
+#' # AVOe 2005R includes a trend decline by default, compare the exact table with the table without decline:
+#' mortalityImprovement(AVOe2005R.male, Period = 2017)
+#' mortalityImprovement(AVOe2005R.male.nodamping, Period = 2017)
 #'
 #' @exportMethod mortalityImprovement
 setGeneric("mortalityImprovement", function(object, ..., Period = NULL, YOB = 1975) standardGeneric("mortalityImprovement"));

R/mortalityTable.ageShift.R

@@ -8,6 +8,15 @@ NULL
 #'
 #' @slot ageShifts  A \code{data.frame} with columns \code{YOB} and \code{shifts} giving the age shifts for each birth year
 #'
+#' @examples
+#' mortalityTables.load("Austria_Annuities_AVOe2005R")
+#' tb = mortalityTable.ageShift(
+#'     ages = ages(AVOe2005R.male),
+#'     deathProbs = deathProbabilities(AVOe2005R.male, YOB = 1992),
+#'     ageShifts = generateAgeShift(1, c(1962, 1985, 2000, 2015, 2040, 2070)))
+#' # The cohort tables for different birth years are just the base probabilities with modified ages
+#' plot(getCohortTable(tb, YOB = 1963), getCohortTable(tb, YOB = 2017))
+#'
 #' @export mortalityTable.ageShift
 #' @exportClass mortalityTable.ageShift
 mortalityTable.ageShift = setClass(
@@ -30,11 +39,13 @@ mortalityTable.ageShift = setClass(
 #' @param YOBs    Vector of birth years in which the age shift changes by \code{step}. The last entry gives the first birth year that does not have any shift defined any more.
 #' @param step    How much the age shift changes in each year given in the \code{YOBs} vector
 #'
-#' @examples generateAgeShift(1, YOBs = c(1922, 1944, 1958, 1973, 1989, 2006, 2023, 2041, 2056))
+#' @examples
+#' generateAgeShift(initial = 1, YOBs = c(1922, 1944, 1958, 1973, 1989, 2006, 2023, 2041, 2056))
+#'
 #' @export
 generateAgeShift = function(initial = 0, YOBs = c(1900, 2100), step = -1) {
     lns = diff(YOBs)
-    shifts = unlist(mapply(rep, initial + step * 0:(length(lns)-1), lns, SIMPLIFY = TRUE))
-    data.frame(shifts = shifts, row.names = YOBs[1]:(utils::tail(YOBs, 1)-1))
+    shifts = unlist(mapply(rep, initial + step * 0:(length(lns) - 1), lns, SIMPLIFY = TRUE))
+    data.frame(shifts = shifts, row.names = YOBs[1]:(utils::tail(YOBs, 1) - 1))
 }
 

R/mortalityTable.improvementFactors.R

@@ -11,6 +11,22 @@ NULL
 #'                   describes the death probabilities in this year)
 #' @slot improvement Yearly improvement factors per age
 #'
+#' @examples
+#' mortalityTables.load("Austria_Annuities_AVOe2005R")
+#' # AVÖ 2005R base table with yearly improvements of 3% for age 0, linearly
+#' # decreasing to 0% for age 120.
+#' tb = mortalityTable.improvementFactors(
+#'     ages = ages(AVOe2005R.male),
+#'     deathProbs = periodDeathProbabilities(AVOe2005R.male, Period = 2002),
+#'     baseYear = 2002,
+#'     improvement = 0.03 * (1 - ages(AVOe2005R.male)/121),
+#'     name = "AVÖ 2005R base with linearly falling improvements (DEMO)"
+#' )
+#' # Yearly trend is declining:
+#' plotMortalityTrend(tb, AVOe2005R.male, Period = 2017, title = "Mortality Trend")
+#' # The cohort tables for different birth years:
+#' plot(getCohortTable(tb, YOB = 1963), getCohortTable(tb, YOB = 2017))
+#'
 #' @export mortalityTable.improvementFactors
 #' @exportClass mortalityTable.improvementFactors
 mortalityTable.improvementFactors = setClass(

R/mortalityTable.jointLives.R

@@ -9,6 +9,16 @@ setClassUnion("mortalityTable(s)", c("mortalityTable", "list"))
 #'
 #' @slot table The \code{mortalityTable} object for all lives (vector if different tables should be used for the different persons)
 #'
+#' @examples
+#' mortalityTables.load("Germany_Census")
+#' table.JL = mortalityTable.jointLives(
+#'     name = "ADSt 24/26 auf verbundene Leben",
+#'     table = mort.DE.census.1924.26.male
+#' )
+#' deathProbabilities(table.JL, YOB = 1977, ageDifferences = c(1, 5, -5, 16))
+#' deathProbabilities(table.JL, YOB = 1977, ageDifferences = c(0))
+#' deathProbabilities(table.JL, YOB = 1977, ageDifferences = c(1, 5, 16))
+#'
 #' @export mortalityTable.jointLives
 #' @exportClass mortalityTable.jointLives
 mortalityTable.jointLives = setClass(
@@ -31,7 +41,20 @@ padLast = function(v, l) {
     pad0(v, l, utils::tail(v, n = 1))
 }
 
-#' @export
+#' Return a matrix of the persons' individual death probabilities of a joint-life
+#' table (instance of \code{\link{mortalityTable.jointLives}})
+#'
+#' @param tables List of life table objects (object inherited from
+#'               \code{\link{mortalityTable}})
+#' @param YOB The birth year for the first person
+#' @param ageDifferences The age differences to the first person
+#'
+#' @examples
+#' mortalityTables.load("Germany_Census")
+#' deathProbabilitiesIndividual(list(mort.DE.census.1924.26.male), 1977, c(0, 0))
+#' deathProbabilitiesIndividual(list(mort.DE.census.1924.26.male), 1977, c(0, -5, 13))
+#'
+#' @export deathProbabilitiesIndividual
 deathProbabilitiesIndividual = function(tables, YOB, ageDifferences) {
     n = max(length(YOB), length(ageDifferences) + 1);
     if (length(YOB) == 1) {
@@ -78,6 +101,20 @@ deathProbabilitiesIndividual = function(tables, YOB, ageDifferences) {
     qxMatrix
 }
 
+#' Return a matrix of the persons' individual period death probabilities of a
+#' joint-life table (instance of \code{\link{mortalityTable.jointLives}})
+#'
+#' @param tables List of life table objects (object inherited from
+#'               \code{\link{mortalityTable}})
+#' @param period The observation period
+#' @param ageDifferences The age differences to the first person
+#'
+#' @examples
+#' mortalityTables.load("Germany_Census")
+#' periodDeathProbabilitiesIndividual(list(mort.DE.census.1924.26.male), 1977, c(0, 0))
+#' periodDeathProbabilitiesIndividual(list(mort.DE.census.1924.26.male), 1977, c(0, -5, 13))
+#'
+#' @export periodDeathProbabilitiesIndividual
 periodDeathProbabilitiesIndividual = function(tables, period, ageDifferences) {
     # prepend a 0, because the first entry has no offset
     ageDifferences = c(0, ageDifferences);
@@ -138,6 +175,17 @@ setMethod("baseYear", "mortalityTable.jointLives",
 #' @describeIn deathProbabilities Return the (cohort) death probabilities of the
 #'                                life table given the birth year (if needed)
 #' @param ageDifferences A vector of age differences of all joint lives.
+#'
+#' @examples
+#' mortalityTables.load("Germany_Census")
+#' table.JL = mortalityTable.jointLives(
+#'     name = "ADSt 24/26 auf verbundene Leben",
+#'     table = mort.DE.census.1924.26.male
+#' )
+#' deathProbabilities(table.JL, YOB = 1977, ageDifferences = c(1, 5, -5, 16))
+#' deathProbabilities(table.JL, YOB = 1977, ageDifferences = c(0))
+#' deathProbabilities(table.JL, YOB = 1977, ageDifferences = c(1, 5, 16))
+#'
 setMethod("deathProbabilities", "mortalityTable.jointLives",
           function(object,  ..., ageDifferences = c(), YOB = 1975) {
               qxMatrix = deathProbabilitiesIndividual(c(object@table), YOB = YOB, ageDifferences = ageDifferences);
@@ -157,6 +205,18 @@ setMethod("getOmega", "mortalityTable.jointLives",
 #' @describeIn periodDeathProbabilities Return the (period) death probabilities
 #'             of the joint lives mortality table for a given observation year
 #' @param ageDifferences A vector of age differences of all joint lives.
+#'
+#' @examples
+#' mortalityTables.load("Germany_Census")
+#' table.JL = mortalityTable.jointLives(
+#'     name = "ADSt 24/26 auf verbundene Leben",
+#'     table = mort.DE.census.1924.26.male
+#' )
+#' periodDeathProbabilities(table.JL, Period = 2017, ageDifferences = c(1, 5, -5, 16))
+#' periodDeathProbabilities(table.JL, Period = 2017, ageDifferences = c(0))
+#' periodDeathProbabilities(table.JL, Period = 2017, ageDifferences = c(1, 5, 16))
+#'
+
 setMethod("periodDeathProbabilities", "mortalityTable.jointLives",
           function(object,  ..., ageDifferences = c(), Period = 1975) {
               qxMatrix = periodDeathProbabilitiesIndividual(c(object@table), period = Period, ageDifferences = ageDifferences);

R/mortalityTable.mixed.R

@@ -3,7 +3,11 @@ NULL
 
 #' Class mortalityTable.mixed - Life table as a mix of two life tables
 #'
-#' A cohort life table obtained by mixing two life tables with the given weights
+#' A cohort life table obtained by mixing two life tables with the given weights.
+#' Typically, when only gender-specific tables are available, unisex tables
+#' are generated by mixing the two gender-specific tables for males and for
+#' females with a pre-defined, constant proportion (e.g. 60:30 or 40:60,
+#' depending on the portfolio and on the security margins).
 #'
 #' @slot table1 The first \code{mortalityTable}
 #' @slot table2 The second \code{mortalityTable}
@@ -11,6 +15,14 @@ NULL
 #' @slot weight2 The weight of the second mortality table
 #' @slot loading Additional security loading
 #'
+#' @examples
+#' mortalityTables.load("Austria_Annuities_AVOe2005R")
+#' # Generate a unisex table with mixing relation 60:40 from male + female tables
+#' AVOe2005R.myUnisex = mortalityTable.mixed(
+#'     table1 = AVOe2005R.male, table2 = AVOe2005R.female,
+#'     weight1 = 0.6, weight2 = 0.4,
+#'     name = "My custom AVÖ 2005R unisex (60:40)")
+#' plot(AVOe2005R.myUnisex, AVOe2005R.male, AVOe2005R.female, Period = 2017)
 #' @export mortalityTable.mixed
 #' @exportClass mortalityTable.mixed
 mortalityTable.mixed = setClass(
@@ -22,7 +34,7 @@ mortalityTable.mixed = setClass(
         weight2 = "numeric",
         loading = "numeric"
     ),
-    prototype=list(
+    prototype = list(
         weight1 = 1/2,
         weight2 = 1/2,
         loading = 0

man/deathProbabilities.Rd

@@ -63,3 +63,18 @@ life table given the birth year (if needed)
 life table given the birth year (if needed)
 }}
 
+\examples{
+mortalityTables.load("Austria_Annuities")
+deathProbabilities(AVOe2005R.male, YOB = 1975)
+deathProbabilities(AVOe2005R.male, YOB = 2017)
+
+mortalityTables.load("Germany_Census")
+table.JL = mortalityTable.jointLives(
+    name = "ADSt 24/26 auf verbundene Leben",
+    table = mort.DE.census.1924.26.male
+)
+deathProbabilities(table.JL, YOB = 1977, ageDifferences = c(1, 5, -5, 16))
+deathProbabilities(table.JL, YOB = 1977, ageDifferences = c(0))
+deathProbabilities(table.JL, YOB = 1977, ageDifferences = c(1, 5, 16))
+
+}

man/deathProbabilitiesIndividual.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/mortalityTable.jointLives.R
+\name{deathProbabilitiesIndividual}
+\alias{deathProbabilitiesIndividual}
+\title{Return a matrix of the persons' individual death probabilities of a joint-life
+table (instance of \code{\link{mortalityTable.jointLives}})}
+\usage{
+deathProbabilitiesIndividual(tables, YOB, ageDifferences)
+}
+\arguments{
+\item{tables}{List of life table objects (object inherited from
+\code{\link{mortalityTable}})}
+
+\item{YOB}{The birth year for the first person}
+
+\item{ageDifferences}{The age differences to the first person}
+}
+\description{
+Return a matrix of the persons' individual death probabilities of a joint-life
+table (instance of \code{\link{mortalityTable.jointLives}})
+}
+\examples{
+mortalityTables.load("Germany_Census")
+deathProbabilitiesIndividual(list(mort.DE.census.1924.26.male), 1977, c(0, 0))
+deathProbabilitiesIndividual(list(mort.DE.census.1924.26.male), 1977, c(0, -5, 13))
+
+}

man/generateAgeShift.Rd

@@ -18,5 +18,6 @@ Generate a dataframe suitable to be passed to the mortalityTable.ageShift
 class.
 }
 \examples{
-generateAgeShift(1, YOBs = c(1922, 1944, 1958, 1973, 1989, 2006, 2023, 2041, 2056))
+generateAgeShift(initial = 1, YOBs = c(1922, 1944, 1958, 1973, 1989, 2006, 2023, 2041, 2056))
+
 }

man/getCohortTable.Rd

@@ -26,3 +26,10 @@ Return the cohort life table as a \code{mortalityTable.period} object
 \code{mortalityTable.period} object
 }}
 
+\examples{
+mortalityTables.load("Austria_Annuities")
+tb75 = getCohortTable(AVOe2005R.male, YOB = 1975)
+# The tb75 is a fixed table with no trend any more
+plot(AVOe2005R.male, tb75, Period = 2017)
+
+}

man/getPeriodTable.Rd

@@ -27,3 +27,10 @@ Return the period life table as a \code{mortalityTable.period} object
 \code{mortalityTable.period} object
 }}
 
+\examples{
+mortalityTables.load("Austria_Annuities")
+tb17 = getPeriodTable(AVOe2005R.male, Period = 2017)
+# The tb17 is a fixed table with no trend any more
+plot(AVOe2005R.male, tb17, YOB = 1975)
+
+}

man/lifeTable.Rd

@@ -25,3 +25,11 @@ Return the lifetable object (package lifecontingencies) for the cohort life tabl
 for the cohort life table
 }}
 
+\examples{
+library("lifecontingencies")
+mortalityTables.load("Austria_Annuities")
+lifeTable(AVOe2005R.male, YOB = 2017)
+axn(lifeTable(AVOe2005R.male, YOB = 1975), x = 65, i = 0.03)
+axn(lifeTable(AVOe2005R.male, YOB = 2017), x = 65, i = 0.03)
+
+}

man/makeQxDataFrame.Rd

@@ -24,3 +24,8 @@ It is not required to call this function manually, \code{plotMortalityTables}
 will automatically do it if object derived from class \code{mortalityTable}
 are passed.
 }
+\examples{
+mortalityTables.load("Austria_Annuities")
+makeQxDataFrame(AVOe2005R.male, AVOe2005R.female, YOB = 1975)
+
+}

man/mortalityImprovement.Rd

@@ -4,7 +4,7 @@
 \name{mortalityImprovement}
 \alias{mortalityImprovement}
 \alias{mortalityImprovement,mortalityTable-method}
-\title{Return the mortality trend / yearly log-mortality improvement of the given period or the given generation.}
+\title{Return the mortality trend (yearly log-death-probability improvement) of the given period or the given generation.}
 \usage{
 mortalityImprovement(object, ..., Period = NULL, YOB = 1975)
 
@@ -16,12 +16,13 @@ mortalityImprovement(object, ..., Period = NULL, YOB = 1975)
 
 \item{...}{Other parameters (currently unused)}
 
-\item{Period}{The observation year for which the mortality improvement should be calculated. If both YOB and Period are given, YOB is ignored.}
+\item{Period}{The observation year for which the mortality improvement should
+be calculated. If both YOB and Period are given, YOB is ignored.}
 
 \item{YOB}{The birth year for which the mortality improvement should be calculated}
 }
 \description{
-Return the mortality trend / yearly log-mortality improvement of the given period or the given generation.
+Return the mortality trend (yearly log-death-probability improvement) of the given period or the given generation.
 }
 \section{Methods (by class)}{
 \itemize{
@@ -29,3 +30,10 @@ Return the mortality trend / yearly log-mortality improvement of the given perio
 life table given the birth or observation year
 }}
 
+\examples{
+mortalityTables.load("Austria_Annuities")
+# AVOe 2005R includes a trend decline by default, compare the exact table with the table without decline:
+mortalityImprovement(AVOe2005R.male, Period = 2017)
+mortalityImprovement(AVOe2005R.male.nodamping, Period = 2017)
+
+}