diff --git a/R/commutationNumbers.R b/R/commutationNumbers.R
index fb33e7f2baf4b4e97c8df4fcf15f47d7c8561d21..c1d75ab8a9fafa29c17aff4d8066e0fa8b9a9c9d 100644
--- a/R/commutationNumbers.R
+++ b/R/commutationNumbers.R
@@ -5,6 +5,7 @@ NULL
#'
#' @param object The life table object (class inherited from mortalityTable)
#' @param ... Other parameters to be passed to the deathProbabilities call (e.g. YOB)
+#' @param ages Vector of ages for which the probabilities should be extracted and commutation numbers calculates
#' @param i Interest rate used for the calculation of the commutation numbers
#'
#' @examples
@@ -12,14 +13,14 @@ NULL
#' commutationNumbers(AVOe2005R.male, i = 0.03, YOB = 1975)
#'
#' @exportMethod commutationNumbers
-setGeneric("commutationNumbers", function(object, ..., i = 0.03) standardGeneric("commutationNumbers"));
+setGeneric("commutationNumbers", function(object, ..., ages = NULL, i = 0.03) standardGeneric("commutationNumbers"));
#' @describeIn commutationNumbers Calculate the commutation numbers for the given
#' parameters, using the mortality table and an interest rate
setMethod("commutationNumbers", "mortalityTable",
- function(object, ..., i = 0.03) {
- ages = ages(object, ...)
- qx = deathProbabilities(object, ...)
+ function(object, ..., ages = NULL, i = 0.03) {
+ ages = if(is.null(ages)) ages(object, ...) else ages
+ qx = deathProbabilities(object, ..., ages = ages)
commutationNumbers(qx, ages = ages, i = i)
})
@@ -49,8 +50,8 @@ setMethod("commutationNumbers", "numeric",
#' parameters, using the pension table and an interest rate
#' Return value is a list of data frames
setMethod("commutationNumbers", "pensionTable",
- function(object, ..., i = 0.03) {
- probs = transitionProbabilities(object, ...)
+ function(object, ..., ages = NULL, i = 0.03) {
+ probs = transitionProbabilities(object, ..., ages = ages)
ages = probs$x
# Exit probabilities of actives are: - not dead or invalid & no transition to pension
act.exit = (1 - probs$q - probs$i) * (1 - probs$ap)
diff --git a/R/deathProbabilities.R b/R/deathProbabilities.R
index c2c1c0efb2e2c405e11f9da3efc75df32b8b1976..fd71cf3491f385731ce8857518bda9f05988f7cd 100644
--- a/R/deathProbabilities.R
+++ b/R/deathProbabilities.R
@@ -5,6 +5,7 @@ NULL
#'
#' @param object The life table object (class inherited from mortalityTable)
#' @param ... Other parameters (currently unused)
+#' @param ages Desired age range (if NULL, the probabilities of the age range provided by the table will be returned), missing ages will be filled with NA
#' @param YOB The birth year for which the death probabilities should be calculated
#'
#' @examples
diff --git a/R/fillAges.R b/R/fillAges.R
index 27a80b994866617e23ca3b16bf7a252339eb3483..6b748f76a4ade075a6f37e2c135d32eef1369e9f 100644
--- a/R/fillAges.R
+++ b/R/fillAges.R
@@ -2,8 +2,13 @@
#' Fill the given probabilities with NA to match the desired age range.
#'
#' @param probs Numeric vector
-#' @param haveAges ages assigned to the given vector
+#' @param givenAges ages assigned to the given vector
#' @param neededAges desired age range for output
+#' @param fill If set, missing values will be replaced with this value. Default is to fill with NA.
+#'
+#' @examples
+#' # Ages 20-70 have linearly increasing death probabilities. Fill with 0 for the whole age range 0-120
+#' fillAges(probs = c(0:50/50), givenAges = 20:70, neededAges = 0:120, fill = 0)
#'
#' @export fillAges
fillAges = function(probs = c(), givenAges = c(), neededAges = NULL, fill = NA_real_) {
diff --git a/R/mortalityTable.period.R b/R/mortalityTable.period.R
index 04ecda1fd3c0c71a6b0ac6c07242736da21a1848..b15483d6684f363fe007096853abb8425de06ab2 100644
--- a/R/mortalityTable.period.R
+++ b/R/mortalityTable.period.R
@@ -15,6 +15,26 @@ setClassUnion("numericOrNULL", c("numeric", "NULL"))
#' @slot exposures (Optional) exposured used to determine death probabilities
#' (can be used as weights for smoothing, for variances, etc.)
#'
+#' @examples
+#' linTable = mortalityTable.period(name="linear mortality", ages = 0:50, deathProbs = 0:50/50)
+#' constTable = mortalityTable.period(name="const. mortality", ages = 0:50,
+#' deathProbs = c(rep(0.1, 50), 1))
+#' plot(linTable, constTable, title="Comparison of linear and constand death probabilities")
+#'
+#' # A sample observation table with exposures and raw probabilities
+#' obsTable = mortalityTable.period(
+#' name = "trivial observed table",
+#' ages = 0:15,
+#' deathProbs = c(
+#' 0.0072, 0.00212, 0.00081, 0.0005, 0.0013,
+#' 0.001, 0.00122, 0.00142, 0.007, 0.0043,
+#' 0.0058, 0.0067, 0.0082, 0.0091, 0.0075, 0.01),
+#' exposures = c(
+#' 150, 222, 350, 362, 542,
+#' 682, 1022, 1053, 1103, 1037,
+#' 968, 736, 822, 701, 653, 438))
+#' plot(obsTable, title = "Observed death probabilities")
+#'
#' @export mortalityTable.period
#' @exportClass mortalityTable.period
mortalityTable.period = setClass(
diff --git a/R/mortalityTable.trendProjection.R b/R/mortalityTable.trendProjection.R
index c291164d240181f6ab79d233f4d68c73bad07940..0daadd2cbfcf3ee4e8fa82dd8968c90947816ea0 100644
--- a/R/mortalityTable.trendProjection.R
+++ b/R/mortalityTable.trendProjection.R
@@ -22,6 +22,30 @@ NULL
#' the dumping function simply modifies the coefficients of
#' \code{trend}.
#'
+#' @examples
+#' obsTable = mortalityTable.trendProjection(
+#' name = "Const. table with trend",
+#' baseYear = 2018,
+#' ages = 0:15,
+#' deathProbs = rep(0.02, 16),
+#' trend = c(
+#' 0.045, 0.04, 0.03, 0.04, 0.042, 0.041, 0.038, 0.035,
+#' 0.032, 0.031, 0.028, 0.020, 0.015, 0.01, 0.005, 0))
+#' # In 2018 the flat mortality can be seen
+#' plotMortalityTables(obsTable, Period = 2018, title = "Period death probabilities 2018")
+#' # In 2038, the age-specific trend affected the probabilities differently for 20 years:
+#' plotMortalityTables(obsTable, Period = 2038, title = "Period death probabilities 2038")
+#' # Consequently, a person born 2018 will also not have constand death probabilities
+#' plotMortalityTables(obsTable, YOB = 2018, title = "Cohort death probabilities, YOB 2018")
+#'
+#' plotMortalityTables(
+#' lapply(2018:2033, function(y) getCohortTable(obsTable, YOB = y)),
+#' title = "Cohort tables for different YOBs", legend.position = c(0.99, 0.01))
+#' plotMortalityTables(
+#' lapply(2018:2033, function(y) getPeriodTable(obsTable, Period = y)),
+#' title = "Period tables for different years", legend.position = c(0.99, 0.01))
+#'
+#'
#' @export mortalityTable.trendProjection
#' @exportClass mortalityTable.trendProjection
mortalityTable.trendProjection = setClass(
diff --git a/R/mortalityTables.list.R b/R/mortalityTables.list.R
index 10b91b99946d5f37a99e0f8d3b28a0944b30f4d5..7592a58ced2fdb8750f761c0c48769d2f85e2078 100644
--- a/R/mortalityTables.list.R
+++ b/R/mortalityTables.list.R
@@ -7,6 +7,12 @@
#' Multiple packages can be given as a vector.
#' @param prefix The file prefix, defaults to MortalityTables. Can be overridden to list other types of files, like "PensionTables"
#'
+#' @examples
+#' mortalityTables.list()
+#' mortalityTables.list("Austria_*")
+#' mortalityTables.list("*Annuities")
+#' mortalityTables.list(package = c("MyCustomPackage"))
+#'
#' @export
mortalityTables.list = function(pattern = "*", package = c("MortalityTables", "MortalityTablesPrivate"), prefix = "MortalityTables") {
ret = c()
@@ -27,6 +33,11 @@ mortalityTables.list = function(pattern = "*", package = c("MortalityTables", "M
#' directory. Defaults to the "MortalityTables" package.
#' Multiple packages can be given as a vector.
#'
+#' @examples
+#' pensionTables.list()
+#' pensionTables.list("USA_*")
+#' pensionTables.list(package = c("MyCustomPackage"))
+#'
#' @export
pensionTables.list = function(pattern = "*", package = c("MortalityTables", "MortalityTablesPrivate")) {
mortalityTables.list(pattern = pattern, package = package, prefix = "PensionTables")
diff --git a/R/mortalityTables.load.R b/R/mortalityTables.load.R
index dc38a3fdbc06c13c51eb3e8180a5e724b0ade483..7b565cc6b131744572dc5c3d5d3746bf17850784 100644
--- a/R/mortalityTables.load.R
+++ b/R/mortalityTables.load.R
@@ -8,6 +8,13 @@
#' Multiple packages can be given as a vector.
#' @param prefix The prefix for the data sets (default is "MortalityTables").
#'
+#' @examples
+#' mortalityTables.list()
+#' mortalityTables.load("Austria_Annuities_*")
+#' mortalityTables.load("Austria_Annuities_AVOe2005R")
+#' mortalityTables.load("*Annuities")
+#' mortalityTables.load("MyCustomTable", package = c("MyCustomPackage"))
+#'
#' @export
mortalityTables.load = function(dataset, package = c("MortalityTables", "MortalityTablesPrivate"), prefix = "MortalityTables") {
sets = mortalityTables.list(dataset, package = package, prefix = prefix);
@@ -41,6 +48,10 @@ mortalityTables.load = function(dataset, package = c("MortalityTables", "Mortali
#' directory. Defaults to the "MortalityTables" package.
#' Multiple packages can be given as a vector.
#'
+#' pensionTables.list()
+#' pensionTables.load("*")
+#' pensionTables.load("USA_PensionPlan_RP2014")
+#'
#' @export
pensionTables.load = function(dataset, package = c("MortalityTables", "MortalityTablesPrivate")) {
mortalityTables.load(dataset = dataset, package = package, prefix = "PensionTables")
diff --git a/R/pensionTable.R b/R/pensionTable.R
index 6bcf66bf4535a354d20b2eef2032358f960b2915..405550c55f8618bde12e2b804efec6a8acc772bf 100644
--- a/R/pensionTable.R
+++ b/R/pensionTable.R
@@ -98,6 +98,7 @@ pensionTableProbArrange = function(x, q, i, qi, r, ap, api, qp, h, qw, yx, qg, a
#' @param object A pension table object (instance of a \code{\linkS4class{pensionTable}} class)
#' @param ... Currently unused
#' @param YOB Year of birth
+#' @param ages Desired age range (if NULL, the probabilities of the age range provided by the table will be returned), missing ages will be filled with NA
#' @param Period Observation year to calculate period transition probabilities.
#' If given, this arguments overrides the \code{YOB} parameter
#' and this function returns period transition probabilities.
@@ -115,6 +116,7 @@ pensionTableProbArrange = function(x, q, i, qi, r, ap, api, qp, h, qw, yx, qg, a
#' invalids retire like actives (i.e. same death
#' probabilities after retirement) or stay invalid until
#' death.
+#' @param OverallMortality Whether the overall mortality should be returned for actives, or the active mortality
#'
#' @examples
#' pensionTables.load("USA_PensionPlans")
@@ -136,7 +138,6 @@ setMethod("transitionProbabilities", "pensionTable",
as.data.frame = as.data.frame))
}
x = if (is.null(ages)) ages(object@qx) else ages;
- # TODO: Make sure all sub-tables have the same age range!
q = deathProbabilities(object@qx, ..., ages = ages, YOB = YOB);
i = deathProbabilities(object@ix, ..., ages = ages, YOB = YOB);
qi = deathProbabilities(object@qix, ..., ages = ages, YOB = YOB);
@@ -194,6 +195,7 @@ setMethod("transitionProbabilities", "pensionTable",
#' @param object A pension table object (instance of a \code{\linkS4class{pensionTable}} class)
#' @param Period Observation year
#' @param ... Currently unused
+#' @param ages Desired age range (if NULL, the probabilities of the age range provided by the table will be returned), missing ages will be filled with NA
#' @param retirement Override the retirement transition probabilities of the pension table. Possible values are:\itemize{
#' \item Single age (describing a deterministric retirement at the given age)
#' \item mortalityTable object: transition probabilities for retirement
@@ -204,6 +206,7 @@ setMethod("transitionProbabilities", "pensionTable",
#' probabilities after retirement) or stay invalid until
#' death.
#' @param as.data.frame Whether the return value should be a data.frame or an array containing transition matrices
+#' @param OverallMortality Whether the overall mortality should be returned for actives, or the active mortality
#'
#' @examples
#' pensionTables.load("USA_PensionPlans")
diff --git a/R/periodDeathProbabilities.R b/R/periodDeathProbabilities.R
index 39c858ec87428ac9fc1c4356df93d298dbfe5c0f..c389d1b4dc6e89013a1e6023c20d8f71fb55908b 100644
--- a/R/periodDeathProbabilities.R
+++ b/R/periodDeathProbabilities.R
@@ -6,8 +6,14 @@ NULL
#'
#' @param object The life table object (class inherited from mortalityTable)
#' @param ... Other parameters (currently unused)
+#' @param ages Desired age range (if NULL, the probabilities of the age range provided by the table will be returned), missing ages will be filled with NA
#' @param Period The observation year for which the period death probabilities should be determined
#'
+#' @examples
+#' mortalityTables.load("Austria_Annuities")
+#' periodDeathProbabilities(AVOe2005R.male, Period = 1975)
+#' periodDeathProbabilities(AVOe2005R.male, Period = 2017)
+#'
#' @exportMethod periodDeathProbabilities
setGeneric("periodDeathProbabilities", function(object, ..., ages = NULL, Period = 1975) standardGeneric("periodDeathProbabilities"));
diff --git a/R/plotMortalityTableComparisons.R b/R/plotMortalityTableComparisons.R
index 840006daed499791328b6bbc8a562adefe6c5fbe..503f420a5cfd85e74064fcacfb2e28eff04572ff 100644
--- a/R/plotMortalityTableComparisons.R
+++ b/R/plotMortalityTableComparisons.R
@@ -5,6 +5,23 @@
#' @inheritParams plotMortalityTables
#' @param reference The reference table that determines the 100\% values. If not given, the first argument of \code{data} is used as reference table.
#'
+#' @examples
+#' # Load the Austrian census data
+#' mortalityTables.load("Austria_Census")
+#'
+#' # Compare some census tables with the mortality of 2011 Austrian males
+#' # plot with the reference argument is the same as calling plotMortalityTableComparisons
+#' plot(mort.AT.census.1869.male, mort.AT.census.1869.female,
+#' mort.AT.census.1971.male, mort.AT.census.1971.female,
+#' mort.AT.census.2011.male, mort.AT.census.2011.female,
+#' title = "Austrian Census tables, relative to 1971 males",
+#' reference = mort.AT.census.1971.male)
+#' plotMortalityTableComparisons(mort.AT.census.1869.male, mort.AT.census.1869.female,
+#' mort.AT.census.1971.male, mort.AT.census.1971.female,
+#' mort.AT.census.2011.male, mort.AT.census.2011.female,
+#' title = "Austrian Census tables, relative to 1971 males",
+#' reference = mort.AT.census.1971.male)
+#'
#' @import scales
#' @export
plotMortalityTableComparisons = function(
diff --git a/R/plotMortalityTables.R b/R/plotMortalityTables.R
index a35bba9250823cd43dcb7a640fb0fb30be377b8d..bbaffb0a0498281e7c3a9cad0a0d82afe511aa60 100644
--- a/R/plotMortalityTables.R
+++ b/R/plotMortalityTables.R
@@ -12,8 +12,30 @@
#' @param legend.position The position of the legend (default is \code{c(0.9,0.1)})
#' @param legend.justification The justification of the legend (default is \code{c(1,)})
#' @param legend.key.width The keywith of the lines in the legend (default is \code{unit(25,"mm")})
+#' @param legend.title Title of the legend
#' @param ages Plot only the given ages
#'
+#' @examples
+#' # Load the Austrian census data
+#' mortalityTables.load("Austria_Annuities")
+#' mortalityTables.load("Austria_Census")
+#'
+#' # Plot some select census tables in a log-linear plot (plot called
+#' # with mortalityTable objects is equla to calling plotMortalitytTables directly)
+#' plot(mort.AT.census.1869.male, mort.AT.census.1869.female,
+#' mort.AT.census.1971.male, mort.AT.census.1971.female,
+#' mort.AT.census.2011.male, mort.AT.census.2011.female,
+#' title="Austrian census tables",
+#' ylab=expression(q[x]), xlab="Age",
+#' xlim=c(0,90),
+#' legend.position=c(0.95,0.05))
+#'
+#' # To compare period or cohort life tables, use the YOB and Period arguments:
+#' plot(AVOe2005R.male, AVOe2005R.female, AVOe1996R.male, AVOe1996R.female,
+#' Period = 2018, title = "Austrian Annuity Tables, Period 2018")
+#' plot(AVOe2005R.male, AVOe2005R.female, AVOe1996R.male, AVOe1996R.female,
+#' YOB = 2000, title = "Austrian Annuity Tables for cohort YOB=2000")
+#'
#' @import scales
#' @export
plotMortalityTables = function(
@@ -72,7 +94,7 @@ plotMortalityTables = function(
pl
}
-globalVariables(c("x", "y", ".x"))
+globalVariables(c("x", "y", ".x", "group"))
#
diff --git a/R/plotMortalityTrend.R b/R/plotMortalityTrend.R
index eb3ae4ce2f95b3382068084fb26527aa42d9ebef..6f8a607c21ae4710c04bb192fdc4a4d74c37b6a8 100644
--- a/R/plotMortalityTrend.R
+++ b/R/plotMortalityTrend.R
@@ -14,7 +14,25 @@
#' @param legend.position The position of the legend (default is \code{c(0.9,0.1)})
#' @param legend.key.width The keywith of the lines in the legend (default is \code{unit(25,"mm")})
#'
-#' @import scales
+#' @examples
+#' # Load the Austrian aunnity data
+#' mortalityTables.load("Austria_Annuities")
+#'
+#' # Compare the trends of these tables
+#' plotMortalityTrend(AVOe2005R.male, AVOe2005R.female, AVOe1996R.male, AVOe1996R.female,
+#' Period = 2002, title = "Trends of Austrian Annuity Tables")
+#' # For tables with a non-constant trend, the Period and YOB can be used to compare
+#' # the age-specific trends that apply to the death probabilities during a given
+#' # period or for a given birth year
+#' plotMortalityTrend(AVOe2005R.male, AVOe2005R.female, AVOe1996R.male, AVOe1996R.female,
+#' YOB = 1950, title = "Trends of Austrian Annuity Tables for cohort YOB=1950")
+#' plotMortalityTrend(AVOe2005R.male, AVOe2005R.female, AVOe1996R.male, AVOe1996R.female,
+#' YOB = 2000, title = "Trends of Austrian Annuity Tables for cohort YOB=2000")
+#' plotMortalityTrend(AVOe2005R.male, AVOe2005R.female, AVOe1996R.male, AVOe1996R.female,
+#' Period = 1999, title = "Trends of Austrian Annuity Tables for Period 2002")
+#' plotMortalityTrend(AVOe2005R.male, AVOe2005R.female, AVOe1996R.male, AVOe1996R.female,
+#' Period = 2030, title = "Trends of Austrian Annuity Tables for Period 2030")
+#'#' @import scales
#' @export
plotMortalityTrend = function(data, ..., xlim=NULL, ylim=NULL, xlab=NULL, ylab=NULL, title = "", legend.position=c(0.9,0.9), legend.key.width = unit(25, "mm")) {
if (!is.data.frame(data)) {
diff --git a/R/setLoading.R b/R/setLoading.R
index 6cf380d9fe64527db1f3950f646baf928808fb48..e9f76fe793b8e614da7f29d1277bdc494d9d0cd5 100644
--- a/R/setLoading.R
+++ b/R/setLoading.R
@@ -6,6 +6,11 @@ NULL
#' @param object A life table object (instance of a \code{mortalityTable} class)
#' @param loading The additional (security) loading to be added to the table.
#'
+#' @examples
+#' mortalityTables.load("Austria_Census")
+#' # Austrian census mortality 2011 reduced by 30%
+#' setLoading(mort.AT.census.2011.male, loading = -0.3)
+#'
#' @exportMethod setLoading
setGeneric("setLoading", function(object, loading = 0) standardGeneric("setLoading"));
diff --git a/R/setModification.R b/R/setModification.R
index 6c0ca5c18c5640e6bc4c9744d5ceb0aab4e1089c..628ffa841e3922759e07892db624b5f5fc4d08b6 100644
--- a/R/setModification.R
+++ b/R/setModification.R
@@ -6,6 +6,24 @@ NULL
#' @param object A life table object (instance of a \code{mortalityTable} class)
#' @param modification The postprocessing modification function (for example, so enforce a lower bound).
#'
+#' @examples
+#' mortalityTables.load("Austria_Census")
+#' # Austrian census mortality 2011, with a lower floor of 0.1% death probability
+#' at11.mod1perm = setModification(mort.AT.census.2011.male,
+#' modification = function(qx) {pmax(qx, 0.001)})
+#' at11.mod1perm@name = paste(at11.mod1perm@name, "at least 0.1%")
+#' # Austrian census mortality 2011, modified with 40% selection for ages
+#' # below 60, vanishing linearly to age 80
+#' at11.modSelection = setModification(mort.AT.census.2011.male,
+#' modification = function(qx) {
+#' qx * c(rep(0.6, 60), 0.6 + 0.4 * (0:20)/20, rep(1, length(qx)-81))
+#' })
+#' at11.modSelection@name = paste(at11.modSelection@name, " 40% selection below 60")
+#'
+#' plot(mort.AT.census.2011.male, at11.mod1perm, at11.modSelection,
+#' title = "Austrian census mortality with modifications", legend.position = c(0.99, 0.01))
+#'
+#'
#' @exportMethod setModification
setGeneric("setModification", function(object, modification = 0) standardGeneric("setModification"));
diff --git a/R/undampenTrend.R b/R/undampenTrend.R
index de4f2a7fc65c83a18cdba13cffaa29b91762dfab..7fb53a3df43ae7b3fdfb90f5e2fc77c54b640db5 100644
--- a/R/undampenTrend.R
+++ b/R/undampenTrend.R
@@ -5,13 +5,21 @@ NULL
#'
#' @param object The life table object (class inherited from mortalityTable)
#'
+#' @examples
+#' mortalityTables.load("Austria_Annuities")
+#' AVOe2005R.male.undamped = undampenTrend(AVOe2005R.male)
+#' AVOe2005R.male.undamped@name = paste(AVOe2005R.male.undamped@name, "no trend dampening")
+#'
+#' plot(AVOe2005R.male, AVOe2005R.male.undamped,
+#' title = "AVOe 2005R with trend dampening and without", YOB = 2000)
+#'
#' @exportMethod undampenTrend
-setGeneric("undampenTrend", function (object) standardGeneric("undampenTrend"));
+setGeneric("undampenTrend", function(object) standardGeneric("undampenTrend"));
#' @describeIn undampenTrend Return a \code{mortalityTable.trendProjection}
#' object with the trend damping removed.
setMethod("undampenTrend", "mortalityTable.trendProjection",
- function (object) {
- object@dampingFunction=identity;
+ function(object) {
+ object@dampingFunction = identity;
object
})
diff --git a/R/whittaker.mortalityTable.R b/R/whittaker.mortalityTable.R
index f6f09982bca117f4f43db026989407fa9165daa0..9a1c9e74012ee1e59fb775affb800d63f62383c6 100644
--- a/R/whittaker.mortalityTable.R
+++ b/R/whittaker.mortalityTable.R
@@ -3,7 +3,13 @@
#' \code{whittaker.mortalityTable} uses the Whittaker-Henderson graduation method
#' to smooth a table of raw observed death probabilities, optionally using the
#' exposures stored in the table as weights (if no exposures are given, equal
-#' weights are applied). All ages with a death probability of \code{NA} will be
+#' weights are applied). The weights (either explicitly given, implicitly taken
+#' from the exposures or implicit equal weights) will be normalized to sum 1.
+#' The parameter lambda indicates the importance of smootheness. A lower value of lambda
+#' will put more emphasis on reproducing the observation as good as possible at the cost of
+#' less smoothness. In turn, a higher value of lambda will force the smoothed result to be
+#' as smooth as possible with possibly larger deviation from the input data.
+#' All ages with a death probability of \code{NA} will be
#' interpolated in the Whittaker-Henderson method (see e.g. Lowrie)
#'
#' @param table Mortality table to be graduated. Must be an instance of a
@@ -13,22 +19,48 @@
#' @param name.postfix Postfix appended to the name of the graduated table
#' @param weights Vector of weights used for graduation. Entries with weight 0
#' will be interpolated. If not given, the exposures of the table
-#' or equal weights are used.
-#'
+#' or equal weights are used. Weight 0 for a certain age indicates
+#' that the observation will not be used for smoothing at all,
+#' and will rather be interpolated from the smoothing of all other values.
#' @param ... additional arguments (currently unused)
-#' @param reference The reference table that determines the 100\% values.
-#' If not given, the absolute mortality values are
-#' compared and plotted on a log-linear scale.
-#' @param trend If set to \code{TRUE}, the function \code{\link{plotMortalityTrend}}
-#' is used to plot the trends of the given tables.
#'
#' @references
#' Walter B. Lowrie: An Extension of the Whittaker-Henderson Method of Graduation, Transactions of Society of Actuaries, 1982, Vol. 34, pp. 329--372
#'
#' @examples
-#' # TODO
+#' # A sample observation table with exposures and raw probabilities
+#' obsTable = mortalityTable.period(
+#' name = "trivial observed table",
+#' ages = 0:15,
+#' deathProbs = c(
+#' 0.0072, 0.00212, 0.00081, 0.0005, 0.0013,
+#' 0.001, 0.00122, 0.00142, 0.007, 0.0043,
+#' 0.0058, 0.0067, 0.0082, 0.0091, 0.0075, 0.01),
+#' exposures = c(
+#' 150, 222, 350, 362, 542,
+#' 682, 1022, 1053, 1103, 1037,
+#' 968, 736, 822, 701, 653, 438))
+#'
+#' # Effect of the different parameters
+#' obsTable.smooth = whittaker.mortalityTable(obsTable,
+#' lambda = 1/10, d = 2, name.postfix = " smoothed (d=2, lambda=1/10)")
+#' obsTable.smooth1 = whittaker.mortalityTable(obsTable,
+#' lambda = 1, d = 2, name.postfix = " smoothed (d=2, lambda=1)")
+#' obsTable.smooth2 = whittaker.mortalityTable(obsTable,
+#' lambda = 1/10, d = 3, name.postfix = " smoothed (d=3, lambda=1/10)")
+#' plot(obsTable, obsTable.smooth, obsTable.smooth1, obsTable.smooth2,
+#' title = "Observed death probabilities")
+#'
+#' # Missing values are interpolated from the Whittaker Henderson
+#' obsTable.missing = obsTable
+#' obsTable.missing@deathProbs[c(6,10,11,12)] = NA_real_
+#' obsTable.interpolated = whittaker.mortalityTable(obsTable,
+#' lambda = 1/10, d = 2, name.postfix = " missing values interpolated")
+#' plot(obsTable.missing, obsTable.interpolated,
+#' title = "Missing values are automatically interpolated") + geom_point(size = 3)
+#'
#'
-#' @seealso \code{\link{whittaker}}
+#' @seealso \code{\link[pracma]{whittaker}}
#'
#' @import scales
#' @export
@@ -41,7 +73,6 @@ whittaker.mortalityTable = function(table, lambda = 10, d = 2, name.postfix = ",
table@name = paste0(table@name, name.postfix)
}
-# browser()
probs = table@deathProbs
orig.probs = probs
ages = table@ages
@@ -82,7 +113,7 @@ whittaker.mortalityTable = function(table, lambda = 10, d = 2, name.postfix = ",
whittaker.interpolate = function(y, lambda = 1600, d = 2, weights = rep(1, length(y))) {
m <- length(y)
- E <- eye(m)
+ E <- diag(1, m, m)
weights = weights * is.finite(y) # non-finite or missing values in y get zero weight
y[!is.finite(y)] = 0
W <- diag(weights)
diff --git a/man/commutationNumbers.Rd b/man/commutationNumbers.Rd
index 09f0b18c010ef314f72577fe9f960e96f53db4a8..28217342fc02760672ebbb5d5be075e79e03a31e 100644
--- a/man/commutationNumbers.Rd
+++ b/man/commutationNumbers.Rd
@@ -8,19 +8,23 @@
\alias{commutationNumbers,pensionTable-method}
\title{Calculate the commutation numbers for the given parameters, using the mortality table and an interest rate}
\usage{
-commutationNumbers(object, ..., i = 0.03)
+commutationNumbers(object, ..., ages = NULL, i = 0.03)
-\S4method{commutationNumbers}{mortalityTable}(object, ..., i = 0.03)
+\S4method{commutationNumbers}{mortalityTable}(object, ..., ages = NULL,
+ i = 0.03)
\S4method{commutationNumbers}{numeric}(object, ages, i = 0.03)
-\S4method{commutationNumbers}{pensionTable}(object, ..., i = 0.03)
+\S4method{commutationNumbers}{pensionTable}(object, ..., ages = NULL,
+ i = 0.03)
}
\arguments{
\item{object}{The life table object (class inherited from mortalityTable)}
\item{...}{Other parameters to be passed to the deathProbabilities call (e.g. YOB)}
+\item{ages}{Vector of ages for which the probabilities should be extracted and commutation numbers calculates}
+
\item{i}{Interest rate used for the calculation of the commutation numbers}
}
\description{
diff --git a/man/deathProbabilities.Rd b/man/deathProbabilities.Rd
index 93c4e594920f18a105df380636c0d343c89e8abf..d5c7025764868873bf6f416107ceace50258db13 100644
--- a/man/deathProbabilities.Rd
+++ b/man/deathProbabilities.Rd
@@ -37,6 +37,8 @@ deathProbabilities(object, ..., ages = NULL, YOB = 1975)
\item{...}{Other parameters (currently unused)}
+\item{ages}{Desired age range (if NULL, the probabilities of the age range provided by the table will be returned), missing ages will be filled with NA}
+
\item{YOB}{The birth year for which the death probabilities should be calculated}
\item{ageDifferences}{A vector of age differences of all joint lives.}
diff --git a/man/fillAges.Rd b/man/fillAges.Rd
index 061f58fb9f6dd95d7d2ea5f292f944f128c3da07..f3bb2fdddf62bd1852a02a0448af2b5ead344010 100644
--- a/man/fillAges.Rd
+++ b/man/fillAges.Rd
@@ -10,10 +10,17 @@ fillAges(probs = c(), givenAges = c(), neededAges = NULL,
\arguments{
\item{probs}{Numeric vector}
+\item{givenAges}{ages assigned to the given vector}
+
\item{neededAges}{desired age range for output}
-\item{haveAges}{ages assigned to the given vector}
+\item{fill}{If set, missing values will be replaced with this value. Default is to fill with NA.}
}
\description{
Fill the given probabilities with NA to match the desired age range.
}
+\examples{
+# Ages 20-70 have linearly increasing death probabilities. Fill with 0 for the whole age range 0-120
+fillAges(probs = c(0:50/50), givenAges = 20:70, neededAges = 0:120, fill = 0)
+
+}
diff --git a/man/mortalityTable.period-class.Rd b/man/mortalityTable.period-class.Rd
index 4b3423d7aa9ff0760ba73ece0f2919d79138ad92..0ada29e5926e6090b04886ccd768395d124d7928 100644
--- a/man/mortalityTable.period-class.Rd
+++ b/man/mortalityTable.period-class.Rd
@@ -21,3 +21,24 @@ information about the period.
(can be used as weights for smoothing, for variances, etc.)}
}}
+\examples{
+linTable = mortalityTable.period(name="linear mortality", ages = 0:50, deathProbs = 0:50/50)
+constTable = mortalityTable.period(name="const. mortality", ages = 0:50,
+ deathProbs = c(rep(0.1, 50), 1))
+plot(linTable, constTable, title="Comparison of linear and constand death probabilities")
+
+# A sample observation table with exposures and raw probabilities
+obsTable = mortalityTable.period(
+ name = "trivial observed table",
+ ages = 0:15,
+ deathProbs = c(
+ 0.0072, 0.00212, 0.00081, 0.0005, 0.0013,
+ 0.001, 0.00122, 0.00142, 0.007, 0.0043,
+ 0.0058, 0.0067, 0.0082, 0.0091, 0.0075, 0.01),
+ exposures = c(
+ 150, 222, 350, 362, 542,
+ 682, 1022, 1053, 1103, 1037,
+ 968, 736, 822, 701, 653, 438))
+plot(obsTable, title = "Observed death probabilities")
+
+}
diff --git a/man/mortalityTable.trendProjection-class.Rd b/man/mortalityTable.trendProjection-class.Rd
index 188204e7233791e53205a6a580984daa367fcb7c..e166c292511f6f763324ddccab86b200a18849ce 100644
--- a/man/mortalityTable.trendProjection-class.Rd
+++ b/man/mortalityTable.trendProjection-class.Rd
@@ -32,3 +32,28 @@ the dumping function simply modifies the coefficients of
\code{trend}.}
}}
+\examples{
+obsTable = mortalityTable.trendProjection(
+ name = "Const. table with trend",
+ baseYear = 2018,
+ ages = 0:15,
+ deathProbs = rep(0.02, 16),
+ trend = c(
+ 0.045, 0.04, 0.03, 0.04, 0.042, 0.041, 0.038, 0.035,
+ 0.032, 0.031, 0.028, 0.020, 0.015, 0.01, 0.005, 0))
+# In 2018 the flat mortality can be seen
+plotMortalityTables(obsTable, Period = 2018, title = "Period death probabilities 2018")
+# In 2038, the age-specific trend affected the probabilities differently for 20 years:
+plotMortalityTables(obsTable, Period = 2038, title = "Period death probabilities 2038")
+# Consequently, a person born 2018 will also not have constand death probabilities
+plotMortalityTables(obsTable, YOB = 2018, title = "Cohort death probabilities, YOB 2018")
+
+plotMortalityTables(
+ lapply(2018:2033, function(y) getCohortTable(obsTable, YOB = y)),
+ title = "Cohort tables for different YOBs", legend.position = c(0.99, 0.01))
+plotMortalityTables(
+ lapply(2018:2033, function(y) getPeriodTable(obsTable, Period = y)),
+ title = "Period tables for different years", legend.position = c(0.99, 0.01))
+
+
+}
diff --git a/man/mortalityTables.list.Rd b/man/mortalityTables.list.Rd
index a32c15bbfe41ca3fdc9c9b0252a3851e3144ac4e..e6880d3228b76a626abd06b9e613f069ac9f7af9 100644
--- a/man/mortalityTables.list.Rd
+++ b/man/mortalityTables.list.Rd
@@ -21,3 +21,10 @@ Multiple packages can be given as a vector.}
List all available sets of life tables provided by the \link[MortalityTables]{MortalityTables-package} package
An existing life table can then be loaded with \link{mortalityTables.load}.
}
+\examples{
+mortalityTables.list()
+mortalityTables.list("Austria_*")
+mortalityTables.list("*Annuities")
+mortalityTables.list(package = c("MyCustomPackage"))
+
+}
diff --git a/man/mortalityTables.load.Rd b/man/mortalityTables.load.Rd
index eca909e5da4b27cb0e4e1675ca5999d611e3c036..36e54837723ed17501ab3cf42315730edcebb073 100644
--- a/man/mortalityTables.load.Rd
+++ b/man/mortalityTables.load.Rd
@@ -21,3 +21,11 @@ Multiple packages can be given as a vector.}
\description{
Load a named set of mortality tables provided by the \link{MortalityTables} package
}
+\examples{
+mortalityTables.list()
+mortalityTables.load("Austria_Annuities_*")
+mortalityTables.load("Austria_Annuities_AVOe2005R")
+mortalityTables.load("*Annuities")
+mortalityTables.load("MyCustomTable", package = c("MyCustomPackage"))
+
+}
diff --git a/man/pensionTables.list.Rd b/man/pensionTables.list.Rd
index 71ea957c8035aa893115957d6987342d2aa19745..ae730b48ef3bee8b5d953f93b71fa44ac134e1eb 100644
--- a/man/pensionTables.list.Rd
+++ b/man/pensionTables.list.Rd
@@ -19,3 +19,9 @@ Multiple packages can be given as a vector.}
List all available sets of pension tables provided by the \link[MortalityTables]{MortalityTables-package} package
An existing pension table can then be loaded with \link{pensionTables.load}.
}
+\examples{
+pensionTables.list()
+pensionTables.list("USA_*")
+pensionTables.list(package = c("MyCustomPackage"))
+
+}
diff --git a/man/pensionTables.load.Rd b/man/pensionTables.load.Rd
index fcb04ffa0b9843d6962baa77975b8a0375eaab6a..14e93653f8a2427f28ab164feb3671f5d0c7e6dc 100644
--- a/man/pensionTables.load.Rd
+++ b/man/pensionTables.load.Rd
@@ -13,8 +13,12 @@ data sets is provided by the function \code{\link{pensionTables.list}}.
Wildcards (*) are allowed to match and load multiple datasets.}
\item{package}{The package that contains the dataset in its \code{extdata/}
-directory. Defaults to the "MortalityTables" package.
-Multiple packages can be given as a vector.}
+ directory. Defaults to the "MortalityTables" package.
+ Multiple packages can be given as a vector.
+
+pensionTables.list()
+pensionTables.load("*")
+pensionTables.load("USA_PensionPlan_RP2014")}
}
\description{
Load a named set of pension tables provided by the \link{MortalityTables} package
diff --git a/man/periodDeathProbabilities.Rd b/man/periodDeathProbabilities.Rd
index 111414792b1d1edcea53d681ae034743f50adfb6..5b3f674f09880bf70c42a36556826aa3e20aafc9 100644
--- a/man/periodDeathProbabilities.Rd
+++ b/man/periodDeathProbabilities.Rd
@@ -38,6 +38,8 @@ periodDeathProbabilities(object, ..., ages = NULL, Period = 1975)
\item{...}{Other parameters (currently unused)}
+\item{ages}{Desired age range (if NULL, the probabilities of the age range provided by the table will be returned), missing ages will be filled with NA}
+
\item{Period}{The observation year for which the period death probabilities should be determined}
\item{ageDifferences}{A vector of age differences of all joint lives.}
@@ -68,6 +70,10 @@ of the joint lives mortality table for a given observation year
}}
\examples{
+mortalityTables.load("Austria_Annuities")
+periodDeathProbabilities(AVOe2005R.male, Period = 1975)
+periodDeathProbabilities(AVOe2005R.male, Period = 2017)
+
mortalityTables.load("Germany_Census")
table.JL = mortalityTable.jointLives(
name = "ADSt 24/26 auf verbundene Leben",
diff --git a/man/periodTransitionProbabilities.Rd b/man/periodTransitionProbabilities.Rd
index f181b5c4f6963ccefb19ac8fbb8f13d88a71061b..e61a03840c04c099a37e13eb0f2add711feb37d7 100644
--- a/man/periodTransitionProbabilities.Rd
+++ b/man/periodTransitionProbabilities.Rd
@@ -19,6 +19,10 @@ periodTransitionProbabilities(object, ...)
\item{Period}{Observation year}
+\item{ages}{Desired age range (if NULL, the probabilities of the age range provided by the table will be returned), missing ages will be filled with NA}
+
+\item{OverallMortality}{Whether the overall mortality should be returned for actives, or the active mortality}
+
\item{retirement}{Override the retirement transition probabilities of the pension table. Possible values are:\itemize{
\item Single age (describing a deterministric retirement at the given age)
\item mortalityTable object: transition probabilities for retirement
diff --git a/man/plotMortalityTableComparisons.Rd b/man/plotMortalityTableComparisons.Rd
index e0e83a728eabcfe74a746cb25cf29bff599302f2..2e6a9ed294ce155e94be2b475a6a3d5b32fa864a 100644
--- a/man/plotMortalityTableComparisons.Rd
+++ b/man/plotMortalityTableComparisons.Rd
@@ -37,3 +37,21 @@ plotMortalityTableComparisons(data, ..., ages = NULL, xlim = NULL,
\description{
\code{plotMortalityTableComparisons} prints multiple life tables (objects of child classes of \code{mortalityTable}) in one plot and scales each by the given reference table, so that the relative mortality can be easily seen. A legend is added showing the names of the tables.
}
+\examples{
+# Load the Austrian census data
+mortalityTables.load("Austria_Census")
+
+# Compare some census tables with the mortality of 2011 Austrian males
+# plot with the reference argument is the same as calling plotMortalityTableComparisons
+plot(mort.AT.census.1869.male, mort.AT.census.1869.female,
+ mort.AT.census.1971.male, mort.AT.census.1971.female,
+ mort.AT.census.2011.male, mort.AT.census.2011.female,
+ title = "Austrian Census tables, relative to 1971 males",
+ reference = mort.AT.census.1971.male)
+plotMortalityTableComparisons(mort.AT.census.1869.male, mort.AT.census.1869.female,
+ mort.AT.census.1971.male, mort.AT.census.1971.female,
+ mort.AT.census.2011.male, mort.AT.census.2011.female,
+ title = "Austrian Census tables, relative to 1971 males",
+ reference = mort.AT.census.1971.male)
+
+}
diff --git a/man/plotMortalityTables.Rd b/man/plotMortalityTables.Rd
index 9504fbcc887b9bf1c0f547713a079293f7a56db8..d05da253ebb4361eb40c6d30b782e497d998c155 100644
--- a/man/plotMortalityTables.Rd
+++ b/man/plotMortalityTables.Rd
@@ -16,6 +16,8 @@ plotMortalityTables(data, ..., ages = NULL, legend.title = "Sterbetafel",
\item{ages}{Plot only the given ages}
+\item{legend.title}{Title of the legend}
+
\item{xlim}{X-axis limitatation (as a two-element vector)}
\item{ylim}{Y-axis limitatation (as a two-element vector)}
@@ -35,3 +37,25 @@ plotMortalityTables(data, ..., ages = NULL, legend.title = "Sterbetafel",
\description{
\code{plotMortalityTables} prints multiple life tables (objects of child classes of \code{mortalityTable}) in one log-linear plot, with a legend showing the names of the tables.
}
+\examples{
+# Load the Austrian census data
+mortalityTables.load("Austria_Annuities")
+mortalityTables.load("Austria_Census")
+
+# Plot some select census tables in a log-linear plot (plot called
+# with mortalityTable objects is equla to calling plotMortalitytTables directly)
+plot(mort.AT.census.1869.male, mort.AT.census.1869.female,
+ mort.AT.census.1971.male, mort.AT.census.1971.female,
+ mort.AT.census.2011.male, mort.AT.census.2011.female,
+ title="Austrian census tables",
+ ylab=expression(q[x]), xlab="Age",
+ xlim=c(0,90),
+ legend.position=c(0.95,0.05))
+
+# To compare period or cohort life tables, use the YOB and Period arguments:
+plot(AVOe2005R.male, AVOe2005R.female, AVOe1996R.male, AVOe1996R.female,
+ Period = 2018, title = "Austrian Annuity Tables, Period 2018")
+plot(AVOe2005R.male, AVOe2005R.female, AVOe1996R.male, AVOe1996R.female,
+ YOB = 2000, title = "Austrian Annuity Tables for cohort YOB=2000")
+
+}
diff --git a/man/plotMortalityTrend.Rd b/man/plotMortalityTrend.Rd
index 7539fafc3114633ccfc11b9dc27ef3367919d93e..10c2787ec1d407e615fa1f94bae7cb6381626857 100644
--- a/man/plotMortalityTrend.Rd
+++ b/man/plotMortalityTrend.Rd
@@ -32,3 +32,23 @@ plotMortalityTrend(data, ..., xlim = NULL, ylim = NULL, xlab = NULL,
of child classes of \code{mortalityTable}) in one plot, with a legend showing
the names of the tables.
}
+\examples{
+# Load the Austrian aunnity data
+mortalityTables.load("Austria_Annuities")
+
+# Compare the trends of these tables
+plotMortalityTrend(AVOe2005R.male, AVOe2005R.female, AVOe1996R.male, AVOe1996R.female,
+ Period = 2002, title = "Trends of Austrian Annuity Tables")
+# For tables with a non-constant trend, the Period and YOB can be used to compare
+# the age-specific trends that apply to the death probabilities during a given
+# period or for a given birth year
+plotMortalityTrend(AVOe2005R.male, AVOe2005R.female, AVOe1996R.male, AVOe1996R.female,
+ YOB = 1950, title = "Trends of Austrian Annuity Tables for cohort YOB=1950")
+plotMortalityTrend(AVOe2005R.male, AVOe2005R.female, AVOe1996R.male, AVOe1996R.female,
+ YOB = 2000, title = "Trends of Austrian Annuity Tables for cohort YOB=2000")
+plotMortalityTrend(AVOe2005R.male, AVOe2005R.female, AVOe1996R.male, AVOe1996R.female,
+ Period = 1999, title = "Trends of Austrian Annuity Tables for Period 2002")
+plotMortalityTrend(AVOe2005R.male, AVOe2005R.female, AVOe1996R.male, AVOe1996R.female,
+ Period = 2030, title = "Trends of Austrian Annuity Tables for Period 2030")
+#' @import scales
+}
diff --git a/man/setLoading.Rd b/man/setLoading.Rd
index 04bea1df0b68366531cea1d9f5d4503c26112687..7581d4de81f685fb45eb0f4ffd62b55c9e5edfbd 100644
--- a/man/setLoading.Rd
+++ b/man/setLoading.Rd
@@ -23,3 +23,9 @@ Return a copy of the table with an additional loading added
\item \code{mortalityTable}: Return the life table with the given loading set
}}
+\examples{
+mortalityTables.load("Austria_Census")
+# Austrian census mortality 2011 reduced by 30\%
+setLoading(mort.AT.census.2011.male, loading = -0.3)
+
+}
diff --git a/man/setModification.Rd b/man/setModification.Rd
index 966f37ca2e51063feb327443c6c63f817decacee..13aa3044d01cd172f380db08d87b7e07885f29fc 100644
--- a/man/setModification.Rd
+++ b/man/setModification.Rd
@@ -23,3 +23,22 @@ Return a copy of the table with the given modification function added
\item \code{mortalityTable}: Return the life table with the given modification set
}}
+\examples{
+mortalityTables.load("Austria_Census")
+# Austrian census mortality 2011, with a lower floor of 0.1\% death probability
+at11.mod1perm = setModification(mort.AT.census.2011.male,
+ modification = function(qx) {pmax(qx, 0.001)})
+at11.mod1perm@name = paste(at11.mod1perm@name, "at least 0.1\%")
+# Austrian census mortality 2011, modified with 40\% selection for ages
+# below 60, vanishing linearly to age 80
+at11.modSelection = setModification(mort.AT.census.2011.male,
+ modification = function(qx) {
+ qx * c(rep(0.6, 60), 0.6 + 0.4 * (0:20)/20, rep(1, length(qx)-81))
+ })
+at11.modSelection@name = paste(at11.modSelection@name, " 40\% selection below 60")
+
+plot(mort.AT.census.2011.male, at11.mod1perm, at11.modSelection,
+ title = "Austrian census mortality with modifications", legend.position = c(0.99, 0.01))
+
+
+}
diff --git a/man/transitionProbabilities.Rd b/man/transitionProbabilities.Rd
index cb4d4a1194f286f7e6c476f97aace18fe70fca7d..e4f3846a32435d50f6af703ac2ff4ca3da6c9df0 100644
--- a/man/transitionProbabilities.Rd
+++ b/man/transitionProbabilities.Rd
@@ -20,6 +20,10 @@ transitionProbabilities(object, ...)
\item{YOB}{Year of birth}
+\item{ages}{Desired age range (if NULL, the probabilities of the age range provided by the table will be returned), missing ages will be filled with NA}
+
+\item{OverallMortality}{Whether the overall mortality should be returned for actives, or the active mortality}
+
\item{Period}{Observation year to calculate period transition probabilities.
If given, this arguments overrides the \code{YOB} parameter
and this function returns period transition probabilities.
diff --git a/man/undampenTrend.Rd b/man/undampenTrend.Rd
index 693bac9d2459552e5487e3e5c7cd0f1e14310bc8..5122bbfc63632f5f490ff80cd0f2b01bc4660693 100644
--- a/man/undampenTrend.Rd
+++ b/man/undampenTrend.Rd
@@ -22,3 +22,12 @@ Return a \code{mortalityTable.trendProjection} object with the trend damping rem
object with the trend damping removed.
}}
+\examples{
+mortalityTables.load("Austria_Annuities")
+AVOe2005R.male.undamped = undampenTrend(AVOe2005R.male)
+AVOe2005R.male.undamped@name = paste(AVOe2005R.male.undamped@name, "no trend dampening")
+
+plot(AVOe2005R.male, AVOe2005R.male.undamped,
+ title = "AVOe 2005R with trend dampening and without", YOB = 2000)
+
+}
diff --git a/man/whittaker.mortalityTable.Rd b/man/whittaker.mortalityTable.Rd
index c51e7d426238ee514c11e691cd0bb825f7c5b982..a1de4348a5aca0c14162d43acdf6a0f516acbf22 100644
--- a/man/whittaker.mortalityTable.Rd
+++ b/man/whittaker.mortalityTable.Rd
@@ -21,29 +21,60 @@ whittaker.mortalityTable(table, lambda = 10, d = 2,
\item{weights}{Vector of weights used for graduation. Entries with weight 0
will be interpolated. If not given, the exposures of the table
-or equal weights are used.}
-
-\item{reference}{The reference table that determines the 100\% values.
-If not given, the absolute mortality values are
-compared and plotted on a log-linear scale.}
-
-\item{trend}{If set to \code{TRUE}, the function \code{\link{plotMortalityTrend}}
-is used to plot the trends of the given tables.}
+or equal weights are used. Weight 0 for a certain age indicates
+that the observation will not be used for smoothing at all,
+and will rather be interpolated from the smoothing of all other values.}
}
\description{
\code{whittaker.mortalityTable} uses the Whittaker-Henderson graduation method
to smooth a table of raw observed death probabilities, optionally using the
exposures stored in the table as weights (if no exposures are given, equal
-weights are applied). All ages with a death probability of \code{NA} will be
+weights are applied). The weights (either explicitly given, implicitly taken
+from the exposures or implicit equal weights) will be normalized to sum 1.
+The parameter lambda indicates the importance of smootheness. A lower value of lambda
+will put more emphasis on reproducing the observation as good as possible at the cost of
+less smoothness. In turn, a higher value of lambda will force the smoothed result to be
+as smooth as possible with possibly larger deviation from the input data.
+All ages with a death probability of \code{NA} will be
interpolated in the Whittaker-Henderson method (see e.g. Lowrie)
}
\examples{
-# TODO
+# A sample observation table with exposures and raw probabilities
+obsTable = mortalityTable.period(
+ name = "trivial observed table",
+ ages = 0:15,
+ deathProbs = c(
+ 0.0072, 0.00212, 0.00081, 0.0005, 0.0013,
+ 0.001, 0.00122, 0.00142, 0.007, 0.0043,
+ 0.0058, 0.0067, 0.0082, 0.0091, 0.0075, 0.01),
+ exposures = c(
+ 150, 222, 350, 362, 542,
+ 682, 1022, 1053, 1103, 1037,
+ 968, 736, 822, 701, 653, 438))
+
+# Effect of the different parameters
+obsTable.smooth = whittaker.mortalityTable(obsTable,
+ lambda = 1/10, d = 2, name.postfix = " smoothed (d=2, lambda=1/10)")
+obsTable.smooth1 = whittaker.mortalityTable(obsTable,
+ lambda = 1, d = 2, name.postfix = " smoothed (d=2, lambda=1)")
+obsTable.smooth2 = whittaker.mortalityTable(obsTable,
+ lambda = 1/10, d = 3, name.postfix = " smoothed (d=3, lambda=1/10)")
+plot(obsTable, obsTable.smooth, obsTable.smooth1, obsTable.smooth2,
+ title = "Observed death probabilities")
+
+# Missing values are interpolated from the Whittaker Henderson
+obsTable.missing = obsTable
+obsTable.missing@deathProbs[c(6,10,11,12)] = NA_real_
+obsTable.interpolated = whittaker.mortalityTable(obsTable,
+ lambda = 1/10, d = 2, name.postfix = " missing values interpolated")
+plot(obsTable.missing, obsTable.interpolated,
+ title = "Missing values are automatically interpolated") + geom_point(size = 3)
+
}
\references{
Walter B. Lowrie: An Extension of the Whittaker-Henderson Method of Graduation, Transactions of Society of Actuaries, 1982, Vol. 34, pp. 329--372
}
\seealso{
-\code{\link{whittaker}}
+\code{\link[pracma]{whittaker}}
}