InsuranceTarif: Base class for traditional Insurance Tarifs (with fixed...
In kainhofer/r-life-insurance-contracts: Framework for Traditional Life Insurance Contracts
InsuranceTarif 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
nameThe tariff's unique name. Will also be used as the key for exported data.
tarifThe tariff's public name (typically a product name), not necessarily unique.
descA short human-readable description of the tariff and its main features.
tariffTypeAn 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.
ParametersA 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.
dummyDummy 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
nameThe unique name / ID of the tariff
typeAn enum specifying the main characteristics of the tarif. See TariffTypeEnum
tarifThe tariff's public name to be stored in the tarif field.
descA 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
nameThe unique name / ID of the tariff
tarifThe tariff's public name to be stored in the tarif field.
descA short human-readable description to be stored in the desc field.
tariffTypeAn 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
paramsContract-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
paramsContract-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
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract 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
paramsThe 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
lenThe desired length of the returned data frame (the number of contract periods desire)
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract 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
lenThe desired length of the returned data frame (the number of contract periods desire)
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract 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
lenThe desired length of the returned data frame (the number of contract periods desire)
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract 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
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract 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
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract 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
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract 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
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract values calculated so far (in the contract$Values
list) then this method is called by the contract object
cashFlowsdata.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
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract values calculated so far (in the contract$Values
list) then this method is called by the contract object
presentValuesThe 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
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract 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
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract 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
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract 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
typeThe 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
premiumsThe 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)
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract values calculated so far (in the contract$Values
list) then this method is called by the contract object
premiumCalculationTimeThe 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 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
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract values calculated so far (in the contract$Values
list) then this method is called by the contract object
premiumCalculationTimeThe 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
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract 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
methodThe method for the balance sheet interpolation (30/360, act/act, act/360, act/365 or a function)
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
yearshow 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
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract 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
paramsContract-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
profitScenarioThe ID of the profit scenario for which to calculate the reserves
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract 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
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract 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
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract 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(values, ...)
Arguments
valuesThe 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(values, params)
Arguments
valuesThe time series, for which future present values at all
times are desired
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
...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
loadingThe premiumFrequencyLoading parameter of the Contract or Tariff to be evaluated
frequencyThe premiumFrequency parameter of the contract
paramsContract-specific, full set of parameters of the contract
(merged parameters of the defaults, the tariff, the profit participation
scheme and the contract)
valuesContract 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
deepWhether 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()
kainhofer/r-life-insurance-contracts documentation built on Sept. 18, 2022, 7:56 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| InsuranceTarif | 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
nameThe tariff's unique name. Will also be used as the key for exported data.
tarifThe tariff's public name (typically a product name), not necessarily unique.
descA short human-readable description of the tariff and its main features.
tariffTypeAn 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.
ParametersA 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.
dummyDummy 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
nameThe unique name / ID of the tariff
typeAn enum specifying the main characteristics of the tarif. See TariffTypeEnum
tarifThe tariff's public name to be stored in the
tariffield.descA short human-readable description to be stored in the
descfield....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
nameThe unique name / ID of the tariff
tarifThe tariff's public name to be stored in the
tariffield.descA short human-readable description to be stored in the
descfield.tariffTypeAn 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
paramsContract-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
paramsContract-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
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) 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
paramsThe 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
lenThe desired length of the returned data frame (the number of contract periods desire)
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) 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
lenThe desired length of the returned data frame (the number of contract periods desire)
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) 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
lenThe desired length of the returned data frame (the number of contract periods desire)
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) 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
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) 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
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) 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
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) 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
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) then this method is called by the contract objectcashFlowsdata.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
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) then this method is called by the contract objectpresentValuesThe 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
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) 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
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) 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
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) 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
typeThe 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
premiumsThe 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)
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) then this method is called by the contract objectpremiumCalculationTimeThe 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 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
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) then this method is called by the contract objectpremiumCalculationTimeThe 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
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) 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
methodThe method for the balance sheet interpolation (30/360, act/act, act/360, act/365 or a function)
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
yearshow 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
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) 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
paramsContract-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
profitScenarioThe ID of the profit scenario for which to calculate the reserves
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) 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
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) 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
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) 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(values, ...)
Arguments
valuesThe 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(values, params)
Arguments
valuesThe time series, for which future present values at all times are desired
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
...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
loadingThe premiumFrequencyLoading parameter of the Contract or Tariff to be evaluated
frequencyThe premiumFrequency parameter of the contract
paramsContract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
valuesContract values calculated so far (in the
contract$Valueslist) 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
deepWhether 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()
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.