Package 'LifeInsureR'

Description

Calculate the age of the insured based on exact age at contract closing, rounded to the nearest birthday.

Usage

age.exactRounded(params, values)

Arguments

Value

the resulting age

Description

Calculate the age of the insured based on the difference of the bith year and contract closing year.

Usage

age.yearDifference(params, values)

Arguments

Value

the resulting age

Description

If hook is a function, apply it to val, otherwise return val unchanged

Usage

applyHook(hook, val, ...)

Arguments

Value

the value with the hook function applied (if a function) or unchanged otherwiese

Examples

applyHook(NULL, 3) # returns 3 unchanged
applyHook(function(x) 2*x, 3) # applies the function, returns 6
applyHook(`+`, 3, 1) # returns 4

Description

Enum to define how much of a contract needs to be calculated automatically.

Details

When an InsuranceContract object is created, all time series are immediately calculated. However, sometimes, one only needs part of the values, so it would be a waste of resources to calculate e.g. all future reserves and profit participation, if only premiums are of interest.

Possible values are:

• "all"

• "probabilities"

• "cashflows"

• "presentvalues"

• "premiums"

• "absvalues"

• "reserves"

• "premiumcomposition"

• "profitparticipation"

• "history"

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

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")
)

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 }
)
contractGridPremium(
    axes = list(
        age = seq(20, 60, 10),
        premiumPeriod = seq(5,30, 5)
    ),
    tarif = tariff,
    sumInsured = 1000,
    contractClosing = as.Date("2023-11-01")
)

Description

Returns a function that sets base alpha (and Zillmer) costs to the given value, but otherwise uses the full costs defined by the Costs parameter.

Usage

costs.baseAlpha(alpha)

Arguments

Details

This function can be set as minCosts parameter for a tariff and makes sure that only alpha costs are modified / waived, but no other costs.

Description

Returns a function that modifies alpha (and Zillmer) costs by the given scale, but otherwise uses the full costs defined by the Costs parameter.

Usage

costs.scaleAlpha(scale)

Arguments

Details

This function can be set as adjustCosts or adjustMinCosts hook parameters for a tariff or contract and can be used to apply cost adjustments on a per-contract basis.

Description

Returns a data.frame with columns

Usage

costsDisplayTable(costs)

Arguments

Description

Convert the cost values array to a tx15 matrix

Usage

costValuesAsDF(costValues)

Arguments

Details

Not to be called directly, but implicitly by the InsuranceContract object. Convert the array containing cost values like cashflows, present values, etc. (objects of dimension tx5x3) to a matrix with dimensions (tx15)

Description

The death benefit will be the full sumInsured for the first year after the deferral period and then decrease like an annuity to 0 at the end of the policyPeriod. This can be used with the deathBenefit parameter for insurance contracts, but should not be called directly.

Usage

deathBenefit.annuityDecreasing(interest)

Arguments

Details

This function is a mere generator function, which takes the interest rate and generates a function that describes a decreasing annuity.

The generated function has the following parameters:

len

The desired length of the Cash flow vector (can be shorter than the policyPeriod, if q_x=1 before the end of the contract, e.g. for life-long insurances)

params

The full parameter set of the insurance contract (including all inherited values from the tariff and the profit participation)

values

The values calculated from the insurance contract so far

Value

vector of decreasing death benefits

Description

The death benefit will be the full sumInsured for the first year after the deferral period and then decrease linearly to 0 at the end of the policyPeriod. This can be used with the deathBenefit parameter for insurance contracts, but should not be called directly.

Usage

deathBenefit.linearDecreasing(len, params, values)

Arguments

Value

vector of linearly decreasing benefits over the whole insurance coverage period

Description

Checks that object and expected are approximately equal using an element-wise absolute tolerance. This is similar to testthat::expect_equal(), but uses abs(x - y) <= tolerance as the element-wise criterion and treats missing reference values as a no-op.

Usage

expect_equal_abs(
  object,
  expected,
  ...,
  tolerance = 0.01,
  info = NULL,
  label = NULL,
  expected.label = NULL
)

Arguments

Details

The comparison is vectorised and applies the rule abs(x - y) <= tolerance element-wise. All elements must satisfy the rule for the expectation to pass. The function mirrors testthat conventions:

• On success, it succeeds silently and returns object invisibly.

• On failure, it throws an expectation error with a waldo diff.

Special handling:

• If expected is NULL or all values in expected are NA, the check is skipped and the expectation succeeds silently. Similarly, individual NA entries in expected are skipped and allow any value in object.

Value

Invisibly returns object on success; otherwise signals a testthat expectation failure.

See Also

testthat::expect_equal(), waldo::compare()

Examples

# Passes: absolute differences ≤ 0.01
expect_equal_abs(c(1, 2, 3), c(1.001, 1.999, 3.0001), tolerance = 0.01)

# Fails with a waldo diff when any element exceeds tolerance
## Not run: 
expect_equal_abs(c(1, 2, 3), c(1.1, 2, 3), tolerance = 0.05)

## End(Not run)

# Skips check when expected is NULL or all NA
expect_equal_abs(1:3, NULL)
expect_equal_abs(1:3, c(NA, NA, NA))

# Forward options to waldo::compare for clearer diffs
## Not run: 
expect_equal_abs(1:3, 1:3 + 1e-4, tolerance = 0,
                 ignore_attr = TRUE, max_diffs = 10)

## End(Not run)

Export an insurance contract (object of class InsuranceContract) to an 'Excel' file

Description

Export an insurance contract (object of class InsuranceContract) to an 'Excel' file

Usage

exportInsuranceContract.xlsx(contract, filename)

Arguments

Details

The function exportInsuranceContract.xlsx exports an object of class InsuranceContract to an 'Excel' file. All basic data, as well as the time series of (absolute and unit) cash flows, reserves, premiums, premium composition and all profit participation scenarios are exported to the file in nicely looking tables.

No new calculations are done in this function. It only prints out the values stored in contract$Values.

Value

None

Examples

library("MortalityTables")
mortalityTables.load("Austria_Annuities_AVOe2005R")
# A trivial deferred annuity tariff with no costs:
tariff = InsuranceTarif$new(name = "Test Annuity", type = "annuity", tarif = "Annuity 1A",
    mortalityTable = AVOe2005R.unisex, i=0.01)
contract = InsuranceContract$new(
    tariff,
    age = 35, YOB = 1981,
    policyPeriod = 30, premiumPeriod = 15, deferralPeriod = 15,
    sumInsured = 1000,
    contractClosing = as.Date("2016-10-01")
);
exportInsuranceContract.xlsx(contract, tempfile("Example_annuity_contract", fileext = ".xlsx"))

Description

Export the given contract to 'Excel' (full history/timeseries of all cash flows, reserves, premiums, etc.) and to a text file (sample calculation required by the Austrian regulation).

Usage

exportInsuranceContractExample(
  contract,
  prf = 10,
  outdir = ".",
  basename = NULL,
  extraname = NULL,
  ...
)

Arguments

Details

Three output files are generated:

• {DATE}_{TARIFF}_Example.xlsx: Full history/timeseries

• {DATE}_{TARIFF}_Example_PremiumWaiver_t10.xlsx: Full history/timeseries after a premium waiver at the given time prf

• {DATE}_{TARIFF}_Examples_VmGlg.txt: Example calculation required for the Austrian regulation (LV-VMGLV)

Value

None

Examples

library("MortalityTables")
mortalityTables.load("Austria_Annuities_AVOe2005R")
# A trivial deferred annuity tariff with no costs:
tariff = InsuranceTarif$new(name="Test Annuity", type="annuity", tarif = "Annuity 1A",
    mortalityTable = AVOe2005R.unisex, i=0.01)
contract = InsuranceContract$new(
    tariff,
    age = 35, YOB = 1981,
    policyPeriod = 30, premiumPeriod = 15, deferralPeriod = 15,
    sumInsured = 1000,
    contractClosing = as.Date("2016-10-01")
);
exportInsuranceContractExample(contract, prf = 10, outdir = tempdir())

Description

Replace all missing values in fields (either missing or NA) with their corresponding values from fallback. Members in fallback that are missing in fields are inserted

Usage

fallbackFields(fields, valuelist)

Arguments

Value

fields with missing values filled from the fallback data

Description

Overwrite all existing fields in the first argument with values given in valuelist. Members of valuelist that are not yet in fields are ignored. This allows a huge valuelist to be used to fill fields in multiple lists with given structure.

Usage

fillFields(fields, valuelist)

Arguments

Value

updated fields list

Description

