diff --git a/DESCRIPTION b/DESCRIPTION
index 2c19883f8797e10720b61605a6a7016b2c456673..457165d324eff5f3dc81917cd19b5798e0e4b27f 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -44,3 +44,4 @@ Suggests:
rmarkdown,
pander
VignetteBuilder: knitr
+Roxygen: list(markdown = TRUE)
diff --git a/NAMESPACE b/NAMESPACE
index 53e471874bcc7e26175fb664047b62cfe7d8845c..b1b60bbe946932d0a3311999aa0b76ec9dbae730 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -50,7 +50,6 @@ export(PP.rate.terminalBonusFund)
export(PP.rate.totalInterest)
export(PP.rate.totalInterest2)
export(ProfitParticipation)
-export(addDataTableWorksheet)
export(applyHook)
export(contractGrid)
export(contractGridPremium)
diff --git a/R/HelperFunctions.R b/R/HelperFunctions.R
index e8e945c39f28898c6ac7adf02a404fe57afc314f..60d3d75d694d46cb06fe65ccfa40bafba6aaa6b5 100644
--- a/R/HelperFunctions.R
+++ b/R/HelperFunctions.R
@@ -282,7 +282,14 @@ fillNAgaps <- function(x, firstBack=FALSE) {
}
-
+#' If \code{val} is a function, evaluate it, otherwise return \code{val}
+#' @param val Function or value
+#' @param ... Argument passed to \code{val} if it is a function
+#' @examples
+#' valueOrFunction(3) # returns 3
+#' valueOrFunction(`+`, 1, 2) # also returns 3
+#' A = `+`
+#' valueOrFunction(A, 1, 2)
#' @export
valueOrFunction = function(val, ...) {
if (is.function(val)) {
@@ -292,6 +299,14 @@ valueOrFunction = function(val, ...) {
}
}
+#' If \code{hook} is a function, apply it to \code{val}, otherwise return \code{val} unchanged
+#' @param hook (optional) function to apply to \code{val} and the other parameters
+#' @param val The value to which the hook is applied (ifgiven)
+#' @param ... optional parameters passed to the hook function (if it is a function)
+#' @examples
+#' applyHook(NULL, 3) # returns 3 unchanged
+#' applyHook(function(x) 2*x, 3) # applies the function, returns 6
+#' applyHook(`+`, 3, 1) # returns 4
#' @export
applyHook = function(hook, val, ...) {
if (is.function(hook)) {
@@ -305,13 +320,14 @@ applyHook = function(hook, val, ...) {
-#' fillFields(fields, valuelist)
-#'
#' 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.
#'
+#' @param fields existing list
+#' @param valuelist list of fields to replace in \code{fields}. Only keys that exist in \code{fields} are overwritten, no new fields are added to \code{fields}
+#'
#' @export
fillFields = function(fields, valuelist) {
fieldsToInsert = intersect(names(fields), names(valuelist));
@@ -319,11 +335,11 @@ fillFields = function(fields, valuelist) {
fields
}
-#' fallbackFields(fields, fallback)
-#'
#' 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
+#' @param fields existing list
+#' @param valuelist list of fields to replace in \code{fields}. Only keys that are missing in \code{fields} are added, no existing fields in \code{fields} are overwritten
#' @export
fallbackFields = function(fields, valuelist) {
keepFields = !sapply(fields, is.null);
@@ -333,7 +349,10 @@ fallbackFields = function(fields, valuelist) {
fields
}
-# extractProfitRates = function(rates, )
+#' Calculate the rolling mean of length 2
+#' @param x vector of values, for which the rolling mean is calculated
+#' @examples
+#' rollingmean(1:10)
#' @export
rollingmean = function(x) (tail(x, -1) + head(x, -1))/2
diff --git a/R/InsuranceParameters.R b/R/InsuranceParameters.R
index ae2d8f6f418dfd80932b22b1ce8ac85286ecd45a..9799a53eabac848ae34d7ae7bf577a443c84b763 100644
--- a/R/InsuranceParameters.R
+++ b/R/InsuranceParameters.R
@@ -1,12 +1,32 @@
#' @include HelperFunctions.R
NULL
-
-#' Initialize a cost matrix with dimensions: [CostType, Basis, Period], with:
-#' CostType: alpha, Zillmer, beta, gamma, gamma_nopremiums, unitcosts
-#' Basis: SumInsured, SumPremiums, GrossPremium, NetPremium, Constant
-#' Period: once, PremiumPeriod, PremiumFree, PolicyPeriod
-#' TODO: gamma an Erlebensleistungen?
+#' Initialize a data structure for the definition of [InsuranceTarif] costs
+#'
+#' Initialize a cost matrix with dimensions: {CostType, Basis, Period}, where:
+#' \describe{
+#' \item{CostType:}{alpha, Zillmer, beta, gamma, gamma_nopremiums, unitcosts}
+#' \item{Basis:}{SumInsured, SumPremiums, GrossPremium, NetPremium, Constant}
+#' \item{Period:}{once, PremiumPeriod, PremiumFree, PolicyPeriod}
+#' }
+#' This cost structure can then be modified for non-standard costs.
+#' The main purpose of this structure is to be passed to [InsuranceContract] or
+#' [InsuranceTarif] definitions.
+# TODO: gamma an Erlebensleistungen?
+#'
+#' @param costs (optional) existing cost structure to duplicate / use as a starting point
+#' @param alpha Alpha costs (charged once, relative to sum of premiums)
+#' @param Zillmer Zillmer costs (charged once, relative to sum of premiums)
+#' @param beta Collection costs (charged on each gross premium, relative to gross premium)
+#' @param gamma Administration costs while premiums are paid (relative to sum insured)
+#' @param gamma.paidUp Administration costs for paid-up contracts (relative to sum insured)
+#' @param gamma.premiumfree Administration costs for planned premium-free period (reltaive to sum insured)
+#' @param unitcosts Unit costs (absolute monetary amount, during premium period)
+#' @param unitcosts.PolicyPeriod Unit costs (absolute monetary amount, during full contract period)
+#'
+#' @examples
+#' # empty cost structure (only 0 costs)
+#' initializeCosts()
#' @export
initializeCosts = function(costs, alpha, Zillmer, beta, gamma, gamma.paidUp, gamma.premiumfree, unitcosts, unitcosts.PolicyPeriod) {
if (missing(costs)) {
@@ -83,6 +103,9 @@ InsuranceContract.Values = list(
#' Default parameters for the InsuranceContract class. 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.
+#'
+#' @examples
+#' InsuranceContract.ParameterDefaults
#' @export
InsuranceContract.ParameterDefaults = list(
ContractData = list(
@@ -207,7 +230,7 @@ InsuranceContract.ParameterStructure$Loadings["premiumFrequencyLoading"] = list(
#' initial parameters provided in \code{params}.
#'
#' @export
-InsuranceContract.ParametersFill = function(params=InsuranceContract.ParameterStructure, costs=NULL, ...) {
+InsuranceContract.ParametersFill = function(params = InsuranceContract.ParameterStructure, costs = NULL, ...) {
# params = InsuranceContract.ParameterStructure;
params$ContractData = fillFields(params$ContractData, list(...));
params$ContractState = fillFields(params$ContractState, list(...));
diff --git a/R/InsuranceTarif.R b/R/InsuranceTarif.R
index 72f1c735706af71ea80c18214bf007db155ac871..f3f2545b7bff9f0b99d7f45381bfa77fe9807b46 100644
--- a/R/InsuranceTarif.R
+++ b/R/InsuranceTarif.R
@@ -7,14 +7,26 @@
NULL
-TariffTypeEnum = objectProperties::setSingleEnum("TariffType", levels = c("annuity", "wholelife", "endowment", "pureendowment", "terme-fix", "dread-disease", "endowment + dread-disease"))
+TariffTypeEnum = objectProperties::setSingleEnum(
+ "TariffType",
+ levels = c(
+ "annuity",
+ "wholelife",
+ "endowment",
+ "pureendowment",
+ "terme-fix",
+ "dread-disease",
+ "endowment + dread-disease"
+ ))
############# Class InsuranceTarif ###########################################
-#' Base class for traditional Insurance Tarifs (with fixed guarantee, profit sharing and no unit-linked component)
+#' Base class for traditional Insurance Tarifs (with fixed guarantee, profit
+#' sharing and no unit-linked component)
#'
-#' @description The class \code{InsuranceTarif} provides the code and general framework to
-#' implement contract-independent functionality of a life insurance product.
+#' @description The class \code{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
@@ -26,8 +38,8 @@ TariffTypeEnum = objectProperties::setSingleEnum("TariffType", levels = c("annui
#' 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 sued for defining an insurance tariff are
-#' the constructor [InsuranceTarif@initialize] and the cloning method
-#' [InsuranceTarif@createModification]. All other methods should never be called
+#' the constructor [InsuranceTarif$initialize()] 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
@@ -36,11 +48,14 @@ TariffTypeEnum = objectProperties::setSingleEnum("TariffType", levels = c("annui
# # Parameters for the constructors
#' @param name The unique name / ID of the tariff
#' @param type An enum specifying the main characteristics of the tarif. See [tariffType]
-#' @param tarif The tariff's public name. See [InsuranceTarif@tarif]
-#' @param desc A short human-readable description. See [InsuranceTarif@desc]
+#' @param tarif The tariff's public name. See [InsuranceTarif$tarif]
+#' @param desc A short human-readable description. See [InsuranceTarif$desc]
# # General parameters for (almost) all function
-#' @param params Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)
-#' @param values Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object
+#' @param params Contract-specific, full set of parameters of the contract
+#' (merged parameters of the defaults, the tariff, the profit participation
+#' scheme and the contract)
+#' @param values Contract values calculated so far (in the \code{contract$Values}
+#' list) then this method is called by the contract object
#'
#' @param premiumCalculationTime The time when the premiums should be
#' (re-)calculated according to the equivalence principle. A time 0
@@ -48,18 +63,20 @@ TariffTypeEnum = objectProperties::setSingleEnum("TariffType", levels = c("annui
#' premium calculation times can be used to re-calculate the new
#' premium after a contract change (possibly including an existing reserve)
#'
+#' @import MortalityTables
#' @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.load("Austria_Census")
+#' 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)
+#' 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",
@@ -70,9 +87,11 @@ TariffTypeEnum = objectProperties::setSingleEnum("TariffType", levels = c("annui
#'
#' # 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)
+#' 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 teh ctr.end.AT1$Values list:
+#' # 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
@@ -93,28 +112,55 @@ InsuranceTarif = R6Class(
tarif = NULL,
#' @field desc A short human-readable description of the tariff and its main features.
desc = NULL,
- #' @field tariffType An enum specifying the main characteristics of the tarif. Possible values are:
- #' \description{
- #' \item{annuity}{Whole life or term annuity (periodic survival benefits) with flexible payouts (constand, increasing, decreasing, arbitrary, etc.)}
- #' \item{wholelife}{A whole or term life insurance with only death benefits. The benefit can be constant, increasing, decreasing, described by a function, etc.}
- #' \item{endowment}{An endowment with death and survival benefits, potentially with different benefits.}
- #' \item{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.}
- #' \item{terme-fix}{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.}
- #' \item{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.}
- #' \item{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.}
+ #' @field tariffType An enum specifying the main characteristics of the tarif.
+ #' Possible values are:
+ #' \describe{
+ #' \item{annuity}{Whole life or term annuity (periodic survival benefits)
+ #' with flexible payouts (constand, increasing, decreasing, arbitrary,
+ #' etc.)}
+ #' \item{wholelife}{A whole or term life insurance with only death benefits.
+ #' The benefit can be constant, increasing, decreasing, described by
+ #' a function, etc.}
+ #' \item{endowment}{An endowment with death and survival benefits,
+ #' potentially with different benefits.}
+ #' \item{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.}
+ #' \item{terme-fix}{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.}
+ #' \item{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.}
+ #' \item{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.}
#' }
- tariffType = ("wholelife"), # possible values: annuity, wholelife, endowment, pureendowment, terme-fix
+ tariffType = ("wholelife"),
- #' @field Parameters A data structure (nested list) containing all relevant parameters describing a contract, its underlying tariff, the profit participation scheme etc. See \seealso{InsuranceContract.ParameterStructure} for all fields.
+ #' @field Parameters A data structure (nested list) containing all relevant
+ #' parameters describing a contract, its underlying tariff, the profit
+ #' participation scheme etc. See [InsuranceContract.ParameterStructure] for
+ #' all fields.
Parameters = InsuranceContract.ParameterStructure,
#' @description Initialize a new tariff object
- #' @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 \code{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):
+ #' @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
+ #' \code{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)
+ #' * 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
@@ -129,9 +175,11 @@ InsuranceTarif = R6Class(
#'
#' @param ... Parameters for the [InsuranceContract.ParametersStructure],
#' defining the characteristics of the tariff.
+ #' @import MortalityTables
#' @examples
- #' mortalityTables.load("Austria_Annuities_AVOe2005R")
- #' tarif.male = InsuranceTarif$new(name = "Annuity Males", type = "annuity", i = 0.01, mortalityTable = AVOe2005R.male)
+ #' MortalityTables::mortalityTables.load("Austria_Annuities_AVOe2005R")
+ #' tarif.male = InsuranceTarif$new(name = "Annuity Males", type = "annuity",
+ #' i = 0.01, mortalityTable = AVOe2005R.male)
initialize = function(name = NULL, type = "wholelife", tarif = "Generic Tarif", desc = "Description of tarif", ...) {
if (!missing(name)) self$name = name;
if (!missing(type)) self$tariffType = type;
@@ -153,22 +201,26 @@ InsuranceTarif = R6Class(
#' @description create a copy of a tariff with certain parameters changed
#' @details This method \code{createModification} returns a copy of the tariff
- #' with all given arguments changed in the tariff's [InsuranceTarif@Parametrers]
+ #' 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 option to a new variable does not create a copy, but reference the
+ #' 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.
#'
- #' @param tariffType An enum specifying the main characteristics of the tarif. See [tariffType]
+ #' @param tariffType An enum specifying the main characteristics of the tarif.
+ #' See [tariffType]
#' @param ... Parameters for the [InsuranceContract.ParametersStructure],
#' defining the characteristics of the tariff.
+ #' @import MortalityTables
#' @examples
- #' 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)
+ #' 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)
createModification = function(name = NULL, tarif = NULL, desc = NULL, tariffType = NULL, ...) {
cloned = self$clone();
if (!missing(name)) cloned$name = name;
@@ -180,16 +232,19 @@ InsuranceTarif = R6Class(
cloned
},
- #' @description Retrieve the parameters for this tariff (can be overridden for each contract)
+ #' @description Retrieve the parameters for this tariff (can be overridden
+ #' for each contract)
#'
#' @examples
- #' tarif.male = InsuranceTarif$new(name = "Annuity Males", type = "annuity", i = 0.01, mortalityTable = AVOe2005R.male)
- #' tarif.male@getParameters()
+ #' tarif.male = InsuranceTarif$new(name = "Annuity Males", type = "annuity",
+ #' i = 0.01, mortalityTable = AVOe2005R.male)
+ #' tarif.male$getParameters()
getParameters = function() {
self$Parameters
},
- #' @description Get some internal parameters cached (length of data.frames, policy periods cut at max.age, etc.)
+ #' @description Get some internal parameters cached (length of data.frames,
+ #' policy periods cut at max.age, etc.)
#'
#' @details This methos is not meant to be called explicitly, but rather used
#' by the InsuranceContract class. It returns a list of maturities and ages
@@ -208,10 +263,12 @@ InsuranceTarif = R6Class(
},
- #' @description Calculate the contract-relevant age(s) given a certain parameter data structure (contract-specific values)
+ #' @description Calculate the contract-relevant age(s) given a certain
+ #' parameter data structure (contract-specific values)
#'
#' @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
+ #' by the InsuranceContract class. It returns the relevant ages during the
+ #' whole contract period
getAges = function(params) {
ages = ages(params$ActuarialBases$mortalityTable, YOB = params$ContractData$YOB);
age = params$ContractData$technicalAge;
@@ -221,7 +278,9 @@ InsuranceTarif = R6Class(
ages
},
- #' @description Calculate the transition probabilities from the contract-specific parameters passed as \code{params} and the already-calculated contract values \code{values}
+ #' @description Calculate the transition probabilities from the contract-specific
+ #' parameters passed as \code{params} and the already-calculated contract
+ #' values \code{values}
#' @details Not to be called directly, but implicitly by the [InsuranceContract] object.
getTransitionProbabilities = function(params, values) {
age = params$ContractData$technicalAge;
@@ -249,13 +308,17 @@ InsuranceTarif = R6Class(
df
},
- #' @description Obtain the cost structure from the cost parameter and the given paremeter set
+ #' @description Obtain the cost structure from the cost parameter and the
+ #' given paremeter set
#' @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 \code{param} and \code{values}(=NULL) returning
#' an array of the required dimensions. This function makes sures that the
#' latter function is actually evaluated.
- #' @param costs The cost parameter passed to the tarif definition or the contract (either an array of the form returned by [initializeCosts()] or a function(params, values) returning such an array)
+ #'
+ #' @param costs The cost parameter passed to the tarif definition or the
+ #' contract (either an array of the form returned by [initializeCosts()] or
+ #' a function(params, values) returning such an array)
getCostValues = function(costs, params) {
valueOrFunction(costs, params = params, values = NULL)
},
@@ -309,7 +372,8 @@ InsuranceTarif = R6Class(
}
},
- #' @description Returns the unit death cash flow for the whole protection period (after potential deferral period!)
+ #' @description 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
#' @details Not to be called directly, but implicitly by the [InsuranceContract] object.
@@ -332,8 +396,8 @@ InsuranceTarif = R6Class(
}
},
- #' @description Returns the basic (unit) cash flows associated with the type of insurance
- #' given in the [InsuranceContract@tariffType] field
+ #' @description Returns the basic (unit) cash flows associated with the type
+ #' of insurance given in the [InsuranceContract@tariffType] field
#' @details Not to be called directly, but implicitly by the [InsuranceContract] object.
getBasicCashFlows = function(params, values) {
deferralPeriod = params$ContractData$deferralPeriod;
@@ -460,7 +524,8 @@ InsuranceTarif = R6Class(
applyHook(params$Hooks$adjustCashFlows, cf, params, values)
},
- #' @description Returns the cost cash flows of the contract given the contract and tariff parameters
+ #' @description Returns the cost cash flows of the contract given the contract
+ #' and tariff parameters
#' @details Not to be called directly, but implicitly by the [InsuranceContract] object.
getCashFlowsCosts = function(params, values) {
dm = dim(params$Costs);
@@ -491,9 +556,10 @@ InsuranceTarif = R6Class(
applyHook(params$Hooks$adjustCashFlowsCosts, cf, params, values)
},
- #' @description Returns the present values of the cash flows of the contract (cash flows already calculated and stored in the \code{cashFlows} data.frame)
+ #' @description Returns the present values of the cash flows of the contract
+ #' (cash flows already calculated and stored in the \code{cashFlows} data.frame)
#' @details Not to be called directly, but implicitly by the [InsuranceContract] object.
- #' @param cashFlows data.frame of cash flows calculated by a call to [InsuranceTarif@getCashFlows()]
+ #' @param cashFlows data.frame of cash flows calculated by a call to [InsuranceTarif$getCashFlows()]
presentValueCashFlows = function(cashFlows, params, values) {
qq = self$getTransitionProbabilities(params);
@@ -551,7 +617,9 @@ InsuranceTarif = R6Class(
pv
},
- #' @description Calculates the present values of the cost cash flows of the contract (cost cash flows alreay calculated by [InsuranceTarif@getCashFlowsCosts()] and stored in the \code{values} list
+ #' @description Calculates the present values of the cost cash flows of the
+ #' contract (cost cash flows alreay calculated by [InsuranceTarif$getCashFlowsCosts()]
+ #' and stored in the \code{values} list
#' @details Not to be called directly, but implicitly by the [InsuranceContract] object.
presentValueCashFlowsCosts = function(params, values) {
len = values$int$l;
@@ -625,7 +693,9 @@ InsuranceTarif = R6Class(
#' @description Calculate the absolute present value time series of the insurance contract
#' @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.
+ #' 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.
getAbsPresentValues = function(params, values) {
@@ -650,7 +720,8 @@ InsuranceTarif = R6Class(
},
- #' @description Calculate the absolute present value time series of the benefits of the insurance contract
+ #' @description Calculate the absolute present value time series of the
+ #' benefits of the insurance contract
#' @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
@@ -687,8 +758,12 @@ InsuranceTarif = R6Class(
#' argument.
#'
#' @param type The premium that is supposed to be calculated ("gross", "Zillmer", "net")
- #' @param coeffBenefits (empty) data structure of the benefit coefficients. The actual values have no meaning, this parameter is only used to derive the required dimensions
- #' @param coeffCosts (empty) data structure of the cost coefficients. The actual values have no meaning, this parameter is only used to derive the required dimensions
+ #' @param coeffBenefits (empty) data structure of the benefit coefficients.
+ #' The actual values have no meaning, this parameter is only used to
+ #' derive the required dimensions
+ #' @param coeffCosts (empty) data structure of the cost coefficients. The
+ #' actual values have no meaning, this parameter is only used to
+ #' derive the required dimensions
#' @param premiums The premium components that have already been calculated
#' (e.g. for net and Zillmer, the gross premium has already been
#' calculated to allow modelling the premium refund)
@@ -761,7 +836,10 @@ InsuranceTarif = R6Class(
coeff
},
- #' @description Calculate the premiums of the InsuranceContract given the parameters, present values and premium cofficients already calculated and stored in the \code{params} and \code{values} lists.
+ #' @description Calculate the premiums of the InsuranceContract given the
+ #' parameters, present values and premium cofficients already calculated and
+ #' stored in the \code{params} and \code{values} lists.
+ #'
#' @details Not to be called directly, but implicitly by the [InsuranceContract] object.
premiumCalculation = function(params, values, premiumCalculationTime = values$int$premiumCalculationTime) {
loadings = params$Loadings;
@@ -850,7 +928,10 @@ InsuranceTarif = R6Class(
list("premiums" = values$premiums, "coefficients" = coefficients)
},
- #' @description Calculate the reserves of the InsuranceContract given the parameters, present values and premiums already calculated and stored in the \code{params} and \code{values} lists.
+ #' @description Calculate the reserves of the InsuranceContract given the
+ #' parameters, present values and premiums already calculated and stored in
+ #' the \code{params} and \code{values} lists.
+ #'
#' @details Not to be called directly, but implicitly by the [InsuranceContract] object.
reserveCalculation = function(params, values) {
t = "0"
@@ -951,9 +1032,11 @@ InsuranceTarif = R6Class(
)
},
- #' @description Calculate the (linear) interpolation factors for the balance sheet reserve (Dec. 31) between the yearly contract clowing dates
+ #' @description Calculate the (linear) interpolation factors for the balance
+ #' sheet reserve (Dec. 31) between the yearly contract clowing dates
#' @details Not to be called directly, but implicitly by the [InsuranceContract] object.
- #' @param years how many years to calculate (for some usances, the factor is different in leap years!)
+ #' @param years how many years to calculate (for some usances, the factor
+ #' is different in leap years!)
getBalanceSheetReserveFactor = function(params, years = 1) {
balanceDate = params$ActuarialBases$balanceSheetDate
year(balanceDate) = year(params$ContractData$contractClosing);
@@ -1016,7 +1099,9 @@ InsuranceTarif = R6Class(
res
},
- #' @description Calculate the profit participation given the contract parameters and the already calculated reserves of the contract.
+ #' @description Calculate the profit participation given the contract
+ #' parameters and the already calculated reserves of the contract.
+ #'
#' @details Not to be called directly, but implicitly by the [InsuranceContract] object.
#' @param ... Additional parameters for the profit participation calculation, passed
#' through to the profit participation scheme's [ProfitParticipation$getProfitParticipation()]
@@ -1234,8 +1319,10 @@ InsuranceTarif = R6Class(
rcumsum = function(vec) rev(cumsum(rev(vec)))
apply(values, 2, rcumsum)
},
- #' @description Calculate all present values for a given time series. The mortalities are taken from the contract's parameters.
- #' @param values The time series, for which future present values at all times are desired
+ #' @description Calculate all present values for a given time series. The
+ #' mortalities are taken from the contract's parameters.
+ #' @param values The time series, for which future present values at all
+ #' times are desired
#' @param ... currently unused
calculatePresentValues = function(values, params) {
len = dim(values)[1];
diff --git a/R/ProfitParticipation.R b/R/ProfitParticipation.R
index 1aca6982c8f9401ac5f43d7ed63c52f88562c552..3f162b3f514eaaf75f7ab1e7d7a953e9b1713f7f 100644
--- a/R/ProfitParticipation.R
+++ b/R/ProfitParticipation.R
@@ -4,30 +4,68 @@
#' @import dplyr
NULL
# Shut up the package checker:
-if (getRversion() >= "2.15.1") utils::globalVariables(c("profitClass"))
+# if (getRversion() >= "2.15.1") utils::globalVariables(c("profitClass"))
#' @export
filterProfitRates = function(rates, classes) {
- dplyr::filter(.data = rates, profitClass %in% classes)
+ dplyr::filter(.data = rates, .data$profitClass %in% classes)
}
#' Base Class for Profit Participation Schemes
#'
-#' base class for Profit Participation schemes (holding contract-independent values and
+#' 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.
+#'
+#' @param params Contract-specific, full set of parameters of the contract
+#' (merged parameters of the defaults, the tariff, the profit participation
+#' scheme and the contract)
+#' @param values Contract values calculated so far (guaranteed component of the
+#' insurance contract, including cash flows, premiums, reserves etc.).
+#'
#' @export
ProfitParticipation = R6Class(
"ProfitParticipation",
public = list(
+ #' @field name The human-readable name of the profit plan.
name = "Name des Gewinnplans",
+ #' @field Parameters Parameter template for profit-participation-specific
+ #' parameters, i.e. the \code{ProfitParticipation} element of the
+ #' [InsuranceContract.ParameterStructure] data structure.
+ #'
+ #' All elements defined in the profit scheme can be overriden per contract
+ #' in the call to \code{[InsuranceContract]$new} or even in the explicit
+ #' call to [InsuranceContract$profitScenario] or [InsuranceContract$addProfitScenario].
Parameters = InsuranceContract.ParameterStructure$ProfitParticipation,
########################################################################m#
- # Function blocks (modular) to determine bases, rates and calculation ####
+ # Function blocks (modular) to determine bases, rates and calculation ##m#
########################################################################m#
+ #' @field Functions list of functions defined to calculate the individual
+ #' components. For each of the profit components
+ #' \itemize{
+ #' \item interest profit
+ #' \item risk profit
+ #' \item expense profit
+ #' \item sum profit
+ #' \item terminal bonus
+ #' \item 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
+ #' \code{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.
Functions = list(
#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@@ -88,6 +126,19 @@ ProfitParticipation = R6Class(
),
+ #' @description Create a new profit participation scheme
+ #' @details This function is called when a new profit participation scheme
+ #' is created with a call to \code{ProfitParticipation$new(...)}. Possible
+ #' parameters to the \code{new}-Call are all parameters from the
+ #' [InsuranceContract.ParameterStructure$ProfitParticipation] 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 [ProfitParticipation$Functions] list defining the functions to calculate the individual
+ #' components of the profit participation (rates, calculation bases, calculation, benefits)
+ #'
+ #' @param name The name of the profit scheme (typicall the name of the profit plan and its version)
+ #' @param ... profit participation parameters to be stored in
+ #' [ProfitParticipation$Parameters] or calculation functions to be stored in [ProfitParticipation$Functions]
initialize = function(name = NULL, ...) {
if (!missing(name)) self$name = name;
self$setParameters(...);
@@ -95,19 +146,42 @@ ProfitParticipation = R6Class(
self$setFallbackParameters();
},
+
+ #' @description Store all passed parameters in the [Parameters] field
+ #' @param ... any of the named fields defined in
+ #' [InsuranceContract.ParameterStructure$ProfitParticipation]. All other
+ #' arguments will be ignored
setParameters = function(...) {
self$Parameters = fillFields(self$Parameters, list(...));
},
+ #' @description Store all passed functions in the [Functions] field
+ #' @param ... any of the functions defined in the [Functions] field. All other
+ #' arguments will be ignored
setFunctions = function(...) {
self$Functions = fillFields(self$Functions, list(...));
},
+ #' @description Fill all missing parameters with the default fall-back values
setFallbackParameters = function() {
self$Parameters = fallbackFields(self$Parameters, list(profitParticipationScheme = self));
self$Parameters = fallbackFields(self$Parameters, InsuranceContract.ParameterDefaults$ProfitParticipation);
},
+ #' @description create a copy of a profit scheme with certain parameters changed
+ #' @details This method \code{createModification} returns a copy of the profit scheme
+ #' with all given arguments changed in the schmes's [ProfitParticipation$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.
+ #'
+ #' @param name The new name for the cloned [ProfitParticipation] object
+ #' @param ... Parameters for the [InsuranceContract.ParametersStructure],
+ #' defining the characteristics of the tariff.
createModification = function(name = NULL, ...) {
cloned = self$clone();
if (!missing(name)) cloned$name = name;
@@ -121,17 +195,40 @@ ProfitParticipation = R6Class(
# Advance Profit Participation ####
##########################################################################m#
+ #' @description Calculate and return the advance profit participation (to be
+ #' applied on the actuarial gross premium)
+ #'
+ #' @details The [InsuranceContract]'s param structure [InsuranceContract.ParameterStructure]
+ #' contains the field \code{params$ProfitParticipation$advanceProfitParticipation},
+ #' which can either be numeric rate for advance profit participation, or
+ #' a function with signature \code{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)
+ #' @return Return either one numerical value (constant for the whole premium payment period)
+ #' of a vector of numerical values for the whole contract period
+ #'
+ #' @param ... optional parameters, to be passed to the advanceProfitParticipation
+ #' field of the parameter structure (if that is a function)
getAdvanceProfitParticipation = function(params, values, ...) {
- "@function getAdvanceProfitParticipation"
- "Return either one numerical value (constant for the whole premium payment period)"
- "of a vector of numerical values for the whole contract period "
valueOrFunction(params$ProfitParticipation$advanceProfitParticipation, params, values, ...)
},
+
+ #' @description Calculate and return the advance profit participation (to be
+ #' applied after unit costs are added to the gross premium)
+ #'
+ #' @details The [InsuranceContract]'s param structure [InsuranceContract.ParameterStructure]
+ #' contains the field \code{params$ProfitParticipation$advanceProfitParticipationInclUnitCost},
+ #' which can either be numeric rate for advance profit participation, or
+ #' a function with signature \code{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)
+ #' @return Return either one numerical value (constant for the whole premium payment period)
+ #' of a vector of numerical values for the whole contract period
+ #'
+ #' @param ... optional parameters, to be passed to the advanceProfitParticipationInclUnitCost
+ #' field of the parameter structure (if that is a function)
getAdvanceProfitParticipationAfterUnitCosts = function(params, values, ...) {
- "@function getAdvanceProfitParticipationAfterUnitCosts"
- "Return either one numerical value (constant for the whole premium payment period)"
- "of a vector of numerical values for the whole contract period "
valueOrFunction(params$ProfitParticipation$advanceProfitParticipationInclUnitCost, params, values, ...)
},
@@ -146,6 +243,9 @@ ProfitParticipation = R6Class(
##########################################################################m#
+ #' @description Set up the data.frame containing the profit participation rates
+ #' @param ... additional parameters passed to the profit calculation functions
+ #' stored in the [Functions] field.
setupRates = function(params, values, ...) {
# 1) Profit scheme or contract provides general company-wide profit rates for some years:
# profitRates
@@ -231,6 +331,12 @@ ProfitParticipation = R6Class(
self$adjustRates(newrates[as.character(years),], params = params, values = values)
},
+ #' @description Adjust the data.frame of profit participation rates after their setup
+ #' @details 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.
+ #' @param rates data.frame of profit paticipation rates
adjustRates = function(rates, params, values) {
rates[1,] = 0;
rates
@@ -240,6 +346,18 @@ ProfitParticipation = R6Class(
+ #' @description Calculation the full time series of profit participation for
+ #' the given contract values
+ #'
+ #' @param 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 \code{calculateFrom} will not be calculated.
+ #' @param profitScenario profit participation values from a previous calculation
+ #' (NULL if profit calculation is to be calculated from the contract inception).
+ #' Values before \code{calculateFrom} will be used from this data.frame.
+ #' @param ... additional parameters to be passed to [setupRates]
getProfitParticipation = function(calculateFrom = 0, profitScenario = NULL, params, values, ...) {
waiting = valueOrFunction(params$ProfitParticipation$waitingPeriod, params = params, values = values);
if (is.numeric(waiting) && waiting > 0) {
@@ -448,7 +566,7 @@ ProfitParticipation = R6Class(
- # Dummy to allow commas
+ #' @field dummy Dummy to allow commas in the previous method
dummy = 0
)
)
diff --git a/R/ProfitParticipation_Functions.R b/R/ProfitParticipation_Functions.R
index 26d692a779972a8150f55100cb34230c19eeb9ca..d36f61a55cfa599d6fa8348b8fd0d04383bb2912 100644
--- a/R/ProfitParticipation_Functions.R
+++ b/R/ProfitParticipation_Functions.R
@@ -10,6 +10,12 @@ NULL
#' the rates and how the assigned profit is calculated.
#'
#' @name ProfitParticipationFunctions
+#' @param rates data.frame of profit rates
+#' @param params Contract-specific, full set of parameters of the contract
+#' (merged parameters of the defaults, the tariff, the profit participation
+#' scheme and the contract)
+#' @param values Contract values calculated so far (guaranteed component of the
+#' insurance contract, including cash flows, premiums, reserves etc.).
NULL
shiftBy = function(rate, n = 1) {
diff --git a/R/addDataTableWorksheet.R b/R/addDataTableWorksheet.R
index 1ee36df944557bfd85d766e5eb38fd5328850029..a8b0f3ed4ba43dc575f978c150dfe66f2915fae0 100644
--- a/R/addDataTableWorksheet.R
+++ b/R/addDataTableWorksheet.R
@@ -1,73 +1,73 @@
#' Add a new worksheet to the excel workbook and export the given data table x to it nicely formatted.
-#' @export
-addDataTableWorksheet = function(wb, sheet, title = NULL, x = NULL, loopdim = 3, style = NULL, tableStyle = "TableStyleMedium17", comparisons = NULL, comparisonStyle = NULL, ...) {
- addWorksheet(wb, sheet);
- rw = 1;
- if (!missing(title)) {
- titleStyle = createStyle(
- fontSize = 26,
- fontColour = "#365F91", borderColour = "#4F81BD",
- borderStyle = "medium", border = "Bottom", textDecoration = "bold")
- writeData(wb, sheet, title, startCol = 1, startRow = rw)
- addStyle(wb, sheet, style = titleStyle, rows = rw, cols = 1);
- rw = rw + 2;
- }
- if (!missing(x)) {
- if (loopdim > length(dim(x)))
- loopdim = length(dim(x));
- if (loopdim < 0)
- loopdim = 1;
- # str(dimnames(x));
- rnames = dimnames(x)[[1]];
- cnames = dimnames(x)[[2]];
- # str("rnames, cnames: ");str(rnames);str(cnames);
- dmname = names(dimnames(x))[[loopdim]];
- dmnameStyle = createStyle(
- fontSize = 20,
- fontColour = "#4F81BD", #borderColour = "#4F81BD",
- # borderStyle = "medium", border = "Bottom",
- textDecoration = "bold")
- headerStyle = createStyle(halign = "center", valign = "center");
- lapply(
- seq_along(dimnames(x)[[loopdim]]),
- function(i) {
- dmheader = paste(dmname, dimnames(x)[[loopdim]][i], sep = " = ")
- writeData(wb, sheet, dmheader, startCol = 1, startRow = rw)
- addStyle(wb, sheet, style = dmnameStyle, rows = rw, cols = 1);
- rw <<- rw + 1;
- writeDataTable(
- wb, sheet,
- x = as.data.frame(x[,,i]), # TODO: Generalize this to use loopdim!
- colNames = TRUE, rowNames = TRUE,
- withFilter = FALSE,
- startCol = 1, startRow = rw,
- tableStyle = tableStyle, headerStyle = headerStyle);
- if (!is.null(style)) {
- addStyle(wb, sheet, style = style, rows = rw + seq_along(rnames), cols = 1 + seq_along(cnames), gridExpand = TRUE, stack = TRUE);
- }
- cl = 1 + length(cnames) + 2;
-
- lapply(
- seq_along(comparisons),
- function(j) {
- writeData(wb, sheet, names(comparisons)[j], startRow = rw - 1, startCol = cl)
- addStyle(wb, sheet, style = dmnameStyle, rows = rw - 1, cols = cl);
-
- writeDataTable(
- wb, sheet,
- x = as.data.frame(comparisons[[j]][,,i]), # TODO: Generalize this to use loopdim!
- colNames = TRUE, rowNames = TRUE,
- withFilter = FALSE,
- startCol = cl, startRow = rw,
- tableStyle = tableStyle, headerStyle = headerStyle);
- if (!is.null(comparisonStyle)) {
- addStyle(wb, sheet, style = comparisonStyle, rows = rw + seq_along(rnames), cols = cl + seq_along(cnames), gridExpand = TRUE, stack = TRUE);
- }
- cl <<- cl + 1 + length(cnames) + 1;
- }
- )
- rw <<- rw + length(rnames) + 1 + 2; # TODO: Generalize this to use loopdim!
- }
- );
- }
-}
+# @export
+# addDataTableWorksheet = function(wb, sheet, title = NULL, x = NULL, loopdim = 3, style = NULL, tableStyle = "TableStyleMedium17", comparisons = NULL, comparisonStyle = NULL, ...) {
+# addWorksheet(wb, sheet);
+# rw = 1;
+# if (!missing(title)) {
+# titleStyle = createStyle(
+# fontSize = 26,
+# fontColour = "#365F91", borderColour = "#4F81BD",
+# borderStyle = "medium", border = "Bottom", textDecoration = "bold")
+# writeData(wb, sheet, title, startCol = 1, startRow = rw)
+# addStyle(wb, sheet, style = titleStyle, rows = rw, cols = 1);
+# rw = rw + 2;
+# }
+# if (!missing(x)) {
+# if (loopdim > length(dim(x)))
+# loopdim = length(dim(x));
+# if (loopdim < 0)
+# loopdim = 1;
+# # str(dimnames(x));
+# rnames = dimnames(x)[[1]];
+# cnames = dimnames(x)[[2]];
+# # str("rnames, cnames: ");str(rnames);str(cnames);
+# dmname = names(dimnames(x))[[loopdim]];
+# dmnameStyle = createStyle(
+# fontSize = 20,
+# fontColour = "#4F81BD", #borderColour = "#4F81BD",
+# # borderStyle = "medium", border = "Bottom",
+# textDecoration = "bold")
+# headerStyle = createStyle(halign = "center", valign = "center");
+# lapply(
+# seq_along(dimnames(x)[[loopdim]]),
+# function(i) {
+# dmheader = paste(dmname, dimnames(x)[[loopdim]][i], sep = " = ")
+# writeData(wb, sheet, dmheader, startCol = 1, startRow = rw)
+# addStyle(wb, sheet, style = dmnameStyle, rows = rw, cols = 1);
+# rw <<- rw + 1;
+# writeDataTable(
+# wb, sheet,
+# x = as.data.frame(x[,,i]), # TODO: Generalize this to use loopdim!
+# colNames = TRUE, rowNames = TRUE,
+# withFilter = FALSE,
+# startCol = 1, startRow = rw,
+# tableStyle = tableStyle, headerStyle = headerStyle);
+# if (!is.null(style)) {
+# addStyle(wb, sheet, style = style, rows = rw + seq_along(rnames), cols = 1 + seq_along(cnames), gridExpand = TRUE, stack = TRUE);
+# }
+# cl = 1 + length(cnames) + 2;
+#
+# lapply(
+# seq_along(comparisons),
+# function(j) {
+# writeData(wb, sheet, names(comparisons)[j], startRow = rw - 1, startCol = cl)
+# addStyle(wb, sheet, style = dmnameStyle, rows = rw - 1, cols = cl);
+#
+# writeDataTable(
+# wb, sheet,
+# x = as.data.frame(comparisons[[j]][,,i]), # TODO: Generalize this to use loopdim!
+# colNames = TRUE, rowNames = TRUE,
+# withFilter = FALSE,
+# startCol = cl, startRow = rw,
+# tableStyle = tableStyle, headerStyle = headerStyle);
+# if (!is.null(comparisonStyle)) {
+# addStyle(wb, sheet, style = comparisonStyle, rows = rw + seq_along(rnames), cols = cl + seq_along(cnames), gridExpand = TRUE, stack = TRUE);
+# }
+# cl <<- cl + 1 + length(cnames) + 1;
+# }
+# )
+# rw <<- rw + length(rnames) + 1 + 2; # TODO: Generalize this to use loopdim!
+# }
+# );
+# }
+# }
diff --git a/R/contractGrid.R b/R/contractGrid.R
index 1346e061a40d679e2f2046a4ce1a222325404ea9..80e76b137a3549f0834494b2f61919005ddb8a4e 100644
--- a/R/contractGrid.R
+++ b/R/contractGrid.R
@@ -3,6 +3,11 @@
#' This function will return the full InsuranceContract objects, so apply can
#' later be used to extract premiums, reserves and other values to display in
#' a grid.
+#'
+#' @param axes List of paramters spanning the dimensions of the grid.
+#' @param YOB optional year of bith. If missing, the \code{observationYear} and the contract's age
+#' @param observationYear The observation year, for which the grid shall be calculated. If given, the YOB is calculated from it, otherwise the contract's YOB is used
+#' @param ... Additional parameters to be passed to [InsuranceContract$new]
#' @export
contractGrid = function(axes = list(age = seq(20, 60, 10), policyPeriod = seq(5, 35, 5)), YOB = NULL, observationYear = NULL, ...) {
@@ -33,8 +38,12 @@ makeContractGridDimname.numeric = function(value) { value }
makeContractGridDimname.double = function(value) { value }
#' @export
makeContractGridDimname.default = function(value) { value }
+#' Generate a dimension label for the object passed as \code{value}, to be used in [contractGrid]
+#' @param value the value along the axis, for which a name should be generated
#' @export
makeContractGridDimname = function(value) { UseMethod("makeContractGridDimname", value) }
+#' Generate proper dimnames for all exntries of the axes of a [contractGrid]
+#' @param axes the axes with all names, for which a name should be generated
#' @export
makeContractGridDimnames = function(axes) {
lapply(axes, function(axis) { lapply(axis, makeContractGridDimname); } )
@@ -45,6 +54,12 @@ makeContractGridDimnames = function(axes) {
#' This function will return the full InsuranceContract objects, so apply can
#' later be used to extract premiums, reserves and other values to display in
#' a grid.
+#'
+#' @param contractGrid (optional) existing contract grid from which to derive
+#' premiums. If not given, [contractGrid] is called with all parameters, so
+#' \code{...} should contain an \code{axes} argument in that case.
+#' @param premium The type of premium to derive (key of the \code{contract$Values$premiums} list.
+#' @param ... Arguments pass on to [contractGrid] if no conract grid is given.
#' @export
contractGridPremium = function(contractGrid = NULL, premium="written", ...) {
if (missing(contractGrid) || is.null(contractGrid)) {
diff --git a/R/exportInsuranceContract_xlsx.R b/R/exportInsuranceContract_xlsx.R
index 3c6fe0c1316fb9dc2cd7e8077a5d8df0aa90d472..30aa2034df9bb7e835be91acbfa62b223d1bccdd 100644
--- a/R/exportInsuranceContract_xlsx.R
+++ b/R/exportInsuranceContract_xlsx.R
@@ -782,7 +782,34 @@ exportCFTable = function(wb, sheet, contract, ccol = 1, crow = 1, styles = c(),
#
############################################################################### #
-
+#' Export an insurance act object tocontract (object of class [InsuranceContract]) to an Excel file
+#'
+#' @details The function \code{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 \code{contract$Values}.
+#'
+#' @param contract The insurance contract to export
+#' @param filename Target Excel filename for export
+#'
+#' @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")
+#' );
+#' exportInsuranceContract.xlsx(contract, "Example_annuity_contract.xlsx")
#' @export
exportInsuranceContract.xlsx = function(contract, filename) {
# TODO: argument checking for contract and filename
diff --git a/R/showVmGlgExamples.R b/R/showVmGlgExamples.R
index 7c89663160f157dbca7f7c374cbc12e58e2825cb..f8d7d956adffe84fa05ce8bc1733ce2f0f7a2572 100644
--- a/R/showVmGlgExamples.R
+++ b/R/showVmGlgExamples.R
@@ -35,7 +35,7 @@ NULL
#' showVmGlgExamples(contract, file = "annuity-example.txt")
#'
#' @export
-showVmGlgExamples = function(contract, prf=10, t=10, t_prf=12, file="", ...) {
+showVmGlgExamples = function(contract, prf = 10, t = 10, t_prf = 12, file = "", ...) {
has.prf = prf < contract$Parameters$ContractData$premiumPeriod;
diff --git a/man/InsuranceContract.ParameterDefaults.Rd b/man/InsuranceContract.ParameterDefaults.Rd
index 0be4491950a2e2b68bef98a60fbe026af7ae875d..e8d20f959ea4974c4f5bf95089bb9acbf7c02cd0 100644
--- a/man/InsuranceContract.ParameterDefaults.Rd
+++ b/man/InsuranceContract.ParameterDefaults.Rd
@@ -17,4 +17,7 @@ Default parameters for the InsuranceContract class. 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.
}
+\examples{
+InsuranceContract.ParameterDefaults
+}
\keyword{datasets}
diff --git a/man/InsuranceTarif.Rd b/man/InsuranceTarif.Rd
index b8299999c6ad196802f8431c98f045abe7da54d3..ddf32c1de25818cf800c081da9b08dd6acc92ad6 100644
--- a/man/InsuranceTarif.Rd
+++ b/man/InsuranceTarif.Rd
@@ -2,10 +2,12 @@
% Please edit documentation in R/InsuranceTarif.R
\name{InsuranceTarif}
\alias{InsuranceTarif}
-\title{Base class for traditional Insurance Tarifs (with fixed guarantee, profit sharing and no unit-linked component)}
+\title{Base class for traditional Insurance Tarifs (with fixed guarantee, profit
+sharing and no unit-linked component)}
\description{
-The class \code{InsuranceTarif} provides the code and general framework to
-implement contract-independent functionality of a life insurance product.
+The class \code{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
@@ -18,8 +20,8 @@ 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 sued for defining an insurance tariff are
-the constructor [InsuranceTarif@initialize] and the cloning method
-[InsuranceTarif@createModification]. All other methods should never be called
+the constructor \link{InsuranceTarif@initialize} and the cloning method
+\link{InsuranceTarif$createModification}. All other methods should never be called
manually.
However, as overriding private methods is not possible in an R6 class, all the
@@ -29,14 +31,15 @@ methods need to be public to allow overriding them in derived classes.
# 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.load("Austria_Census")
+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)
+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",
@@ -47,9 +50,11 @@ endowment.AT1 = InsuranceTarif$new(
# 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)
+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 teh ctr.end.AT1$Values list:
+# 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
@@ -63,23 +68,27 @@ ctr.end.AT1$Values$premiumComposition
## Method `InsuranceTarif$new`
## ------------------------------------------------
-mortalityTables.load("Austria_Annuities_AVOe2005R")
-tarif.male = InsuranceTarif$new(name = "Annuity Males", type = "annuity", i = 0.01, mortalityTable = AVOe2005R.male)
+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.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)
+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()
+tarif.male = InsuranceTarif$new(name = "Annuity Males", type = "annuity",
+ i = 0.01, mortalityTable = AVOe2005R.male)
+tarif.male$getParameters()
}
\section{Public fields}{
\if{html}{\out{<div class="r6-fields">}}
@@ -90,18 +99,35 @@ tarif.male@getParameters()
\item{\code{desc}}{A short human-readable description of the tariff and its main features.}
-\item{\code{tariffType}}{An enum specifying the main characteristics of the tarif. Possible values are:
-\description{
- \item{annuity}{Whole life or term annuity (periodic survival benefits) with flexible payouts (constand, increasing, decreasing, arbitrary, etc.)}
- \item{wholelife}{A whole or term life insurance with only death benefits. The benefit can be constant, increasing, decreasing, described by a function, etc.}
- \item{endowment}{An endowment with death and survival benefits, potentially with different benefits.}
- \item{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.}
- \item{terme-fix}{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.}
- \item{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.}
- \item{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.}
+\item{\code{tariffType}}{An enum specifying the main characteristics of the tarif.
+Possible values are:
+\describe{
+\item{annuity}{Whole life or term annuity (periodic survival benefits)
+with flexible payouts (constand, increasing, decreasing, arbitrary,
+etc.)}
+\item{wholelife}{A whole or term life insurance with only death benefits.
+The benefit can be constant, increasing, decreasing, described by
+a function, etc.}
+\item{endowment}{An endowment with death and survival benefits,
+potentially with different benefits.}
+\item{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.}
+\item{terme-fix}{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.}
+\item{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.}
+\item{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.}
}}
-\item{\code{Parameters}}{A data structure (nested list) containing all relevant parameters describing a contract, its underlying tariff, the profit participation scheme etc. See \seealso{InsuranceContract.ParameterStructure} for all fields.}
+\item{\code{Parameters}}{A data structure (nested list) containing all relevant
+parameters describing a contract, its underlying tariff, the profit
+participation scheme etc. See \link{InsuranceContract.ParameterStructure} for
+all fields.}
\item{\code{dummy}}{Dummy field to allow commas after the previous method}
}
@@ -163,32 +189,43 @@ Initialize a new tariff object
\describe{
\item{\code{name}}{The unique name / ID of the tariff}
-\item{\code{type}}{An enum specifying the main characteristics of the tarif. See [tariffType]}
+\item{\code{type}}{An enum specifying the main characteristics of the tarif. See \link{tariffType}}
-\item{\code{tarif}}{The tariff's public name. See [InsuranceTarif@tarif]}
+\item{\code{tarif}}{The tariff's public name. See \link{InsuranceTarif@tarif}}
-\item{\code{desc}}{A short human-readable description. See [InsuranceTarif@desc]}
+\item{\code{desc}}{A short human-readable description. See \link{InsuranceTarif@desc}}
-\item{\code{...}}{Parameters for the [InsuranceContract.ParametersStructure],
+\item{\code{...}}{Parameters for the \link{InsuranceContract.ParametersStructure},
defining the characteristics of the tariff.}
}
\if{html}{\out{</div>}}
}
\subsection{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 \code{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 constructor function defines a tariff and generates the
+corresponding data structure, which can then be used with the \link{InsuranceContract}
+class to define an actual contract using the tariff.
+
+The arguments passed to this function will be stored inside the
+\code{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):
+\itemize{
+\item InsuranceContract object (parameters passed directly to the individual
+contract)
+\item ProfitParticipation object (parameters for profit participation, passed
+to the definition of the profit plan, which is used for the tarif
+definition or the contract)
+\item InsuranceTarif object (parameters passed to the definition of the tariff
+that was used for the contract)
+\item Defaults taken from \link{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\% and a certain mortality table,
+with a guaranteed interest rate of 1\\% and a certain mortality table,
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.
@@ -196,8 +233,9 @@ tariff for such comparisons, as long as only parameters are changed.
\subsection{Examples}{
\if{html}{\out{<div class="r example copy">}}
-\preformatted{mortalityTables.load("Austria_Annuities_AVOe2005R")
-tarif.male = InsuranceTarif$new(name = "Annuity Males", type = "annuity", i = 0.01, mortalityTable = AVOe2005R.male)
+\preformatted{MortalityTables::mortalityTables.load("Austria_Annuities_AVOe2005R")
+tarif.male = InsuranceTarif$new(name = "Annuity Males", type = "annuity",
+ i = 0.01, mortalityTable = AVOe2005R.male)
}
\if{html}{\out{</div>}}
@@ -224,24 +262,25 @@ create a copy of a tariff with certain parameters changed
\describe{
\item{\code{name}}{The unique name / ID of the tariff}
-\item{\code{tarif}}{The tariff's public name. See [InsuranceTarif@tarif]}
+\item{\code{tarif}}{The tariff's public name. See \link{InsuranceTarif@tarif}}
-\item{\code{desc}}{A short human-readable description. See [InsuranceTarif@desc]}
+\item{\code{desc}}{A short human-readable description. See \link{InsuranceTarif@desc}}
-\item{\code{tariffType}}{An enum specifying the main characteristics of the tarif. See [tariffType]}
+\item{\code{tariffType}}{An enum specifying the main characteristics of the tarif.
+See \link{tariffType}}
-\item{\code{...}}{Parameters for the [InsuranceContract.ParametersStructure],
+\item{\code{...}}{Parameters for the \link{InsuranceContract.ParametersStructure},
defining the characteristics of the tariff.}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
This method \code{createModification} returns a copy of the tariff
-with all given arguments changed in the tariff's [InsuranceTarif@Parametrers]
+with all given arguments changed in the tariff's \link{InsuranceTarif@Parametrers}
parameter list.
As InsuranceTarif is a R6 class with reference logic, simply assigning
-the option to a new variable does not create a copy, but reference the
+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.
@@ -249,9 +288,11 @@ to the values passed to this method.
\subsection{Examples}{
\if{html}{\out{<div class="r example copy">}}
-\preformatted{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)
+\preformatted{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)
}
\if{html}{\out{</div>}}
@@ -262,15 +303,17 @@ tarif.unisex = tarif.male@createModification(name = "Annuity unisex", mortalityT
\if{html}{\out{<a id="method-getParameters"></a>}}
\if{latex}{\out{\hypertarget{method-getParameters}{}}}
\subsection{Method \code{getParameters()}}{
-Retrieve the parameters for this tariff (can be overridden for each contract)
+Retrieve the parameters for this tariff (can be overridden
+for each contract)
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$getParameters()}\if{html}{\out{</div>}}
}
\subsection{Examples}{
\if{html}{\out{<div class="r example copy">}}
-\preformatted{tarif.male = InsuranceTarif$new(name = "Annuity Males", type = "annuity", i = 0.01, mortalityTable = AVOe2005R.male)
-tarif.male@getParameters()
+\preformatted{tarif.male = InsuranceTarif$new(name = "Annuity Males", type = "annuity",
+ i = 0.01, mortalityTable = AVOe2005R.male)
+tarif.male$getParameters()
}
\if{html}{\out{</div>}}
@@ -281,7 +324,8 @@ tarif.male@getParameters()
\if{html}{\out{<a id="method-getInternalValues"></a>}}
\if{latex}{\out{\hypertarget{method-getInternalValues}{}}}
\subsection{Method \code{getInternalValues()}}{
-Get some internal parameters cached (length of data.frames, policy periods cut at max.age, etc.)
+Get some internal parameters cached (length of data.frames,
+policy periods cut at max.age, etc.)
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$getInternalValues(params, ...)}\if{html}{\out{</div>}}
}
@@ -289,7 +333,9 @@ Get some internal parameters cached (length of data.frames, policy periods cut a
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
\item{\code{...}}{currently unused}
}
@@ -306,7 +352,8 @@ relevant for the contract-specific calculations
\if{html}{\out{<a id="method-getAges"></a>}}
\if{latex}{\out{\hypertarget{method-getAges}{}}}
\subsection{Method \code{getAges()}}{
-Calculate the contract-relevant age(s) given a certain parameter data structure (contract-specific values)
+Calculate the contract-relevant age(s) given a certain
+parameter data structure (contract-specific values)
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$getAges(params)}\if{html}{\out{</div>}}
}
@@ -314,13 +361,16 @@ Calculate the contract-relevant age(s) given a certain parameter data structure
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
}
\if{html}{\out{</div>}}
}
\subsection{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
+by the InsuranceContract class. It returns the relevant ages during the
+whole contract period
}
}
@@ -328,7 +378,9 @@ by the InsuranceContract class. It returns the relevant ages during the whole co
\if{html}{\out{<a id="method-getTransitionProbabilities"></a>}}
\if{latex}{\out{\hypertarget{method-getTransitionProbabilities}{}}}
\subsection{Method \code{getTransitionProbabilities()}}{
-Calculate the transition probabilities from the contract-specific parameters passed as \code{params} and the already-calculated contract values \code{values}
+Calculate the transition probabilities from the contract-specific
+parameters passed as \code{params} and the already-calculated contract
+values \code{values}
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$getTransitionProbabilities(params, values)}\if{html}{\out{</div>}}
}
@@ -336,14 +388,17 @@ Calculate the transition probabilities from the contract-specific parameters pas
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -351,7 +406,8 @@ Not to be called directly, but implicitly by the [InsuranceContract] object.
\if{html}{\out{<a id="method-getCostValues"></a>}}
\if{latex}{\out{\hypertarget{method-getCostValues}{}}}
\subsection{Method \code{getCostValues()}}{
-Obtain the cost structure from the cost parameter and the given paremeter set
+Obtain the cost structure from the cost parameter and the
+given paremeter set
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$getCostValues(costs, params)}\if{html}{\out{</div>}}
}
@@ -359,15 +415,19 @@ Obtain the cost structure from the cost parameter and the given paremeter set
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{costs}}{The cost parameter passed to the tarif definition or the contract (either an array of the form returned by [initializeCosts()] or a function(params, values) returning such an array)}
+\item{\code{costs}}{The cost parameter passed to the tarif definition or the
+contract (either an array of the form returned by \code{\link[=initializeCosts]{initializeCosts()}} or
+a function(params, values) returning such an array)}
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
}
\if{html}{\out{</div>}}
}
\subsection{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()])
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
+The cost parameter can be either an array of costs (generated by \code{\link[=initializeCosts]{initializeCosts()}})
or a function with parameters \code{param} and \code{values}(=NULL) returning
an array of the required dimensions. This function makes sures that the
latter function is actually evaluated.
@@ -379,10 +439,12 @@ latter function is actually evaluated.
\if{latex}{\out{\hypertarget{method-getPremiumCF}{}}}
\subsection{Method \code{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))
+\itemize{
+\item For constant premiums it will be rep(1, premiumPeriod),
+\item for single premiums it will be c(1, 0, 0, ...),
+\item for increasing premiums it will be (1+increase)^(0:(premiumPeriod-1))
and 0 after the premium period
+}
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$getPremiumCF(len, params, values)}\if{html}{\out{</div>}}
}
@@ -392,14 +454,17 @@ and 0 after the premium period
\describe{
\item{\code{len}}{The desired length of the returned data frame (the number of contract periods desire)}
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -408,10 +473,12 @@ Not to be called directly, but implicitly by the [InsuranceContract] object.
\if{latex}{\out{\hypertarget{method-getAnnuityCF}{}}}
\subsection{Method \code{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))
+the whole annuity payment period (after potential deferral period)
+\itemize{
+\item For constant annuity it will be rep(1, annuityPeriod),
+\item for increasing annuities it will be (1+increase)^(0:(premiumPeriod-1))
and 0 after the premium period
+}
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$getAnnuityCF(len, params, values)}\if{html}{\out{</div>}}
}
@@ -421,14 +488,17 @@ and 0 after the premium period
\describe{
\item{\code{len}}{The desired length of the returned data frame (the number of contract periods desire)}
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -436,9 +506,12 @@ Not to be called directly, but implicitly by the [InsuranceContract] object.
\if{html}{\out{<a id="method-getDeathCF"></a>}}
\if{latex}{\out{\hypertarget{method-getDeathCF}{}}}
\subsection{Method \code{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
+Returns the unit death cash flow for the whole protection
+period (after potential deferral period!)
+\itemize{
+\item For constant death benefit it will be rep(1, policyPeriod),
+\item for linearly decreasing sum insured it will be (policyPeriod:0)/policyPeriod
+}
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$getDeathCF(len, params, values)}\if{html}{\out{</div>}}
}
@@ -448,14 +521,17 @@ Returns the unit death cash flow for the whole protection period (after potentia
\describe{
\item{\code{len}}{The desired length of the returned data frame (the number of contract periods desire)}
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -463,8 +539,8 @@ Not to be called directly, but implicitly by the [InsuranceContract] object.
\if{html}{\out{<a id="method-getBasicCashFlows"></a>}}
\if{latex}{\out{\hypertarget{method-getBasicCashFlows}{}}}
\subsection{Method \code{getBasicCashFlows()}}{
-Returns the basic (unit) cash flows associated with the type of insurance
-given in the [InsuranceContract@tariffType] field
+Returns the basic (unit) cash flows associated with the type
+of insurance given in the \link{InsuranceContract@tariffType} field
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$getBasicCashFlows(params, values)}\if{html}{\out{</div>}}
}
@@ -472,14 +548,17 @@ given in the [InsuranceContract@tariffType] field
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -495,14 +574,17 @@ Returns the cash flows for the contract given the parameters
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -510,7 +592,8 @@ Not to be called directly, but implicitly by the [InsuranceContract] object.
\if{html}{\out{<a id="method-getCashFlowsCosts"></a>}}
\if{latex}{\out{\hypertarget{method-getCashFlowsCosts}{}}}
\subsection{Method \code{getCashFlowsCosts()}}{
-Returns the cost cash flows of the contract given the contract and tariff parameters
+Returns the cost cash flows of the contract given the contract
+and tariff parameters
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$getCashFlowsCosts(params, values)}\if{html}{\out{</div>}}
}
@@ -518,14 +601,17 @@ Returns the cost cash flows of the contract given the contract and tariff parame
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -533,7 +619,8 @@ Not to be called directly, but implicitly by the [InsuranceContract] object.
\if{html}{\out{<a id="method-presentValueCashFlows"></a>}}
\if{latex}{\out{\hypertarget{method-presentValueCashFlows}{}}}
\subsection{Method \code{presentValueCashFlows()}}{
-Returns the present values of the cash flows of the contract (cash flows already calculated and stored in the \code{cashFlows} data.frame)
+Returns the present values of the cash flows of the contract
+(cash flows already calculated and stored in the \code{cashFlows} data.frame)
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$presentValueCashFlows(cashFlows, params, values)}\if{html}{\out{</div>}}
}
@@ -541,16 +628,19 @@ Returns the present values of the cash flows of the contract (cash flows already
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{cashFlows}}{data.frame of cash flows calculated by a call to [InsuranceTarif@getCashFlows()]}
+\item{\code{cashFlows}}{data.frame of cash flows calculated by a call to \code{\link[=InsuranceTarif@getCashFlows]{InsuranceTarif@getCashFlows()}}}
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -558,7 +648,9 @@ Not to be called directly, but implicitly by the [InsuranceContract] object.
\if{html}{\out{<a id="method-presentValueCashFlowsCosts"></a>}}
\if{latex}{\out{\hypertarget{method-presentValueCashFlowsCosts}{}}}
\subsection{Method \code{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 \code{values} list
+Calculates the present values of the cost cash flows of the
+contract (cost cash flows alreay calculated by \code{\link[=InsuranceTarif@getCashFlowsCosts]{InsuranceTarif@getCashFlowsCosts()}}
+and stored in the \code{values} list
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$presentValueCashFlowsCosts(params, values)}\if{html}{\out{</div>}}
}
@@ -566,14 +658,17 @@ Calculates the present values of the cost cash flows of the contract (cost cash
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -594,7 +689,7 @@ Convert the cost values array to a tx15 matrix
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
Convert the array containing cost values like cashflows, present
values, etc. (objects of dimension tx5x3) to a matrix with dimensions (tx15)
}
@@ -612,9 +707,12 @@ Calculate the cash flows in monetary terms of the insurance contract
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
}
\if{html}{\out{</div>}}
}
@@ -624,7 +722,7 @@ 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.
+This method is NOT to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -640,18 +738,23 @@ Calculate the absolute present value time series of the insurance contract
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
}
\if{html}{\out{</div>}}
}
\subsection{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.
+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.
+This method is NOT to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -659,7 +762,8 @@ This method is NOT to be called directly, but implicitly by the [InsuranceContra
\if{html}{\out{<a id="method-presentValueBenefits"></a>}}
\if{latex}{\out{\hypertarget{method-presentValueBenefits}{}}}
\subsection{Method \code{presentValueBenefits()}}{
-Calculate the absolute present value time series of the benefits of the insurance contract
+Calculate the absolute present value time series of the
+benefits of the insurance contract
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$presentValueBenefits(params, values)}\if{html}{\out{</div>}}
}
@@ -667,9 +771,12 @@ Calculate the absolute present value time series of the benefits of the insuranc
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
}
\if{html}{\out{</div>}}
}
@@ -678,9 +785,9 @@ 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.
+by the previous functions of this classe.
-This method is NOT to be called directly, but implicitly by the [InsuranceContract] object.
+This method is NOT to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -706,17 +813,24 @@ Calculate the linear coefficients of the premium calculation formula for the ins
\describe{
\item{\code{type}}{The premium that is supposed to be calculated ("gross", "Zillmer", "net")}
-\item{\code{coeffBenefits}}{(empty) data structure of the benefit coefficients. The actual values have no meaning, this parameter is only used to derive the required dimensions}
+\item{\code{coeffBenefits}}{(empty) data structure of the benefit coefficients.
+The actual values have no meaning, this parameter is only used to
+derive the required dimensions}
-\item{\code{coeffCosts}}{(empty) data structure of the cost coefficients. The actual values have no meaning, this parameter is only used to derive the required dimensions}
+\item{\code{coeffCosts}}{(empty) data structure of the cost coefficients. The
+actual values have no meaning, this parameter is only used to
+derive the required dimensions}
\item{\code{premiums}}{The premium components that have already been calculated
(e.g. for net and Zillmer, the gross premium has already been
calculated to allow modelling the premium refund)}
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
\item{\code{premiumCalculationTime}}{The time when the premiums should be
(re-)calculated according to the equivalence principle. A time 0
@@ -727,7 +841,7 @@ premium after a contract change (possibly including an existing reserve)}
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
When \code{getPremiumCoefficients} is called, the \code{values$premiums}
array has NOT yet been filled! Instead, all premiums already calculated
(and required for the premium coefficients) are passed in the \code{premiums}
@@ -739,7 +853,9 @@ argument.
\if{html}{\out{<a id="method-premiumCalculation"></a>}}
\if{latex}{\out{\hypertarget{method-premiumCalculation}{}}}
\subsection{Method \code{premiumCalculation()}}{
-Calculate the premiums of the InsuranceContract given the parameters, present values and premium cofficients already calculated and stored in the \code{params} and \code{values} lists.
+Calculate the premiums of the InsuranceContract given the
+parameters, present values and premium cofficients already calculated and
+stored in the \code{params} and \code{values} lists.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$premiumCalculation(
params,
@@ -751,9 +867,12 @@ Calculate the premiums of the InsuranceContract given the parameters, present va
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
\item{\code{premiumCalculationTime}}{The time when the premiums should be
(re-)calculated according to the equivalence principle. A time 0
@@ -764,7 +883,7 @@ premium after a contract change (possibly including an existing reserve)}
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -772,7 +891,9 @@ Not to be called directly, but implicitly by the [InsuranceContract] object.
\if{html}{\out{<a id="method-reserveCalculation"></a>}}
\if{latex}{\out{\hypertarget{method-reserveCalculation}{}}}
\subsection{Method \code{reserveCalculation()}}{
-Calculate the reserves of the InsuranceContract given the parameters, present values and premiums already calculated and stored in the \code{params} and \code{values} lists.
+Calculate the reserves of the InsuranceContract given the
+parameters, present values and premiums already calculated and stored in
+the \code{params} and \code{values} lists.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$reserveCalculation(params, values)}\if{html}{\out{</div>}}
}
@@ -780,14 +901,17 @@ Calculate the reserves of the InsuranceContract given the parameters, present va
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -795,7 +919,8 @@ Not to be called directly, but implicitly by the [InsuranceContract] object.
\if{html}{\out{<a id="method-getBalanceSheetReserveFactor"></a>}}
\if{latex}{\out{\hypertarget{method-getBalanceSheetReserveFactor}{}}}
\subsection{Method \code{getBalanceSheetReserveFactor()}}{
-Calculate the (linear) interpolation factors for the balance sheet reserve (Dec. 31) between the yearly contract clowing dates
+Calculate the (linear) interpolation factors for the balance
+sheet reserve (Dec. 31) between the yearly contract clowing dates
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$getBalanceSheetReserveFactor(params, years = 1)}\if{html}{\out{</div>}}
}
@@ -803,14 +928,17 @@ Calculate the (linear) interpolation factors for the balance sheet reserve (Dec.
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{years}}{how many years to calculate (for some usances, the factor is different in leap years!)}
+\item{\code{years}}{how many years to calculate (for some usances, the factor
+is different in leap years!)}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -819,8 +947,8 @@ Not to be called directly, but implicitly by the [InsuranceContract] object.
\if{latex}{\out{\hypertarget{method-reserveCalculationBalanceSheet}{}}}
\subsection{Method \code{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
+year by interpolation from the contract values calculated for
+the yearly reference date of the contract
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$reserveCalculationBalanceSheet(params, values)}\if{html}{\out{</div>}}
}
@@ -828,14 +956,17 @@ Calculate the reserves for the balance sheets at Dec. 31 of each
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -843,7 +974,8 @@ Not to be called directly, but implicitly by the [InsuranceContract] object.
\if{html}{\out{<a id="method-calculateProfitParticipation"></a>}}
\if{latex}{\out{\hypertarget{method-calculateProfitParticipation}{}}}
\subsection{Method \code{calculateProfitParticipation()}}{
-Calculate the profit participation given the contract parameters and the already calculated reserves of the contract.
+Calculate the profit participation given the contract
+parameters and the already calculated reserves of the contract.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$calculateProfitParticipation(params, ...)}\if{html}{\out{</div>}}
}
@@ -851,15 +983,17 @@ Calculate the profit participation given the contract parameters and the already
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
\item{\code{...}}{Additional parameters for the profit participation calculation, passed
-through to the profit participation scheme's [ProfitParticipation$getProfitParticipation()]}
+through to the profit participation scheme's \code{\link[=ProfitParticipation$getProfitParticipation]{ProfitParticipation$getProfitParticipation()}}}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -877,16 +1011,19 @@ Calculate the reserves after profit participation for the given profit scenario
\describe{
\item{\code{profitScenario}}{The ID of the profit scenario for which to calculate the reserves}
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
\item{\code{...}}{TODO}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -902,14 +1039,17 @@ Return the time series of the basic contract
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
}
}
@@ -925,15 +1065,18 @@ Calculate the time series of the premium decomposition of the contract
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
-\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values} list) then this method is called by the contract object}
+\item{\code{values}}{Contract values calculated so far (in the \code{contract$Values}
+list) then this method is called by the contract object}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
-Not to be called directly, but implicitly by the [InsuranceContract] object.
- All premiums, reserves and present values have already been calculated.
+Not to be called directly, but implicitly by the \link{InsuranceContract} object.
+All premiums, reserves and present values have already been calculated.
}
}
@@ -960,7 +1103,8 @@ Generic function to calculate future sums of the values
\if{html}{\out{<a id="method-calculatePresentValues"></a>}}
\if{latex}{\out{\hypertarget{method-calculatePresentValues}{}}}
\subsection{Method \code{calculatePresentValues()}}{
-Calculate all present values for a given time series. The mortalities are taken from the contract's parameters.
+Calculate all present values for a given time series. The
+mortalities are taken from the contract's parameters.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$calculatePresentValues(values, params)}\if{html}{\out{</div>}}
}
@@ -968,9 +1112,12 @@ Calculate all present values for a given time series. The mortalities are taken
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{values}}{The time series, for which future present values at all times are desired}
+\item{\code{values}}{The time series, for which future present values at all
+times are desired}
-\item{\code{params}}{Contract-specific, full set of parameters of the contract (merged parameters of the defaults, the tariff, the profit participation scheme and the contract)}
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
\item{\code{...}}{currently unused}
}
diff --git a/man/ProfitParticipation.Rd b/man/ProfitParticipation.Rd
index b909ff7c6f3cdaf4850636b743f65c34bdc0f30b..5a0a7891b4c2dd2aa037d093ba73197d56415317 100644
--- a/man/ProfitParticipation.Rd
+++ b/man/ProfitParticipation.Rd
@@ -4,9 +4,94 @@
\alias{ProfitParticipation}
\title{Base Class for Profit Participation Schemes}
\description{
-base class for Profit Participation schemes (holding contract-independent values and
+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 \link{InsuranceTarif} or \link{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 \code{ProfitParticipation$new(...)}. Possible
+parameters to the \code{new}-Call are all parameters from the
+\link{InsuranceContract.ParameterStructure$ProfitParticipation} 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 \link{Functions} list defining the functions to calculate the individual
+components of the profit participation (rates, calculation bases, calculation, benefits)
+
+This method \code{createModification} returns a copy of the profit scheme
+with all given arguments changed in the schmes's \link{ProfitParticipation@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 \link{InsuranceContract}'s param structure \link{InsuranceContract.ParameterStructure}
+contains the field \code{params$ProfitParticipation$advanceProfitParticipation},
+which can either be numeric rate for advance profit participation, or
+a function with signature \code{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 \link{InsuranceContract}'s param structure \link{InsuranceContract.ParameterStructure}
+contains the field \code{params$ProfitParticipation$advanceProfitParticipationInclUnitCost},
+which can either be numeric rate for advance profit participation, or
+a function with signature \code{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.
+}
+\section{Public fields}{
+\if{html}{\out{<div class="r6-fields">}}
+\describe{
+\item{\code{name}}{The human-readable name of the profit plan.}
+
+\item{\code{Parameters}}{Parameter template for profit-participation-specific
+parameters, i.e. the \code{ProfitParticipation} element of the
+\link{InsuranceContract.ParameterStructure} data structure.
+
+All elements defined in the profit scheme can be overriden per contract
+in the call to \code{[InsuranceContract]$new} or even in the explicit
+call to \link{InsuranceContract$profitScenario} or \link{InsuranceContract$addProfitScenario}.}
+
+\item{\code{Functions}}{list of functions defined to calculate the individual
+components. For each of the profit components
+\itemize{
+\item interest profit
+\item risk profit
+\item expense profit
+\item sum profit
+\item terminal bonus
+\item terminal bonus fund
+}
+a rate, a profit base and a calculation function can be defined, by assigning one of the pre-defined
+\link{ProfitParticipationFunctions} or proving your own function with signature
+\code{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.}
+
+\item{\code{dummy}}{Dummy to allow commas in the previous method}
+}
+\if{html}{\out{</div>}}
}
\section{Methods}{
\subsection{Public methods}{
@@ -28,33 +113,64 @@ reserves).
\if{html}{\out{<a id="method-new"></a>}}
\if{latex}{\out{\hypertarget{method-new}{}}}
\subsection{Method \code{new()}}{
+Create a new profit participation scheme
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{ProfitParticipation$new(name = NULL, ...)}\if{html}{\out{</div>}}
}
+\subsection{Arguments}{
+\if{html}{\out{<div class="arguments">}}
+\describe{
+\item{\code{name}}{The name of the profit scheme (typicall the name of the profit plan and its version)}
+
+\item{\code{...}}{profit participation parameters to be stored in
+\link{Parameters} or calculation functions to be stored in \link{Functions}}
+}
+\if{html}{\out{</div>}}
+}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-setParameters"></a>}}
\if{latex}{\out{\hypertarget{method-setParameters}{}}}
\subsection{Method \code{setParameters()}}{
+Store all passed parameters in the \link{Parameters} field
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{ProfitParticipation$setParameters(...)}\if{html}{\out{</div>}}
}
+\subsection{Arguments}{
+\if{html}{\out{<div class="arguments">}}
+\describe{
+\item{\code{...}}{any of the named fields defined in
+\link{InsuranceContract.ParameterStructure$ProfitParticipation}. All other
+arguments will be ignored}
+}
+\if{html}{\out{</div>}}
+}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-setFunctions"></a>}}
\if{latex}{\out{\hypertarget{method-setFunctions}{}}}
\subsection{Method \code{setFunctions()}}{
+Store all passed functions in the \link{Functions} field
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{ProfitParticipation$setFunctions(...)}\if{html}{\out{</div>}}
}
+\subsection{Arguments}{
+\if{html}{\out{<div class="arguments">}}
+\describe{
+\item{\code{...}}{any of the functions defined in the \link{Functions} field. All other
+arguments will be ignored}
+}
+\if{html}{\out{</div>}}
+}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-setFallbackParameters"></a>}}
\if{latex}{\out{\hypertarget{method-setFallbackParameters}{}}}
\subsection{Method \code{setFallbackParameters()}}{
+Fill all missing parameters with the default fall-back values
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{ProfitParticipation$setFallbackParameters()}\if{html}{\out{</div>}}
}
@@ -64,24 +180,58 @@ reserves).
\if{html}{\out{<a id="method-createModification"></a>}}
\if{latex}{\out{\hypertarget{method-createModification}{}}}
\subsection{Method \code{createModification()}}{
+create a copy of a profit scheme with certain parameters changed
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{ProfitParticipation$createModification(name = NULL, ...)}\if{html}{\out{</div>}}
}
+\subsection{Arguments}{
+\if{html}{\out{<div class="arguments">}}
+\describe{
+\item{\code{name}}{The new name for the cloned \link{ProfitParticipation} object}
+
+\item{\code{...}}{Parameters for the \link{InsuranceContract.ParametersStructure},
+defining the characteristics of the tariff.}
+}
+\if{html}{\out{</div>}}
+}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-getAdvanceProfitParticipation"></a>}}
\if{latex}{\out{\hypertarget{method-getAdvanceProfitParticipation}{}}}
\subsection{Method \code{getAdvanceProfitParticipation()}}{
+Calculate and return the advance profit participation (to be
+applied on the actuarial gross premium)
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{ProfitParticipation$getAdvanceProfitParticipation(params, values, ...)}\if{html}{\out{</div>}}
}
+\subsection{Arguments}{
+\if{html}{\out{<div class="arguments">}}
+\describe{
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
+
+\item{\code{values}}{Contract values calculated so far (guaranteed component of the
+insurance contract, including cash flows, premiums, reserves etc.).}
+
+\item{\code{...}}{optional parameters, to be passed to the advanceProfitParticipation
+field of the parameter structure (if that is a function)}
+}
+\if{html}{\out{</div>}}
+}
+\subsection{Returns}{
+Return either one numerical value (constant for the whole premium payment period)
+of a vector of numerical values for the whole contract period
+}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-getAdvanceProfitParticipationAfterUnitCosts"></a>}}
\if{latex}{\out{\hypertarget{method-getAdvanceProfitParticipationAfterUnitCosts}{}}}
\subsection{Method \code{getAdvanceProfitParticipationAfterUnitCosts()}}{
+Calculate and return the advance profit participation (to be
+applied after unit costs are added to the gross premium)
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{ProfitParticipation$getAdvanceProfitParticipationAfterUnitCosts(
params,
@@ -90,29 +240,81 @@ reserves).
)}\if{html}{\out{</div>}}
}
+\subsection{Arguments}{
+\if{html}{\out{<div class="arguments">}}
+\describe{
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
+
+\item{\code{values}}{Contract values calculated so far (guaranteed component of the
+insurance contract, including cash flows, premiums, reserves etc.).}
+
+\item{\code{...}}{optional parameters, to be passed to the advanceProfitParticipationInclUnitCost
+field of the parameter structure (if that is a function)}
+}
+\if{html}{\out{</div>}}
+}
+\subsection{Returns}{
+Return either one numerical value (constant for the whole premium payment period)
+of a vector of numerical values for the whole contract period
+}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-setupRates"></a>}}
\if{latex}{\out{\hypertarget{method-setupRates}{}}}
\subsection{Method \code{setupRates()}}{
+Set up the data.frame containing the profit participation rates
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{ProfitParticipation$setupRates(params, values, ...)}\if{html}{\out{</div>}}
}
+\subsection{Arguments}{
+\if{html}{\out{<div class="arguments">}}
+\describe{
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
+
+\item{\code{values}}{Contract values calculated so far (guaranteed component of the
+insurance contract, including cash flows, premiums, reserves etc.).}
+
+\item{\code{...}}{additional parameters passed to the profit calculation functions
+stored in the \link{Functions} field.}
+}
+\if{html}{\out{</div>}}
+}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-adjustRates"></a>}}
\if{latex}{\out{\hypertarget{method-adjustRates}{}}}
\subsection{Method \code{adjustRates()}}{
+Adjust the data.frame of profit participation rates after their setup
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{ProfitParticipation$adjustRates(rates, params, values)}\if{html}{\out{</div>}}
}
+\subsection{Arguments}{
+\if{html}{\out{<div class="arguments">}}
+\describe{
+\item{\code{rates}}{data.frame of profit paticipation rates}
+
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
+
+\item{\code{values}}{Contract values calculated so far (guaranteed component of the
+insurance contract, including cash flows, premiums, reserves etc.).}
+}
+\if{html}{\out{</div>}}
+}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-getProfitParticipation"></a>}}
\if{latex}{\out{\hypertarget{method-getProfitParticipation}{}}}
\subsection{Method \code{getProfitParticipation()}}{
+Calculation the full time series of profit participation for
+the given contract values
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{ProfitParticipation$getProfitParticipation(
calculateFrom = 0,
@@ -123,6 +325,30 @@ reserves).
)}\if{html}{\out{</div>}}
}
+\subsection{Arguments}{
+\if{html}{\out{<div class="arguments">}}
+\describe{
+\item{\code{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 \code{calculateFrom} will not be calculated.}
+
+\item{\code{profitScenario}}{profit participation values from a previous calculation
+(NULL if profit calculation is to be calculated from the contract inception).
+Values before \code{calculateFrom} will be used from this data.frame.}
+
+\item{\code{params}}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
+
+\item{\code{values}}{Contract values calculated so far (guaranteed component of the
+insurance contract, including cash flows, premiums, reserves etc.).}
+
+\item{\code{...}}{additional parameters to be passed to \link{setupRates}}
+}
+\if{html}{\out{</div>}}
+}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-clone"></a>}}
diff --git a/man/ProfitParticipationFunctions.Rd b/man/ProfitParticipationFunctions.Rd
index 89782c4d1ae84efa8adb442114abfbf08f994ec6..efbf420c22a8d2ab5d2fbc08425141c32c93290d 100644
--- a/man/ProfitParticipationFunctions.Rd
+++ b/man/ProfitParticipationFunctions.Rd
@@ -128,6 +128,16 @@ PP.benefit.TerminalBonus5Years(profits, params, ...)
PP.benefit.TerminalBonus(profits, params, ...)
}
+\arguments{
+\item{rates}{data.frame of profit rates}
+
+\item{params}{Contract-specific, full set of parameters of the contract
+(merged parameters of the defaults, the tariff, the profit participation
+scheme and the contract)}
+
+\item{values}{Contract values calculated so far (guaranteed component of the
+insurance contract, including cash flows, premiums, reserves etc.).}
+}
\description{
Various helper functions for the \code{ProfitParticipation} class that
provide the building blocks for the individual components of profit participation,
diff --git a/man/addDataTableWorksheet.Rd b/man/addDataTableWorksheet.Rd
deleted file mode 100644
index ed66359cb45387b46d55757fc351a65e3f5afbeb..0000000000000000000000000000000000000000
--- a/man/addDataTableWorksheet.Rd
+++ /dev/null
@@ -1,22 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/addDataTableWorksheet.R
-\name{addDataTableWorksheet}
-\alias{addDataTableWorksheet}
-\title{Add a new worksheet to the excel workbook and export the given data table x to it nicely formatted.}
-\usage{
-addDataTableWorksheet(
- wb,
- sheet,
- title = NULL,
- x = NULL,
- loopdim = 3,
- style = NULL,
- tableStyle = "TableStyleMedium17",
- comparisons = NULL,
- comparisonStyle = NULL,
- ...
-)
-}
-\description{
-Add a new worksheet to the excel workbook and export the given data table x to it nicely formatted.
-}
diff --git a/man/applyHook.Rd b/man/applyHook.Rd
new file mode 100644
index 0000000000000000000000000000000000000000..e1e336d0ee8e0bddb6153f5256402fa622ff14a9
--- /dev/null
+++ b/man/applyHook.Rd
@@ -0,0 +1,23 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/HelperFunctions.R
+\name{applyHook}
+\alias{applyHook}
+\title{If \code{hook} is a function, apply it to \code{val}, otherwise return \code{val} unchanged}
+\usage{
+applyHook(hook, val, ...)
+}
+\arguments{
+\item{hook}{(optional) function to apply to \code{val} and the other parameters}
+
+\item{val}{The value to which the hook is applied (ifgiven)}
+
+\item{...}{optional parameters passed to the hook function (if it is a function)}
+}
+\description{
+If \code{hook} is a function, apply it to \code{val}, otherwise return \code{val} unchanged
+}
+\examples{
+applyHook(NULL, 3) # returns 3 unchanged
+applyHook(function(x) 2*x, 3) # applies the function, returns 6
+applyHook(`+`, 3, 1) # returns 4
+}
diff --git a/man/contractGrid.Rd b/man/contractGrid.Rd
index 6f823355049967880fcf39c886bdea78421faec9..df7a9517a9a4b265a0fd1001c6c3a0c57b08af3d 100644
--- a/man/contractGrid.Rd
+++ b/man/contractGrid.Rd
@@ -15,6 +15,15 @@ contractGrid(
...
)
}
+\arguments{
+\item{axes}{List of paramters spanning the dimensions of the grid.}
+
+\item{YOB}{optional year of bith. If missing, the \code{observationYear} and the contract's age}
+
+\item{observationYear}{The observation year, for which the grid shall be calculated. If given, the YOB is calculated from it, otherwise the contract's YOB is used}
+
+\item{...}{Additional parameters to be passed to \link{InsuranceContract$new}}
+}
\description{
Create a multi-dimensional grid of InsuranceContract objects, where the axes
ranges are given with the axes argument.
diff --git a/man/contractGridPremium.Rd b/man/contractGridPremium.Rd
index 9bedebacfead145e073a1a9ec87fcc84e092e36c..de0296777fd84ab328329ee2cb085541185541df 100644
--- a/man/contractGridPremium.Rd
+++ b/man/contractGridPremium.Rd
@@ -10,6 +10,15 @@ a grid.}
\usage{
contractGridPremium(contractGrid = NULL, premium = "written", ...)
}
+\arguments{
+\item{contractGrid}{(optional) existing contract grid from which to derive
+premiums. If not given, \link{contractGrid} is called with all parameters, so
+\code{...} should contain an \code{axes} argument in that case.}
+
+\item{premium}{The type of premium to derive (key of the \code{contract$Values$premiums} list.}
+
+\item{...}{Arguments pass on to \link{contractGrid} if no conract grid is given.}
+}
\description{
Create a multi-dimensional grid of premiums for insurance contracts, where the axes
ranges are given with the axes argument.
diff --git a/man/exportInsuranceContract.xlsx.Rd b/man/exportInsuranceContract.xlsx.Rd
new file mode 100644
index 0000000000000000000000000000000000000000..7c27311b3ce11d5cd237217101759456fb569a54
--- /dev/null
+++ b/man/exportInsuranceContract.xlsx.Rd
@@ -0,0 +1,41 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/exportInsuranceContract_xlsx.R
+\name{exportInsuranceContract.xlsx}
+\alias{exportInsuranceContract.xlsx}
+\title{Export an insurance act object tocontract (object of class \link{InsuranceContract}) to an Excel file}
+\usage{
+exportInsuranceContract.xlsx(contract, filename)
+}
+\arguments{
+\item{contract}{The insurance contract to export}
+
+\item{filename}{Target Excel filename for export}
+}
+\description{
+Export an insurance act object tocontract (object of class \link{InsuranceContract}) to an Excel file
+}
+\details{
+The function \code{exportInsuranceContract.xlsx} exports an object
+of class \link{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 \code{contract$Values}.
+}
+\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")
+);
+exportInsuranceContract.xlsx(contract, "Example_annuity_contract.xlsx")
+}
diff --git a/man/exportInsuranceContractExample.Rd b/man/exportInsuranceContractExample.Rd
index d9da74169b64ae96d43227f6f9a88727bd097a81..e27dbf9fa20253b32263cf4fc6bdbf438f467441 100644
--- a/man/exportInsuranceContractExample.Rd
+++ b/man/exportInsuranceContractExample.Rd
@@ -29,11 +29,13 @@ required by the Austrian regulation).
}
\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 \code{prf}
- - [DATE]_[TARIFF]_Examples_VmGlg.txt: Example calculation required for the
- Austrian regulation (LV-VMGLV)
+\itemize{
+\item \link{DATE}_\link{TARIFF}_Example.xlsx: Full history/timeseries
+\item \link{DATE}_\link{TARIFF}_Example_PremiumWaiver_t10.xlsx: Full history/timeseries
+after a premium waiver at the given time \code{prf}
+\item \link{DATE}_\link{TARIFF}_Examples_VmGlg.txt: Example calculation required for the
+Austrian regulation (LV-VMGLV)
+}
}
\examples{
library("MortalityTables")
diff --git a/man/fallbackFields.Rd b/man/fallbackFields.Rd
index edf71a342065b0e27c5bd3912b1b446d01ca726e..9a23f6e9db765d2cfc781f4d14ac5e0abab41209 100644
--- a/man/fallbackFields.Rd
+++ b/man/fallbackFields.Rd
@@ -2,10 +2,17 @@
% Please edit documentation in R/HelperFunctions.R
\name{fallbackFields}
\alias{fallbackFields}
-\title{fallbackFields(fields, fallback)}
+\title{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{
+\item{fields}{existing list}
+
+\item{valuelist}{list of fields to replace in \code{fields}. Only keys that are missing in \code{fields} are added, no existing fields in \code{fields} are overwritten}
+}
\description{
Replace all missing values in fields (either missing or NA) with
their corresponding values from fallback. Members in fallback that are missing
diff --git a/man/fillFields.Rd b/man/fillFields.Rd
index 9c0203d8ce209881db7cc3fa336d1207d75dce15..28aefd382f360f390feb51d2727106fa58802afe 100644
--- a/man/fillFields.Rd
+++ b/man/fillFields.Rd
@@ -2,10 +2,18 @@
% Please edit documentation in R/HelperFunctions.R
\name{fillFields}
\alias{fillFields}
-\title{fillFields(fields, valuelist)}
+\title{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{
+\item{fields}{existing list}
+
+\item{valuelist}{list of fields to replace in \code{fields}. Only keys that exist in \code{fields} are overwritten, no new fields are added to \code{fields}}
+}
\description{
Overwrite all existing fields in the first argument with
values given in valuelist. Members of valuelist that are not yet in
diff --git a/man/initializeCosts.Rd b/man/initializeCosts.Rd
index e08bf5c61cdecf2109258b503fa2ea94f4bcb709..72b3b546c57d4965594d9c4c19f80ca0caf30b72 100644
--- a/man/initializeCosts.Rd
+++ b/man/initializeCosts.Rd
@@ -2,11 +2,7 @@
% Please edit documentation in R/InsuranceParameters.R
\name{initializeCosts}
\alias{initializeCosts}
-\title{Initialize a cost matrix with dimensions: [CostType, Basis, Period], with:
- CostType: alpha, Zillmer, beta, gamma, gamma_nopremiums, unitcosts
- Basis: SumInsured, SumPremiums, GrossPremium, NetPremium, Constant
- Period: once, PremiumPeriod, PremiumFree, PolicyPeriod
-TODO: gamma an Erlebensleistungen?}
+\title{Initialize a data structure for the definition of \link{InsuranceTarif} costs}
\usage{
initializeCosts(
costs,
@@ -20,10 +16,37 @@ initializeCosts(
unitcosts.PolicyPeriod
)
}
+\arguments{
+\item{costs}{(optional) existing cost structure to duplicate / use as a starting point}
+
+\item{alpha}{Alpha costs (charged once, relative to sum of premiums)}
+
+\item{Zillmer}{Zillmer costs (charged once, relative to sum of premiums)}
+
+\item{beta}{Collection costs (charged on each gross premium, relative to gross premium)}
+
+\item{gamma}{Administration costs while premiums are paid (relative to sum insured)}
+
+\item{gamma.paidUp}{Administration costs for paid-up contracts (relative to sum insured)}
+
+\item{gamma.premiumfree}{Administration costs for planned premium-free period (reltaive to sum insured)}
+
+\item{unitcosts}{Unit costs (absolute monetary amount, during premium period)}
+
+\item{unitcosts.PolicyPeriod}{Unit costs (absolute monetary amount, during full contract period)}
+}
\description{
-Initialize a cost matrix with dimensions: [CostType, Basis, Period], with:
- CostType: alpha, Zillmer, beta, gamma, gamma_nopremiums, unitcosts
- Basis: SumInsured, SumPremiums, GrossPremium, NetPremium, Constant
- Period: once, PremiumPeriod, PremiumFree, PolicyPeriod
-TODO: gamma an Erlebensleistungen?
+Initialize a cost matrix with dimensions: {CostType, Basis, Period}, where:
+\describe{
+\item{CostType:}{alpha, Zillmer, beta, gamma, gamma_nopremiums, unitcosts}
+\item{Basis:}{SumInsured, SumPremiums, GrossPremium, NetPremium, Constant}
+\item{Period:}{once, PremiumPeriod, PremiumFree, PolicyPeriod}
+}
+This cost structure can then be modified for non-standard costs.
+The main purpose of this structure is to be passed to \link{InsuranceContract} or
+\link{InsuranceTariff} definitions.
+}
+\examples{
+# empty cost structure (only 0 costs)
+initializeCosts()
}
diff --git a/man/makeContractGridDimname.Rd b/man/makeContractGridDimname.Rd
new file mode 100644
index 0000000000000000000000000000000000000000..531630030010e12572b2fde6df58fb1e09069856
--- /dev/null
+++ b/man/makeContractGridDimname.Rd
@@ -0,0 +1,14 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/contractGrid.R
+\name{makeContractGridDimname}
+\alias{makeContractGridDimname}
+\title{Generate a dimension label for the object passed as \code{value}, to be used in \link{contactGrid}}
+\usage{
+makeContractGridDimname(value)
+}
+\arguments{
+\item{value}{the value along the axis, for which a name should be generated}
+}
+\description{
+Generate a dimension label for the object passed as \code{value}, to be used in \link{contactGrid}
+}
diff --git a/man/makeContractGridDimnames.Rd b/man/makeContractGridDimnames.Rd
new file mode 100644
index 0000000000000000000000000000000000000000..f8ced4fde975066216aa1a0e8a56ab1fdcf061da
--- /dev/null
+++ b/man/makeContractGridDimnames.Rd
@@ -0,0 +1,14 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/contractGrid.R
+\name{makeContractGridDimnames}
+\alias{makeContractGridDimnames}
+\title{Generate proper dimnames for all exntries of the axes of a \link{contractGrid}}
+\usage{
+makeContractGridDimnames(axes)
+}
+\arguments{
+\item{axes}{the axes with all names, for which a name should be generated}
+}
+\description{
+Generate proper dimnames for all exntries of the axes of a \link{contractGrid}
+}
diff --git a/man/rollingmean.Rd b/man/rollingmean.Rd
new file mode 100644
index 0000000000000000000000000000000000000000..de7fe2086f7dc4b541abc5f107e79befdb74e210
--- /dev/null
+++ b/man/rollingmean.Rd
@@ -0,0 +1,17 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/HelperFunctions.R
+\name{rollingmean}
+\alias{rollingmean}
+\title{Calculate the rolling mean of length 2}
+\usage{
+rollingmean(x)
+}
+\arguments{
+\item{x}{vector of values, for which the rolling mean is calculated}
+}
+\description{
+Calculate the rolling mean of length 2
+}
+\examples{
+rollingmean(1:10)
+}
diff --git a/man/valueOrFunction.Rd b/man/valueOrFunction.Rd
new file mode 100644
index 0000000000000000000000000000000000000000..9b09a76bd5f4b7e80cca8049dd1c8605d7f4d188
--- /dev/null
+++ b/man/valueOrFunction.Rd
@@ -0,0 +1,22 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/HelperFunctions.R
+\name{valueOrFunction}
+\alias{valueOrFunction}
+\title{If \code{val} is a function, evaluate it, otherwise return \code{val}}
+\usage{
+valueOrFunction(val, ...)
+}
+\arguments{
+\item{val}{Function or value}
+
+\item{...}{Argument passed to \code{val} if it is a function}
+}
+\description{
+If \code{val} is a function, evaluate it, otherwise return \code{val}
+}
+\examples{
+valueOrFunction(3) # returns 3
+valueOrFunction(`+`, 1, 2) # also returns 3
+A = `+`
+valueOrFunction(A, 1, 2)
+}