From e6ec9ce1c6430b529c4643bdbfbe0710b01a9066 Mon Sep 17 00:00:00 2001
From: Reinhold Kainhofer <reinhold@kainhofer.com>
Date: Mon, 11 Sep 2017 00:21:26 +0000
Subject: [PATCH] Add examples
CRAN requires examples for all functions => Start adding them.
Export and document deathProbabilitiesIndividual and periodDeathProbabilitiesIndividual
---
NAMESPACE | 1 +
R/deathProbabilities.R | 6 +-
R/getCohortTable.R | 6 ++
R/getPeriodTable.R | 6 ++
R/lifeTable.R | 9 ++-
R/makeQxDataFrame.R | 4 ++
R/mortalityComparisonTable.R | 2 -
R/mortalityImprovement.R | 11 +++-
R/mortalityTable.ageShift.R | 17 ++++-
R/mortalityTable.improvementFactors.R | 16 +++++
R/mortalityTable.jointLives.R | 62 ++++++++++++++++++-
R/mortalityTable.mixed.R | 16 ++++-
man/deathProbabilities.Rd | 15 +++++
man/deathProbabilitiesIndividual.Rd | 27 ++++++++
man/generateAgeShift.Rd | 3 +-
man/getCohortTable.Rd | 7 +++
man/getPeriodTable.Rd | 7 +++
man/lifeTable.Rd | 8 +++
man/makeQxDataFrame.Rd | 5 ++
man/mortalityImprovement.Rd | 14 ++++-
man/mortalityTable.ageShift-class.Rd | 10 +++
...mortalityTable.improvementFactors-class.Rd | 17 +++++
man/mortalityTable.jointLives-class.Rd | 11 ++++
man/mortalityTable.mixed-class.Rd | 15 ++++-
man/periodDeathProbabilities.Rd | 11 ++++
man/periodDeathProbabilitiesIndividual.Rd | 27 ++++++++
26 files changed, 316 insertions(+), 17 deletions(-)
create mode 100644 man/deathProbabilitiesIndividual.Rd
create mode 100644 man/periodDeathProbabilitiesIndividual.Rd
diff --git a/NAMESPACE b/NAMESPACE
index bbffe45..3212ce0 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -23,6 +23,7 @@ export(mortalityTables.load)
export(pensionTable)
export(pensionTables.list)
export(pensionTables.load)
+export(periodDeathProbabilitiesIndividual)
export(plotMortalityTableComparisons)
export(plotMortalityTables)
export(plotMortalityTrend)
diff --git a/R/deathProbabilities.R b/R/deathProbabilities.R
index 202cbaa..c172cfa 100644
--- a/R/deathProbabilities.R
+++ b/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)
})
-
diff --git a/R/getCohortTable.R b/R/getCohortTable.R
index bea275d..23e0ca9 100644
--- a/R/getCohortTable.R
+++ b/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"));
diff --git a/R/getPeriodTable.R b/R/getPeriodTable.R
index 6a03f73..cce0915 100644
--- a/R/getPeriodTable.R
+++ b/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, ...)
diff --git a/R/lifeTable.R b/R/lifeTable.R
index 82f29a6..728002e 100644
--- a/R/lifeTable.R
+++ b/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);
diff --git a/R/makeQxDataFrame.R b/R/makeQxDataFrame.R
index 6e84133..e2d5f6a 100644
--- a/R/makeQxDataFrame.R
+++ b/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!
diff --git a/R/mortalityComparisonTable.R b/R/mortalityComparisonTable.R
index 15415a0..49dec04 100644
--- a/R/mortalityComparisonTable.R
+++ b/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)
diff --git a/R/mortalityImprovement.R b/R/mortalityImprovement.R
index b4b1eaa..75376a5 100644
--- a/R/mortalityImprovement.R
+++ b/R/mortalityImprovement.R
@@ -1,12 +1,19 @@
#' @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"));
diff --git a/R/mortalityTable.ageShift.R b/R/mortalityTable.ageShift.R
index 0bd0750..ecce835 100644
--- a/R/mortalityTable.ageShift.R
+++ b/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))
}
diff --git a/R/mortalityTable.improvementFactors.R b/R/mortalityTable.improvementFactors.R
index bf61cf5..fcc9b1a 100644
--- a/R/mortalityTable.improvementFactors.R
+++ b/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(
diff --git a/R/mortalityTable.jointLives.R b/R/mortalityTable.jointLives.R
index 013ffb6..35e7334 100644
--- a/R/mortalityTable.jointLives.R
+++ b/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);
diff --git a/R/mortalityTable.mixed.R b/R/mortalityTable.mixed.R
index a7a0252..25bdcc7 100644
--- a/R/mortalityTable.mixed.R
+++ b/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
diff --git a/man/deathProbabilities.Rd b/man/deathProbabilities.Rd
index 9741acc..616d0e8 100644
--- a/man/deathProbabilities.Rd
+++ b/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))
+
+}
diff --git a/man/deathProbabilitiesIndividual.Rd b/man/deathProbabilitiesIndividual.Rd
new file mode 100644
index 0000000..2c26918
--- /dev/null
+++ b/man/deathProbabilitiesIndividual.Rd
@@ -0,0 +1,27 @@
+% 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))
+
+}
diff --git a/man/generateAgeShift.Rd b/man/generateAgeShift.Rd
index 01bbcd8..2a0307c 100644
--- a/man/generateAgeShift.Rd
+++ b/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))
+
}
diff --git a/man/getCohortTable.Rd b/man/getCohortTable.Rd
index 7b1c5a9..9a03864 100644
--- a/man/getCohortTable.Rd
+++ b/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)
+
+}
diff --git a/man/getPeriodTable.Rd b/man/getPeriodTable.Rd
index a9aec4d..593791f 100644
--- a/man/getPeriodTable.Rd
+++ b/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)
+
+}
diff --git a/man/lifeTable.Rd b/man/lifeTable.Rd
index 15423ea..f649a4d 100644
--- a/man/lifeTable.Rd
+++ b/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)
+
+}
diff --git a/man/makeQxDataFrame.Rd b/man/makeQxDataFrame.Rd
index 4bbac45..d09ae4e 100644
--- a/man/makeQxDataFrame.Rd
+++ b/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)
+
+}
diff --git a/man/mortalityImprovement.Rd b/man/mortalityImprovement.Rd
index 346fd38..b166f07 100644
--- a/man/mortalityImprovement.Rd
+++ b/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)
+
+}
diff --git a/man/mortalityTable.ageShift-class.Rd b/man/mortalityTable.ageShift-class.Rd
index bda4c19..62f3ab5 100644
--- a/man/mortalityTable.ageShift-class.Rd
+++ b/man/mortalityTable.ageShift-class.Rd
@@ -14,3 +14,13 @@ A cohort life table, obtained by age-shifting from a given base table (death pro
\item{\code{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))
+
+}
diff --git a/man/mortalityTable.improvementFactors-class.Rd b/man/mortalityTable.improvementFactors-class.Rd
index 7624964..6cb1c6f 100644
--- a/man/mortalityTable.improvementFactors-class.Rd
+++ b/man/mortalityTable.improvementFactors-class.Rd
@@ -19,3 +19,20 @@ describes the death probabilities in this year)}
\item{\code{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))
+
+}
diff --git a/man/mortalityTable.jointLives-class.Rd b/man/mortalityTable.jointLives-class.Rd
index c2c911d..b789c67 100644
--- a/man/mortalityTable.jointLives-class.Rd
+++ b/man/mortalityTable.jointLives-class.Rd
@@ -15,3 +15,14 @@ multiple lives, each possibly using a different mortality table.
\item{\code{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))
+
+}
diff --git a/man/mortalityTable.mixed-class.Rd b/man/mortalityTable.mixed-class.Rd
index 565d125..ebab4d0 100644
--- a/man/mortalityTable.mixed-class.Rd
+++ b/man/mortalityTable.mixed-class.Rd
@@ -6,7 +6,11 @@
\alias{mortalityTable.mixed}
\title{Class mortalityTable.mixed - Life table as a mix of two life tables}
\description{
-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).
}
\section{Slots}{
@@ -22,3 +26,12 @@ A cohort life table obtained by mixing two life tables with the given weights
\item{\code{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)
+}
diff --git a/man/periodDeathProbabilities.Rd b/man/periodDeathProbabilities.Rd
index 3530781..884916e 100644
--- a/man/periodDeathProbabilities.Rd
+++ b/man/periodDeathProbabilities.Rd
@@ -67,3 +67,14 @@ of the life table for a given observation year
of the joint lives mortality table for a given observation year
}}
+\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))
+
+}
diff --git a/man/periodDeathProbabilitiesIndividual.Rd b/man/periodDeathProbabilitiesIndividual.Rd
new file mode 100644
index 0000000..218765a
--- /dev/null
+++ b/man/periodDeathProbabilitiesIndividual.Rd
@@ -0,0 +1,27 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/mortalityTable.jointLives.R
+\name{periodDeathProbabilitiesIndividual}
+\alias{periodDeathProbabilitiesIndividual}
+\title{Return a matrix of the persons' individual period death probabilities of a
+joint-life table (instance of \code{\link{mortalityTable.jointLives}})}
+\usage{
+periodDeathProbabilitiesIndividual(tables, period, ageDifferences)
+}
+\arguments{
+\item{tables}{List of life table objects (object inherited from
+\code{\link{mortalityTable}})}
+
+\item{period}{The observation period}
+
+\item{ageDifferences}{The age differences to the first person}
+}
+\description{
+Return a matrix of the persons' individual period death probabilities of a
+joint-life table (instance of \code{\link{mortalityTable.jointLives}})
+}
+\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))
+
+}
--
GitLab