Sometimes one has a vector with some gaps (NA) values, which cause problems for several numeric functions. This function fillNAgaps fills these missing values by inserting the last preceeding non-NA-value. Leading NA values (at the start of the vector will not be modified). If the argument firstBack = TRUE, leading NA-values are replaced by the first non-NA value. Trailing NAs are always replaced by the last previous NA-value.

Usage

fillNAgaps(x, firstBack = FALSE)

Arguments

Details

This code was taken from the R Cookbook: http://www.cookbook-r.com/Manipulating_data/Filling_in_NAs_with_last_non-NA_value/ LICENSE (from that page): The R code is freely available for use without any restrictions. In other words: you may reuse the R code for any purpose (and under any license).

Value

vector with NAs properly replaced

Description

This is a rather trivial helper function, which just calls dplyr::filter().

Usage

filterProfitRates(rates, classes)

Arguments

Description

Tariffs are typically calculated with yearly premium installments. When premiums are paid more often then one a year (in advance), the insurance receives part of the premium later (or not at all in case of death), so a surcharge for premium payment frequencies higher than yearly is applied to the premium, typically in the form of a percentage of the premium.

This function generates the internal data structure to define surcharges for monthly, quarterly and semiannual premium payments. The given surcharges can be either given as percentage points (e.g. 1.5 means 1.5% = 0.015) or as fractions of 1 (i.e. 0.015 also means 1.5% surcharge). The heuristics applied to distinguish percentage points and fractions is that all values larger than 0.1 are understood as percentage points and values 0.1 and lower are understood as fractions of 1. As a consequence, a frequency charge of 10% or more MUST be given as percentage points.

Currently, the frequency charges are internally represented as a named list, list("1" = 0, "2" = 0.01, "4" = 0.02, "12" = 0.03), but that might change in the future, so it is advised to use this function rather than explicitly using the named list in your code.

Usage

freqCharge(monthly = 0, quarterly = 0, semiannually = 0, yearly = 0)

Arguments

Value

a named list of surcharges for names 1 (yearly), 2 (semiannually), 4 (quarterly) and 12 (monthly) payments

Description

While the package allows individual tariff object to be created and used, one can also register the tariffs for each company with the package.

Usage

get.tariff(Company, Produkt, GV = NULL, AV = NULL)

Arguments

Details

After registering the tariff/product with the function register.tariff(), this function can be used to retrieve the InsuranceTarif object using the given ID.

Value

The InsuranceTarif object defining the tariff/product.

Examples

library(MortalityTables)
library(magrittr)
mortalityTables.load("Austria_Annuities_AVOe2005R")
InsuranceTarif$new(
    type = "annuity",
    # tarif = "Ann1",
    # desc = "An annuity with single-premium",
    premiumPeriod = 1,
    mortalityTable = AVOe2005R.unisex,
    i = 0.005
) %>%
     register.tariff(Company = "ExVAG", Produkt = "ImmAnn1") %>%
     register.tariff(Company = "ExVAG", Produkt = "ImmAnn1_BV")

 Tariff.ImmAnnuity = get.tariff("ExVAG", "ImmAnn1")

Description

While the package allows individual tariff object to be created and used, one can also register the tariffs for each company with the package.

Usage

get.tariffs(Company = NULL)

Arguments

Details

After registering the tariff/product with the function register.tariff(), this function can be used to retrieve the InsuranceTarif object using the given ID.

Value

The list of InsuranceTarif objects registered for the company

Examples

library(MortalityTables)
library(magrittr)
mortalityTables.load("Austria_Annuities_AVOe2005R")
InsuranceTarif$new(
    type = "annuity",
    # tarif = "Ann1",
    # desc = "An annuity with single-premium",
    premiumPeriod = 1,
    mortalityTable = AVOe2005R.unisex,
    i = 0.005
) %>%
     register.tariff(Company = "ExVAG", Produkt = "ImmAnn1") %>%
     register.tariff(Company = "ExVAG", Produkt = "ImmAnn1_BV")

get.tariffs("ExVAG")

Description

Set all entries of the given vector to 0 up until index 'start'

Usage

head0(v, start = 0, value.start = 0)

Arguments

Value

the vector v with the first start elements replaced by 0.

Examples

head0(1:10, 3)

Initialize or modify a data structure for the definition of InsuranceTarif costs

Description

Initialize a cost matrix with dimensions: {CostType, Basis, Period}, where:

CostType:

alpha, Zillmer, beta, gamma, gamma_nopremiums, unitcosts

Basis:

SumInsured, SumPremiums, GrossPremium, NetPremium, Benefits, Constant

Period:

once, PremiumPeriod, PremiumFree, PolicyPeriod, CommissionPeriod

This cost structure can then be modified for non-standard costs using the setCost() function. The main purpose of this structure is to be passed to InsuranceContract or InsuranceTarif definitions.

Usage

initializeCosts(
  costs,
  alpha,
  Zillmer,
  alpha.ongoing,
  alpha.commission,
  beta,
  gamma,
  gamma.paidUp,
  gamma.premiumfree,
  gamma.contract,
  gamma.afterdeath,
  gamma.fullcontract,
  unitcosts,
  unitcosts.PolicyPeriod
)

Arguments

Value

an insurance cost structure (multi-dimensional matrix)

Examples

# empty cost structure (only 0 costs)
initializeCosts()

# the most common cost types can be given in initializeCosts()
initializeCosts(alpha = 0.04, Zillmer = 0.025, beta = 0.05, gamma.contract = 0.001)

# The same cost structure manually
costs.Bsp = initializeCosts();
costs.Bsp[["alpha", "SumPremiums", "once"]] = 0.04;
costs.Bsp[["Zillmer", "SumPremiums", "once"]] = 0.025;
costs.Bsp[["beta", "GrossPremium", "PremiumPeriod"]] = 0.05;
costs.Bsp[["gamma", "SumInsured", "PolicyPeriod"]] = 0.001;

# The same structure using the setCost() function:
library(magrittr)
costs.Bsp = initializeCosts() %>%
  setCost("alpha", "SumPremiums", "once", 0.04) %>%
  setCost("Zillmer", "SumPremiums", "once", 0.025) %>%
  setCost("beta", "GrossPremium", "PremiumPeriod", 0.05) %>%
  setCost("gamma", "SumInsured", "PolicyPeriod", 0.001)

Description

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.

Details

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:

• Premium payments (in advance or in arrears) at each timestep

• Survival payments at each timestep

• Guaranteed payments at each timestep

• Death benefits at each timestep

• Disease benefits at each timestep

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:

• premium cash flows: 1, 1, 1, 1, 1, ...

• survival cash flows: 0, 0, 0, 0, 0, ...

• guaranteed cash flows: 0, 0, 0, 0, 0, ...

• death benefit cash flows: 1, 1, 1, 1, 1, ...

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

• premium cash flows: 1, 0, 0, 0, 0, ...

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

• premium cash flows: 1, 1, 1, 1, 1, ...

• survival cash flows: 0, 0, ..., 0, 1

• guaranteed cash flows: 0, 0, 0, 0, 0, ...

• death benefit cash flows: 0, 0, 0, 0, 0, ...

An endowment has also death benefits during the contract duration:

• premium cash flows: 1, 1, 1, 1, 1, ...

• survival cash flows: 0, 0, ..., 0, 1

• guaranteed cash flows: 0, 0, 0, 0, 0, ...

• death benefit cash flows: 1, 1, 1, 1, 1, ...

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

• premium cash flows: 1, 1, ..., 1, 0, 0, 0, ...

• survival cash flows: 0, 0, ..., 0, 1, 1, 1,...

• guaranteed cash flows: 0, 0, 0, 0, 0, ...

• death benefit cash flows: 1, 2, 3, 4, 5, ..., 0, 0, ...

A terme-fix (termfix) 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):

• premium cash flows: 1, 1, 1, 1, ..., 1

• survival cash flows: 0, 0, 0, 0, ..., 0

• guaranteed cash flows: 0, 0, 0, ..., 0, 1

• death benefit cash flows: 0, 0, 0, 0, ..., 0

Public fields

Methods

Public methods

• InsuranceContract$new()

• InsuranceContract$copy()

• InsuranceContract$addHistorySnapshot()

• InsuranceContract$addBlock()

• InsuranceContract$addDynamics()

• InsuranceContract$addExtension()

• InsuranceContract$calculateContract()

• InsuranceContract$consolidateBlocks()

• InsuranceContract$premiumWaiver()

• InsuranceContract$profitScenario()

• InsuranceContract$addProfitScenario()

• InsuranceContract$getCFlength()

• InsuranceContract$getPolicyTerm()

• InsuranceContract$getPremiumTerm()

• InsuranceContract$clone()

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

Details

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:

• age ... Age of the insured person (used to derive mortalities / transition probabilities)

• policyPeriod ... Maturity of the policy (in years)

• premiumPeriod ... How long premiums are paid (premiumPeriod = 1 for single-premium contracts, premiumPeriod equals policyPeriod for regular premium payments for the whole contract period, while other premium payment durations indicate premium payments only for shorter periods than the whole contract duration. Contract extensions without any premium payments are indicated by premiumPeriod=0). Default is equal to policyPeriod

• sumInsured ... The sum insured (i.e. survival benefit for endowments, death benefit for whole/term life insurances, annuity payments for annuities)

• contractClosing ... Date of the contract beginning (typically created using something like as.Date("2020-08-01"))

• YOB ... Year of birth of the insured (for cohort mortality tables). If not given, YOB is derived from age and contractClosing.

• deferralPeriod ... Deferral period for deferred annuities (i.e. when annuity payments start at a future point in time). Default is 0.

• premiumFrequency ... How many premium payments per year are made (e.g. 1 for yearly premiums, 4 for quarterly premiumd, 12 for monthly premium payments). Default is 1 (yearly premiums).

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.

Method copy()

Usage

InsuranceContract$copy()

Returns

A new object of InsuranceContract class with independently cloned blocks.

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

Details

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

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",
  parent = self,
  ...
)

Arguments

Details

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

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

Details

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.

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

Details

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

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

Details

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.

Method consolidateBlocks()

Aggregate values from all child contract blocks (if any)

Usage

InsuranceContract$consolidateBlocks(valuesFrom = 0)

Arguments

Details

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.

Method premiumWaiver()

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

Usage

InsuranceContract$premiumWaiver(t, ...)

Arguments

Details

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.

Examples

# TODO

Method profitScenario()

Calculate one profit scenario and return all values

Usage

InsuranceContract$profitScenario(...)

Arguments

Details

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

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

Details

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.

Examples

# TODO

Method getCFlength()

Retrieve the actual length of all cashflows, derived from the contract's parameters

Getter method to get the actual cash flow length for benefits, premiums, costs, etc. The returned value takes into account the policyPeriod parameter, but also the maximum age of the underlying mortality tables and potentially other parameters.

The return value also includes time steps that are zero by definition, i.e. for the premiums cash flows, the return value will also include the remaining policy period after the premium payment phase. It merely returns the maximum length that algorithms must / should consider.

Usage

InsuranceContract$getCFlength()

Returns

The length of the corresponding cash flow vectors/matrices. In many cases, it will be equal to policyPeriod, but might be shorter (e.g. if the mortality table ends before the contractual policy period) or longer in exceptional cases.

Method getPolicyTerm()

Retrieve the actual length of the contract's maturity, factoring in the length of the mortality table

Getter method to get the actual policy duration, taking into account the policyPeriod parameter, but also the maximum age of the underlying mortality tables and potentially other parameters.

Usage

InsuranceContract$getPolicyTerm()

Returns

The length of the whole contract period. In many cases, it will be equal to policyPeriod, but might be shorter (e.g. if the mortality table ends before the contractual policy period) or longer in exceptional cases.

Method getPremiumTerm()

Retrieve the actual length of the contract's premium payment term, factoring in the length of the mortality table

Getter method to get the actual premium payment term, taking into account the premiumPeriod and policyPeriod parameters, but also the maximum age of the underlying mortality tables and potentially other parameters.

Usage

InsuranceContract$getPremiumTerm()

Returns

The length of the premium payment period. In many cases, it will be equal to premiumPeriod or policyPeriod, but might be shorter (e.g. if the mortality table ends before the contractual policy period) or longer in exceptional cases.

Method clone()

The objects of this class are cloneable with this method.

Usage

InsuranceContract$clone(deep = FALSE)

Arguments

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

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

$premium

Premium, given to determine the sumInsured (default: NULL)

$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 lubridate::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)

$premiumRefundPeriod

The period, during which the premium refund on death applies. By default, deferred contracts will refund premiums only during the deferral period, all other contracts during the whole contract. Default is premiumRefundPeriod.default

$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

$survivalBenefit

The survival benefit (relative to the initial sum insured). By default, for (pure) endowments a survival benefit of 1 is assumed at the end of the contract period. Other values (e.g. double survival benefit in endowments) or multiple survival payments during the contract period can be set with this parameter. A single numeric value indicates a single survival benefit at the end of the contract, a vector of numeric values indicates yearly survival benefits (not neccessarily with a survival payment at the end of the contract). Can be set to a function(len, params, values) returning the benefit as a numeric value or vector.

$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 lubridate::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).

$paidUpSumCalculation

A function describing the calculation of the paid-up sum insured If given, it must be a function with signature function(res, absPV, params, values), where res is a data.frame of the calculated reserves.

$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

$zillmering

Whether the contract uses Zillmering (and bases reserves on the Zillmer reserve as opposed to the adequate reserve) (default: TRUE)

$betaGammaInZillmer

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

$gammaInZillmer

Whether gamma- (but not beta-) 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.

$surrenderPenaltyOnPremiumWaiver

Whether the surrender penalty is also applied to premium waivers (but no longer on surrenders after a premium waiver), or only on surrenders (with or without a preceding premium waiver). (default: TRUE)

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

$profitAttributionAtExpiration

Whether the profit attribution at expiration is relevant or should be zeroed out. The latter is needed when profits are calculated at the balance sheet date and assigned on the next policy anniversarz

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

$adjustPremiums

Adjust the resulting premiums. function(premiums = list(premiums, coefficients, sumInsured), params, values)

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

$Rounding

A RoundingHelper object to specify rounding of intermediate values. Alternatively, a named list of rounding specifications can be given, which is used to construct a new RoundingHelper object.

Examples

InsuranceContract.ParameterDefaults

Description

Provide default values for the insurance contract parameters if any of the parameters is not explicitly set.

Usage

InsuranceContract.ParametersFallback(params, fallback, ppParameters = TRUE)

Arguments

Description

Initialize the insurance contract parameters from the passed arguments. Arguments not given are left unchanged. If no existing parameter structure is given, an empty (i.e. all NULL entries) structure is used.

Usage

InsuranceContract.ParametersFill(
  params = InsuranceContract.ParameterStructure,
  costs = NULL,
  minCosts = NULL,
  ...
)

Arguments

Description

All values are filled with NULL, so the functions InsuranceContract.ParametersFill and InsuranceContract.ParametersFallback can be used to override existing parameters or to provide default values for unset (NULL) entries.

Usage

InsuranceContract.ParameterStructure

Format

An object of class list of length 9.

Description

Data structure (filled only with NULL) for insurance contract class member values.

Usage

InsuranceContract.Values

Format

An object of class list of length 19.

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

Methods

Public methods

• InsuranceTarif$new()

• InsuranceTarif$createModification()

• InsuranceTarif$getParameters()

• InsuranceTarif$updateInternalValues()

• InsuranceTarif$getCFlength()

• InsuranceTarif$getPolicyTerm()

• InsuranceTarif$getPremiumTerm()

• InsuranceTarif$getAges()

• InsuranceTarif$getTransitionProbabilities()

• InsuranceTarif$getCostValues()

• InsuranceTarif$getPremiumCF()

• InsuranceTarif$getAnnuityCF()

• InsuranceTarif$getDeathCF()

• InsuranceTarif$getSurvivalCF()

• InsuranceTarif$getBasicCashFlows()

• InsuranceTarif$getCashFlows()

• InsuranceTarif$getCashFlowsCosts()

• InsuranceTarif$presentValueCashFlows()

• InsuranceTarif$presentValueCashFlowsCosts()

• InsuranceTarif$getAbsCashFlows()

• InsuranceTarif$getAbsPresentValues()

• InsuranceTarif$presentValueBenefits()

• InsuranceTarif$getPremiumCoefficients()

• InsuranceTarif$sumInsuredCalculation()

• InsuranceTarif$premiumCalculation()

• InsuranceTarif$reserveCalculation()

• InsuranceTarif$getBalanceSheetReserveFactor()

• InsuranceTarif$reserveCalculationBalanceSheet()

• InsuranceTarif$calculateProfitParticipation()

• InsuranceTarif$reservesAfterProfit()

• InsuranceTarif$getBasicDataTimeseries()

• InsuranceTarif$premiumDecomposition()

• InsuranceTarif$calculateFutureSums()

• InsuranceTarif$calculatePresentValues()

• InsuranceTarif$evaluateFrequencyLoading()

• InsuranceTarif$clone()

Method new()

Initialize a new tariff object

Usage

InsuranceTarif$new(
  name = NULL,
  type = "wholelife",
  tarif = "Generic Tarif",
  desc = "Description of tarif",
  ...
)

