From ae7e289945ae9ea48883460223d76588c0cfc01d Mon Sep 17 00:00:00 2001
From: Kainhofer Reinhold <reinhold@kainhofer.com>
Date: Wed, 17 Jul 2019 16:44:34 +0200
Subject: [PATCH] Add documentation to many utility functions

---
 R/utilityFunctions.R            | 50 +++++++++++++++++++++++++++++++--
 man/deathProbabilities.Rd       |  9 +++++-
 man/fitExpExtrapolation.Rd      | 20 +++++++++++++
 man/getOmega.Rd                 |  8 +++++-
 man/mT.fillAges.Rd              | 24 ++++++++++++++++
 man/mT.scaleProbs.Rd            | 26 +++++++++++++++++
 man/mT.setName.Rd               | 21 ++++++++++++++
 man/mT.setTrend.Rd              | 32 +++++++++++++++++++++
 man/periodDeathProbabilities.Rd | 12 +++++++-
 man/setModification.Rd          | 10 +++----
 10 files changed, 202 insertions(+), 10 deletions(-)
 create mode 100644 man/fitExpExtrapolation.Rd
 create mode 100644 man/mT.fillAges.Rd
 create mode 100644 man/mT.scaleProbs.Rd
 create mode 100644 man/mT.setName.Rd
 create mode 100644 man/mT.setTrend.Rd

diff --git a/R/utilityFunctions.R b/R/utilityFunctions.R
index 8ee6af9..2e33569 100644
--- a/R/utilityFunctions.R
+++ b/R/utilityFunctions.R
@@ -1,4 +1,4 @@
-#' @include mortalityTable.R
+#' @include mortalityTable.R mortalityTable.trendProjection.R mortalityTable.improvementFactors.R pensionTable.R
 NULL
 
 
