InsuranceContract.ParameterDefaults: Default parameters for the InsuranceContract class.

In kainhofer/r-life-insurance-contracts: Framework for Traditional Life Insurance Contracts

Default parameters for the InsuranceContract class.

Description

A new contract will be pre-filled with these values, and values passed in the constructor (or with other setter functions) will override these values.

Usage

InsuranceContract.ParameterDefaults

Format

The parameter list is a list of lists with the following structure:

Sublists:

• $ContractData ... Contract-specific data (policy period, closing, age, sum insured, premium payments, etc.)

• $ContractState ... Current contract state (paid-up, surrender penalty already applied, alpha costs already (partially) refunded)

• $ActuarialBases ... Actuarial bases for the contract calculation (mortality/invalidity table, guaranteed interest, surrender penalty, etc.)

• $Costs, $minCosts ... Expenses charged to the contract (see initializeCosts())

• $Loadings ... Loadings, rebates and other charges of the tariff / contract (tax, unit costs, surcharge for no medial exam, premium/benefit frequency loading)

• $Features ... Peculiarities of the tariff (to enable non-standard formulas for certain company-specific historical "glitches" in the tariff definitions.)

• $ProfitParticipation ... Profit scheme and profit participation rates (default values, can be overwritten per profit scenario)

• $Hooks ... Hook functions to allow modification of various calculation aspects (e.g. modify the default cash flows after their setup)

Elements of sublist InsuranceContract.ParameterDefault$ContractData

These values are typically set per contract and not by the tariff. Notable exceptions are the contract duration in some instances and the premiumPeriod=1 for single-premium contracts.

$id

ID of the contract (to distinguish individual parts in contracts with multiple parts, e.g. dynamic increases), default = "Hauptvertrag"

$sumInsured

Sum insured, default = 100,000

$initialCapital

Reserve/Capital that is already available at contract inception, e.g. from a previous contract. No tax or acquisition costs are applied to this capital.

$YOB (deprecated)

Year of birth of the insured, used to determine the age for the application of the mortality table

$birthDate

Date of birth of the insured, used to determine the age for the application of the mortality table. Alternatively, the year alone can be passed as YOB.

$age

Age of the insured

$technicalAge

Technical age of the insured (when the age for the application of the mortality table does not coincide with the real age)

$ageDifferences

Vector of age differences to the first insured for contracts with multiple insured (i.e. joint-lives)

$sex

Sex of the insured, to allow gender-specific prixing (e.g. different mortalities or age modification), default="unisex", Type is SexEnum

$policyPeriod

Policy Duration (in years)

$premiumPeriod

Premium payment period (in year), for single-premium contracts, premiumPeriod = 1. Default is policyPeriod, i.e. regular premiums during the whole contract period

$deferralPeriod

deferral period for annuities, i.e. the period survival payments start only after this period, typically the retirement age. This applies mostly to tariffs of type annuity, although deferral periods are possible (but not common) for all other types of insurance, too.

$guaranteedPeriod

guaranteed annuity payment period. The annuity pays out for this period, even if the insured dies. This applies only to tariffs of type annuity.

$contractClosing

The date (variable of type Date) when the coverage of the contract starts (not neccessarily equal to the date when the contract was signed). Typically generated by a call to as.Date(). The year is relevant to derive the age of the insured, while month and day are relevant for the interpolation of the balance sheet reserves

$blockStart

