From d6df2c4f3441fd99c708c3970365e59ed880eeb8 Mon Sep 17 00:00:00 2001
From: Reinhold Kainhofer <reinhold@kainhofer.com>
Date: Wed, 26 Aug 2020 01:34:55 +0200
Subject: [PATCH] Doc work on InsuranceContract
Also fix the InsuranceParameteers lists.
---
NAMESPACE | 1 +
R/HelperFunctions.R | 22 ++
R/InsuranceContract.R | 211 ++++++++++++----
R/InsuranceParameters.R | 5 +-
man/CalculationSingleEnum-class.Rd | 16 ++
man/InsuranceContract.ParameterDefaults.Rd | 82 ++++---
man/InsuranceContract.Rd | 264 +++++++++++++++++----
7 files changed, 468 insertions(+), 133 deletions(-)
create mode 100644 man/CalculationSingleEnum-class.Rd
diff --git a/NAMESPACE b/NAMESPACE
index 8dc3157..45d60ab 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -70,6 +70,7 @@ export(padLast)
export(rollingmean)
export(showVmGlgExamples)
export(valueOrFunction)
+exportClasses(CalculationSingleEnum)
exportClasses(PaymentTimeSingleEnum)
exportClasses(SexSingleEnum)
exportClasses(TariffTypeSingleEnum)
diff --git a/R/HelperFunctions.R b/R/HelperFunctions.R
index 56a5892..cba4674 100644
--- a/R/HelperFunctions.R
+++ b/R/HelperFunctions.R
@@ -26,6 +26,28 @@ PaymentTimeEnum = objectProperties::setSingleEnum("PaymentTime", levels = c("in
#' @export
SexEnum = objectProperties::setSingleEnum("Sex", levels = c("unisex", "male", "female"));
+#' Enum to define how much of a contract needs to be calculated automatically.
+#' @details
+#' When an [InsuranceContract] object is created, all time series are immediately
+#' calculated. However, sometimes, one only needs part of the values, so it
+#' would be a waste of resources to calculate e.g. all future reserves and
+#' profit participation, if only premiums are of interest.
+#'
+#' @export
+CalculationEnum = objectProperties::setSingleEnum("Calculation",
+ levels = c(
+ "all",
+ "probabilities",
+ "cashflows",
+ "presentvalues",
+ "premiums",
+ "absvalues",
+ "reserves",
+ "premiumcomposition",
+ "profitparticipation",
+ "history"
+ )
+)
#' Describes the death benefit of a linearly decreasing whole life insurance (after a possible deferall period)
#'
diff --git a/R/InsuranceContract.R b/R/InsuranceContract.R
index bc2df4e..877ac9f 100644
--- a/R/InsuranceContract.R
+++ b/R/InsuranceContract.R
@@ -4,6 +4,8 @@
#' @import R6
NULL
+
+
############ Class InsuranceContract ###########################################
#' Base Class for Insurance Contracts
#'
@@ -26,6 +28,52 @@ NULL
#' field of the object.
#'
#'
+#' # Calculation approach: Valuation
+#'
+#' The calculation of all contract values is controlled by the function
+#' [InsuranceContract$calculateContract()] (using methods of the [InsuranceTarif]
+#' object) and follows the following logic:
+#'
+#' 1. First the **contingent (unit) cash flows** and the **transition probbilities**
+#' are determined.
+#' 2. The **actuarial equivalence principle** states that at time of inception, the
+#' (net and gross) premium must be determined in a way that the present value
+#' of the future benefits and costs minus the present value of the future premiums
+#' must be equal, i.e. in expectation the future premiums ove the whole lifetime
+#' of the contract will exactly cover the benefits and costs. Similarly, at all
+#' later time steps, the difference between these two present values needs to be
+#' reserved (i.e. has already been paid by the customer by previous premiums).
+#' 2. This allows the premiums to be calculated by first calculating the **present
+#' values** for all of the **benefit and costs cash flow** vectors.
+#' 3. The formulas
+#' to calculate the gross, Zillmer and net **premiums** involve simple linear
+#' combinations of these present values, so the **coefficients of these formulas**
+#' are determined next.
+#' 4. With the coefficients of the premium formulas calculated, all **premiums
+#' can be calculated** (first the gross premium, because due to potential gross
+#' premium refunds in case of death, the formula for the net premium requires
+#' the gross premium, which the formula for the gross premium involves no other
+#' type of premuim).
+#' 5. With premiums determined, all unit cash flows and unit present values can
+#' now be expressed in monetary terms / as **absolute cash flows** (i.e. the actual Euro-amount that flows
+#' rather than a percentage).
+#' 6. As described above, the difference between the present values of premiums
+#' and present values of benefits and costs is defined as the required amount
+#' of reserves, so the **reserves (net, gross, administration cost, balance sheet)**
+#' and all values derived from them (i.e. surrender value, sum insured in case of
+#' premium waiver, etc.) are calculated.
+#' 7. The **decomposition of the premium** into parts dedicated to specific purposes
+#' (tax, rebates, net premium, gross premium, Zillmer premium, cost components,
+#' risk premium, savings premium, etc.) can be done once the reserves are
+#' ready (since e.g. the savings premium is defined as the difference of
+#' discounted reserves at times $t$ and $t+1$).
+#' 8. If the contract has **(discretionary or obligatory) profit sharing**B mechanisms
+#' included, the corresponding [ProfitParticipation] object can calculate that
+#' profit sharing amounts, once all guaranteed values are calculated. This can
+#' also be triggered manually (with custom profit sharing rates) by calling
+#' the methods [InsuranceContract$profitScenario()] or [InsuranceContract$addProfitScenario()].
+#'
+#'
#' # Calculation approach: Cash Flows
#'
#' An insurance contract is basically defined by the (unit) cash flows it produces:
@@ -87,51 +135,10 @@ NULL
#' * guaranteed cash flows: 0, 0, 0, ..., 0, 1
#' * death benefit cash flows: 0, 0, 0, 0, ..., 0
#'
-#' # Calculation approach: Valuation
-#'
-#' The calculation of all contract values is controlled by the function
-#' [InsuranceContract$calculateContract()] (using methods of the [InsuranceTarif]
-#' object) and follows the following logic:
-#'
-#' 1. First the **contingent (unit) cash flows** and the **transition probbilities** are determined.
-#' 2. The **actuarial equivalence principle** states that at time of inception, the
-#' (net and gross) premium must be determined in a way that the present value
-#' of the future benefits and costs minus the present value of the future premiums
-#' must be equal, i.e. in expectation the future premiums ove the whole lifetime
-#' of the contract will exactly cover the benefits and costs. Similarly, at all
-#' later time steps, the difference between these two present values needs to be
-#' reserved (i.e. has already been paid by the customer by previous premiums).
-#' 2. This allows the premiums to be calculated by first calculating the **present
-#' values** for all of the **benefit and costs cash flow** vectors.
-#' 3. The formulas
-#' to calculate the gross, Zillmer and net **premiums** involve simple linear
-#' combinations of these present values, so the **coefficients of these formulas**
-#' are determined next.
-#' 4. With the coefficients of the premium formulas calculated, all **premiums
-#' can be calculated** (first the gross premium, because due to potential gross
-#' premium refunds in case of death, the formula for the net premium requires
-#' the gross premium, which the formula for the gross premium involves no other
-#' type of premuim).
-#' 5. With premiums determined, all unit cash flows and unit present values can
-#' now be expressed in monetary terms / as **absolute cash flows** (i.e. the actual Euro-amount that flows
-#' rather than a percentage).
-#' 6. As described above, the difference between the present values of premiums
-#' and present values of benefits and costs is defined as the required amount
-#' of reserves, so the **reserves (net, gross, administration cost, balance sheet)**
-#' and all values derived from them (i.e. surrender value, sum insured in case of
-#' premium waiver, etc.) are calculated.
-#' 7. The **decomposition of the premium** into parts dedicated to specific purposes
-#' (tax, rebates, net premium, gross premium, Zillmer premium, cost components,
-#' risk premium, savings premium, etc.) can be done once the reserves are
-#' ready (since e.g. the savings premium is defined as the difference of
-#' discounted reserves at times $t$ and $t+1$).
-#' 8. If the contract has **(discretionary or obligatory) profit sharing**B mechanisms
-#' included, the corresponding [ProfitParticipation] object can calculate that
-#' profit sharing amounts, once all guaranteed values are calculated. This can
-#' also be triggered manually (with custom profit sharing rates) by calling
-#' the methods [InsuranceContract$profitScenario()] or [InsuranceContract$addProfitScenario()].
-#'
+
#'
+#' @examples
+#' # TODO
#'
#' @export
InsuranceContract = R6Class(
@@ -192,6 +199,68 @@ InsuranceContract = R6Class(
#### The code:
+ #' @description Create a new insurance contract (for the given tariff/product) and calculate all time series
+ #'
+ #' @details The \code{InsuranceContract$new()} function creates a new
+ #' insurance contract for the given tariff, using the parameters passed
+ #' to the function (and the defaults specified in the tariff).
+ #'
+ #' As soon as this function is called, the contract object calculates
+ #' all time series (cash flows, premiums, reserves, profit participation)
+ #' for the whole contract duration.
+ #'
+ #' The most important parameters that are typically passed to the
+ #' constructor are:
+ #' * \code{age} ... Age of the insured person (used to derive mortalities / transition probabilities)
+ #' * \code{policyPeriod} ... Maturity of the policy (in years)
+ #' * \code{premiumPeriod} ... How long premiums are paid (\code{premiumPeriod = 1}
+ #' for single-premium contracts, \code{premiumPeriod} equals
+ #' \code{policyPeriod} for regular premium payments for the whole
+ #' contract period, while other premium payment durations indicate
+ #' premium payments only for shorter periods than the whole contract
+ #' duration). Default is equal to \code{policyPeriod}
+ #' * \code{sumInsured} ... The sum insured (i.e. survival benefit for
+ #' endowments, death benefit for whole/term life insurances,
+ #' annuity payments for annuities)
+ #' * \code{contractClosing} ... Date of the contract beginning (typically
+ #' created using something like \code{as.Date("2020-08-01")})
+ #' * \code{YOB} ... Year of birth of the insured (for cohort mortality
+ #' tables). If not given, YOB is derived from \code{age} and
+ #' \code{contractClosing}.
+ #' * \code{deferralPeriod} ... Deferral period for deferred annuities
+ #' (i.e. when annuity payments start at a future point in time).
+ #' Default is 0.
+ #' * \code{premiumFrequency} ... How many premium payments per year are
+ #' made (e.g. 1 for yearly premiums, 4 for quarterly premiumd,
+ #' 12 for monthly premium payments). Default is 1 (yearly premiums).
+ #'
+ #' While these are the most common and most important parameters, all
+ #' parameters can be overwritten on a per-contract basis, even those
+ #' that are defined by the tariff. For a full list and explanation of all
+ #' parameters, see [InsuranceContract.ParameterDefaults].
+ #'
+ #' @param tarif The [InsuranceTarif] object describing the Tariff/Product
+ #' and providing defaults for the parameters.
+ #' @param parent For contracts with multiple contract blocks (dynamic
+ #' increases, sum increases, riders), each child is created with
+ #' a pointer to its parent. NULL for single-block contracts or
+ #' for the overall-contract of a multi-block contract. This
+ #' parameter is used internally, but should not be used in
+ #' user-written code.
+ #' @param calculate how much of the contract's time series need to be
+ #' calculated. See [CalculateEnum] for all possible values. This
+ #' is usefull to prevent calculation of e.g. reserves and profit
+ #' participation, when one only wants to create a grid of premiums.
+ #' @param profitid The ID of the default profit participation scenario.
+ #' The default profit participation scenario uses the default
+ #' values passed, while further scenarios can be added by
+ #' [InsuranceContract$addProfitScenario()].
+ #' @param ... Further parameters (age, sum insured, contract closing /
+ #' begin, premium payment details, etc.) of the contract, which
+ #' can also override parameters defined at the tariff-level.
+ #' Possible values are all sub-fields of the
+ #' [InsuranceContract.ParameterDefaults] data structure.
+ #'
initialize = function(tarif, parent = NULL, calculate = "all", profitid = "default", ...) {
private$initParams = c(list(tarif = tarif, parent = parent, calculate = calculate, profitid = profitid), list(...))
self$tarif = tarif;
@@ -228,6 +297,31 @@ InsuranceContract = R6Class(
invisible(self)
},
+ #' @description Add the current state of the contract to the history list
+ #'
+ #' @details The \code{InsuranceContract$addHistorySnapshot()} function
+ #' adds the current (or the explicitly given) state of the contract
+ #' (parameters, calculated values, tarif, list of all contract blocks)
+ #' to the history list (available in the \code{history} field of the
+ #' contract, i.e. \code{InsuranceContract$history}).
+ #'
+ #' @param time the time described by the snapshot
+ #' @param comment a comment to store together with the contract state
+ #' @param type The type of action that caused a history snapshot to
+ #' be stored. Typical values are "Contract" to describe the initial
+ #' contract, "Premium Waiver" or "Dynamic Increase".
+ #' @param params The set of params to be stored in the history snapshot
+ #' (default is \code{self$Parameters}, if not explicitly given)
+ #' @param values The calculated time series of all contract values
+ #' calculated so far. Default is \code{self$Values}, if not
+ #' explicitly given
+ #' @param tarif The underlying [InsuranceTarif] object describing the
+ #' Product/Tariff. Default is \code{self$tarif}, if not explicitly given.
+ #' @param blocks The list of all contract children for contracts with
+ #' multiple insurance blocks (e.g. dynamic increases, riders, etc.)
+ #'
+ #' @examples
+ #' # TODO
addHistorySnapshot = function(time = 0, comment = "Initial contract values", type = "Contract", params = self$Parameters, values = self$Values, tarif = self$tarif, blocks = self$blocks) {
self$history = rbind(
self$history,
@@ -246,6 +340,35 @@ InsuranceContract = R6Class(
invisible(self)
},
+ #' @description Add a child contract block (e.g. a dynamic increase or a rider) to an insurance contract
+ #'
+ #' @details Contracts with multiple contract blocks (typically either
+ #' contracts with dynamic increases, sum increases or protection riders)
+ #' are constructed by instantiating the child block (e.g. a single
+ #' dynamic increase or the rider) independently with its own (shorter)
+ #' duration and then inserting it into the parent contract with this
+ #' function at the given time.
+ #'
+ #' If no [InsuranceContract] object is passed as \code{block}, a copy
+ #' of the parent is created with overriding parameters given in \code{...}.
+ #'
+ #' @param id The identifier of the child block to be inserted
+ #' @param block The [InsuranceContract] object describing the child block.
+ #' If NULL (or not given at all), a copy of the parent will be
+ #' created
+ #' @param t Then the child block starts, relative to the parent block.
+ #' The child block is calculated independently (with time 0
+ #' describing its own start), so when aggregating all values from
+ #' the individual blocks to overall values for the whole contract,
+ #' the child's values need to be translated to the parent contracts's
+ #' time frame using this parameter
+ #' @param comment The comment to use in the history snapshot.
+ #' @param ... parameters to be passed to [InsuranceContract$new()] when
+ #' \code{block} is not given and a copy of the parent should be
+ #' created with overrides.
+ #'
+ #' @examples
+ #' # TODO
addBlock = function(id = NULL, block = NULL, t = block$Values$int$blockStart, comment = comment, ...) {
if (missing(block) || is.null(block) || !is(block, "InsuranceContract")) {
# Create a block with the same tariff and parameters as the main contract, but allow overriding params with the ... arguments
diff --git a/R/InsuranceParameters.R b/R/InsuranceParameters.R
index 0a670e0..c7950b5 100644
--- a/R/InsuranceParameters.R
+++ b/R/InsuranceParameters.R
@@ -140,7 +140,7 @@ InsuranceContract.Values = list(
#' default = "Hauptvertrag"}
#' \item{\code{$sumInsured}}{Sum insured, default = 100,000}
#' \item{\code{$YOB}}{Year of birth of the insured, used to determine the
-#' age for the application of the mortality table},
+#' age for the application of the mortality table}
#' \item{\code{$age}}{Age of the insured}
#' \item{\code{$technicalAge}}{Technical age of the insured (when the age
#' for the application of the mortality table does not coincide
@@ -185,7 +185,6 @@ InsuranceContract.Values = list(
#' "in arrears"}
#' \item{\code{$premiumFrequency}}{Number of premium payments per year, default is 1.}
#' \item{\code{$benefitFrequency}}{Number of benefit payments per year, default is 1.}
-#'
#' \item{\code{$widowProportion}}{For annuities with a widow transition,
#' this describes the factor of the widow benefits relative to
#' the original benefit.}
@@ -303,7 +302,6 @@ InsuranceContract.Values = list(
#' rate (percentage rebate of the gross premium)}
#' \item{\code{$advanceProfitParticipationInclUnitCost}}{Advance profit
#' participation rate (percentage rebate on the gross premium after all surcharges and unit costs.}
-#'
#' \item{\code{$waitingPeriod}}{Waiting period of the profit sharing (e.g.
#' no profit in the first two years of a contract, or similar)}
#' \item{\code{$guaranteedInterest}}{Individual contract-specific overrides
@@ -317,7 +315,6 @@ InsuranceContract.Values = list(
#' \item{\code{$terminalBonusRate}}{Terminal bonus rate (non-terminal-bonus
#' fund, but "old" Austrian terminal bonus)}
#' \item{\code{$terminalBonusFundRate}}{Terminal bonus fund rate}
-
#' \item{\code{$profitParticipationScheme}}{Profit participation scheme (object of class [ProfitParticipation])}
#' \item{\code{$profitComponents}}{Profit components of the profit scheme. List containing one or more of \code{c("interest", "risk", "expense", "sum", "terminal")}}
#' \item{\code{$profitClass}}{String describing the profit class the tariff
diff --git a/man/CalculationSingleEnum-class.Rd b/man/CalculationSingleEnum-class.Rd
new file mode 100644
index 0000000..b84793a
--- /dev/null
+++ b/man/CalculationSingleEnum-class.Rd
@@ -0,0 +1,16 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/HelperFunctions.R
+\docType{class}
+\name{CalculationSingleEnum-class}
+\alias{CalculationSingleEnum-class}
+\alias{CalculationEnum}
+\title{Enum to define how much of a contract needs to be calculated automatically.}
+\description{
+Enum to define how much of a contract needs to be calculated automatically.
+}
+\details{
+When an \link{InsuranceContract} object is created, all time series are immediately
+calculated. However, sometimes, one only needs part of the values, so it
+would be a waste of resources to calculate e.g. all future reserves and
+profit participation, if only premiums are of interest.
+}
diff --git a/man/InsuranceContract.ParameterDefaults.Rd b/man/InsuranceContract.ParameterDefaults.Rd
index e1907bb..68ddbb3 100644
--- a/man/InsuranceContract.ParameterDefaults.Rd
+++ b/man/InsuranceContract.ParameterDefaults.Rd
@@ -42,7 +42,7 @@ contracts with multiple parts, e.g. dynamic increases),
default = "Hauptvertrag"}
\item{\code{$sumInsured}}{Sum insured, default = 100,000}
\item{\code{$YOB}}{Year of birth of the insured, used to determine the
-age for the application of the mortality table},
+age for the application of the mortality table}
\item{\code{$age}}{Age of the insured}
\item{\code{$technicalAge}}{Technical age of the insured (when the age
for the application of the mortality table does not coincide
@@ -86,25 +86,24 @@ are paid in advance (default) or arrears. Value is of type
\link{PaymentTimeEnum} with possible values "in advance" and
"in arrears"}
\item{\code{$premiumFrequency}}{Number of premium payments per year, default is 1.}
-\item{\code{$benefitFrequency}}{Number of benefit payments per year, default is 1.}\preformatted{\\item\{\code{$widowProportion}\}\{For annuities with a widow transition,
- this describes the factor of the widow benefits relative to
- the original benefit.\}
-\\item\{\code{$deathBenefitProportion}\}\{For endowments with a death and
- survival benefit, this describes the proportion of the death
- benefit relative to the survival benefit.\}
-\\item\{\code{$premiumRefund}\}\{Proportion of (gross) premiums refunded on
- death (including additional risk, e.g. 1.10 = 110\% of paid premiums)\}
-\\item\{\code{$premiumIncrease}\}\{The yearly growth factor of the premium,
- i.e. 1.05 means +5\% increase each year; a vector describes the
- premiums for all years\}
-\\item\{\code{$annuityIncrease}\}\{The yearly growth factor of the annuity
- payments, i.e. 1.05 means +5\% increase each year; a vector
- describes the annuity unit payments for all years\}
-\\item\{\code{$deathBenefit}\}\{The yearly relative death benefit (relative
- to the initial sum insured); Can be set to a \code{function(len,
- params, values)}, e.g. \code{deathBenefit = deathBenefit.linearDecreasing}\}
-}
-
+\item{\code{$benefitFrequency}}{Number of benefit payments per year, default is 1.}
+\item{\code{$widowProportion}}{For annuities with a widow transition,
+this describes the factor of the widow benefits relative to
+the original benefit.}
+\item{\code{$deathBenefitProportion}}{For endowments with a death and
+survival benefit, this describes the proportion of the death
+benefit relative to the survival benefit.}
+\item{\code{$premiumRefund}}{Proportion of (gross) premiums refunded on
+death (including additional risk, e.g. 1.10 = 110\% of paid premiums)}
+\item{\code{$premiumIncrease}}{The yearly growth factor of the premium,
+i.e. 1.05 means +5\% increase each year; a vector describes the
+premiums for all years}
+\item{\code{$annuityIncrease}}{The yearly growth factor of the annuity
+payments, i.e. 1.05 means +5\% increase each year; a vector
+describes the annuity unit payments for all years}
+\item{\code{$deathBenefit}}{The yearly relative death benefit (relative
+to the initial sum insured); Can be set to a \code{function(len,
+ params, values)}, e.g. \code{deathBenefit = deathBenefit.linearDecreasing}}
}
}
@@ -208,28 +207,27 @@ while the bases, on which they are applied is defined in the profit scheme.
\item{\code{$advanceProfitParticipation}}{Advance profit participation
rate (percentage rebate of the gross premium)}
\item{\code{$advanceProfitParticipationInclUnitCost}}{Advance profit
-participation rate (percentage rebate on the gross premium after all surcharges and unit costs.}\preformatted{\\item\{\code{$waitingPeriod}\}\{Waiting period of the profit sharing (e.g.
- no profit in the first two years of a contract, or similar)\}
-\\item\{\code{$guaranteedInterest}\}\{Individual contract-specific overrides
- of the guaranteed interest rate (i.e. not keyed by year)\}
-\\item\{\code{$interestProfitRate}\}\{Interest profit rate (guaranteed interest
- rate + interest profit rate = total credited rate)\}
-\\item\{\code{$totalInterest}\}\{Total credited rate (guarantee + interest profit)\}
-\\item\{\code{$mortalityProfitRate}\}\{Mortality Profit rate\}
-\\item\{\code{$expenseProfitRate}\}\{Expense profit rate\}
-\\item\{\code{$sumProfitRate}\}\{Sum profit rate (for high sumInsured)\}
-\\item\{\code{$terminalBonusRate}\}\{Terminal bonus rate (non-terminal-bonus
- fund, but "old" Austrian terminal bonus)\}
-\\item\{\code{$terminalBonusFundRate}\}\{Terminal bonus fund rate\}
-\\item\{\code{$profitParticipationScheme}\}\{Profit participation scheme (object of class [ProfitParticipation])\}
-\\item\{\code{$profitComponents}\}\{Profit components of the profit scheme. List containing one or more of \code{c("interest", "risk", "expense", "sum", "terminal")}\}
-\\item\{\code{$profitClass}\}\{String describing the profit class the tariff
- is assigned to. Profit classes are used to bundle similar
- contracts (e.g. following similar risks) together. Profit
- participation rates are defined at the level of profit classes.\}
-\\item\{\code{$profitRates}\}\{General, company-wide profit rates, key columns are year and profitClass\}
-
-\\item\{\code{$scenarios}\}\{profit participation scenarios (list of overridden parameters for each scenario)\}
+participation rate (percentage rebate on the gross premium after all surcharges and unit costs.}
+\item{\code{$waitingPeriod}}{Waiting period of the profit sharing (e.g.
+no profit in the first two years of a contract, or similar)}
+\item{\code{$guaranteedInterest}}{Individual contract-specific overrides
+of the guaranteed interest rate (i.e. not keyed by year)}
+\item{\code{$interestProfitRate}}{Interest profit rate (guaranteed interest
+rate + interest profit rate = total credited rate)}
+\item{\code{$totalInterest}}{Total credited rate (guarantee + interest profit)}
+\item{\code{$mortalityProfitRate}}{Mortality Profit rate}
+\item{\code{$expenseProfitRate}}{Expense profit rate}
+\item{\code{$sumProfitRate}}{Sum profit rate (for high sumInsured)}
+\item{\code{$terminalBonusRate}}{Terminal bonus rate (non-terminal-bonus
+fund, but "old" Austrian terminal bonus)}
+\item{\code{$terminalBonusFundRate}}{Terminal bonus fund rate}
+\item{\code{$profitParticipationScheme}}{Profit participation scheme (object of class \link{ProfitParticipation})}
+\item{\code{$profitComponents}}{Profit components of the profit scheme. List containing one or more of \code{c("interest", "risk", "expense", "sum", "terminal")}}
+\item{\code{$profitClass}}{String describing the profit class the tariff
+is assigned to. Profit classes are used to bundle similar
+contracts (e.g. following similar risks) together. Profit
+participation rates are defined at the level of profit classes.}
+\item{\code{$profitRates}}{General, company-wide profit rates, key columns are year and profitClass}\preformatted{\\item\{\code{$scenarios}\}\{profit participation scenarios (list of overridden parameters for each scenario)\}
}
}
diff --git a/man/InsuranceContract.Rd b/man/InsuranceContract.Rd
index 94c17a2..875320b 100644
--- a/man/InsuranceContract.Rd
+++ b/man/InsuranceContract.Rd
@@ -4,6 +4,11 @@
\alias{InsuranceContract}
\title{Base Class for Insurance Contracts}
\description{
+Base Class for Insurance Contracts
+
+Base Class for Insurance Contracts
+}
+\details{
R6 class that models a complete, general insurance contract.
The corresponding tariff and the profit participation scheme, as well as
all other relevant contract parameters (if not defined by the tariff or
@@ -22,6 +27,52 @@ whole contract period are calculated and can be accessed via the \code{Values}
field of the object.
}
+\section{Calculation approach: Valuation}{
+The calculation of all contract values is controlled by the function
+\code{\link[=InsuranceContract$calculateContract]{InsuranceContract$calculateContract()}} (using methods of the \link{InsuranceTarif}
+object) and follows the following logic:
+\enumerate{
+\item First the \strong{contingent (unit) cash flows} and the \strong{transition probbilities}
+are determined.
+\item The \strong{actuarial equivalence principle} states that at time of inception, the
+(net and gross) premium must be determined in a way that the present value
+of the future benefits and costs minus the present value of the future premiums
+must be equal, i.e. in expectation the future premiums ove the whole lifetime
+of the contract will exactly cover the benefits and costs. Similarly, at all
+later time steps, the difference between these two present values needs to be
+reserved (i.e. has already been paid by the customer by previous premiums).
+\item This allows the premiums to be calculated by first calculating the \strong{present
+values} for all of the \strong{benefit and costs cash flow} vectors.
+\item The formulas
+to calculate the gross, Zillmer and net \strong{premiums} involve simple linear
+combinations of these present values, so the \strong{coefficients of these formulas}
+are determined next.
+\item With the coefficients of the premium formulas calculated, all \strong{premiums
+can be calculated} (first the gross premium, because due to potential gross
+premium refunds in case of death, the formula for the net premium requires
+the gross premium, which the formula for the gross premium involves no other
+type of premuim).
+\item With premiums determined, all unit cash flows and unit present values can
+now be expressed in monetary terms / as \strong{absolute cash flows} (i.e. the actual Euro-amount that flows
+rather than a percentage).
+\item As described above, the difference between the present values of premiums
+and present values of benefits and costs is defined as the required amount
+of reserves, so the \strong{reserves (net, gross, administration cost, balance sheet)}
+and all values derived from them (i.e. surrender value, sum insured in case of
+premium waiver, etc.) are calculated.
+\item The \strong{decomposition of the premium} into parts dedicated to specific purposes
+(tax, rebates, net premium, gross premium, Zillmer premium, cost components,
+risk premium, savings premium, etc.) can be done once the reserves are
+ready (since e.g. the savings premium is defined as the difference of
+discounted reserves at times $t$ and $t+1$).
+\item If the contract has \strong{(discretionary or obligatory) profit sharing}B mechanisms
+included, the corresponding \link{ProfitParticipation} object can calculate that
+profit sharing amounts, once all guaranteed values are calculated. This can
+also be triggered manually (with custom profit sharing rates) by calling
+the methods \code{\link[=InsuranceContract$profitScenario]{InsuranceContract$profitScenario()}} or \code{\link[=InsuranceContract$addProfitScenario]{InsuranceContract$addProfitScenario()}}.
+}
+}
+
\section{Calculation approach: Cash Flows}{
An insurance contract is basically defined by the (unit) cash flows it produces:
\itemize{
@@ -87,53 +138,80 @@ probabilities):
\item guaranteed cash flows: 0, 0, 0, ..., 0, 1
\item death benefit cash flows: 0, 0, 0, 0, ..., 0
}
-}
-\section{Calculation approach: Valuation}{
-The calculation of all contract values is controlled by the function
-\code{\link[=InsuranceContract$calculateContract]{InsuranceContract$calculateContract()}} (using methods of the \link{InsuranceTarif}
-object) and follows the following logic:
-\enumerate{
-\item First the \strong{contingent (unit) cash flows} and the \strong{transition probbilities} are determined.
-\item The \strong{actuarial equivalence principle} states that at time of inception, the
-(net and gross) premium must be determined in a way that the present value
-of the future benefits and costs minus the present value of the future premiums
-must be equal, i.e. in expectation the future premiums ove the whole lifetime
-of the contract will exactly cover the benefits and costs. Similarly, at all
-later time steps, the difference between these two present values needs to be
-reserved (i.e. has already been paid by the customer by previous premiums).
-\item This allows the premiums to be calculated by first calculating the \strong{present
-values} for all of the \strong{benefit and costs cash flow} vectors.
-\item The formulas
-to calculate the gross, Zillmer and net \strong{premiums} involve simple linear
-combinations of these present values, so the \strong{coefficients of these formulas}
-are determined next.
-\item With the coefficients of the premium formulas calculated, all \strong{premiums
-can be calculated} (first the gross premium, because due to potential gross
-premium refunds in case of death, the formula for the net premium requires
-the gross premium, which the formula for the gross premium involves no other
-type of premuim).
-\item With premiums determined, all unit cash flows and unit present values can
-now be expressed in monetary terms / as \strong{absolute cash flows} (i.e. the actual Euro-amount that flows
-rather than a percentage).
-\item As described above, the difference between the present values of premiums
-and present values of benefits and costs is defined as the required amount
-of reserves, so the \strong{reserves (net, gross, administration cost, balance sheet)}
-and all values derived from them (i.e. surrender value, sum insured in case of
-premium waiver, etc.) are calculated.
-\item The \strong{decomposition of the premium} into parts dedicated to specific purposes
-(tax, rebates, net premium, gross premium, Zillmer premium, cost components,
-risk premium, savings premium, etc.) can be done once the reserves are
-ready (since e.g. the savings premium is defined as the difference of
-discounted reserves at times $t$ and $t+1$).
-\item If the contract has \strong{(discretionary or obligatory) profit sharing} mechanisms
-included, the corresponding \link{ProfitParticipation} object can calculate that
-profit sharing amounts, once all guaranteed values are calculated. This can
-also be triggered manually (with custom profit sharing rates) by calling
-the methods \code{\link[=InsuranceContract$profitScenario]{InsuranceContract$profitScenario()}} or \code{\link[=InsuranceContract$addProfitScenario]{InsuranceContract$addProfitScenario()}}.
+The \code{InsuranceContract$new()} function creates a new
+insurance contract for the given tariff, using the parameters passed
+to the function (and the defaults specified in the tariff).
+
+As soon as this function is called, the contract object calculates
+all time series (cash flows, premiums, reserves, profit participation)
+for the whole contract duration.
+
+The most important parameters that are typically passed to the
+constructor are:
+\itemize{
+\item \code{age} ... Age of the insured person (used to derive mortalities / transition probabilities)
+\item \code{policyPeriod} ... Maturity of the policy (in years)
+\item \code{premiumPeriod} ... How long premiums are paid (\code{premiumPeriod = 1}
+for single-premium contracts, \code{premiumPeriod} equals
+\code{policyPeriod} for regular premium payments for the whole
+contract period, while other premium payment durations indicate
+premium payments only for shorter periods than the whole contract
+duration). Default is equal to \code{policyPeriod}
+\item \code{sumInsured} ... The sum insured (i.e. survival benefit for
+endowments, death benefit for whole/term life insurances,
+annuity payments for annuities)
+\item \code{contractClosing} ... Date of the contract beginning (typically
+created using something like \code{as.Date("2020-08-01")})
+\item \code{YOB} ... Year of birth of the insured (for cohort mortality
+tables). If not given, YOB is derived from \code{age} and
+\code{contractClosing}.
+\item \code{deferralPeriod} ... Deferral period for deferred annuities
+(i.e. when annuity payments start at a future point in time).
+Default is 0.
+\item \code{premiumFrequency} ... How many premium payments per year are
+made (e.g. 1 for yearly premiums, 4 for quarterly premiumd,
+12 for monthly premium payments). Default is 1 (yearly premiums).
}
+
+While these are the most common and most important parameters, all
+parameters can be overwritten on a per-contract basis, even those
+that are defined by the tariff. For a full list and explanation of all
+parameters, see \link{InsuranceContract.ParameterDefaults}.
+
+The \code{InsuranceContract$addHistorySnapshot()} function
+adds the current (or the explicitly given) state of the contract
+(parameters, calculated values, tarif, list of all contract blocks)
+to the history list (available in the \code{history} field of the
+contract, i.e. \code{InsuranceContract$history}).
+
+Contracts with multiple contract blocks (typically either
+contracts with dynamic increases, sum increases or protection riders)
+are constructed by instantiating the child block (e.g. a single
+dynamic increase or the rider) independently with its own (shorter)
+duration and then inserting it into the parent contract with this
+function at the given time.
+
+If no \link{InsuranceContract} object is passed as \code{block}, a copy
+of the parent is created with overriding parameters given in \code{...}.
}
+\examples{
+# TODO
+
+
+## ------------------------------------------------
+## Method `InsuranceContract$addHistorySnapshot`
+## ------------------------------------------------
+
+# TODO
+
+## ------------------------------------------------
+## Method `InsuranceContract$addBlock`
+## ------------------------------------------------
+
+# TODO
+}
\section{Public fields}{
\if{html}{\out{<div class="r6-fields">}}
\describe{
@@ -199,6 +277,7 @@ contract state and its values before the change).}
\if{html}{\out{<a id="method-new"></a>}}
\if{latex}{\out{\hypertarget{method-new}{}}}
\subsection{Method \code{new()}}{
+Create a new insurance contract (for the given tariff/product) and calculate all time series
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceContract$new(
tarif,
@@ -209,11 +288,43 @@ contract state and its values before the change).}
)}\if{html}{\out{</div>}}
}
+\subsection{Arguments}{
+\if{html}{\out{<div class="arguments">}}
+\describe{
+\item{\code{tarif}}{The \link{InsuranceTarif} object describing the Tariff/Product
+and providing defaults for the parameters.}
+
+\item{\code{parent}}{For contracts with multiple contract blocks (dynamic
+increases, sum increases, riders), each child is created with
+a pointer to its parent. NULL for single-block contracts or
+for the overall-contract of a multi-block contract. This
+parameter is used internally, but should not be used in
+user-written code.}
+
+\item{\code{calculate}}{how much of the contract's time series need to be
+calculated. See \link{CalculateEnum} for all possible values. This
+is usefull to prevent calculation of e.g. reserves and profit
+participation, when one only wants to create a grid of premiums.}
+
+\item{\code{profitid}}{The ID of the default profit participation scenario.
+The default profit participation scenario uses the default
+values passed, while further scenarios can be added by
+\code{\link[=InsuranceContract$addProfitScenario]{InsuranceContract$addProfitScenario()}}.}
+
+\item{\code{...}}{Further parameters (age, sum insured, contract closing /
+begin, premium payment details, etc.) of the contract, which
+can also override parameters defined at the tariff-level.
+Possible values are all sub-fields of the
+\link{InsuranceContract.ParameterDefaults} data structure.}
+}
+\if{html}{\out{</div>}}
+}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-addHistorySnapshot"></a>}}
\if{latex}{\out{\hypertarget{method-addHistorySnapshot}{}}}
\subsection{Method \code{addHistorySnapshot()}}{
+Add the current state of the contract to the history list
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceContract$addHistorySnapshot(
time = 0,
@@ -226,11 +337,46 @@ contract state and its values before the change).}
)}\if{html}{\out{</div>}}
}
+\subsection{Arguments}{
+\if{html}{\out{<div class="arguments">}}
+\describe{
+\item{\code{time}}{the time described by the snapshot}
+
+\item{\code{comment}}{a comment to store together with the contract state}
+
+\item{\code{type}}{The type of action that caused a history snapshot to
+be stored. Typical values are "Contract" to describe the initial
+contract, "Premium Waiver" or "Dynamic Increase".}
+
+\item{\code{params}}{The set of params to be stored in the history snapshot
+(default is \code{self$Parameters}, if not explicitly given)}
+
+\item{\code{values}}{The calculated time series of all contract values
+calculated so far. Default is \code{self$Values}, if not
+explicitly given}
+
+\item{\code{tarif}}{The underlying \link{InsuranceTarif} object describing the
+Product/Tariff. Default is \code{self$tarif}, if not explicitly given.}
+
+\item{\code{blocks}}{The list of all contract children for contracts with
+multiple insurance blocks (e.g. dynamic increases, riders, etc.)}
+}
+\if{html}{\out{</div>}}
+}
+\subsection{Examples}{
+\if{html}{\out{<div class="r example copy">}}
+\preformatted{# TODO
+}
+\if{html}{\out{</div>}}
+
+}
+
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-addBlock"></a>}}
\if{latex}{\out{\hypertarget{method-addBlock}{}}}
\subsection{Method \code{addBlock()}}{
+Add a child contract block (e.g. a dynamic increase or a rider) to an insurance contract
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceContract$addBlock(
id = NULL,
@@ -241,6 +387,38 @@ contract state and its values before the change).}
)}\if{html}{\out{</div>}}
}
+\subsection{Arguments}{
+\if{html}{\out{<div class="arguments">}}
+\describe{
+\item{\code{id}}{The identifier of the child block to be inserted}
+
+\item{\code{block}}{The \link{InsuranceContract} object describing the child block.
+If NULL (or not given at all), a copy of the parent will be
+created}
+
+\item{\code{t}}{Then the child block starts, relative to the parent block.
+The child block is calculated independently (with time 0
+describing its own start), so when aggregating all values from
+the individual blocks to overall values for the whole contract,
+the child's values need to be translated to the parent contracts's
+time frame using this parameter}
+
+\item{\code{comment}}{The comment to use in the history snapshot.}
+
+\item{\code{...}}{parameters to be passed to \code{\link[=InsuranceContract$new]{InsuranceContract$new()}} when
+\code{block} is not given and a copy of the parent should be
+created with overrides.}
+}
+\if{html}{\out{</div>}}
+}
+\subsection{Examples}{
+\if{html}{\out{<div class="r example copy">}}
+\preformatted{# TODO
+}
+\if{html}{\out{</div>}}
+
+}
+
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-addDynamics"></a>}}
--
GitLab