@@ -48,7 +48,14 @@ fitExtrapolationLaw = function(data, ages, data.ages = ages, Dx = NULL, Ex = NUL
 
 
 
-# Fit an exponential function exp(-A*(x-x0)) to the last value (f(100) and f'(100) need to coincide):
+#' Fit an exponential function exp(-A*(x-x0)) to the last value (f(100) and f'(100) need to coincide):
+#'
+#' @param data data.frame to which an exponential function should be fit
+#' @param idx Index of the position of the fit
+#' @param up Whether the fit is forward- or backward-facing
+#' @param verbose Whether to include data about the fit in the output
+#'
+# exportMethod fitExpExtrapolation
 fitExpExtrapolation = function(data, idx, up = TRUE, verbose = FALSE) {
     # browser()
     # Anchor point of the extrapolation
@@ -73,6 +80,15 @@ fitExpExtrapolation = function(data, idx, up = TRUE, verbose = FALSE) {
 }
 
 
+#' Sets a new name for the given mortality table or the list/table/array of mortalityTables
+#'
+#' @param table A life table object (instance of a \code{mortalityTable} class) or a list, table or array of mortalityTable objects
+#' @param name New name for the table.
+#'
+#' @examples
+#' mortalityTables.load("Austria_Annuities")
+#' mT.setName(AVOe2005R.male, name = "Austrian male Annuity table 2005-R")
+#'
 #' @export
 mT.setName = function(table, name) {
     if (is.array(table)) {
@@ -92,6 +108,17 @@ mT.setName = function(table, name) {
 
 
 
+#' Restrict the given \code{mortalityTable} object(s) to given ages, potentially filling with NA values to ensure they cover the full desired age range
+#'
+#' @param table A life table object (instance of a \code{mortalityTable} class) or a list, table or array of mortalityTable objects
+#' @param neededAges The vector of ages the returned objects should cover (even if the values are 0 or NA)
+#' @param fill The value to use for all ages for which the original table(s) do not have any information
+#'
+#' @examples
+#' mortalityTables.load("Austria_Annuities")
+#' # return a table with only ages 100-130, where ages above 120 (not defined in the original table) are filled with qx=1:
+#' mT.fillAges(AVOe2005R.male, neededAges = 100:130, fill = 1)
+#'
 #' @export
 mT.fillAges = function(table, neededAges, fill = 0) {
     if (is.array(table)) {
@@ -125,6 +152,17 @@ mT.fillAges = function(table, neededAges, fill = 0) {
     table
 }
 
+#' Scale all probabilities of the given \code{mortalityTable} object(s) by the given factor
+#'
+#' @param table A life table object (instance of a \code{mortalityTable} class) or a list, table or array of mortalityTable objects
+#' @param factor Scaling factor for the probabilities (1.0 means unchanged)
+#' @param name.postfix String to append to the original name of the table
+#' @param name New name, overwriting the existing name of the table (takes precedence over \code{name.postfix})
+#'
+#' @examples
+#' mortalityTables.load("Austria_Annuities")
+#' mT.scaleProbs(AVOe2005R.male, 1.5) # Add 50% to all death probabilities of the table
+#'
 #' @export
 mT.scaleProbs = function(table, factor = 1.0, name.postfix = "scaled", name = NULL) {
     if (is.array(table)) {
@@ -151,6 +189,14 @@ mT.scaleProbs = function(table, factor = 1.0, name.postfix = "scaled", name = NU
 }
 
 
+#' Set/Add a trend vector for the probabilities of the given \code{mortalityTable} object(s). Returns a \code{mortalityTable.trendProjection} object
+#'
+#' @param table A life table object (instance of a \code{mortalityTable} class) or a list, table or array of mortalityTable objects
+#' @param trend Trend vector to be applied to the mortality table
+#' @param trendages Ages corresponding to the values of the \code{trend} vector
+#' @param baseYear Base year for the trend projection (passed on to \code{mortalityTable.trendProjection})
+#' @param dampingFunction Trend damping (passed on to \code{mortalityTable.trendProjection})
+#'
 #' @export
 mT.setTrend = function(table, trend, trendages = NULL, baseYear = NULL, dampingFunction = identity) {
     if (is.array(table)) {
diff --git a/man/deathProbabilities.Rd b/man/deathProbabilities.Rd
index 3969727..801627d 100644
--- a/man/deathProbabilities.Rd
+++ b/man/deathProbabilities.Rd
@@ -1,6 +1,6 @@
 % Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/deathProbabilities.R,
-%   R/mortalityTable.jointLives.R
+%   R/mortalityTable.observed.R, R/mortalityTable.jointLives.R
 \docType{methods}
 \name{deathProbabilities}
 \alias{deathProbabilities}
@@ -9,6 +9,7 @@
 \alias{deathProbabilities,mortalityTable.trendProjection-method}
 \alias{deathProbabilities,mortalityTable.improvementFactors-method}
 \alias{deathProbabilities,mortalityTable.mixed-method}
+\alias{deathProbabilities,mortalityTable.observed-method}
 \alias{deathProbabilities,mortalityTable.jointLives-method}
 \title{Return the (cohort) death probabilities of the life table given the birth year (if needed)}
 \usage{
@@ -29,6 +30,9 @@ deathProbabilities(object, ..., ages = NULL, YOB = 1975)
 \S4method{deathProbabilities}{mortalityTable.mixed}(object, ...,
   ages = NULL, YOB = 1975)
 
+\S4method{deathProbabilities}{mortalityTable.observed}(object, ...,
+  ages = NULL, YOB = 1975)
+
 \S4method{deathProbabilities}{mortalityTable.jointLives}(object, ...,
   ageDifferences = c(), ages = NULL, YOB = 1975)
 }
@@ -63,6 +67,9 @@ life table given the birth year (if needed)
 \item \code{mortalityTable.mixed}: Return the (cohort) death probabilities of the
 life table given the birth year (if needed)
 
+\item \code{mortalityTable.observed}: Return the (cohort) death probabilities of the
+life table given the birth year (if needed)
+
 \item \code{mortalityTable.jointLives}: Return the (cohort) death probabilities of the
 life table given the birth year (if needed)
 }}
diff --git a/man/fitExpExtrapolation.Rd b/man/fitExpExtrapolation.Rd
new file mode 100644
index 0000000..5dc3069
--- /dev/null
+++ b/man/fitExpExtrapolation.Rd
@@ -0,0 +1,20 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/utilityFunctions.R
+\name{fitExpExtrapolation}
+\alias{fitExpExtrapolation}
+\title{Fit an exponential function exp(-A*(x-x0)) to the last value (f(100) and f'(100) need to coincide):}
+\usage{
+fitExpExtrapolation(data, idx, up = TRUE, verbose = FALSE)
+}
+\arguments{
+\item{data}{data.frame to which an exponential function should be fit}
+
+\item{idx}{Index of the position of the fit}
+
+\item{up}{Whether the fit is forward- or backward-facing}
+
+\item{verbose}{Whether to include data about the fit in the output}
+}
+\description{
+Fit an exponential function exp(-A*(x-x0)) to the last value (f(100) and f'(100) need to coincide):
+}
diff --git a/man/getOmega.Rd b/man/getOmega.Rd
index 5439dea..72b9ccb 100644
--- a/man/getOmega.Rd
+++ b/man/getOmega.Rd
@@ -1,10 +1,12 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/getOmega.R, R/mortalityTable.jointLives.R
+% Please edit documentation in R/getOmega.R, R/mortalityTable.observed.R,
+%   R/mortalityTable.jointLives.R
 \docType{methods}
 \name{getOmega}
 \alias{getOmega}
 \alias{getOmega,mortalityTable.period-method}
 \alias{getOmega,mortalityTable.mixed-method}
+\alias{getOmega,mortalityTable.observed-method}
 \alias{getOmega,mortalityTable.jointLives-method}
 \title{Return the maximum age of the life table}
 \usage{
@@ -14,6 +16,8 @@ getOmega(object)
 
 \S4method{getOmega}{mortalityTable.mixed}(object)
 
+\S4method{getOmega}{mortalityTable.observed}(object)
+
 \S4method{getOmega}{mortalityTable.jointLives}(object)
 }
 \arguments{
@@ -28,6 +32,8 @@ Return the maximum age of the life table
 
 \item \code{mortalityTable.mixed}: Return the maximum age of the mixed life table
 
+\item \code{mortalityTable.observed}: Return the maximum age of the period life table
+
 \item \code{mortalityTable.jointLives}: Return the maximum age of the joint lives mortality table (returns the maximum age of the first table used for joint lives, as the ages of the joint lives are now known to the function)
 }}
 
diff --git a/man/mT.fillAges.Rd b/man/mT.fillAges.Rd
new file mode 100644
index 0000000..abff96f
--- /dev/null
+++ b/man/mT.fillAges.Rd
@@ -0,0 +1,24 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/utilityFunctions.R
+\name{mT.fillAges}
+\alias{mT.fillAges}
+\title{Restrict the given \code{mortalityTable} object(s) to given ages, potentially filling with NA values to ensure they cover the full desired age range}
+\usage{
+mT.fillAges(table, neededAges, fill = 0)
+}
+\arguments{
+\item{table}{A life table object (instance of a \code{mortalityTable} class) or a list, table or array of mortalityTable objects}
+
+\item{neededAges}{The vector of ages the returned objects should cover (even if the values are 0 or NA)}
+
+\item{fill}{The value to use for all ages for which the original table(s) do not have any information}
+}
+\description{
+Restrict the given \code{mortalityTable} object(s) to given ages, potentially filling with NA values to ensure they cover the full desired age range
+}
+\examples{
+mortalityTables.load("Austria_Annuities")
+# return a table with only ages 100-130, where ages above 120 (not defined in the original table) are filled with qx=1:
+mT.fillAges(AVOe2005R.male, neededAges = 100:130, fill = 1)
+
+}
diff --git a/man/mT.scaleProbs.Rd b/man/mT.scaleProbs.Rd
new file mode 100644
index 0000000..a2c799d
--- /dev/null
+++ b/man/mT.scaleProbs.Rd
@@ -0,0 +1,26 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/utilityFunctions.R
+\name{mT.scaleProbs}
+\alias{mT.scaleProbs}
+\title{Scale all probabilities of the given \code{mortalityTable} object(s) by the given factor}
+\usage{
+mT.scaleProbs(table, factor = 1, name.postfix = "scaled",
+  name = NULL)
+}
+\arguments{
+\item{table}{A life table object (instance of a \code{mortalityTable} class) or a list, table or array of mortalityTable objects}
+
+\item{factor}{Scaling factor for the probabilities (1.0 means unchanged)}
+
+\item{name.postfix}{String to append to the original name of the table}
+
+\item{name}{New name, overwriting the existing name of the table (takes precedence over \code{name.postfix})}
+}
+\description{
+Scale all probabilities of the given \code{mortalityTable} object(s) by the given factor
+}
+\examples{
+mortalityTables.load("Austria_Annuities")
+mT.scaleProbs(AVOe2005R.male, 1.5) # Add 50\% to all death probabilities of the table
+
+}
diff --git a/man/mT.setName.Rd b/man/mT.setName.Rd
new file mode 100644
index 0000000..a39fa36
--- /dev/null
+++ b/man/mT.setName.Rd
@@ -0,0 +1,21 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/utilityFunctions.R
+\name{mT.setName}
+\alias{mT.setName}
+\title{Sets a new name for the given mortality table or the list/table/array of mortalityTables}
+\usage{
+mT.setName(table, name)
+}
+\arguments{
+\item{table}{A life table object (instance of a \code{mortalityTable} class) or a list, table or array of mortalityTable objects}
+
+\item{name}{New name for the table.}
+}
+\description{
+Sets a new name for the given mortality table or the list/table/array of mortalityTables
+}
+\examples{
+mortalityTables.load("Austria_Annuities")
+mT.setName(AVOe2005R.male, name = "Austrian male Annuity table 2005-R")
+
+}
diff --git a/man/mT.setTrend.Rd b/man/mT.setTrend.Rd
new file mode 100644
index 0000000..231fbda
--- /dev/null
+++ b/man/mT.setTrend.Rd
@@ -0,0 +1,32 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/utilityFunctions.R
+\name{mT.setTrend}
+\alias{mT.setTrend}
+\alias{mT.addTrend}
+\title{Set/Add a trend vector for the probabilities of the given \code{mortalityTable} object(s). Returns a \code{mortalityTable.trendProjection} object}
+\usage{
+mT.setTrend(table, trend, trendages = NULL, baseYear = NULL,
+  dampingFunction = identity)
+
+mT.addTrend(table, trend, trendages = NULL, baseYear = NULL,
+  dampingFunction = identity)
+}
+\arguments{
+\item{table}{A life table object (instance of a \code{mortalityTable} class) or a list, table or array of mortalityTable objects}
+
+\item{trend}{Trend vector to be applied to the mortality table}
+
+\item{trendages}{Ages corresponding to the values of the \code{trend} vector}
+
+\item{baseYear}{Base year for the trend projection (passed on to \code{mortalityTable.trendProjection})}
+
+\item{dampingFunction}{Trend damping (passed on to \code{mortalityTable.trendProjection})}
+}
+\description{
+Set/Add a trend vector for the probabilities of the given \code{mortalityTable} object(s). Returns a \code{mortalityTable.trendProjection} object
+}
+\section{Functions}{
+\itemize{
+\item \code{mT.addTrend}: Add a trend to the mortality table (returns a mortalityTable.trendProjection obect)
+}}
+
diff --git a/man/periodDeathProbabilities.Rd b/man/periodDeathProbabilities.Rd
index bad8d2a..4d5d1d3 100644
--- a/man/periodDeathProbabilities.Rd
+++ b/man/periodDeathProbabilities.Rd
@@ -1,6 +1,6 @@
 % Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/periodDeathProbabilities.R,
-%   R/mortalityTable.jointLives.R
+%   R/mortalityTable.observed.R, R/mortalityTable.jointLives.R
 \docType{methods}
 \name{periodDeathProbabilities}
 \alias{periodDeathProbabilities}
@@ -9,6 +9,7 @@
 \alias{periodDeathProbabilities,mortalityTable.trendProjection-method}
 \alias{periodDeathProbabilities,mortalityTable.improvementFactors-method}
 \alias{periodDeathProbabilities,mortalityTable.mixed-method}
+\alias{periodDeathProbabilities,mortalityTable.observed-method}
 \alias{periodDeathProbabilities,mortalityTable.jointLives-method}
 \title{Return the (period) death probabilities of the life table for a given
 observation year}
@@ -32,6 +33,9 @@ periodDeathProbabilities(object, ..., ages = NULL, Period = 1975)
 \S4method{periodDeathProbabilities}{mortalityTable.mixed}(object, ...,
   ages = NULL, Period = 1975)
 
+\S4method{periodDeathProbabilities}{mortalityTable.observed}(object, ...,
+  ages = NULL, Period = 1975)
+
 \S4method{periodDeathProbabilities}{mortalityTable.jointLives}(object, ...,
   ageDifferences = c(), ages = NULL, Period = 1975)
 }
@@ -67,6 +71,12 @@ of the life table for a given observation year
 \item \code{mortalityTable.mixed}: Return the (period) death probabilities
 of the life table for a given observation year
 
+\item \code{mortalityTable.observed}: Return the (period) death probabilities
+of the life table for a given observation year
+If the observed mortality table does not provide data
+for the desired period, the period closest to the
+`Period` argument will be used and a warning printed.
+
 \item \code{mortalityTable.jointLives}: Return the (period) death probabilities
 of the joint lives mortality table for a given observation year
 }}
diff --git a/man/setModification.Rd b/man/setModification.Rd
index 008a845..661d1de 100644
--- a/man/setModification.Rd
+++ b/man/setModification.Rd
@@ -1,17 +1,17 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/setModification.R, R/utilityFunctions.R
+% Please edit documentation in R/utilityFunctions.R, R/setModification.R
 \docType{methods}
-\name{setModification}
+\name{mT.round,mortalityTable-method}
+\alias{mT.round,mortalityTable-method}
 \alias{setModification}
 \alias{setModification,mortalityTable-method}
-\alias{mT.round,mortalityTable-method}
 \title{Return a copy of the table with the given modification function added}
 \usage{
+\S4method{mT.round}{mortalityTable}(object, digits = 8)
+
 setModification(object, modification = 0)
 
 \S4method{setModification}{mortalityTable}(object, modification = 0)
-
-\S4method{mT.round}{mortalityTable}(object, digits = 8)
 }
 \arguments{
 \item{object}{A life table object (instance of a \code{mortalityTable} class)}
-- 
GitLab