InsuranceContract {LifeInsureR}R Documentation

Base Class for Insurance Contracts

Description

Base Class for Insurance Contracts

Base Class for Insurance Contracts

Details

R6 class that models a complete, general insurance contract. The corresponding tariff and the profit participation scheme, as well as all other relevant contract parameters (if not defined by the tariff or explicitly overridden by the contract) can be given in the constructor.

Usage

The typical usage of this class is to simply call InsuranceContract$new().

All parameters from the InsuranceContract.ParameterDefaults can be passed to the constructor of the class (i.e. the InsuranceContract$new()-call). Parameters not explicitly given, will be taken from the tariff or as a fall-back mechanism from the InsuranceContract.ParameterDefaults defaults.

Immediately upon construction, all premiums, reserves and cash flows for the whole contract period are calculated and can be accessed via the Values field of the object.

Calculation approach: Valuation

The calculation of all contract values is controlled by the function InsuranceContract$calculateContract() (using methods of the InsuranceTarif object) and follows the following logic:

  1. First the contingent (unit) cash flows and the transition probbilities are determined.

  2. The actuarial equivalence principle states that at time of inception, the (net and gross) premium must be determined in a way that the present value of the future benefits and costs minus the present value of the future premiums must be equal, i.e. in expectation the future premiums ove the whole lifetime of the contract will exactly cover the benefits and costs. Similarly, at all later time steps, the difference between these two present values needs to be reserved (i.e. has already been paid by the customer by previous premiums).

  3. This allows the premiums to be calculated by first calculating the present values for all of the benefit and costs cash flow vectors.

  4. The formulas to calculate the gross, Zillmer and net premiums involve simple linear combinations of these present values, so the coefficients of these formulas are determined next.

  5. With the coefficients of the premium formulas calculated, all premiums can be calculated (first the gross premium, because due to potential gross premium refunds in case of death, the formula for the net premium requires the gross premium, which the formula for the gross premium involves no other type of premuim).

  6. With premiums determined, all unit cash flows and unit present values can now be expressed in monetary terms / as absolute cash flows (i.e. the actual Euro-amount that flows rather than a percentage).

  7. As described above, the difference between the present values of premiums and present values of benefits and costs is defined as the required amount of reserves, so the reserves (net, gross, administration cost, balance sheet) and all values derived from them (i.e. surrender value, sum insured in case of premium waiver, etc.) are calculated.

  8. The decomposition of the premium into parts dedicated to specific purposes (tax, rebates, net premium, gross premium, Zillmer premium, cost components, risk premium, savings premium, etc.) can be done once the reserves are ready (since e.g. the savings premium is defined as the difference of discounted reserves at times $t$ and $t+1$).

  9. If the contract has (discretionary or obligatory) profit sharingB mechanisms included, the corresponding ProfitParticipation object can calculate that profit sharing amounts, once all guaranteed values are calculated. This can also be triggered manually (with custom profit sharing rates) by calling the methods InsuranceContract$profitScenario()] or InsuranceContract$addProfitScenario().

Calculation approach: Cash Flows

An insurance contract is basically defined by the (unit) cash flows it produces:

Together with the transition probabilities (mortalityTable parameter) the present values can be calculated, from which the premiums follow and finally the reserves and a potential profit sharing.

For example, a term life insurance with regular premiums would have the following cash flows:

A single-premium term life insurance would look similar, except for the premiums:

A pure endowment has no death benefits, but a survival benefit of 1 at the maturity of the contract:

An endowment has also death benefits during the contract duration:

A (deferred) annuityB has premium cash flows only during the deferral peroid and only survival cash flows during the annuity payment phase. Often, in case of death during the deferral period, all premiums paid are refunded as a death benefit.:

A terme-fix insurance has a guaranteed payment at maturity, even if the insured has already died. The premiums, however, are only paid until death (which is not reflected in the contingent cash flows, but rather in the transition probabilities):

The InsuranceContract$new() function creates a new insurance contract for the given tariff, using the parameters passed to the function (and the defaults specified in the tariff).

As soon as this function is called, the contract object calculates all time series (cash flows, premiums, reserves, profit participation) for the whole contract duration.

The most important parameters that are typically passed to the constructor are:

While these are the most common and most important parameters, all parameters can be overwritten on a per-contract basis, even those that are defined by the tariff. For a full list and explanation of all parameters, see InsuranceContract.ParameterDefaults.