Arguments

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

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 updateInternalValues()

Update some internal parameters cached (length of data.frames, policy periods cut at max.age, etc.)

Usage

InsuranceTarif$updateInternalValues(int, params, ...)

Arguments

Details

This method 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 getCFlength()

Retrieve the actual length of all cashflows, derived from the contract's parameters

Getter method to get the actual cash flow length for benefits, premiums, costs, etc. The returned value takes into account the policyPeriod parameter, but also the maximum age of the underlying mortality tables and potentially other parameters.

The return value also includes time steps that are zero by definition, i.e. for the premiums cash flows, the return value will also include the remaining policy period after the premium payment phase. It merely returns the maximum length that algorithms must / should consider.

Usage

InsuranceTarif$getCFlength(values)

Arguments

Returns

The length of the corresponding cash flow vectors/matrices. In many cases, it will be equal to policyPeriod, but might be shorter (e.g. if the mortality table ends before the contractual policy period) or longer in exceptional cases.

Method getPolicyTerm()

Retrieve the actual length of the contract's maturity, factoring in the length of the mortality table

Getter method to get the actual policy duration, taking into account the policyPeriod parameter, but also the maximum age of the underlying mortality tables and potentially other parameters.

Usage

InsuranceTarif$getPolicyTerm(values)

Arguments

Returns

The length of the whole contract period. In many cases, it will be equal to policyPeriod, but might be shorter (e.g. if the mortality table ends before the contractual policy period) or longer in exceptional cases.

Method getPremiumTerm()

Retrieve the actual length of the contract's premium payment term, factoring in the length of the mortality table

Getter method to get the actual premium payment term, taking into account the premiumPeriod and policyPeriod parameters, but also the maximum age of the underlying mortality tables and potentially other parameters.

Usage

InsuranceTarif$getPremiumTerm(values)

Arguments

Returns

The length of the premium payment period. In many cases, it will be equal to premiumPeriod or policyPeriod, but might be shorter (e.g. if the mortality table ends before the contractual policy period) or longer in exceptional cases.

Method getAges()

Calculate the contract-relevant age(s) given a certain parameter data structure (contract-specific values)

Usage

InsuranceTarif$getAges(params, values)

Arguments

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

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

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

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

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

Details

Not to be called directly, but implicitly by the InsuranceContract object.

Method getSurvivalCF()

Returns the unit survival cash flow profile for the whole contract period (after potential deferral period!)

• a single numeric value indicates a single survival payment at the end of the contract

• a vector of numeric values indicates potentially multiple survival payments for the whole contract period (paddded with 0 to the full contract length if shorter)

Usage

InsuranceTarif$getSurvivalCF(len, params, values)

Arguments

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

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

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

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

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

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

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

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

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

Details

Not to be called directly, but implicitly by the InsuranceContract object. When getPremiumCoefficients is called, the values$premiums array has NOT yet been filled! Instead, all premiums already calculated (and required for the premium coefficients) are passed in the premiums argument.

Method sumInsuredCalculation()

Calculate the sumInsured of the InsuranceContract given the parameters and premiums given and teh , present values already calculated and stored in the params and values lists.

Usage

InsuranceTarif$sumInsuredCalculation(
  params,
  values,
  calculationTime = values$int$premiumCalculationTime
)

Arguments

Details

Not to be called directly, but implicitly by the InsuranceContract object.

Method premiumCalculation()

Calculate the premiums of the InsuranceContract given the parameters, present values and premium cofficients already calculated and stored in the params and values lists.

Usage

InsuranceTarif$premiumCalculation(
  params,
  values,
  premiumCalculationTime = values$int$premiumCalculationTime
)

Arguments

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

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

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

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

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

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

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

Details

Not to be called directly, but implicitly by the InsuranceContract object. All premiums, reserves and present values have already been calculated.

Method calculateFutureSums()

Generic function to calculate future sums of the values

Usage

InsuranceTarif$calculateFutureSums(cf, ...)

Arguments

Method calculatePresentValues()

Calculate all present values for a given time series. The mortalities are taken from the contract's parameters.

Usage

InsuranceTarif$calculatePresentValues(cf, params, values)

Arguments

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

Method clone()

The objects of this class are cloneable with this method.

Usage

InsuranceTarif$clone(deep = FALSE)

Arguments

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()

Description

Regular premium contracts are identified by the parameter premiumPeriod > 1.

Usage

isRegularPremiumContract(params, values)

Arguments

Value

TRUE or FALSE, indicating a contract with regular premiums

Description

Single premium contracts are identified by the parameter premiumPeriod = 1.

Usage

isSinglePremiumContract(params, values)

Arguments

Value

TRUE or FALSE, indicating a single-premium contract or not

Description

Uses a Shiny checkbox GUI if shiny is available (e.g., in RStudio), otherwise falls back to a text-based multi-select list.

Usage

LIC_debug_configure(title = "LifeInsureR debug options")

Arguments

Details

• Preselects options that are currently TRUE.

• Provides Select all / Select none controls (Shiny UI).

• Provides a Cancel button that exits without changes.

The selected options will be set to TRUE, all un-selected options will be set to FALSE.

Value

Invisibly, a named logical vector of all keys and their values after setting; returns NULL if cancelled.

Create human-readable labels for the dimensions in a contractGrid()

Description

The function makeContractGridDimname generates a short, human-readable dimension label for the entries along the axes of a contractGrid(). The default is to use the value unchanged as the row-/columnname, but for some parameter values (like a InsuranceTarif or mortalityTable) a custom method of this function is needed to create the (short) human-readable representation for the axes in the grid.

The function makeContractGridDimnames generate proper dimnames for all entries of the axes of a contractGrid() by calling makeContractGridDimname on each of the axes' values

Usage

makeContractGridDimname(value)

makeContractGridDimnames(axes)

Arguments

Value

The name of the entry in the dimnames of contractGrid()

an array of dimnames derived from the axes definitions of contractGrid()

Functions

• makeContractGridDimname(): Create a short, human-readable dimensional name for an object (default S3 method)

• makeContractGridDimnames(): Generate proper dimnames for all entries of the axes of a contractGrid()

Examples

library(MortalityTables)
mortalityTables.load("Austria_Census")

makeContractGridDimname(mort.AT.census.2011.unisex)

makeContractGridDimnames(axes = list(
    age = seq(30,60,10),
    mortalityTable = c(mort.AT.census.2011.unisex, mort.AT.census.2011.male,
                       mort.AT.census.2011.female))
)

Description

Pad a vector with 0 to a desired length

Usage

pad0(v, l, value = 0, start = 0, value.start = 0)

Arguments

Value

returns the vector v padded to length l with value value (default 0).

Examples

pad0(1:5, 7)   # Pad to length 7 with zeroes
pad0(1:5, 3)   # no padding, but cut at length 3

# 3 leading zeroes, then the vector start (10 elements of vector, no additional padding needed):
pad0(1:10, 13, start = 3)

# padding with value other than zero:
pad0(1:5, 7, value = "pad")

Description

This function is just a trivial wrapper around pad0 and only calls pad0() with the last element of the vector as padding value instead of the default 0.

Usage

padLast(v, ...)

Arguments

Value

vector padded to the correct length

Examples

padLast(1:5, 7) # 5 is repeated twice
padLast(1:5, 3) # no padding needed

Description

Enum to describe when a benefit or premium payment is due (in advance or in arrears)

Details

Currently, only two values are allowed;

• "in advance"

• "in arrears"

Description

If a premium refund is set for the tariff, the default is the full contract period, except for deferred contracts (typically deferred life annuities), for which the deferral period is the refund period.

Usage

premiumRefundPeriod.default(params, values)

Arguments

Value

The length of the premium refund period (deferral period for deferred contracts, contract period otherwise)

Description

While the package allows individual tariff object to be created and used, one can also register the tariffs for each company with the package.

Usage

prepare.tariff(Company, Tariff, type = "endowment", destfile = NULL)

Arguments

Details

After registering the tariff/product with the function register.tariff(), this function can be used to retrieve the InsuranceTarif object using the given ID.

Value

The InsuranceTarif object defining the tariff/product.

Examples

library(MortalityTables)
library(magrittr)
mortalityTables.load("Austria_Annuities_AVOe2005R")
InsuranceTarif$new(
    type = "annuity",
    # tarif = "Ann1",
    # desc = "An annuity with single-premium",
    premiumPeriod = 1,
    mortalityTable = AVOe2005R.unisex,
    i = 0.005
) %>%
     register.tariff(Company = "ExVAG", Produkt = "ImmAnn1") %>%
     register.tariff(Company = "ExVAG", Produkt = "ImmAnn1_BV")

 Tariff.ImmAnnuity = get.tariff("ExVAG", "ImmAnn1")