For contracts with multiple blocks (e.g. multiple dynamic increases, where each increase is modelled like a separate contract), this variable holds the offset of the current contract block relative to the main contract block. The main block starts a 0, dynamic increases start later! This value is only used by the parent block (i.e. $t=0$ of the child is aligned with $t=blockStart$ of the parent block.

$premiumPayments

Whether premiums are paid in advance (default) or arrears. Value is of type PaymentTimeEnum with possible values "in advance" and "in arrears"

$benefitPayments

Whether recurring benefits (e.g. annuities) are paid in advance (default) or arrears. Value is of type PaymentTimeEnum with possible values "in advance" and "in arrears"

$premiumFrequency

Number of premium payments per year, default is 1.

$benefitFrequency

Number of benefit payments per year, default is 1.

$premiumRefund

Proportion of (gross) premiums refunded on death (including additional risk, e.g. 1.10 = 110% of paid premiums)

$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

$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

$deathBenefit

The yearly relative death benefit (relative to the initial sum insured); Can be set to a function(len, params, values), e.g. deathBenefit = deathBenefit.linearDecreasing

$benefitParameter

(optional) Tariff-specific parameter to indicate special benefit conditions (e.g. for non-constant benefits the initial starting value, or a minimum benefit, etc.). This parameter is not used automatically, but needs to be processed by a custom $deathBenefit function.

$costWaiver

The fraction of the costs that are waived (only those cost components that are defined to be waivable, i.e. by defining a corresponding $minCosts). Linearly interpolates between $Costs and $minCosts, if the latter is set. Otherwise is has no effect.

$attributes

Additional custom attributes (as a named list), which can be used for particular behaviour of different contracts or contract slices.

Elements of sublist InsuranceContract.ParameterDefault$ContractState

Contract-specific status variables holding the status of the contract.

$premiumWaiver

Whether the contract is paid-up.

$surrenderPenalty

Whether a surrender penalty still applies (e.g. because it has already been applied during a contract change, or because due to legal reasons it can no longer be applied)

$alphaRefunded

Whether alpha costs have (at least partially) been refunded (e.g. when a contract is changed or paid-up). Default is not yet refunded.

Elements of sublist InsuranceContract.ParameterDefault$ActuarialBases

Tarif-specific actuarial calculation parameters of the contract. Typically, these values are set by the tariff, but can be overridden by contract (e.g. while prototyping a new product or a product change).

$mortalityTable

The mortalityTable object describing the mortality of the insured

$invalidityTable

For contracts with invalidity benefits, the mortalityTable object describing the probabilities of invalidity

$invalidityEndsContract

For contracts with invalidity benefits, whether a payment of an invalidity benefit ends the contract.

$i

Guaranteed yearly interest rate, default is 0.00, i.e. 0%

$balanceSheetDate

The day/month when balance sheet reserves are calculated. Value of type Date, typically generated with as.Date(). The year is actually irrelevant, only the day and month are relevant.

$balanceSheetMethod

How to interpolate the balance sheet reserves (at the balandeSheetDate) from the yearly contractual reserves. Either a string "30/360", "act/act", "act/360", "act/365" or a function with signature balanceSheetMethod(params, contractDates, balanceDates) that returns a vector of coefficients for each year to interpolate the reserves available at the given contractDates for the desired balanceDates

$unearnedPremiumsMethod

How to calculate the unearned premiums (considering the balance sheet date and the premium frequency). A function with signature unearnedPremiumsMethod(params, dates)

$surrenderValueCalculation

A function describing the surrender value calculation. If NULL, the full reserve will be used as surrender value. If given, it must be a function with signature function(SurrenderReserve, params, values).

$premiumWaiverValueCalculation

A function describing the reserve used to derive the premium-free sum insured. If NULL, the surrender value will be used. If given, it must be a function with signature function(SurrenderReserve, params, values)

$premiumFrequencyOrder

Order of the approximation for payments within the year (unless an extra frequency loading is used => then leave this at 0)

$benefitFrequencyOrder

Order of the approximation for payments within the year (unless an extra frequency loading is used => then leave this at 0)

Elements of sublist InsuranceContract.ParameterDefault$Costs

Definition of contractual costs charged to the contract. See initializeCosts().

$Costs

The full cost defined for the contract / tariff, usually set with initializeCosts() and setCost()

$minCosts

The minimum costs defined for the contract / tariff that cannot be waived. Either an explicit cost definition structure generated by initializeCosts() and setCost(), or a function(params, values, costs), where the full costs are passed as third parameter, so the function can modify only those cost parts that can be waived at all.

Elements of sublist InsuranceContract.ParameterDefault$Loadings

$ongoingAlphaGrossPremium

Acquisition cost that increase the gross premium

$tax

insurance tax, factor on each premium paid, default is 4%, i.e. i=0.04

$unitcosts

Annual unit cost for each policy, absolute value (can be a function)

$security

Additional security loading on all benefit payments, factor on all benefits

$noMedicalExam

Loading when no medicial exam is done, % of SumInsured

$noMedicalExamRelative

Loading when no medicial exam is done, % of gross premium

$sumRebate

gross premium reduction for large premiums, % of SumInsured

$extraRebate

gross premium reduction for any reason, % of SumInsured

$premiumRebate

gross premium reduction for large premiums, % of gross premium

$partnerRebate

Rebate on premium with all surcharges and rebates when more than one contract is written with identical parameters. Sums with advanceBonusInclUnitCost and premiumRebate.

$extraChargeGrossPremium

extra charges on gross premium (smoker, leisure activities, BMI too high, etc.)

$benefitFrequencyLoading

Loading on the benefit for premium payment frequencies of more than once a year. Format is list("1" = 0.0, "2" = 0.0, "4" = 0.0, "12" = 0.0)

$premiumFrequencyLoading

Loading on the premium for premium payment frequencies of more than once a year. Format is list("1" = 0.0, "2" = 0.0, "4" = 0.0, "12" = 0.0)

$alphaRefundPeriod

How long the acquisition costs should be (partially) refunded in case of surrender or premium waiver.

$commissionPeriod

Period, over which the acquisition costs are charged to the contract (if not fully up-front or over the whole contract period). This has only an effect for cost definitions with duration "CommissionPeriod". Default is 5 years.

Elements of sublist InsuranceContract.ParameterDefault$Features

$betaGammaInZillmer

Whether beta and gamma-costs should be included in the Zillmer premium calculation

$alphaRefundLinear

Whether the refund of alpha-costs on surrender is linear in t or follows the NPV of an annuity

$useUnearnedPremiums

Whether unearned premiums should be reported in the balance sheet reserves. Otherwise, a premium paid at the beginning of the period is added to the reserve at that time for balance-sheet purposes. For regular premiums, the default is TRUE, i.e. the balance-sheet reserve at time $t$ does not include the premium paid at time $t$, but unearned premiums are included in the balance sheet reserves. For single-premium contracts, there are no "unearned" premiums, but the initial single premium is added to the reserve immediately for balance-sheet purposes. In particular, the balance sheet reserve at time $t=0$ is not 0, but the premium paid. In turn, no unearned premiums are applied.

$surrenderIncludesCostsReserves

Whether (administration) cost reserves are paid out on surrender (i.e. included in the surrender value before surrender penalties are applied)

$unitcostsInGross

Whether unit costs are included in the gross premium calculation or added after gross premiums. (default: FALSE)

$absPremiumRefund

Constant death benefit (typically premium refund of a previous contract), relative to the sum insured.

$alphaCostsCommission

Whether alpha costs over the commision period are given as their actual yearly value ("actual"), or whether the given value is the sum ("sum") or the present value ("presentvalue") over the whole commission period.

Elements of sublist InsuranceContract.ParameterDefault$ProfitParticipation

Parameters describing the profit participation (instance of ProfitParticipation) Most element descrive some kind of profit rate (which can vary in time), while the bases, on which they are applied is defined in the profit scheme.

$advanceProfitParticipation

Advance profit participation rate (percentage rebate of the gross premium)

$advanceProfitParticipationInclUnitCost

Advance profit participation rate (percentage rebate on the gross premium after all surcharges and unit costs.

$waitingPeriod

Waiting period of the profit sharing (e.g. no profit in the first two years of a contract, or similar)

$guaranteedInterest

Individual contract-specific overrides of the guaranteed interest rate (i.e. not keyed by year)

$interestProfitRate

Interest profit rate (guaranteed interest rate + interest profit rate = total credited rate)

$totalInterest

Total credited rate (guarantee + interest profit)

$mortalityProfitRate

Mortality Profit rate

$expenseProfitRate

Expense profit rate

$sumProfitRate

Sum profit rate (for high sumInsured)

$terminalBonusRate

Terminal bonus rate (non-terminal-bonus fund, but "old" Austrian terminal bonus)

$terminalBonusFundRate

Terminal bonus fund rate

$profitParticipationScheme

Profit participation scheme (object of class ProfitParticipation)

$profitComponents

Profit components of the profit scheme. List containing one or more of c("interest", "risk", "expense", "sum", "terminal")

$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.

$profitRates

General, company-wide profit rates, key columns are year and profitClass

$scenarios

profit participation scenarios (list of overridden parameters for each scenario)

Elements of sublist InsuranceContract.ParameterDefault$Hooks

$adjustCashFlows

Function with signature function(x, params, values, ...) to adjust the benefit/premium cash flows after their setup.

$adjustCashFlowsCosts

Function with signature function(x, params, values, ...) to adjust the costs cash flows after their setup.

$adjustCosts

Function with signature function(costs, params, values, ...) to adjust the tariff costs after their setup (e.g. contract-specific conditions/waivers, etc.).

$adjustMinCosts

Function with signature function(minCosts, costs, params, values, ...) to adjust the tariff minimum (unwaivable) costs after their setup (e.g. contract-specific conditions/waivers, etc.).

$adjustPresentValues

Adjust the present value vectors that are later used to derive premiums and reserves. function(presentValues, params, values)

$adjustPresentValuesCosts

Adjust the present value cost vectors used to derive premiums and reserves. function(presentValuesCosts, params, values)

$adjustPremiumCoefficients

Function with signature function(coeff, type, premiums, params, values, premiumCalculationTime) to adjust the coefficients for premium calculation after their default setup. Use cases are e.g. term-fix tariffs where the Zillmer premium term contains the administration cost over the whole contract, but not other gamma- or beta-costs.

$adjustPVForReserves

Adjust the absolute present value vectors used to derive reserves (e.g. when a sum rebate is subtracted from the gamma-cost reserves without influencing the premium calculation). function(absPV, params, values)

$premiumRebateCalculation

Calculate the actual premium rebate from the rebate rate (e.g. when the premium rate is given as a yearly cost reduction applied to a single-premium contract). function(premiumRebateRate, params = params, values = values)

Examples

InsuranceContract.ParameterDefaults

kainhofer/r-life-insurance-contracts documentation built on Sept. 18, 2022, 7:56 p.m.