The InsuranceContract$addHistorySnapshot() function adds the current (or the explicitly given) state of the contract (parameters, calculated values, tarif, list of all contract blocks) to the history list (available in the history field of the contract, i.e. InsuranceContract$history).

Contracts with multiple contract blocks (typically either contracts with dynamic increases, sum increases or protection riders) are constructed by instantiating the child block (e.g. a single dynamic increase or the rider) independently with its own (shorter) duration and then inserting it into the parent contract with this function at the given time.

If no InsuranceContract object is passed as block, a copy of the parent is created with overriding parameters given in ....

This method adds a new contract block describing a dynamic or sum increase (increasing the sum insured at a later time $t$ than contract inception). This increase is modelled by a separate InsuranceContract object with the sum difference as its own sumInsured. 

     By default, all parameters are taken from the main contract,
     with the maturity adjusted to match the original contract's
     maturity.

     The main contract holds all child blocks, controls their
     valueation and aggregates all children's values to the
     total values of the overall contract.

When a contract expires, this function adds a follow-up contract (with either the same or a different tariff), using the existing reserve as additionalCapital at inception. Technically, a child block using the new contract data of the extension is added to the original contract. The over-all contract values are then the sum of the original contract (providing values until expiration) and the extension (providing values after the extension).

This method calculates all contract values (potentially starting from and preserving all values before a later time valuesFrom). This function is not meant to be called directly, but internally, whenever a contract is created or modified. 

     There is, however, a legitimate case to call this function
     when a contract was initially created with a value of
     \code{calculate} other than "all", so not all values of the
     contract were calculated. When one later needs more values
     than were initially calculated, this function can be called.
     However, any contract changes might need to be rolled back
     and reapplied again afterwards. So even in this case it is
     probably easier to create the contract object from scratch
     again.

This function is an internal function for contracts with multiple child blocks (dynamic increases, sum increases, riders). It takes the values from all child blocks and calculates the overall values from all child blocks aggregated. 

   This function should not be called manually.

This function modifies the contract at time $t$ so that no further premiums are paid (i.e. a paid-up contract) and the sumInsured is adjusted according to the existing reserves.

This function calculates one profit scenario with the provided profit participation parameters (all parameters not given in the call are taken from their values of the contract, profit participation scheme or tariff).

This function calculates one profit scenario with the provided profit participation parameters (all parameters not given in the call are taken from their values of the contract, profit participation scheme or tariff). The results are stored in a list of profit scenarios inside the contract. 

    This function can be chained to calculate and add multiple
    profit scenarios.

Public fields

tarif

The InsuranceTarif underlying this contract. The tarif is the abstract product description (i.e. defining the type of insurance, fixing tpyes of benefits, specifying costs, guaranteed interest rate, mortality tables, potential profit sharing mechanisms, etc.), while the contract holds the individual parts like age, sum insured, contract duration, premium payment frequency, etc.

parent

A pointer to the parent contract. Some contracts consist of multiple parts (e.g. a main savings contract with a dread-disease rider, or a contract with multiple dynamic increases). These are internally represented by one InsuranceContract object per contract part, plus one contract object combining them and deriving combined premiums, reserves and profit participation. The child contracts (i.e. the objects representing the individual parts) have a pointer to their parent, while the overall contract holds a list of all its child contract parts.

ContractParameters

Insurance contract parameters explicitly specified in the contract (i.e. parameters that are NOT taken from the tariff of the defaults).

Parameters

Full set of insurance contract parameters applying to this contract. The set of parameters is a combination of explicitly given (contract-specific) values, parameters determined by the tariff and default values.

Values

List of all contract values (cash flows, present values, premiums, reserves, premium decomposition, profit participation, etc.). These values will be calculated and filled when the contract is created and updated whenever the contract is changed.

blocks

For contracts with multiple contract parts: List of all tariff blocks (independently calculated InsuranceContract objects, that are combined to one contract, e.g. dynamic/sum increases). If this field is empty, this object describes a contract block (calculated as a stand-alone tariff), otherwise it will simply be the sum of its blocks (adjusted to span the same time periods)

history

A list keeping track of all contract changes (including the whole contract state and its values before the change).

dummy.public

dummy field to allow a trailing comma after the previous field/method

Methods

Public methods

Method new()

Create a new insurance contract (for the given tariff/product) and calculate all time series

