Skip to content
Snippets Groups Projects
Commit d6df2c4f authored by Reinhold Kainhofer's avatar Reinhold Kainhofer
Browse files

Doc work on InsuranceContract 

Also fix the InsuranceParameteers lists.
parent 0091fd72
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
NAMESPACE
+ 1
− 0
View file @ d6df2c4f
......@@ -70,6 +70,7 @@ export(padLast)
export(rollingmean)
export(showVmGlgExamples)
export(valueOrFunction)
exportClasses(CalculationSingleEnum)
exportClasses(PaymentTimeSingleEnum)
exportClasses(SexSingleEnum)
exportClasses(TariffTypeSingleEnum)
......
R/HelperFunctions.R
+ 22
− 0
View file @ d6df2c4f
......@@ -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)
#'
......
R/InsuranceContract.R
+ 167
− 44
View file @ d6df2c4f
......@@ -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
......
R/InsuranceParameters.R
+ 1
− 4
View file @ d6df2c4f
......@@ -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
......
man/CalculationSingleEnum-class.Rd 0 → 100644
+ 16
− 0
View file @ d6df2c4f
% 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.
}
man/InsuranceContract.ParameterDefaults.Rd
+ 40
− 42
View file @ d6df2c4f
......@@ -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)\}
}
}
......
man/InsuranceContract.Rd
+ 221
− 43
View file @ d6df2c4f
......@@ -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>}}
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment