contractGrid {LifeInsureR}

Create a grid of InsuranceContract objects or premiums with each axis representing one varying parameter

Description

The function contractGrid creates a (two- or multi-dimensional) grid of InsuranceContract objects, where each axis represents one of the insurance parameters varying as given in the axes argument (as a named list).

The function contractGridPremium returns a grid of premiums as requested in the premium parameter rather than the full InsuranceContract objects. It is a convenience wrapper around contractGrid and is recommended if one is only interested in a grid of one particular value (typically some kind of premium). The function contractGridPremium can also be used on an existing contractGrid-generated grid of contracts to extract grid of numerical values of the specified premiums. If no contract grid is passed to contractGridPremium, contractGrid will be called to create it.

Usage

contractGrid(
  axes = list(age = seq(20, 60, 10), policyPeriod = seq(5, 35, 5)),
  YOB = NULL,
  observationYear = NULL,
  ...
)

contractGridPremium(
  contractGrid = NULL,
  premium = "written",
  .fun = function(cntr) {
     cntr$Values$premiums[[premium]]
 },
  ...
)

Arguments

axes

List of paramters spanning the dimensions of the grid.

YOB

optional year of bith. If missing, the observationYear and the contract's age

observationYear

The observation year, for which the grid shall be calculated. If given, the YOB is calculated from it, otherwise the contract's YOB is used

...

In contractGrid: Additional parameters to be passed to InsuranceContract$new(); In contractGridPremium: Additional parameters to be passed to contractGrid.

contractGrid

(optional) existing contract grid from which to derive premiums. If not given, contractGrid is called with all parameters, so ... should contain an axes argument in that case.

premium

The type of premium to derive (key of the contract$Values$premiums list.

.fun

The function to extract the desired premium from a contract object. By default it accesses the premium vector and extracts the type of premium given in the premium parameter. One can, however pass any other extractor function to access e.g. reserves, cash flows etc. at any desired time.

Details

The function contractGrid will return the full InsuranceContract objects, so apply can later be used to extract premiums, reserves and other values to display in a grid. For this feature, one can also use the convenience function contractGridPremium.

The axes list describing the parameters changing along the axes of the resulting grid is internally expanded with expand.grid(). The resulting flat list of parameter (together with the fixed parameters passed as ...) is then passed to the InsuranceContract$new() call to create the corresponding contract object.

To create the human-readable row-/columnnames of the resulting array, the function makeContractGridDimname() for each value of the axes, allowing human-readable representations e.g. of a tariff or a mortality table as the dimension label.

Value

multi-dimensional array of insurance contracts (dimensions defined by the axes argument)

a array of premiums (or other contract-specific value) for the grid defined by the axes argument to contractGrid

Examples

library("MortalityTables")
mortalityTables.load("Austria_Annuities_AVOe2005R")
# A trivial deferred annuity tariff with no costs, premiums during whole 
# deferral period, 30 years annuity payments:
tariff = InsuranceTarif$new(name="Test Annuity", type="annuity", tarif = "Annuity 1A",
    mortalityTable = AVOe2005R.unisex, i=0.01, 
    deferralPeriod = function(params, ...) { params$ContractData$premiumPeriod }, 
    policyPeriod = function(params, ...) { params$ContractData$premiumPeriod + 30 }
)
contractGrid(
    axes = list(
        age = seq(20, 60, 10),
        premiumPeriod = seq(5,30, 5)
    ),
    tarif = tariff,
    sumInsured = 1000,
    contractClosing = as.Date("2023-11-01")
)