Description

Enum to define the different components of profit participation.

Details

Profit participation schemes typically consist of different components, which are calculated independently. Typical components are interest profit to distribute investment gains to the customer, risk profit and expense profit to return security margins in the biometric risk and the expenses to the customer and sum profit, which aplies to contracts with higher sums insured, where charged expenses are calculated from the sum insured, while the actual expenses are more or less constant. Thus, high contracts are charged more, which causes profits that are returned as sum profit.

As a special case, part of the profits can be stored in a terminal bonus reserve and only distributed on maturity (or potentially on death), but not on surrender. Some (older) profit participation schemes add an independently calculated bonus on maturity (e.g. twice the total profit assignment of the last year) at maturity to give customers an additional incentive not to surrender a contract.

Possible values are (multiple can be given):

• "interest"

• "risk"

• "expense"

• "sum"

• "terminal"

• "TBF"

Description

Base Class for Profit Participation Schemes

Base Class for Profit Participation Schemes

Details

Base class for Profit Participation schemes (holding contract-independent values and providing methods to calculate the profit participation values from the given reserves).

The profit participation object is typically not used directly, but rather defined once and then passed on to an InsuranceTarif or InsuranceContract object, where it will be used internally when profit participation is calculated.

This class provides the technical implementation of a profit plan for traditional life insurance contracts with a guaranteed component (calculated before the profit scheme comes into play) and a discretionary profit on top.

This function is called when a new profit participation scheme is created with a call to ProfitParticipation$new(...). Possible parameters to the new-Call are all parameters from the ProfitParticipation sublist of the InsuranceContract.ParameterStructure parameter structure (which are understood as template values that can be overridden per contract or even per profit participation scenario) and the components of the Functions field defining the functions to calculate the individual components of the profit participation (rates, calculation bases, calculation, benefits)

This method createModification returns a copy of the profit scheme with all given arguments changed in the schmes's Parameters parameter list.

As ProfitParticipation is a R6 class with reference logic, simply assigning the object to a new variable does not create a copy, but references the original profit scheme 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.

The InsuranceContract's param structure InsuranceContract.ParameterStructure contains the field params$ProfitParticipation$advanceProfitParticipation, which can either be numeric rate for advance profit participation, or a function with signature function(params, values, ...) that returns the advance profit participation rate when called with the contract's parameters and the values calculated so far (cash flows and premiums)

The InsuranceContract's param structure InsuranceContract.ParameterStructure contains the field params$ProfitParticipation$advanceProfitParticipationInclUnitCost, which can either be numeric rate for advance profit participation, or a function with signature function(params, values, ...) that returns the advance profit participation rate when called with the contract's parameters and the values calculated so far (cash flows and premiums)

This function provides an easy way to modify the whole set of profit rates after their initial setup. Possible applications are waiting periods, which can be implemented once for all rates rather than inside each individual calculation period.

Public fields

Methods

Public methods

• ProfitParticipation$new()

• ProfitParticipation$setParameters()

• ProfitParticipation$setFunctions()

• ProfitParticipation$setFallbackParameters()

• ProfitParticipation$createModification()

• ProfitParticipation$getAdvanceProfitParticipation()

• ProfitParticipation$getAdvanceProfitParticipationAfterUnitCosts()

• ProfitParticipation$setupRates()

• ProfitParticipation$adjustRates()

• ProfitParticipation$getProfitParticipation()

• ProfitParticipation$clone()

Method new()

Create a new profit participation scheme

Usage

ProfitParticipation$new(name = NULL, ...)

Arguments

Method setParameters()

Store all passed parameters in the Parameters field

Usage

ProfitParticipation$setParameters(...)

Arguments

Method setFunctions()

Store all passed functions in the Functions field

Usage

ProfitParticipation$setFunctions(...)

Arguments

Method setFallbackParameters()

Fill all missing parameters with the default fall-back values

Usage

ProfitParticipation$setFallbackParameters()

Method createModification()

create a copy of a profit scheme with certain parameters changed

Usage

ProfitParticipation$createModification(name = NULL, ...)

Arguments

Method getAdvanceProfitParticipation()

Calculate and return the advance profit participation (to be applied on the actuarial gross premium)

Usage

ProfitParticipation$getAdvanceProfitParticipation(params, values, ...)

Arguments

Returns

Return either one numerical value (constant for the whole premium payment period) of a vector of numerical values for the whole contract period

Method getAdvanceProfitParticipationAfterUnitCosts()

Calculate and return the advance profit participation (to be applied after unit costs are added to the gross premium)

Usage

ProfitParticipation$getAdvanceProfitParticipationAfterUnitCosts(
  params,
  values,
  ...
)

Arguments

Returns

Return either one numerical value (constant for the whole premium payment period) of a vector of numerical values for the whole contract period

Method setupRates()

Set up the data.frame containing the profit participation rates

Usage

ProfitParticipation$setupRates(params, values, ...)

Arguments

Method adjustRates()

Adjust the data.frame of profit participation rates after their setup

Usage

ProfitParticipation$adjustRates(rates, params, values)

Arguments

Method getProfitParticipation()

Calculation the full time series of profit participation for the given contract values

Usage

ProfitParticipation$getProfitParticipation(
  calculateFrom = 0,
  profitScenario = NULL,
  params,
  values,
  ...
)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

ProfitParticipation$clone(deep = FALSE)

Arguments

Description

Various helper functions for the ProfitParticipation class that provide the building blocks for the individual components of profit participation, the rates and how the assigned profit is calculated.

Usage

PP.base.NULL(rates, params, values, ...)

PP.base.PreviousZillmerReserve(rates, params, values, ...)

PP.base.ZillmerReserveT2(rates, params, values, ...)

PP.base.contractualReserve(rates, params, values, ...)

PP.base.previousContractualReserve(rates, params, values, ...)

PP.base.meanContractualReserve(rates, params, values, ...)

PP.base.meanZillmerReserve(rates, params, values, ...)

PP.base.meanZillmerReserveForward(rates, params, values, ...)

PP.base.ZillmerRiskPremium(rates, params, values, ...)

PP.base.sumInsured(rates, params, values, ...)

PP.base.totalProfitAssignment(res, ...)

PP.rate.interestProfit(rates, ...)

PP.rate.riskProfit(rates, ...)

PP.rate.expenseProfit(rates, ...)

PP.rate.sumProfit(rates, ...)

PP.rate.terminalBonus(rates, ...)

PP.rate.terminalBonusFund(rates, ...)

PP.rate.interestProfitPlusGuarantee(rates, ...)

PP.rate.interestProfit2PlusGuarantee(rates, ...)

PP.rate.totalInterest(rates, ...)

PP.rate.totalInterest2(rates, ...)

PP.rate.interestProfit2(rates, ...)

getTerminalBonusReserve(
  profits,
  rates,
  terminalBonus,
  terminalBonusAccount,
  params,
  values,
  ...
)

PP.calculate.RateOnBase(base, rate, waiting, rates, params, values, ...)

PP.calculate.RateOnBaseMin0(base, rate, waiting, rates, params, values, ...)

PP.calculate.RatePlusGuaranteeOnBase(
  base,
  rate,
  waiting,
  rates,
  params,
  values,
  ...
)

PP.calculate.RateOnBaseSGFFactor(
  base,
  rate,
  waiting,
  rates,
  params,
  values,
  ...
)

sumProfits(profits, cols)

PP.benefit.ProfitPlusTerminalBonusReserve(profits, ...)

PP.benefit.Profit(profits, ...)

PP.benefit.ProfitPlusGuaranteedInterest(profits, rates, ...)

PP.benefit.ProfitPlusTotalInterest(profits, rates, params, values)

PP.benefit.ProfitPlusHalfTotalInterest(profits, ...)

PP.benefit.ProfitPlusHalfGuaranteedInterest(profits, rates, ...)

PP.benefit.ProfitPlusInterestMinGuaranteeTotal(profits, rates, ...)

PP.benefit.ProfitPlusHalfInterestMinGuaranteeTotal(profits, rates, ...)

PP.benefit.ProfitGuaranteeSupporting(profits, rates, params, values, ...)

PP.benefit.TerminalBonus5YearsProRata(profits, params, values, ...)

PP.benefit.TerminalBonus5Years(profits, params, ...)

PP.benefit.TerminalBonus(profits, params, ...)

PP.benefit.None(profits, ...)

Arguments

Functions

• PP.base.NULL(): Basis for profit: NONE (i.e. always returns 0)

