InsuranceTarif {LifeInsureR} | R Documentation |
Base class for traditional Insurance Tarifs (with fixed guarantee, profit sharing and no unit-linked component)
Description
The class InsuranceTarif
provides the code and general
framework to implement contract-independent functionality of a life insurance
product.
Details
This is a base class for holding contract-independent values and
providing methods to calculate cash flows, premiums, etc. Objects of this
class do NOT contain contract-specific values like age, death probabilities,
premiums, reserves, etc. Rather, they are the calculation kernels that will
be called by the InsuranceContract
objects to make the actual,
tariff-specific calculations.
Most methods of this class are not meant to be called manually, but are supposed
to be called by the InsuranceContract object with contract-specific information.
The only methods that are typically used for defining an insurance tariff are
the constructor InsuranceTarif$new()
and the cloning method
InsuranceTarif$createModification()
.
All other methods should never be called manually.
However, as overriding private methods is not possible in an R6 class, all the methods need to be public to allow overriding them in derived classes.
Public fields
name
The tariff's unique name. Will also be used as the key for exported data.
tarif
The tariff's public name (typically a product name), not necessarily unique.
desc
A short human-readable description of the tariff and its main features.
tariffType
An enum specifying the main characteristics of the tarif. Possible values are:
- annuity
Whole life or term annuity (periodic survival benefits) with flexible payouts (constand, increasing, decreasing, arbitrary, etc.)
- wholelife
A whole or term life insurance with only death benefits. The benefit can be constant, increasing, decreasing, described by a function, etc.
- endowment
An endowment with death and survival benefits, potentially with different benefits.
- pureendowment
A pure endowment with only a survival benefit at the end of the contract. Optionally, in case of death, all or part of the premiums paid may be refunded.
- terme-fix
A terme-fix insurance with a fixed payout at the end of the contract, even if the insured dies before that time. Premiums are paid until death of the insured.
- dread-disease
A dread-disease insurance, which pays in case of a severe illness (typically heart attacks, cancer, strokes, etc.), but not in case of death.
- endowment + dread-disease
A combination of an endowment and a temporary dread-disease insurance. Benefits occur either on death, severe illness or survival, whichever comes first.
Parameters
A data structure (nested list) containing all relevant parameters describing a contract, its underlying tariff, the profit participation scheme etc. See InsuranceContract.ParameterStructure for all fields.
dummy
Dummy field to allow commas after the previous method
Methods
Public methods
Method new()
Initialize a new tariff object
Usage
InsuranceTarif$new( name = NULL, type = "wholelife", tarif = "Generic Tarif", desc = "Description of tarif", ... )
Arguments
name
The unique name / ID of the tariff
type
An enum specifying the main characteristics of the tarif. See TariffTypeEnum
tarif
The tariff's public name to be stored in the
tarif
field.desc
A short human-readable description to be stored in the
desc
field....
Parameters for the InsuranceContract.ParameterStructure, defining the characteristics of the tariff.
Details
The constructor function defines a tariff and generates the corresponding data structure, which can then be used with the InsuranceContract class to define an actual contract using the tariff.
The arguments passed to this function will be stored inside the
Parameters
field of the class, inside one of the lists sublists.
The parameters are stacked from different layers (higher levels override
default values from lower layers):
InsuranceContract object (parameters passed directly to the individual contract)
ProfitParticipation object (parameters for profit participation, passed to the definition of the profit plan, which is used for the tarif definition or the contract)
InsuranceTarif object (parameters passed to the definition of the tariff that was used for the contract)
Defaults taken from InsuranceContract.ParameterStructure
The general implementation of this parameter layering means that (a) a tariff can already provide default values for contracts (e.g. a default maturity, default sum insured, etc) and (b) individual contracts can override all parameters defined with the underlying tariff. In particular the latter feature has many use-cases in prototyping: E.g. when you have a tariff with a guaranteed interest rate of 1\ one can immediately instantiate a contract with an updated interest rate or mortality table for comparison. There is no need to re-implement a tariff for such comparisons, as long as only parameters are changed.
Examples
MortalityTables::mortalityTables.load("Austria_Annuities_AVOe2005R") tarif.male = InsuranceTarif$new(name = "Annuity Males", type = "annuity", i = 0.01, mortalityTable = AVOe2005R.male)
Method createModification()
create a copy of a tariff with certain parameters changed
Usage
InsuranceTarif$createModification( name = NULL, tarif = NULL, desc = NULL, tariffType = NULL, ... )
Arguments
name
The unique name / ID of the tariff
tarif
The tariff's public name to be stored in the
tarif
field.desc
A short human-readable description to be stored in the
desc
field.tariffType
An enum specifying the main characteristics of the tarif. See TariffTypeEnum
...
Parameters for the InsuranceContract.ParameterStructure, defining the characteristics of the tariff.
Details
This method createModification
returns a copy of the tariff
with all given arguments changed in the tariff's InsuranceTarif$Parameters
parameter list.
As InsuranceTarif is a R6 class with reference logic, simply assigning the object to a new variable does not create a copy, but references the original tariff object. To create an actual copy, one needs to call this method, which first clones the whole object and then adjusts all parameters to the values passed to this method.
Examples
MortalityTables::mortalityTables.load("Austria_Annuities_AVOe2005R") tarif.male = InsuranceTarif$new(name = "Annuity Males", type = "annuity", i = 0.01, mortalityTable = AVOe2005R.male) tarif.unisex = tarif.male$createModification(name = "Annuity unisex", mortalityTable = AVOe2005R.unisex)
Method getParameters()
Retrieve the parameters for this tariff (can be overridden for each contract)
Usage
InsuranceTarif$getParameters()
Examples
tarif.male = InsuranceTarif$new(name = "Annuity Males", type = "annuity", i = 0.01, mortalityTable = AVOe2005R.male) tarif.male$getParameters()
Method getInternalValues()
Get some internal parameters cached (length of data.frames, policy periods cut at max.age, etc.)
Usage
InsuranceTarif$getInternalValues(params, ...)
Arguments
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
...
currently unused
Details
This methos is not meant to be called explicitly, but rather used by the InsuranceContract class. It returns a list of maturities and ages relevant for the contract-specific calculations
Method getAges()
Calculate the contract-relevant age(s) given a certain parameter data structure (contract-specific values)
Usage
InsuranceTarif$getAges(params)
Arguments
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
Details
This method is not meant to be called explicitly, but rather used by the InsuranceContract class. It returns the relevant ages during the whole contract period
Method getTransitionProbabilities()
Calculate the transition probabilities from the contract-specific
parameters passed as params
and the already-calculated contract
values values
Usage
InsuranceTarif$getTransitionProbabilities(params, values)
Arguments
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract object
Details
Not to be called directly, but implicitly by the InsuranceContract object.
Method getCostValues()
Obtain the cost structure from the cost parameter and the given paremeter set
Usage
InsuranceTarif$getCostValues(params)
Arguments
params
The parameters of the contract / tariff
Details
Not to be called directly, but implicitly by the InsuranceContract object.
The cost parameter can be either an array of costs (generated by initializeCosts()
)
or a function with parameters param
and values
(=NULL) returning
an array of the required dimensions. This function makes sures that the
latter function is actually evaluated.
Method getPremiumCF()
Returns the unit premium cash flow for the whole contract period.
For constant premiums it will be rep(1, premiumPeriod),
for single premiums it will be c(1, 0, 0, ...),
for increasing premiums it will be (1+increase)^(0:(premiumPeriod-1)) and 0 after the premium period
Usage
InsuranceTarif$getPremiumCF(len, params, values)
Arguments
len
The desired length of the returned data frame (the number of contract periods desire)
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract object
Details
Not to be called directly, but implicitly by the InsuranceContract object.
Method getAnnuityCF()
Returns the unit annuity cash flow (guaranteed and contingent) for the whole annuity payment period (after potential deferral period)
For constant annuity it will be rep(1, annuityPeriod),
for increasing annuities it will be (1+increase)^(0:(premiumPeriod-1)) and 0 after the premium period
Usage
InsuranceTarif$getAnnuityCF(len, params, values)
Arguments
len
The desired length of the returned data frame (the number of contract periods desire)
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract object
Details
Not to be called directly, but implicitly by the InsuranceContract object.
Method getDeathCF()
Returns the unit death cash flow for the whole protection period (after potential deferral period!)
For constant death benefit it will be rep(1, policyPeriod),
for linearly decreasing sum insured it will be (policyPeriod:0)/policyPeriod
Usage
InsuranceTarif$getDeathCF(len, params, values)
Arguments
len
The desired length of the returned data frame (the number of contract periods desire)
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract object
Details
Not to be called directly, but implicitly by the InsuranceContract object.
Method getBasicCashFlows()
Returns the basic (unit) cash flows associated with the type
of insurance given in the InsuranceTarif's tariffType
field
Usage
InsuranceTarif$getBasicCashFlows(params, values)
Arguments
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract object
Details
Not to be called directly, but implicitly by the InsuranceContract object.
Method getCashFlows()
Returns the cash flows for the contract given the parameters
Usage
InsuranceTarif$getCashFlows(params, values)
Arguments
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract object
Details
Not to be called directly, but implicitly by the InsuranceContract object.
Method getCashFlowsCosts()
Returns the cost cash flows of the contract given the contract and tariff parameters
Usage
InsuranceTarif$getCashFlowsCosts(params, values)
Arguments
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract object
Details
Not to be called directly, but implicitly by the InsuranceContract object.
Method presentValueCashFlows()
Returns the present values of the cash flows of the contract
(cash flows already calculated and stored in the cashFlows
data.frame)
Usage
InsuranceTarif$presentValueCashFlows(params, values)
Arguments
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract objectcashFlows
data.frame of cash flows calculated by a call to
InsuranceTarif$getCashFlows()
Details
Not to be called directly, but implicitly by the InsuranceContract object.
Method presentValueCashFlowsCosts()
Calculates the present values of the cost cash flows of the
contract (cost cash flows alreay calculated by InsuranceTarif$getCashFlowsCosts()
and stored in the values
list
Usage
InsuranceTarif$presentValueCashFlowsCosts(params, values, presentValues)
Arguments
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract objectpresentValues
The present values of the insurance claims (without costs)
Details
Not to be called directly, but implicitly by the InsuranceContract object.
Method getAbsCashFlows()
Calculate the cash flows in monetary terms of the insurance contract
Usage
InsuranceTarif$getAbsCashFlows(params, values)
Arguments
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract object
Details
Once the premiums of the insurance contracts are calculated, all cash flows can also be expressed in absolute terms. This function calculates these time series in monetary terms, once the premiums are calculated by the previous functions of this class.
This method is NOT to be called directly, but implicitly by the InsuranceContract object.
Method getAbsPresentValues()
Calculate the absolute present value time series of the insurance contract
Usage
InsuranceTarif$getAbsPresentValues(params, values)
Arguments
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract object
Details
Once the premiums of the insurance contracts are calculated, all present values can also be expressed in absolute terms. This function calculates these time series in monetary terms, once the premiums and the unit-benefit present values are calculated by the previous functions of this classe.
This method is NOT to be called directly, but implicitly by the InsuranceContract object.
Method presentValueBenefits()
Calculate the absolute present value time series of the benefits of the insurance contract
Usage
InsuranceTarif$presentValueBenefits(params, values)
Arguments
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract object
Details
Once the premiums of the insurance contracts are calculated, all present values can also be expressed in absolute terms. This function calculates these time series of the benefits present values in monetary terms, once the premiums and the unit-benefit present values are calculated by the previous functions of this classe.
This method is NOT to be called directly, but implicitly by the InsuranceContract object.
Method getPremiumCoefficients()
Calculate the linear coefficients of the premium calculation formula for the insurance contract
Usage
InsuranceTarif$getPremiumCoefficients( type = "gross", coeffBenefits, coeffCosts, premiums, params, values, premiumCalculationTime = values$int$premiumCalculationTime )
Arguments
type
The premium that is supposed to be calculated ("gross", "Zillmer", "net")
coeffBenefits
(empty) data structure of the benefit coefficients. The actual values have no meaning, this parameter is only used to derive the required dimensions
coeffCosts
(empty) data structure of the cost coefficients. The actual values have no meaning, this parameter is only used to derive the required dimensions
premiums
The premium components that have already been calculated (e.g. for net and Zillmer, the gross premium has already been calculated to allow modelling the premium refund)
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract objectpremiumCalculationTime
The time when the premiums should be (re-)calculated according to the equivalence principle. A time 0 means the initial premium calculation at contract closing, later premium calculation times can be used to re-calculate the new premium after a contract change (possibly including an existing reserve)
Details
Not to be called directly, but implicitly by the InsuranceContract object.
When getPremiumCoefficients
is called, the values$premiums
array has NOT yet been filled! Instead, all premiums already calculated
(and required for the premium coefficients) are passed in the premiums
argument.
Method sumInsuredCalculation()
Calculate the sumInsured of the InsuranceContract given the
parameters and premiums given and teh , present values already calculated and
stored in the params
and values
lists.
Usage
InsuranceTarif$sumInsuredCalculation( params, values, calculationTime = values$int$premiumCalculationTime )
Arguments
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract objectcalculationTime
the time when the sumInsured should be recalculated from the given premium
Details
Not to be called directly, but implicitly by the InsuranceContract object.
Method premiumCalculation()
Calculate the premiums of the InsuranceContract given the
parameters, present values and premium cofficients already calculated and
stored in the params
and values
lists.
Usage
InsuranceTarif$premiumCalculation( params, values, premiumCalculationTime = values$int$premiumCalculationTime )
Arguments
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract objectpremiumCalculationTime
The time when the premiums should be (re-)calculated according to the equivalence principle. A time 0 means the initial premium calculation at contract closing, later premium calculation times can be used to re-calculate the new premium after a contract change (possibly including an existing reserve)
Details
Not to be called directly, but implicitly by the InsuranceContract object.
Method reserveCalculation()
Calculate the reserves of the InsuranceContract given the
parameters, present values and premiums already calculated and stored in
the params
and values
lists.
Usage
InsuranceTarif$reserveCalculation(params, values)
Arguments
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract object
Details
Not to be called directly, but implicitly by the InsuranceContract object.
Method getBalanceSheetReserveFactor()
Calculate the (linear) interpolation factors for the balance sheet reserve (Dec. 31) between the yearly contract closing dates
Usage
InsuranceTarif$getBalanceSheetReserveFactor(method, params, years = 1)
Arguments
method
The method for the balance sheet interpolation (30/360, act/act, act/360, act/365 or a function)
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
years
how many years to calculate (for some usances, the factor is different in leap years!)
Details
Not to be called directly, but implicitly by the InsuranceContract object.
Method reserveCalculationBalanceSheet()
Calculate the reserves for the balance sheets at Dec. 31 of each year by interpolation from the contract values calculated for the yearly reference date of the contract
Usage
InsuranceTarif$reserveCalculationBalanceSheet(params, values)
Arguments
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract object
Details
Not to be called directly, but implicitly by the InsuranceContract object.
Method calculateProfitParticipation()
Calculate the profit participation given the contract parameters and the already calculated reserves of the contract.
Usage
InsuranceTarif$calculateProfitParticipation(params, ...)
Arguments
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
...
Additional parameters for the profit participation calculation, passed through to the profit participation scheme's
ProfitParticipation$getProfitParticipation()
Details
Not to be called directly, but implicitly by the InsuranceContract object.
Method reservesAfterProfit()
Calculate the reserves after profit participation for the given profit scenario
Usage
InsuranceTarif$reservesAfterProfit(profitScenario, params, values, ...)
Arguments
profitScenario
The ID of the profit scenario for which to calculate the reserves
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract object...
TODO
Details
Not to be called directly, but implicitly by the InsuranceContract object.
Method getBasicDataTimeseries()
Return the time series of the basic contract
Usage
InsuranceTarif$getBasicDataTimeseries(params, values)
Arguments
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract object
Details
Not to be called directly, but implicitly by the InsuranceContract object.
Method premiumDecomposition()
Calculate the time series of the premium decomposition of the contract
Usage
InsuranceTarif$premiumDecomposition(params, values)
Arguments
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract object
Details
Not to be called directly, but implicitly by the InsuranceContract object. All premiums, reserves and present values have already been calculated.
Method calculateFutureSums()
Generic function to calculate future sums of the values
Usage
InsuranceTarif$calculateFutureSums(cf, ...)
Arguments
cf
The time series, for which future sums at all times are desired
...
currently unused
Method calculatePresentValues()
Calculate all present values for a given time series. The mortalities are taken from the contract's parameters.
Usage
InsuranceTarif$calculatePresentValues(cf, params, values)
Arguments
cf
The time series, for which future present values at all times are desired
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract object...
currently unused
Method evaluateFrequencyLoading()
Calculate the premium frequency loading, i.e. the surcharge on the premium for those cases where the premium is not paid yearly. Return values can be either a numeric value or a named list with all possible premium frequencies as keys.
Usage
InsuranceTarif$evaluateFrequencyLoading(loading, frequency, params, values)
Arguments
loading
The premiumFrequencyLoading parameter of the Contract or Tariff to be evaluated
frequency
The premiumFrequency parameter of the contract
params
Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
values
Contract values calculated so far (in the
contract$Values
list) then this method is called by the contract object
Method clone()
The objects of this class are cloneable with this method.
Usage
InsuranceTarif$clone(deep = FALSE)
Arguments
deep
Whether to make a deep clone.
Examples
# Define an insurance tariff for 10-year endowments, using a guaranteed interest
# rate of 1% and the Austrian population mortality table of the census 2011.
# Premiums are paid monthly in advance during the whole contract period.
MortalityTables::mortalityTables.load("Austria_Census")
# Cost structure:
# - 4% up-front acquisition costs (of premium sum)
# - 1% collection cost of each premium paid
# - 1%o yearly administration cost (of the sum insured) as long as premiums are paid
# - 2%o yearly administration cost for paid-up contracts
# - 10 Euro yearly unit costs (as long as premiums are paid)
costs.endw = initializeCosts(alpha = 0.04, beta = 0.01, gamma = 0.001,
gamma.paidUp = 0.002, gamma.premiumfree = 0.002, unitcosts = 10)
endowment.AT1 = InsuranceTarif$new(
name = "Endow AT 1%", type = "endowment", tarif = "Austrian Endowment",
desc = "An endowment for Austrian insured with 1% interest and no profit participation",
ContractPeriod = 10,
i = 0.01, mortalityTable = mort.AT.census.2011.unisex,
costs = costs.endw, premiumFrequency = 12)
# The instantiation of the actual contract will provide the contract specific
# information and immediately calculate all further values:
ctr.end.AT1 = InsuranceContract$new(tarif = endowment.AT1,
contractClosing = as.Date("2020-07-01"), age = 42)
# All values for the contract are already calculated during construction and
# stored in the ctr.end.AT1$Values list:
ctr.end.AT1$Values$basicData
ctr.end.AT1$Values$transitionProbabilities
ctr.end.AT1$Values$cashFlowsCosts
ctr.end.AT1$Values$presentValues
ctr.end.AT1$Values$premiums
ctr.end.AT1$Values$reserves
ctr.end.AT1$Values$premiumComposition
# etc.
## ------------------------------------------------
## Method `InsuranceTarif$new`
## ------------------------------------------------
MortalityTables::mortalityTables.load("Austria_Annuities_AVOe2005R")
tarif.male = InsuranceTarif$new(name = "Annuity Males", type = "annuity",
i = 0.01, mortalityTable = AVOe2005R.male)
## ------------------------------------------------
## Method `InsuranceTarif$createModification`
## ------------------------------------------------
MortalityTables::mortalityTables.load("Austria_Annuities_AVOe2005R")
tarif.male = InsuranceTarif$new(name = "Annuity Males", type = "annuity",
i = 0.01, mortalityTable = AVOe2005R.male)
tarif.unisex = tarif.male$createModification(name = "Annuity unisex",
mortalityTable = AVOe2005R.unisex)
## ------------------------------------------------
## Method `InsuranceTarif$getParameters`
## ------------------------------------------------
tarif.male = InsuranceTarif$new(name = "Annuity Males", type = "annuity",
i = 0.01, mortalityTable = AVOe2005R.male)
tarif.male$getParameters()