Usage
InsuranceContract$new(
  tarif,
  parent = NULL,
  calculate = "all",
  profitid = "default",
  ...
)
Arguments
tarif

The InsuranceTarif object describing the Tariff/Product and providing defaults for the parameters.

parent

For contracts with multiple contract blocks (dynamic increases, sum increases, riders), each child is created with a pointer to its parent. NULL for single-block contracts or for the overall-contract of a multi-block contract. This parameter is used internally, but should not be used in user-written code.

calculate

how much of the contract's time series need to be calculated. See CalculationEnum for all possible values. This is usefull to prevent calculation of e.g. reserves and profit participation, when one only wants to create a grid of premiums.

profitid

The ID of the default profit participation scenario. The default profit participation scenario uses the default values passed, while further scenarios can be added by InsuranceContract$addProfitScenario().

...

Further parameters (age, sum insured, contract closing / begin, premium payment details, etc.) of the contract, which can also override parameters defined at the tariff-level. Possible values are all sub-fields of the InsuranceContract.ParameterDefaults data structure.

Method addHistorySnapshot()

Add the current state of the contract to the history list

Usage
InsuranceContract$addHistorySnapshot(
  time = 0,
  comment = "Initial contract values",
  type = "Contract",
  params = self$Parameters,
  values = self$Values,
  tarif = self$tarif,
  blocks = self$blocks
)
Arguments
time

the time described by the snapshot

comment

a comment to store together with the contract state

type

The type of action that caused a history snapshot to be stored. Typical values are "Contract" to describe the initial contract, "Premium Waiver" or "Dynamic Increase".

params

The set of params to be stored in the history snapshot (default is self$Parameters, if not explicitly given)

values

The calculated time series of all contract values calculated so far. Default is self$Values, if not explicitly given

tarif

The underlying InsuranceTarif object describing the Product/Tariff. Default is self$tarif, if not explicitly given.

blocks

The list of all contract children for contracts with multiple insurance blocks (e.g. dynamic increases, riders, etc.)

Examples
# TODO

Method addBlock()

Add a child contract block (e.g. a dynamic increase or a rider) to an insurance contract

Usage
InsuranceContract$addBlock(
  id = NULL,
  block = NULL,
  t = block$Values$int$blockStart,
  comment = paste0("Additional block at time t=", t),
  blockType = "Dynamics",
  ...
)
Arguments
id

The identifier of the child block to be inserted

block

The InsuranceContract object describing the child block. If NULL (or not given at all), a copy of the parent will be created.

t

Then the child block starts, relative to the parent block. The child block is calculated independently (with time 0 describing its own start), so when aggregating all values from the individual blocks to overall values for the whole contract, the child's values need to be translated to the parent contracts's time frame using this parameter

comment

The comment to use in the history snapshot.

blockType

The type of block to be added (e.g. Dynamics, Extension, etc.). Can be any (short) string.

...

parameters to be passed to InsuranceContract$new() when block is not given and a copy of the parent should be created with overrides.

Examples
# TODO

Method addDynamics()

Add a dynamic increase with the same parameters as the main contract part

Usage
InsuranceContract$addDynamics(t, NewSumInsured, SumInsuredDelta, id, ...)
Arguments
t

The time within the main contract when the sum increase happens. The InsuranceContract object describing the dynamic increase will still internally start at its own time 0, but the aggregation by the main contract will correctly offset to the time $t$ within the main contract.

NewSumInsured

The over-all new sum insured (sum of original contract and all dynamica increaeses). The sumInsured of the new dynamic increase block will be determined as the difference of the old and new overall sum insured. Alternatively, it can directly be given as the SumInsuredDelta argument instead.

SumInsuredDelta

The sum insured of only the dynamic increase, i.e. the sumInsured of the dynamic contract block only. The overall sum insured will increase by this amount. Only one of NewSumInsured and SumInsuredDelta is needed, the other one will be calculated accordingly. If both are given, the SumInsuredDelta will take precedence.

id

The identifier of the contract block describing the dynamic increase. This is a free-form string that should be unique within the list of child blocks. It will be displayed in the 'Excel' export feature and in the history snapshot list.

...

Parameters to override in the dynamic block. By default, all parameters of the main contract block will be used, but they can be overridden per dynamic increase block.

Examples
# TODO

Method addExtension()

Add a contract extension after the contract has ended (existing reserve is used as initial capital of the follow-up contract).