• PP.base.PreviousZillmerReserve(): Basis for profit: Previous Zillmer reserve (no administration cost reserve)

• PP.base.ZillmerReserveT2(): Basis for profit: Zillmer reserve (no administration cost reserve) at time t-2

• PP.base.contractualReserve(): Basis for profit: Contractual reserve (including administration costs) at time t

• PP.base.previousContractualReserve(): Basis for profit: Contractual reserve (including administration costs) at time t-1

• PP.base.meanContractualReserve(): Basis for profit: Contractual reserve (including administration costs) averaged over t and t-1

• PP.base.meanZillmerReserve(): Basis for profit: Zillmer reserve (excluding administration costs) averaged over t and t-1

• PP.base.meanZillmerReserveForward(): Basis for profit: Zillmer reserve (excluding administration costs) averaged over t+1 and t

• PP.base.ZillmerRiskPremium(): Basis for risk/mortality profit: Zillmer Risk Premium of the past year

• PP.base.sumInsured(): Basis for expense/sum profit: sum insured

• PP.base.totalProfitAssignment(): Basis for Terminal Bonus Fund Assignment: total profit assignment of the year

• PP.rate.interestProfit(): Returns the array of interest profit rates (keyed by year)

• PP.rate.riskProfit(): Returns the array of risk profit rates (keyed by year)

• PP.rate.expenseProfit(): Returns the array of expense profit rates (keyed by year)

• PP.rate.sumProfit(): Returns the array of sum profit rates (keyed by year)

• PP.rate.terminalBonus(): Returns the array of terminal bonus rates (keyed by year)

• PP.rate.terminalBonusFund(): Returns the array of terminal bonus rates (keyed by year) as the terminal bonus fund ratio

• PP.rate.interestProfitPlusGuarantee(): Rate for interest on past profits: total credited rate, but at least the guarantee

• PP.rate.interestProfit2PlusGuarantee(): Rate for interest on past profits: total creditedrate2, but at least the guarantee

• PP.rate.totalInterest(): Rate for interest on past profits: total interest rate

• PP.rate.totalInterest2(): Rate for interest on past profits: second total interest rate

• PP.rate.interestProfit2(): Rate for interest on past profits: second interest profit rate (not including guaranteed interest), keyed by year

• getTerminalBonusReserve(): Calculate the terminal bonus reserve.

• PP.calculate.RateOnBase(): Calculate profit by a simple rate applied on the basis (with an optional waiting vector of values 0 or 1)

• PP.calculate.RateOnBaseMin0(): Calculate profit by a simple rate applied on the basis (with an optional waiting vector of values 0 or 1), bound below by 0

• PP.calculate.RatePlusGuaranteeOnBase(): Calculate profit by a rate + guaranteed interest applied on the basis (with an optional waiting vector of values 0 or 1)

• PP.calculate.RateOnBaseSGFFactor(): Calculate profit by a simple rate applied on the basis (with only (1-SGFFactor) put into profit participation, and an optional waiting vector of values 0 or 1)

• sumProfits(): Extract the given columns of the profit participation array of values and sum them up. Columns that do not exist, because the profit scheme does not provide the corresponding profit component will be silently ignored. This allows generic benefit calculation functions to be written that do not need to distinguish e.g. whether an old-style terminal bonus or a terminal bonus fund is provided.

  This function is not meant to be called directly, but within a profit benefit calculation function.

• PP.benefit.ProfitPlusTerminalBonusReserve(): Calculate survival benefit as total profit amount plus the terminal bonus reserve

• PP.benefit.Profit(): Calculate benefit as total profit accrued so far

• PP.benefit.ProfitPlusGuaranteedInterest(): Calculate accrued death benefit as total profit with (guaranteed) interest for one year

• PP.benefit.ProfitPlusTotalInterest(): Calculate accrued death benefit as total profit with total interest (interest on profit rate) for one year

• PP.benefit.ProfitPlusHalfTotalInterest(): Calculate accrued benefit as total profit with total interest (interest on profit rate) for half a year

• PP.benefit.ProfitPlusHalfGuaranteedInterest(): Calculate death benefit as total profit with (guaranteed) interest for one year

• PP.benefit.ProfitPlusInterestMinGuaranteeTotal(): Calculate accrued benefit as total profit with interest for one year (max of guarantee and total interest)

• PP.benefit.ProfitPlusHalfInterestMinGuaranteeTotal(): Calculate accrued benefit as total profit with interest for half a year (max of guarantee and total interest)

• PP.benefit.ProfitGuaranteeSupporting(): Calculate accrued benefit as regular profit, but used to cover initial Zillmerization

• PP.benefit.TerminalBonus5YearsProRata(): Calculate benefit from terminal bonus as 1/n parts of the terminal bonus reserve during the last 5 years

• PP.benefit.TerminalBonus5Years(): Terminal bonus is only paid out during the last 5 years of the contract (but never during the first 10 years)

• PP.benefit.TerminalBonus(): Calculate benefit from terminal bonus (full bonus), either old-style terminal bonus reserve or Terminal Bonus Fund (TBF)

• PP.benefit.None(): No benefit paid out

Description

PVfactory (R6Class for present values with arbitrary dimensions)

PVfactory (R6Class for present values with arbitrary dimensions)

Details

provides functions to calculate present values for survival, death, dread disease, invalidity and guaranteed benefits in various dimensions

Methods

Public methods

• PVfactory$new()

• PVfactory$guaranteed()

• PVfactory$survival()

• PVfactory$death()

• PVfactory$disease()

• PVfactory$afterDeath()

• PVfactory$clone()

Method new()

Initialize the present value factory with defaults for qx, interest and multiple payments per year

Usage

PVfactory$new(qx, m = 1, mCorrection = list(alpha = 1, beta = 0), v = 1)

Arguments

Method guaranteed()

Present values of guaranteed benefits (paid in advance or arrears, possible multiple times per year)

Usage

PVfactory$guaranteed(
  advance = NULL,
  arrears = NULL,
  start = 0,
  ...,
  m = private$m,
  mCorrection = private$mCorrection,
  v = private$v
)

Arguments

Method survival()

Present values of survival benefits (paid in advance or arrears, possible multiple times per year)

Usage

PVfactory$survival(
  advance = NULL,
  arrears = NULL,
  start = 0,
  ...,
  m = private$m,
  mCorrection = private$mCorrection,
  v = private$v
)

Arguments

Method death()

Present values of death benefits

Usage

PVfactory$death(benefits, start = 0, ..., v = private$v)

Arguments

Method disease()

Present values of disease benefits

Usage

PVfactory$disease(benefits, start = 0, ..., v = private$v)

Arguments

Method afterDeath()

Present values of guaranteed benefits after death (paid in advance or arrears, possible multiple times per year)

Usage

PVfactory$afterDeath(
  advance = NULL,
  arrears = NULL,
  start = 0,
  ...,
  m = private$m,
  mCorrection = private$mCorrection,
  v = private$v
)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

PVfactory$clone(deep = FALSE)

Arguments

Description

While the package allows individual tariff object to be created and used, one can also register the tariffs for each company with the package.

Usage

register.company(Company, ...)

Arguments

Details

This function sets up the company data (including the short name) and other parameters/features used for templating. Once a company is registered with a short name (and optionally its long name and other parameters), one can register tariffs/producs with the register.tariff() function.

Value

None

Examples

register.company("ExVAG", name = "Example Versicherung AG")

Description

While the package allows individual tariff object to be created and used, one can also register the tariffs for each company with the package.

Usage

register.tariff(Tarif, Company, Produkt, GV = NULL, AV = NULL)

Arguments

Details

This function registers a InsuranceTarif object with the LiveInsureR package using a given ID, so automated scripts can then retrieve the products/tariffs based on those IDs (e.g. tariff IDs used in the policy administration systems) using the function get.tariff().

Value

The Tarif is returned, so this function can be chained to register the same object with multiple names or GV/AB combinations.

Examples

library(MortalityTables)
library(magrittr)
mortalityTables.load("Austria_Annuities_AVOe2005R")
 Tariff.ImmAnnuity = InsuranceTarif$new(
    type = "annuity",
    # tarif = "Ann1",
    # desc = "An annuity with single-premium",
    premiumPeriod = 1,
    mortalityTable = AVOe2005R.unisex,
    i = 0.005
) %>%
     register.tariff(Company = "ExVAG", Produkt = "ImmAnn1") %>%
     register.tariff(Company = "ExVAG", Produkt = "ImmAnn1_BV")

Description

Calculate the rolling mean of length 2

Usage

rollingmean(x)

Arguments

Examples

rollingmean(1:10)

Description

