ProfitParticipation {LifeInsureR}

Base Class for Profit Participation Schemes

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

name

The human-readable name of the profit plan.

Parameters

Parameter template for profit-participation-specific parameters, i.e. the ProfitParticipation element of the InsuranceContract.ParameterStructure data structure.

All elements defined in the profit scheme can be overriden per contract in the call to [InsuranceContract]$new or even in the explicit call to InsuranceContract$profitScenario() or InsuranceContract$addProfitScenario().

Functions

list of functions defined to calculate the individual components. For each of the profit components

• interest profit

• risk profit

• expense profit

• sum profit

• terminal bonus

• terminal bonus fund

a rate, a profit base and a calculation function can be defined, by assigning one of the pre-defined ProfitParticipationFunctions or proving your own function with signature function(rates, params, values, ...). Additionally, for each of the benefit types (survival, death, surrender, premium waiver) a function can be provided to calculate the benefit stemming from profit participation.

dummy

Dummy to allow commas in the previous method

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

name

The name of the profit scheme (typicall the name of the profit plan and its version)

...

profit participation parameters to be stored in the ⁠Parameters field or calculation functions to be stored in the ⁠Functions' field

Method setParameters()

Store all passed parameters in the Parameters field

Usage

ProfitParticipation$setParameters(...)

Arguments

...

any of the named fields defined in the ProfitParticipation sublist of the InsuranceContract.ParameterStructure. All other arguments will be ignored

Method setFunctions()

Store all passed functions in the Functions field

Usage

ProfitParticipation$setFunctions(...)

Arguments

...

any of the functions defined in the Functions field. All other arguments will be ignored

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

name

The new name for the cloned ProfitParticipation object

...

Parameters for the InsuranceContract.ParameterStructure, defining the characteristics of the tariff.

Method getAdvanceProfitParticipation()

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

Usage

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

Arguments

params

Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)

values

Contract values calculated so far (guaranteed component of the insurance contract, including cash flows, premiums, reserves etc.).

...

optional parameters, to be passed to the advanceProfitParticipation field of the parameter structure (if that is a function)

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

params

Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)

values

Contract values calculated so far (guaranteed component of the insurance contract, including cash flows, premiums, reserves etc.).

...

optional parameters, to be passed to the advanceProfitParticipationInclUnitCost field of the parameter structure (if that is a function)

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

params

Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)

values

Contract values calculated so far (guaranteed component of the insurance contract, including cash flows, premiums, reserves etc.).

...

additional parameters passed to the profit calculation functions stored in the Functions field.

Method adjustRates()

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

Usage

ProfitParticipation$adjustRates(rates, params, values)

Arguments

rates

data.frame of profit paticipation rates

params

Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)

values

Contract values calculated so far (guaranteed component of the insurance contract, including cash flows, premiums, reserves etc.).

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

calculateFrom

The time from which to start calculating the profit participation. When a contract is changed at some time t (possibly even changing the profit scheme), all future profit participation needs to be re-calculated from that time on, without changing past profit participation. All values before calculateFrom will not be calculated.

profitScenario

profit participation values from a previous calculation (NULL if profit calculation is to be calculated from the contract inception). Values before calculateFrom will be used from this data.frame.

params

Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)

values

Contract values calculated so far (guaranteed component of the insurance contract, including cash flows, premiums, reserves etc.).

...

additional parameters to be passed to ProfitParticipation$setupRates()

Method clone()

The objects of this class are cloneable with this method.

Usage

ProfitParticipation$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.