Usage
InsuranceContract$addExtension(
  id = NULL,
  t = NULL,
  comment = paste0("Contract extension at time t=", t),
  ...
)
Arguments
id

The identifier of the child block to be inserted

t

The time of the extension (relative to the parent block), by default contract expiration of the parent block. The extension is calculated independently (with time 0 describing its own start), but using the existing reserve as initialCapital and the parent's parameters as fall-back values.

comment

The comment to use in the history snapshot.

...

Additional parameters to be passed to InsuranceContract$new to create the contract extension object.

Examples
# TODO

Method calculateContract()

Calculate all time series of the contract from the parameters

Usage
InsuranceContract$calculateContract(
  calculate = "all",
  valuesFrom = 0,
  premiumCalculationTime = 0,
  preservePastPV = TRUE,
  additionalCapital = 0,
  recalculatePremiums = TRUE,
  recalculatePremiumSum = TRUE,
  history_comment = NULL,
  history_type = "Contract"
)
Arguments
calculate

Which values to calculate. See CalculationEnum

valuesFrom

Calculate only values starting from this time step on (all values before that time will be preserved). This is required when a contract is changed significantly (potentially even switching to a new tariff), so that the calculation bases for previous periods are no longer available.

premiumCalculationTime

The time point when the premium should be re-calculated (including existing reserves) based on the actuarial equivalence principle. All reserves will be based on these new premiums.

preservePastPV

Whether present value before the recalculation time valuesFrom should be preserved or recalculated. When they are recalculated, the present values are consistent to the new cash flows over the whole contract period, but they no longer represent the actual contract state at these times. If values are not recalculated, the reserves at each time step represent the proper state at that point in time.

additionalCapital

The capital that is added to the contract (e.g. capital carried over from a previous contract) at the premium calculation time.

recalculatePremiums

Whether the premiums should be recalculated at time premiumCalculationTime at all.

recalculatePremiumSum

Whether to recalculate the overall premium sum when the premium is recalculated.

history_comment

The comment for the history snapshot entry

history_type

The type (free-form string) to record in the history snapshot

Method consolidateBlocks()

Aggregate values from all child contract blocks (if any)

Usage
InsuranceContract$consolidateBlocks(valuesFrom = 0)
Arguments
valuesFrom

The time from when to aggragate values. Values before that time will be left unchanged.

Method premiumWaiver()

Stop premium payments and re-calculate sumInsured of the paid-up contract

Usage
InsuranceContract$premiumWaiver(t, ...)
Arguments
t

Time of the premium waiver.

...

Further parameters (currently unused)

Examples
# TODO

Method profitScenario()

Calculate one profit scenario and return all values

Usage
InsuranceContract$profitScenario(...)
Arguments
...

Scenario-specific profit sharing parameters, overriding the default values. Typically, adjusted profit rates are required in a profitScenario.

Returns

a data.frame holding all profit participation values (rates, bases for the different profit types, profit allocations, terminal bonus funds, profit in case of death/surrender/premium waiver)

Examples
# TODO

Method addProfitScenario()

Calculate one profit scenario and store it in the contract

Usage
InsuranceContract$addProfitScenario(id, ...)
Arguments
id

The unique ID of the profit scenario. Will be used as key in the list of profit scenarios and printed out in the 'Excel' export.

...

Scenario-specific profit sharing parameters, overriding the default values. Typically, adjusted profit rates are required in a profitScenario.

Examples
# TODO

Method clone()

The objects of this class are cloneable with this method.

Usage
InsuranceContract$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

Examples

# TODO


## ------------------------------------------------
## Method `InsuranceContract$addHistorySnapshot`
## ------------------------------------------------

# TODO

## ------------------------------------------------
## Method `InsuranceContract$addBlock`
## ------------------------------------------------

# TODO

## ------------------------------------------------
## Method `InsuranceContract$addDynamics`
## ------------------------------------------------

# TODO

## ------------------------------------------------
## Method `InsuranceContract$addExtension`
## ------------------------------------------------

# TODO

## ------------------------------------------------
## Method `InsuranceContract$premiumWaiver`
## ------------------------------------------------

# TODO

## ------------------------------------------------
## Method `InsuranceContract$profitScenario`
## ------------------------------------------------

# TODO

## ------------------------------------------------
## Method `InsuranceContract$addProfitScenario`
## ------------------------------------------------

# TODO
[Package LifeInsureR version 1.0.0 Index]