This function is a drop-in replacement for round that uses mathematical rounding (round half away from zero) instead of IEEE-754 "round to even" (banker's rounding).

Usage

round_half_up(x, digits = 0)

Arguments

Details

Values exactly halfway between two representable numbers (i.e. fractional part of 0.5) are always rounded away from zero.

Apart from the tie-breaking rule, the behavior matches round:

• vectorised over x

• supports positive and negative digits

• preserves attributes (names, dimensions)

• propagates NA, NaN, Inf

Base R's round() uses IEC 60559 / IEEE-754 rounding ("round to even") for numerical stability:

round(c(0.5, 1.5, 2.5))
# 0 2 2

This function instead implements round half away from zero:

round_half_up(c(0.5, 1.5, 2.5))
# 1 2 3

This behavior is often required in actuarial, financial, and regulatory contexts.

Value

A numeric object of the same shape and attributes as x, containing the rounded values.

See Also

round, floor, ceiling

Examples

round_half_up(1:10 + 0.5)
round_half_up(c(-1.5, -0.5, 0.5, 1.5))
round_half_up(1.2345, digits = 3)
round_half_up(149, digits = -1)

Description

The class RoundingHelper provides the code and settings to define numeric rounding rules for premiums, reserves, benefits etc. of a life insurance contract. By default, no rounding it applied.

The helper is sets up with list of named entries, specifying rounding accuracy for each particular value/use-case. The arguments are "name = value" pairs, where "name" describes the purpose of the rounding (e.g. "net premium"), while the value determines rounding accuracy. value can either be an integer (describing the number of digits to round to, e.g. with value 2, two decimal places after the comma will be rounded, e.g. 3.14159265 -> 3.14). Alternatively, a function(val) can be given, which will be applied to value(s) to be rounded. That function should be vectorizable.

Public fields

Methods

Public methods

• RoundingHelper$new()

• RoundingHelper$round()

• RoundingHelper$setRounding()

• RoundingHelper$getRounding()

• RoundingHelper$clone()

Method new()

Initialize the rounding settings

Usage

RoundingHelper$new(...)

Arguments

Details

Sets up the rounding helper by giving a list of named entries, specifying rounding accuracy for each particular value. The arguments are "name = value" pairs, where "name" describes the purpose of the rounding (e.g. "net premium"), while the value determines rounding accuracy. value can either be an integer (describing the number of digits to round to, e.g. with value 2, two decimal places after the comma will be rounded, e.g. 3.14159265 -> 3.14). Alternatively, a function(val) can be given, which will be applied to value(s) to be rounded. That function should be vectorizable.

Examples

rounding = RoundingHelper$new(raw = 0, hundred = -2, accurate = 4)
rounding$round("raw", c(1234.567891, 0.00012345, 1234))
rounding$round("hundred", c(1234.567891, 0.00012345, 1234))
rounding$round("accurate", c(1234.567891, 0.00012345, 1234))
rounding$round("non-existing", c(1234.567891, 0.00012345, 1234))

# Rounding with functions: Rounding to 5-cent steps, or rounding down to 10 cents:
rnd.5ct = function(value) { round_half_up(value * 20) / 20 }
rnd.down10ct = function(value) { round_half_up(value - 0.05, 1) }
rounding = RoundingHelper$new("five-cent" = rnd.5ct, "down10cent" = rnd.down10ct)
rounding$round("five-cent", c(1234.567891, 0.00012345, 1234.98))
rounding$round("down10cent", c(1234.567891, 0.00012345, 1234.98, 1234.10))

Method round()

Round the given values using the pre-defined accuracy

Usage

RoundingHelper$round(spec, value, ...)

Arguments

Details

Rounds the given values using the accuracies defined in the internal rounding list (set either via the 'initialize' function or via a call to 'setRounding'. The accuracies are defined using a 'spec' identifier, which allows to define different accuracies for different uses

Examples

rounding = RoundingHelper$new(raw = 0, hundred = -2, accurate = 4)
rounding$round("raw", c(1234.567891, 0.00012345, 1234))
rounding$round("hundred", c(1234.567891, 0.00012345, 1234))
rounding$round("accurate", c(1234.567891, 0.00012345, 1234))
# If the given spec does not exist, no rounding it applied
rounding$round("non-existing", c(1234.567891, 0.00012345, 1234))

# Rounding to 5-cent steps, or rounding down to 10 cents:
rnd.5ct = function(value) { round(value * 20) / 20 }
rnd.down10ct = function(value) { round(value - 0.05, 1) }
rounding = RoundingHelper$new("five-cent" = rnd.5ct, "down10cent" = rnd.down10ct)
rounding$round("five-cent", c(1234.567891, 0.00012345, 1234.98))
rounding$round("down10cent", c(1234.567891, 0.00012345, 1234.98, 1234.10))

Method setRounding()

Define rounding accuracy for a certain identifier

Usage

RoundingHelper$setRounding(key, spec, ...)

Arguments

Details

Configures the rounding helper for a given named entry, specifying rounding accuracy for each particular value

Examples

rounding = RoundingHelper$new(raw = 0, hundred = -2, accurate = 4)
rounding$round("raw", c(1234.567891, 0.00012345, 1234))
rounding$round("hundred", c(1234.567891, 0.00012345, 1234))
rounding$round("accurate", c(1234.567891, 0.00012345, 1234))
# If the given spec does not exist, no rounding it applied
rounding$round("non-existing", c(1234.567891, 0.00012345, 1234))
# Add a new spec with different settings:
rounding$setRounding("non-existing", 1)
rounding$round("non-existing", c(1234.567891, 0.00012345, 1234))

Method getRounding()

Extract rounding accuracy for a certain identifier

Usage

RoundingHelper$getRounding(key, ...)

Arguments

Details

Read out the rounding for a given named entry.

Examples

rounding = RoundingHelper$new(raw = 0, hundred = -2, accurate = 4)
rounding$getRounding("hundred")

Method clone()

The objects of this class are cloneable with this method.

Usage

RoundingHelper$clone(deep = FALSE)

Arguments

Examples

rounding = RoundingHelper$new(raw = 0, hundred = -2, accurate = 4)
rounding$round("raw", c(1234.567891, 0.00012345, 1234))
rounding$round("hundred", c(1234.567891, 0.00012345, 1234))
rounding$round("accurate", c(1234.567891, 0.00012345, 1234))
rounding$round("non-existing", c(1234.567891, 0.00012345, 1234))

# Rounding with functions: Rounding to 5-cent steps, or rounding down to 10 cents:
rnd.5ct = function(value) { round_half_up(value * 20) / 20 }
rnd.down10ct = function(value) { round_half_up(value - 0.05, 1) }

rounding = RoundingHelper$new("five-cent" = rnd.5ct, "down10cent" = rnd.down10ct)
rounding$round("five-cent", c(1234.567891, 0.00012345, 1234.98))
rounding$round("down10cent", c(1234.567891, 0.00012345, 1234.98, 1234.10))

## ------------------------------------------------
## Method `RoundingHelper$new`
## ------------------------------------------------

rounding = RoundingHelper$new(raw = 0, hundred = -2, accurate = 4)
rounding$round("raw", c(1234.567891, 0.00012345, 1234))
rounding$round("hundred", c(1234.567891, 0.00012345, 1234))
rounding$round("accurate", c(1234.567891, 0.00012345, 1234))
rounding$round("non-existing", c(1234.567891, 0.00012345, 1234))

# Rounding with functions: Rounding to 5-cent steps, or rounding down to 10 cents:
rnd.5ct = function(value) { round_half_up(value * 20) / 20 }
rnd.down10ct = function(value) { round_half_up(value - 0.05, 1) }
rounding = RoundingHelper$new("five-cent" = rnd.5ct, "down10cent" = rnd.down10ct)
rounding$round("five-cent", c(1234.567891, 0.00012345, 1234.98))
rounding$round("down10cent", c(1234.567891, 0.00012345, 1234.98, 1234.10))

## ------------------------------------------------
## Method `RoundingHelper$round`
## ------------------------------------------------

rounding = RoundingHelper$new(raw = 0, hundred = -2, accurate = 4)
rounding$round("raw", c(1234.567891, 0.00012345, 1234))
rounding$round("hundred", c(1234.567891, 0.00012345, 1234))
rounding$round("accurate", c(1234.567891, 0.00012345, 1234))
# If the given spec does not exist, no rounding it applied
rounding$round("non-existing", c(1234.567891, 0.00012345, 1234))

# Rounding to 5-cent steps, or rounding down to 10 cents:
rnd.5ct = function(value) { round(value * 20) / 20 }
rnd.down10ct = function(value) { round(value - 0.05, 1) }
rounding = RoundingHelper$new("five-cent" = rnd.5ct, "down10cent" = rnd.down10ct)
rounding$round("five-cent", c(1234.567891, 0.00012345, 1234.98))
rounding$round("down10cent", c(1234.567891, 0.00012345, 1234.98, 1234.10))

## ------------------------------------------------
## Method `RoundingHelper$setRounding`
## ------------------------------------------------

rounding = RoundingHelper$new(raw = 0, hundred = -2, accurate = 4)
rounding$round("raw", c(1234.567891, 0.00012345, 1234))
rounding$round("hundred", c(1234.567891, 0.00012345, 1234))
rounding$round("accurate", c(1234.567891, 0.00012345, 1234))
# If the given spec does not exist, no rounding it applied
rounding$round("non-existing", c(1234.567891, 0.00012345, 1234))
# Add a new spec with different settings:
rounding$setRounding("non-existing", 1)
rounding$round("non-existing", c(1234.567891, 0.00012345, 1234))

## ------------------------------------------------
## Method `RoundingHelper$getRounding`
## ------------------------------------------------

rounding = RoundingHelper$new(raw = 0, hundred = -2, accurate = 4)
rounding$getRounding("hundred")

Update one component of an InsuranceTarif's cost structure

Description

Insurance tariff costs are defined by a cost matrix with dimensions: {CostType, Basis, Period}, where:

CostType:

alpha, Zillmer, beta, gamma, gamma_nopremiums, unitcosts

Basis:

SumInsured, SumPremiums, GrossPremium, NetPremium, Constant

Period:

once, PremiumPeriod, PremiumFree, PolicyPeriod, AfterDeath, FullContract

After creation (using the function initializeCosts()), the funciton setCost can be used to modify a single entry. While initializeCosts() provides arguments to set the most common types of cost parameters in one call, the setCost function allows to modify any cost parameter.

Usage

setCost(costs, type, basis = "SumInsured", frequency = "PolicyPeriod", value)

Arguments

Details

This function modifies a copy of the cost structure and returns it, so this function can be chained as often as desired and final return value will contain all cost modifications.

Value

The modified cost structure

Examples

costs = initializeCosts()
setCost(costs, "alpha", "SumPremiums", "once", 0.05)

Description

Enum to describe possible sexes in an insurance contract or tariff.

Details

Currently, the only possible values are:

• "unisex"

• "male"

• "female"

Description

Display the values of the example calculation of the given insurance contract as required by the Austrian regulation (LV-VMGLV, "LV Versicherungsmathematische Grundlagen Verordnung").

Usage

showVmGlgExamples(contract, prf = 10, t = 10, t_prf = 12, file = "", ...)

Arguments

Value

Name of the output file (invisible) or empty if printed to console

Examples

library(MortalityTables)
mortalityTables.load("Austria_Annuities_AVOe2005R")
# A trivial deferred annuity tariff with no costs:
tariff = InsuranceTarif$new(name="Test Annuity", type="annuity",
    mortalityTable = AVOe2005R.unisex, i=0.01)
contract = InsuranceContract$new(
    tariff,
    age = 35, YOB = 1981,
    policyPeriod = 30, premiumPeriod = 15, deferralPeriod = 15,
    sumInsured = 1000,
    contractClosing = as.Date("2016-10-01")
);
showVmGlgExamples(contract)

# Optionally output to a file rather than the console:

showVmGlgExamples(contract, file =  tempfile("annuity-example", fileext = ".txt"))

Description

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 or termfix

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.

Description

Compares the calculated profit participation values in an InsuranceContract object with reference values (typically read from an Excel sheet). The comparison is column-wise and uses expect_equal_abs() to allow for small numeric deviations.

Usage

testProfitParticipation(
  contract = NULL,
  tolerance = 0.01,
  path = "RefValues.xlsx",
  sheet = contract$tarif$name,
  scenario = "default",
  ...
)

Arguments

Details

The function performs the following steps:

1. If no contract is provided, creates one using the supplied tariff parameters via InsuranceContract$new(...).

2. If scenario is missing or not yet present in contract$Values$profitScenarios, generates or adds it.

3. Reads reference data from the specified Excel sheet using readxl::read_excel().

4. For each column present in both the reference data and the scenario matrix, compares corresponding numeric values using expect_equal_abs(), with the specified tolerance.

Columns not present in both datasets are ignored. Missing or malformed scenario matrices trigger a warning (to be implemented).

Value

Invisibly returns contract. The function is primarily used for validation inside testthat test suites; each column comparison generates a testthat expectation.

See Also

expect_equal_abs(), readxl::read_excel(), testthat::expect_equal()

Examples

## Not run: 
# Compare profit participation results to reference values
testProfitParticipation(
  contract = my_contract,
  path = system.file("extdata", "RefValues.xlsx", package = "LifeInsureR"),
  sheet = "Tariff12",
  scenario = "Scenario1",
  tolerance = 0.001
)

# Create and test a new contract on the fly
testProfitParticipation(
  tariff = "GB",
  startAge = 30,
  sumInsured = 100000,
  path = "RefValues.xlsx"
)

## End(Not run)

Description

Check the values of the example calculation of the given insurance contract as required by the Austrian regulation (LV-VMGLV, "LV Versicherungsmathematische Grundlagen Verordnung"). Missing params not passed to the function call will be silently ignored and not cause unit test failures.

Usage

testVmGlgExample(
  contract,
  prf = 10,
  t = 10,
  t_prf = 12,
  net,
  Zillmer,
  gross,
  written,
  savings,
  risk,
  ZillmerRes,
  ZillmerRes.prf,
  VwKostenRes,
  VwKostenRes.prf,
  Bilanzreserve,
  Praemienuebertrag,
  Rueckkaufsreserve,
  Rueckkaufswert,
  Abschlusskostenruecktrag,
  Rueckkaufswert.prf,
  VS.prf,
  absTolerance = 0.015,
  ...
)

Arguments

Details

The easiest way to write unit-tests is using the function vmGlgExample.generateTest

Value

None

Examples

## Not run: 
library(MortalityTables)
library(testthat)
mortalityTables.load("Austria_Annuities_AVOe2005R")

test_that("Testtarif", {
    # A trivial deferred annuity tariff with no costs:
    library(MortalityTables)
    mortalityTables.load("Austria_Annuities")
    tariff = InsuranceTarif$new(name="Test Annuity", type="annuity",
        mortalityTable = AVOe2005R.unisex, i = 0.01)
    contract = InsuranceContract$new(
        tariff,
        age = 35, YOB = 1981,
        policyPeriod = 30, premiumPeriod = 15, deferralPeriod = 15,
        sumInsured = 1000,
        contractClosing = as.Date("2016-10-01")
    );

    testVmGlgExample(
        contract, t = 10,
        net = 850.09, # NOT_CHECKED: Zillmer = 950.09,
        gross = 850.09,
        written = 884.09,
        savings = 857.09, risk = -7.00,
        ZillmerRes = 9011.40,
        ZillmerRes.prf = 9205.96,
        VwKostenRes = 0.00,
        VwKostenRes.prf = 0.00,
        Bilanzreserve = 9250.35,
        Praemienuebertrag = 637.567,
        Rueckkaufsreserve = 9011.40,
        Rueckkaufswert = 9011.40,
        Abschlusskostenruecktrag = 0.00,
        Rueckkaufswert.prf = 9205.96,
        VS.prf = 684.117
    )
})

## End(Not run)

Description

If val is a function, evaluate it, otherwise return val

Usage

valueOrFunction(val, ...)

Arguments

Value

the value, potentially with the given function applied

Examples

valueOrFunction(3) # returns 3
valueOrFunction(`+`, 1, 2) # also returns 3
A = `+`
valueOrFunction(A, 1, 2)

Description

This function calculates the required reference values for the given insurance contract as required by the Austrian regulation (LV-VMGLV, "LV Versicherungsmathematische Grundlagen Verordnung") and generates the code for unit-testing the contract with these values. The code printed can be directly copied into a unit test file.

Usage

vmGlgExample.generateTest(contract, prf = 10, t = 10, t_prf = 12, ...)

Arguments

Value

None (code is printed to the console, but no value returned)

Examples

library(MortalityTables)
mortalityTables.load("Austria_Annuities_AVOe2005R")
# A trivial deferred annuity tariff with no costs:
tariff = InsuranceTarif$new(name="Test Annuity", type="annuity",
    mortalityTable = AVOe2005R.unisex, i=0.01)
vmGlgExample.generateTest(tariff,
    age = 35, YOB = 1981,
    policyPeriod = 30, premiumPeriod = 15, deferralPeriod = 15,
    sumInsured = 1000,
    contractClosing = as.Date("2016-10-01")
)