diff --git a/NAMESPACE b/NAMESPACE
index b1b60bbe946932d0a3311999aa0b76ec9dbae730..36d79792448d767e09a9b9cb21a5f3f9d9b1ba12 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -70,6 +70,7 @@ export(padLast)
export(rollingmean)
export(showVmGlgExamples)
export(valueOrFunction)
+exportClasses(TariffTypeSingleEnum)
import(MortalityTables)
import(R6)
import(dplyr)
diff --git a/R/HelperFunctions.R b/R/HelperFunctions.R
index 60d3d75d694d46cb06fe65ccfa40bafba6aaa6b5..e19647bba733c12b6d66bc8032aa8bc95f8a5982 100644
--- a/R/HelperFunctions.R
+++ b/R/HelperFunctions.R
@@ -4,8 +4,25 @@
#' @importFrom methods new
#'
+# @name PaymentTimeSingleEnum
+# @description Enum to describe when a benefit or premium payment is due (in advance or in arrears)
+# @details Currently, only two values are allowed;
+# * "in advance"
+# * "in arrears
+#
+# @export
PaymentTimeEnum = objectProperties::setSingleEnum("PaymentTime", levels = c("in advance", "in arrears"))
#PaymentCountEnum = objectProperties::setSingleEnum(PaymentCount, levels = c(1,2,3))
+
+# @name SexSingleEnum
+# @description Enum to describe possble sexes in an insurance contract or tariff.
+# @details
+# Currently, only possible values are allowed;
+# * "unisex"
+# * "male"
+# * "female"
+#
+# @export
SexEnum = objectProperties::setSingleEnum("Sex", levels = c("unisex", "male", "female"))
@@ -37,14 +54,24 @@ deathBenefit.linearDecreasing = function(len, params, values) {
#' This can be used with the \code{deathBenefit} parameter for insurance
#' contracts, but should not be called directly.
#'
-#' @param len The desired length of the Cash flow vector (can be shorter than
+#' This function is a mere generator function, which takes the interest rate and
+#' generates a function that describes a decreasing annuity.
+#'
+#' The generated function has the following parameters:
+#' \describe{
+#' \item{len}{The desired length of the Cash flow vector (can be shorter than
#' the policyPeriod, if q_x=1 before the end of the contract, e.g.
-#' for life-long insurances)
-#' @param params The full parameter set of the insurance contract (including
-#' all inherited values from the tariff and the profit participation)
-#' @param values The values calculated from the insurance contract so far
+#' for life-long insurances)}
+#' \item{params}{The full parameter set of the insurance contract (including
+#' all inherited values from the tariff and the profit participation)}
+#' \item{values}{The values calculated from the insurance contract so far}
+#' }
#'
-#' @export
+#'
+#' @param interest The interest rate of the loan, which is underlying the insurance.
+#'
+#'
+#'@export
deathBenefit.annuityDecreasing = function(interest) {
function(len, params, values) {
protectionPeriod = params$ContractData$policyPeriod - params$ContractData$deferralPeriod;
@@ -212,6 +239,27 @@ correctionPaymentFrequency = function(i, m = 1, order = 0) {
list(alpha = alpha, beta = beta);
}
+#' Pad a vector with 0 to a desired length
+#'
+#' @param v the vector to pad with 0
+#' @param l the desired (resulting) length of the vector
+#' @param value the value to pad with (if padding is needed). Default to 0, but
+#' can be overridden to pad with any other value.
+#' @param start the first \code{start} values are always set to 0 (default is 0),
+#' the vector \code{v} starts only after these leading zeroes. The number of
+#' leading zeroes counts towards the desired length
+#'
+#' @return returns the vector \code{v} padded to length \code{l} with value \code{value} (default 0).
+#'
+#' @examples
+#' pad0(1:5, 7) # Pad to length 7 with zeroes
+#' pad0(1:5, 3) # no padding, but cut at length 3
+#'
+#' # 3 leading zeroes, then the vector start (10 elements of vector, no additional padding needed):
+#' pad0(1:10, 13, start = 3)
+#'
+#' # padding with value other than zero:
+#' pad0(1:5, 7, value = "pad")
#' @export
pad0 = function(v, l, value = 0, start = 0) {
# 3 cases: desired length<=start => only 0
@@ -228,6 +276,13 @@ pad0 = function(v, l, value = 0, start = 0) {
}
#' Set all entries of the given vector to 0 up until index 'start'
+#' @param v the vector to modify
+#' @param start how many leading elements to zero out
+#'
+#' @return the vector \code{v} with the first \code{start} elements replaced by 0.
+#'
+#' @examples
+#' head0(1:10, 3)
#' @export
head0 = function(v, start = 0) {
if (start == 0) {
@@ -237,16 +292,45 @@ head0 = function(v, start = 0) {
}
}
+#' Pad the vector \code{v} to length \code{l} by repeating the last entry of the
+#' vector.
+#'
+#' This function callc [pad0()] with the last element of the vector as padding value
+#'
+#' @param v the vector to pad by repeating the last element
+#' @param l the desired (resulting) length of the vector
+#' @param start the first \code{start} values are always set to 0 (default is 0),
+#' the vector \code{v} starts only after these leading zeroes. The number of
+#' leading zeroes counts towards the desired length
+#'
+#' @examples
+#' padLast(1:5, 7) # 5 is repeated twice
+#' padLast(1:5, 3) # no padding needed
+#'
#' @export
padLast = function(v, l, start = 0) {
pad0(v, l, value = tail(v, n = 1), start = start)
}
-#' Taken from the R Cookbook:
+#' Replace all \code{NA} entries of a vector with the previous non-NA value
+#'
+#' Sometimes one has a vector with some gaps (\code{NA}) values, which cause
+#' problems for several numeric functions. This function \code{fillNAgaps} fills
+#' these missing values by inserting the last preceeding non-NA-value. Leading
+#' NA values (at the start of the vector will not be modified). If the
+#' argument \code{firstBack = TRUE}, leading \code{NA}-values are replaced by
+#' the first non-NA value.
+#' Trailing NAs are always replaced by the last previous NA-value.
+#'
+#' This code was taken from the R Cookbook:
#' http://www.cookbook-r.com/Manipulating_data/Filling_in_NAs_with_last_non-NA_value/
#' LICENSE (from that page): The R code is freely available for use without any restrictions.
#' In other words: you may reuse the R code for any purpose (and under any license).
#'
+#' @param x The vector where NA-values should be filled by repeating the last preceeding non-NA value
+#' @param firstBack if \code{TRUE}, leading NAs are replaced by the first non-NA
+#' value in the vector, otherwise leading NAs are left untouched.
+#'
#' @export
fillNAgaps <- function(x, firstBack=FALSE) {
## NA's in a vector or factor are replaced with last non-NA values
diff --git a/R/InsuranceParameters.R b/R/InsuranceParameters.R
index 9799a53eabac848ae34d7ae7bf577a443c84b763..3fac537f34e959537e1ee138dd88ea625356121f 100644
--- a/R/InsuranceParameters.R
+++ b/R/InsuranceParameters.R
@@ -104,6 +104,240 @@ InsuranceContract.Values = list(
#' pre-filled with these values, and values passed in the constructor (or with
#' other setter functions) will override these values.
#'
+#' @format The parameter list is a list of lists with the following structure:
+#'
+#' Sublists:
+#' \itemize{
+#' \item \code{$ContractData} ... Contract-specific data (policy period,
+#' closing, age, sum insured, premium payments, etc.)
+#' \item \code{$ContractState} ... Current contract state (paid-up, surrender
+#' penalty already applied, alpha costs already (partially) refunded)
+#' \item \code{$ActuarialBases} ... Actuarial bases for the contract
+#' calculation (mortality/invalidity table, guaranteed interest,
+#' surrender penalty, etc.)
+#' \item \code{$Costs} ... Expenses charged to the contract (see [initializeCosts()])
+#' \item \code{$Loadings} ... Loadings, rebates and other charges of the
+#' tariff / contract (tax, unit costs, surcharge for no medial exam, premium/benefit frequency loading)
+#' \item \code{$Features} ... Peculiarities of the tariff (to enable
+#' non-standard formulas for certain company-specific historical
+#' "glitches" in the tariff definitions.)
+#' \item \code{$ProfitParticipation} ... Profit scheme and profit participation
+#' rates (default values, can be overwritten per profit scenario)
+#' \item \code{$Hooks} ... Hook functions to allow modification of various
+#' calculation aspects (e.g. modify the default cash flows after
+#' their setup)
+#' }
+#'
+#' ## Elements of sublist \code{InsuranceContract.ParameterDefault$ContractData}
+#'
+#' These values are typically set per contract and not by the tariff. Notable
+#' exceptions are the contract duration in some instances and the premiumPeriod=1
+#' for single-premium contracts.
+#'
+#' \describe{
+#' \item{\code{$id}}{ID of the contract (to distinguish individual parts in
+#' contracts with multiple parts, e.g. dynamic increases),
+#' default = "Hauptvertrag"}
+#' \item{\code{$sumInsured}}{Sum insured, default = 100,000}
+#' \item{\code{$YOB}}{Year of birth of the insured, used to determine the
+#' age for the application of the mortality table},
+#' \item{\code{$age}}{Age of the insured}
+#' \item{\code{$technicalAge}}{Technical age of the insured (when the age
+#' for the application of the mortality table does not coincide
+#' with the real age)}
+#' \item{\code{$ageDifferences}}{Vector of age differences to the first
+#' insured for contracts with multiple insured (i.e. joint-lives)}
+#' \item{\code{$sex}}{Sex of the insured, to allow gender-specific prixing
+#' (e.g. different mortalities or age modification), default="unisex",
+#' Type is [SexSingleEnum]}
+#' \item{\code{$policyPeriod}}{Policy Duration (in years)}
+#' \item{\code{$premiumPeriod}}{Premium payment period (in year), for
+#' single-premium contracts, \code{premiumPeriod = 1}. Default is
+#' \code{policyPeriod}, i.e. regular premiums during the whole
+#' contract period}
+#' \item{\code{$deferralPeriod}}{deferral period for annuities, i.e. the
+#' period survival payments start only after this period, typically
+#' the retirement age. This applies mostly to tariffs of type
+#' annuity, although deferral periods are possible (but not common)
+#' for all other types of insurance, too.}
+#' \item{\code{$guaranteedPeriod}}{guaranteed annuity payment period. The
+#' annuity pays out for this period, even if the insured dies.
+#' This applies only to tariffs of type annuity.}
+#' \item{\code{$contractClosing}}{The date (variable of type [Date]) when
+#' the coverage of the contract starts (not neccessarily equal to
+#' the date when the contract was signed). Typically generated by
+#' a call to [as.Date()]. The year is relevant to derive the age
+#' of the insured, while month and day are relevant for the
+#' interpolation of the balance sheet reserves}
+#' \item{\code{$blockStart}}{For contracts with multiple blocks (e.g.
+#' multiple dynamic increases, where each increase is modelled
+#' like a separate contract), this variable holds the offset of
+#' the current contract block relative to the main contract block.
+#' The main block starts a 0, dynamic increases start later! This
+#' value is only used by the parent block (i.e. $t=0$ of the child
+#' is aligned with $t=blockStart$ of the parent block.}
+#' \item{\code{$premiumPayments}}{Whether premiums are paid in advance
+#' (default) or arrears. Value is of type [PaymentTimeSingleEnum]
+#' with possible values "in advance" and 'in arrears"}
+#' \item{\code{$benefitPayments}}{Whether recurring benefits (e.g. annuities)
+#' are paid in advance (default) or arrears. Value is of type
+#' [PaymentTimeSingleEnum] with possible values "in advance" and
+#' "in arrears"}
+#' \item{\code{$premiumFrequency}}{Number of premium payments per year, default is 1.}
+#' \item{\code{$benefitFrequency}}{Number of benefit payments per year, default is 1.}
+#'
+#' \item{\code{$widowProportion}}{For annuities with a widow transition,
+#' this describes the factor of the widow benefits relative to
+#' the original benefit.}
+#' \item{\code{$deathBenefitProportion}}{For endowments with a death and
+#' survival benefit, this describes the proportion of the death
+#' benefit relative to the survival benefit.}
+#' \item{\code{$premiumRefund}}{Proportion of (gross) premiums refunded on
+#' death (including additional risk, e.g. 1.10 = 110% of paid premiums)}
+#' \item{\code{$premiumIncrease}}{The yearly growth factor of the premium,
+#' i.e. 1.05 means +5% increase each year; a vector describes the
+#' premiums for all years}
+#' \item{\code{$annuityIncrease}}{The yearly growth factor of the annuity
+#' payments, i.e. 1.05 means +5% increase each year; a vector
+#' describes the annuity unit payments for all years}
+#' \item{\code{$deathBenefit}}{The yearly relative death benefit (relative
+#' to the initial sum insured); Can be set to a \code{function(len,
+#' params, values)}, e.g. \code{deathBenefit = deathBenefit.linearDecreasing}}
+#' }
+#'
+#' ## Elements of sublist \code{InsuranceContract.ParameterDefault$ContractState}
+#'
+#' Contract-specific status variables holding the status of the contract.
+#'
+#' \describe{
+#' \item{\code{$premiumWaiver}}{Whether the contract is paid-up.}
+#' \item{\code{$surrenderPenalty}}{Whether a surrender penalty still applies
+#' (e.g. because it has already been applied during a contract change,
+#' or because due to legal reasons it can no longer be applied)}
+#' \item{\code{$alphaRefunded}}{Whether alpha costs have (at least partially)
+#' been refunded (e.g. when a contract is changed or paid-up). Default
+#' is not yet refunded.}
+#' }
+#'
+#'
+#' ## Elements of sublist \code{InsuranceContract.ParameterDefault$ActuarialBases}
+#'
+#' Tarif-specific actuarial calculation parameters of the contract. Typically,
+#' these values are set by the tariff, but can be overridden by contract (e.g.
+#' while prototyping a new product or a product change).
+#'
+#' \describe{
+#' \item{\code{$mortalityTable}}{The [mortalityTable] object describing the
+#' mortality of the insured}
+#' \item{\code{$invalidityTable}}{For contracts with invalidity benefits,
+#' the [mortalityTable] object describing the probabilities of
+#' invalidity}
+#' \item{\code{$invalidityEndsContract}}{For contracts with invalidity
+#' benefits, whether a payment of an invalidity benefit ends the
+#' contract.}
+#' \item{\code{$i}}{Guaranteed yearly interest rate, default is 0.00, i.e. 0%}
+#' \item{\code{$balanceSheetDate}}{The day/month when balance sheet reserves
+#' are calculated. Value of type [Date], typically generated with
+#' [as.Date()]. The year is actually irrelevant, only the day and
+#' month are relevant.}
+#' \item{\code{$balanceSheetMethod}}{How to interpolate the balance sheet
+#' reserves (at the balandeSheetDate) from the yearly contractual
+#' reserves.}
+#' \item{\code{$surrenderValueCalculation}}{A function describing the surrender
+#' value calculation.}
+#' \item{\code{$premiumFrequencyOrder}}{Order of the approximation for
+#' payments within the year (unless an extra frequency loading is
+#' used => then leave this at 0)}
+#' \item{\code{$benefitFrequencyOrder}}{Order of the approximation for
+#' payments within the year (unless an extra frequency loading is
+#' used => then leave this at 0)}
+#' }
+#'
+#' ## Elements of sublist \code{InsuranceContract.ParameterDefault$Costs}
+#'
+#' Definition of contractual costs charged to the contract. See [initializeCosts()].
+#'
+#' ## Elements of sublist \code{InsuranceContract.ParameterDefault$Loadings}
+#'
+#' \describe{
+#' \item{\code{$ongoingAlphaGrossPremium}}{Acquisition cost that increase the gross premium}
+#' \item{\code{$tax}}{insurance tax, factor on each premium paid, default is 4%, i.e. \code{i=0.04}}
+#' \item{\code{$unitcosts}}{Annual unit cost for each policy, absolute value (can be a function)}
+#' \item{\code{$security}}{Additional security loading on all benefit payments, factor on all benefits}
+#' \item{\code{$noMedicalExam}}{Loading when no medicial exam is done, % of SumInsured}
+#' \item{\code{$noMedicalExamRelative}}{Loading when no medicial exam is done, % of gross premium}
+#' \item{\code{$sumRebate}}{gross premium reduction for large premiums, % of SumInsured}
+#' \item{\code{$extraRebate}}{gross premium reduction for any reason, % of SumInsured}
+#' \item{\code{$premiumRebate}}{gross premium reduction for large premiums, % of gross premium}
+#' \item{\code{$partnerRebate}}{Rebate on premium with all surcharges and
+#' rebates when more than one contract is written with identical
+#' parameters. Sums with advanceBonusInclUnitCost and premiumRebate.}
+#' \item{\code{$extraChargeGrossPremium}}{extra charges on gross premium
+#' (smoker, leisure activities, BMI too high, etc.)}
+#' \item{\code{$benefitFrequencyLoading}}{Loading on the benefit for premium
+#' payment frequencies of more than once a year. Format is
+#' \code{list("1" = 0.0, "2" = 0.0, "4" = 0.0, "12" = 0.0)}}
+#' \item{\code{$premiumFrequencyLoading}}{Loading on the premium for premium
+#' payment frequencies of more than once a year. Format is
+#' \code{list("1" = 0.0, "2" = 0.0, "4" = 0.0, "12" = 0.0)}}
+#' }
+#'
+#'
+#' ## Elements of sublist \code{InsuranceContract.ParameterDefault$Features}
+#'
+#' \describe{
+#' \item{\code{$betaGammaInZillmer}}{Whether beta and gamma-costs should be
+#' included in the Zillmer premium calculation}
+#' \item{\code{$alphaRefundLinear}}{Whether the refund of alpha-costs on
+#' surrender is linear in t or follows the NPV of an annuity}
+#' }
+#'
+#' ## Elements of sublist \code{InsuranceContract.ParameterDefault$ProfitParticipation}
+#'
+#' Parameters describing the profit participation (instance of [ProfitParticipation])
+#' Most element descrive some kind of profit rate (which can vary in time),
+#' while the bases, on which they are applied is defined in the profit scheme.
+#'
+#' \describe{
+#' \item{\code{$advanceProfitParticipation}}{Advance profit participation
+#' rate (percentage rebate of the gross premium)}
+#' \item{\code{$advanceProfitParticipationInclUnitCost}}{Advance profit
+#' participation rate (percentage rebate on the gross premium after all surcharges and unit costs.}
+#'
+#' \item{\code{$waitingPeriod}}{Waiting period of the profit sharing (e.g.
+#' no profit in the first two years of a contract, or similar)}
+#' \item{\code{$guaranteedInterest}}{Individual contract-specific overrides
+#' of the guaranteed interest rate (i.e. not keyed by year)}
+#' \item{\code{$interestProfitRate}}{Interest profit rate (guaranteed interest
+#' rate + interest profit rate = total credited rate)}
+#' \item{\code{$totalInterest}}{Total credited rate (guarantee + interest profit)}
+#' \item{\code{$mortalityProfitRate}}{Mortality Profit rate}
+#' \item{\code{$expenseProfitRate}}{Expense profit rate}
+#' \item{\code{$sumProfitRate}}{Sum profit rate (for high sumInsured)}
+#' \item{\code{$terminalBonusRate}}{Terminal bonus rate (non-terminal-bonus
+#' fund, but "old" Austrian terminal bonus)}
+#' \item{\code{$terminalBonusFundRate}}{Terminal bonus fund rate}
+
+#' \item{\code{$profitParticipationScheme}}{Profit participation scheme (object of class [ProfitParticipation])}
+#' \item{\code{$profitComponents}}{Profit components of the profit scheme. List containing one or more of \code{c("interest", "risk", "expense", "sum", "terminal")}}
+#' \item{\code{$profitClass}}{String describing the profit class the tariff
+#' is assigned to. Profit classes are used to bundle similar
+#' contracts (e.g. following similar risks) together. Profit
+#' participation rates are defined at the level of profit classes.}
+#' \item{\code{$profitRates}}{General, company-wide profit rates, key columns are year and profitClass}
+#'
+#' \item{\code{$scenarios}}{profit participation scenarios (list of overridden parameters for each scenario)}
+#' }
+#'
+#' ## Elements of sublist \code{InsuranceContract.ParameterDefault$Hooks}
+#'
+#' \describe{
+#' \item{\code{$adjustCashFlows}}{Function with signature \code{function(x, params, values, ...)} to adjust the benefit/premium cash flows after their setup.}
+#' \item{\code{$adjustCashFlowsCosts}}{Function with signature \code{function(x, params, values, ...)} to adjust the costs cash flows after their setup.}
+#' }
+#'
+#'
+#'
#' @examples
#' InsuranceContract.ParameterDefaults
#' @export
diff --git a/R/InsuranceTarif.R b/R/InsuranceTarif.R
index f3f2545b7bff9f0b99d7f45381bfa77fe9807b46..5a690afacf9dd0147c333d59e542e24e69e4befa 100644
--- a/R/InsuranceTarif.R
+++ b/R/InsuranceTarif.R
@@ -6,7 +6,31 @@
#' @importFrom objectProperties setSingleEnum
NULL
-
+#' 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.}
+#' }
+#' @export
TariffTypeEnum = objectProperties::setSingleEnum(
"TariffType",
levels = c(
@@ -37,8 +61,8 @@ TariffTypeEnum = objectProperties::setSingleEnum(
#'
#' 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
+#' The only methods that are typically used for defining an insurance tariff are
+#' the constructor [InsuranceTarif$new()] and the cloning method
#' [InsuranceTarif$createModification()]. All other methods should never be called
#' manually.
#'
@@ -47,7 +71,7 @@ TariffTypeEnum = objectProperties::setSingleEnum(
#'
# # 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 type An enum specifying the main characteristics of the tarif. See [TariffTypeEnum]
#' @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
@@ -173,7 +197,7 @@ InsuranceTarif = R6Class(
#' or mortality table for comparison. There is no need to re-implement a
#' tariff for such comparisons, as long as only parameters are changed.
#'
- #' @param ... Parameters for the [InsuranceContract.ParametersStructure],
+ #' @param ... Parameters for the [InsuranceContract.Parameterstructure],
#' defining the characteristics of the tariff.
#' @import MortalityTables
#' @examples
@@ -397,7 +421,7 @@ InsuranceTarif = R6Class(
},
#' @description Returns the basic (unit) cash flows associated with the type
- #' of insurance given in the [InsuranceContract@tariffType] field
+ #' of insurance given in the [InsuranceTarif$tariffType] field
#' @details Not to be called directly, but implicitly by the [InsuranceContract] object.
getBasicCashFlows = function(params, values) {
deferralPeriod = params$ContractData$deferralPeriod;
diff --git a/R/exportInsuranceContractExample.R b/R/exportInsuranceContractExample.R
index 1045a95a1ac6b7b1ca56f8895ba00f9a43af6928..295df7075fa3e4ea7496f3965a73ba5ccb6b7361 100644
--- a/R/exportInsuranceContractExample.R
+++ b/R/exportInsuranceContractExample.R
@@ -10,22 +10,30 @@ NULL
#' required by the Austrian regulation).
#'
#' Three output files are generated:
-#' - [DATE]_[TARIFF]_Example.xlsx: Full history/timeseries
-#' - [DATE]_[TARIFF]_Example_PremiumWaiver_t10.xlsx: Full history/timeseries
+#' - {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
+#' - {DATE}_{TARIFF}_Examples_VmGlg.txt: Example calculation required for the
#' Austrian regulation (LV-VMGLV)
#'
#' @param contract The \code{\link{InsuranceContract}} object to be exported
#' @param prf The time of the premium waiver
#' @param outdir The output directory (the file names are not configurable)
+#' @param basename The base output filename (sans .xlsx). If missing, a name of
+#' the form 2020-08-01_TARIFNAME_EXTRANAME_RZ0.01_x35_YoB1977_LZ45_PrZ20_VS100000
+#' is used. If given, the main contract without modification will be
+#' exported to basename.xlsx, while the example with premium waiver will be
+#' exported to basename_PremiumWaiver_t10.xlsx and the text file containing
+#' the examples required by the LV-VMGV is exported to basename_VmGlg.txt.
+#' @param extraname If basename is not given, this allows a suffix to distinguish
+#' multiple exports.
#' @param ... Further parameters (passed on to \code{\link{showVmGlgExamples}})
#'
#' @examples
#' library("MortalityTables")
#' mortalityTables.load("Austria_Annuities_AVOe2005R")
#' # A trivial deferred annuity tariff with no costs:
-#' tariff = InsuranceTarif$new(name="Test Annuity", type="annuity",
+#' tariff = InsuranceTarif$new(name="Test Annuity", type="annuity", tarif = "Annuity 1A",
#' mortalityTable = AVOe2005R.unisex, i=0.01)
#' contract = InsuranceContract$new(
#' tariff,
diff --git a/R/exportInsuranceContract_xlsx.R b/R/exportInsuranceContract_xlsx.R
index 30aa2034df9bb7e835be91acbfa62b223d1bccdd..2b30850bd0a1325c2dba461c3de99dd0039eeef1 100644
--- a/R/exportInsuranceContract_xlsx.R
+++ b/R/exportInsuranceContract_xlsx.R
@@ -800,7 +800,7 @@ exportCFTable = function(wb, sheet, contract, ccol = 1, crow = 1, styles = c(),
#' library("MortalityTables")
#' mortalityTables.load("Austria_Annuities_AVOe2005R")
#' # A trivial deferred annuity tariff with no costs:
-#' tariff = InsuranceTarif$new(name="Test Annuity", type="annuity",
+#' tariff = InsuranceTarif$new(name = "Test Annuity", type = "annuity", tarif = "Annuity 1A",
#' mortalityTable = AVOe2005R.unisex, i=0.01)
#' contract = InsuranceContract$new(
#' tariff,
diff --git a/R/showVmGlgExamples.R b/R/showVmGlgExamples.R
index f8d7d956adffe84fa05ce8bc1733ce2f0f7a2572..0049d11576e4e9f45a636471ce0dff1bfb7231b6 100644
--- a/R/showVmGlgExamples.R
+++ b/R/showVmGlgExamples.R
@@ -18,6 +18,7 @@ NULL
#' @param ... Further parameters (currently unused)
#'
#' @examples
+#' library(MortalityTables)
#' mortalityTables.load("Austria_Annuities_AVOe2005R")
#' # A trivial deferred annuity tariff with no costs:
#' tariff = InsuranceTarif$new(name="Test Annuity", type="annuity",
diff --git a/man/InsuranceContract.ParameterDefaults.Rd b/man/InsuranceContract.ParameterDefaults.Rd
index e8d20f959ea4974c4f5bf95089bb9acbf7c02cd0..ab8291f3fbbce36bf6e94cdad0cfe1402cdd780a 100644
--- a/man/InsuranceContract.ParameterDefaults.Rd
+++ b/man/InsuranceContract.ParameterDefaults.Rd
@@ -7,7 +7,241 @@
pre-filled with these values, and values passed in the constructor (or with
other setter functions) will override these values.}
\format{
-An object of class \code{list} of length 8.
+The parameter list is a list of lists with the following structure:
+
+Sublists:
+\itemize{
+\item \code{$ContractData} ... Contract-specific data (policy period,
+closing, age, sum insured, premium payments, etc.)
+\item \code{$ContractState} ... Current contract state (paid-up, surrender
+penalty already applied, alpha costs already (partially) refunded)
+\item \code{$ActuarialBases} ... Actuarial bases for the contract
+calculation (mortality/invalidity table, guaranteed interest,
+surrender penalty, etc.)
+\item \code{$Costs} ... Expenses charged to the contract (see \code{\link[=initializeCosts]{initializeCosts()}})
+\item \code{$Loadings} ... Loadings, rebates and other charges of the
+tariff / contract (tax, unit costs, surcharge for no medial exam, premium/benefit frequency loading)
+\item \code{$Features} ... Peculiarities of the tariff (to enable
+non-standard formulas for certain company-specific historical
+"glitches" in the tariff definitions.)
+\item \code{$ProfitParticipation} ... Profit scheme and profit participation
+rates (default values, can be overwritten per profit scenario)
+\item \code{$Hooks} ... Hook functions to allow modification of various
+calculation aspects (e.g. modify the default cash flows after
+their setup)
+}
+\subsection{Elements of sublist \code{InsuranceContract.ParameterDefault$ContractData}}{
+
+These values are typically set per contract and not by the tariff. Notable
+exceptions are the contract duration in some instances and the premiumPeriod=1
+for single-premium contracts.
+
+\describe{
+\item{\code{$id}}{ID of the contract (to distinguish individual parts in
+contracts with multiple parts, e.g. dynamic increases),
+default = "Hauptvertrag"}
+\item{\code{$sumInsured}}{Sum insured, default = 100,000}
+\item{\code{$YOB}}{Year of birth of the insured, used to determine the
+age for the application of the mortality table},
+\item{\code{$age}}{Age of the insured}
+\item{\code{$technicalAge}}{Technical age of the insured (when the age
+for the application of the mortality table does not coincide
+with the real age)}
+\item{\code{$ageDifferences}}{Vector of age differences to the first
+insured for contracts with multiple insured (i.e. joint-lives)}
+\item{\code{$sex}}{Sex of the insured, to allow gender-specific prixing
+(e.g. different mortalities or age modification), default="unisex",
+Type is \link{SexSingleEnum}}
+\item{\code{$policyPeriod}}{Policy Duration (in years)}
+\item{\code{$premiumPeriod}}{Premium payment period (in year), for
+single-premium contracts, \code{premiumPeriod = 1}. Default is
+\code{policyPeriod}, i.e. regular premiums during the whole
+contract period}
+\item{\code{$deferralPeriod}}{deferral period for annuities, i.e. the
+period survival payments start only after this period, typically
+the retirement age. This applies mostly to tariffs of type
+annuity, although deferral periods are possible (but not common)
+for all other types of insurance, too.}
+\item{\code{$guaranteedPeriod}}{guaranteed annuity payment period. The
+annuity pays out for this period, even if the insured dies.
+This applies only to tariffs of type annuity.}
+\item{\code{$contractClosing}}{The date (variable of type \link{Date}) when
+the coverage of the contract starts (not neccessarily equal to
+the date when the contract was signed). Typically generated by
+a call to \code{\link[=as.Date]{as.Date()}}. The year is relevant to derive the age
+of the insured, while month and day are relevant for the
+interpolation of the balance sheet reserves}
+\item{\code{$blockStart}}{For contracts with multiple blocks (e.g.
+multiple dynamic increases, where each increase is modelled
+like a separate contract), this variable holds the offset of
+the current contract block relative to the main contract block.
+The main block starts a 0, dynamic increases start later! This
+value is only used by the parent block (i.e. $t=0$ of the child
+is aligned with $t=blockStart$ of the parent block.}
+\item{\code{$premiumPayments}}{Whether premiums are paid in advance
+(default) or arrears. Value is of type \link{PaymentTimeSingleEnum}
+with possible values "in advance" and 'in arrears"}
+\item{\code{$benefitPayments}}{Whether recurring benefits (e.g. annuities)
+are paid in advance (default) or arrears. Value is of type
+\link{PaymentTimeSingleEnum} with possible values "in advance" and
+"in arrears"}
+\item{\code{$premiumFrequency}}{Number of premium payments per year, default is 1.}
+\item{\code{$benefitFrequency}}{Number of benefit payments per year, default is 1.}\preformatted{\\item\{\code{$widowProportion}\}\{For annuities with a widow transition,
+ this describes the factor of the widow benefits relative to
+ the original benefit.\}
+\\item\{\code{$deathBenefitProportion}\}\{For endowments with a death and
+ survival benefit, this describes the proportion of the death
+ benefit relative to the survival benefit.\}
+\\item\{\code{$premiumRefund}\}\{Proportion of (gross) premiums refunded on
+ death (including additional risk, e.g. 1.10 = 110\% of paid premiums)\}
+\\item\{\code{$premiumIncrease}\}\{The yearly growth factor of the premium,
+ i.e. 1.05 means +5\% increase each year; a vector describes the
+ premiums for all years\}
+\\item\{\code{$annuityIncrease}\}\{The yearly growth factor of the annuity
+ payments, i.e. 1.05 means +5\% increase each year; a vector
+ describes the annuity unit payments for all years\}
+\\item\{\code{$deathBenefit}\}\{The yearly relative death benefit (relative
+ to the initial sum insured); Can be set to a \code{function(len,
+ params, values)}, e.g. \code{deathBenefit = deathBenefit.linearDecreasing}\}
+}
+
+}
+}
+
+\subsection{Elements of sublist \code{InsuranceContract.ParameterDefault$ContractState}}{
+
+Contract-specific status variables holding the status of the contract.
+
+\describe{
+\item{\code{$premiumWaiver}}{Whether the contract is paid-up.}
+\item{\code{$surrenderPenalty}}{Whether a surrender penalty still applies
+(e.g. because it has already been applied during a contract change,
+or because due to legal reasons it can no longer be applied)}
+\item{\code{$alphaRefunded}}{Whether alpha costs have (at least partially)
+been refunded (e.g. when a contract is changed or paid-up). Default
+is not yet refunded.}
+}
+}
+
+\subsection{Elements of sublist \code{InsuranceContract.ParameterDefault$ActuarialBases}}{
+
+Tarif-specific actuarial calculation parameters of the contract. Typically,
+these values are set by the tariff, but can be overridden by contract (e.g.
+while prototyping a new product or a product change).
+
+\describe{
+\item{\code{$mortalityTable}}{The \link{mortalityTable} object describing the
+mortality of the insured}
+\item{\code{$invalidityTable}}{For contracts with invalidity benefits,
+the \link{mortalityTable} object describing the probabilities of
+invalidity}
+\item{\code{$invalidityEndsContract}}{For contracts with invalidity
+benefits, whether a payment of an invalidity benefit ends the
+contract.}
+\item{\code{$i}}{Guaranteed yearly interest rate, default is 0.00, i.e. 0\%}
+\item{\code{$balanceSheetDate}}{The day/month when balance sheet reserves
+are calculated. Value of type \link{Date}, typically generated with
+\code{\link[=as.Date]{as.Date()}}. The year is actually irrelevant, only the day and
+month are relevant.}
+\item{\code{$balanceSheetMethod}}{How to interpolate the balance sheet
+reserves (at the balandeSheetDate) from the yearly contractual
+reserves.}
+\item{\code{$surrenderValueCalculation}}{A function describing the surrender
+value calculation.}
+\item{\code{$premiumFrequencyOrder}}{Order of the approximation for
+payments within the year (unless an extra frequency loading is
+used => then leave this at 0)}
+\item{\code{$benefitFrequencyOrder}}{Order of the approximation for
+payments within the year (unless an extra frequency loading is
+used => then leave this at 0)}
+}
+}
+
+\subsection{Elements of sublist \code{InsuranceContract.ParameterDefault$Costs}}{
+
+Definition of contractual costs charged to the contract. See \code{\link[=initializeCosts]{initializeCosts()}}.
+}
+
+\subsection{Elements of sublist \code{InsuranceContract.ParameterDefault$Loadings}}{
+
+\describe{
+\item{\code{$ongoingAlphaGrossPremium}}{Acquisition cost that increase the gross premium}
+\item{\code{$tax}}{insurance tax, factor on each premium paid, default is 4\%, i.e. \code{i=0.04}}
+\item{\code{$unitcosts}}{Annual unit cost for each policy, absolute value (can be a function)}
+\item{\code{$security}}{Additional security loading on all benefit payments, factor on all benefits}
+\item{\code{$noMedicalExam}}{Loading when no medicial exam is done, \% of SumInsured}
+\item{\code{$noMedicalExamRelative}}{Loading when no medicial exam is done, \% of gross premium}
+\item{\code{$sumRebate}}{gross premium reduction for large premiums, \% of SumInsured}
+\item{\code{$extraRebate}}{gross premium reduction for any reason, \% of SumInsured}
+\item{\code{$premiumRebate}}{gross premium reduction for large premiums, \% of gross premium}
+\item{\code{$partnerRebate}}{Rebate on premium with all surcharges and
+rebates when more than one contract is written with identical
+parameters. Sums with advanceBonusInclUnitCost and premiumRebate.}
+\item{\code{$extraChargeGrossPremium}}{extra charges on gross premium
+(smoker, leisure activities, BMI too high, etc.)}
+\item{\code{$benefitFrequencyLoading}}{Loading on the benefit for premium
+payment frequencies of more than once a year. Format is
+\code{list("1" = 0.0, "2" = 0.0, "4" = 0.0, "12" = 0.0)}}
+\item{\code{$premiumFrequencyLoading}}{Loading on the premium for premium
+payment frequencies of more than once a year. Format is
+\code{list("1" = 0.0, "2" = 0.0, "4" = 0.0, "12" = 0.0)}}
+}
+}
+
+\subsection{Elements of sublist \code{InsuranceContract.ParameterDefault$Features}}{
+
+\describe{
+\item{\code{$betaGammaInZillmer}}{Whether beta and gamma-costs should be
+included in the Zillmer premium calculation}
+\item{\code{$alphaRefundLinear}}{Whether the refund of alpha-costs on
+surrender is linear in t or follows the NPV of an annuity}
+}
+}
+
+\subsection{Elements of sublist \code{InsuranceContract.ParameterDefault$ProfitParticipation}}{
+
+Parameters describing the profit participation (instance of \link{ProfitParticipation})
+Most element descrive some kind of profit rate (which can vary in time),
+while the bases, on which they are applied is defined in the profit scheme.
+
+\describe{
+\item{\code{$advanceProfitParticipation}}{Advance profit participation
+rate (percentage rebate of the gross premium)}
+\item{\code{$advanceProfitParticipationInclUnitCost}}{Advance profit
+participation rate (percentage rebate on the gross premium after all surcharges and unit costs.}\preformatted{\\item\{\code{$waitingPeriod}\}\{Waiting period of the profit sharing (e.g.
+ no profit in the first two years of a contract, or similar)\}
+\\item\{\code{$guaranteedInterest}\}\{Individual contract-specific overrides
+ of the guaranteed interest rate (i.e. not keyed by year)\}
+\\item\{\code{$interestProfitRate}\}\{Interest profit rate (guaranteed interest
+ rate + interest profit rate = total credited rate)\}
+\\item\{\code{$totalInterest}\}\{Total credited rate (guarantee + interest profit)\}
+\\item\{\code{$mortalityProfitRate}\}\{Mortality Profit rate\}
+\\item\{\code{$expenseProfitRate}\}\{Expense profit rate\}
+\\item\{\code{$sumProfitRate}\}\{Sum profit rate (for high sumInsured)\}
+\\item\{\code{$terminalBonusRate}\}\{Terminal bonus rate (non-terminal-bonus
+ fund, but "old" Austrian terminal bonus)\}
+\\item\{\code{$terminalBonusFundRate}\}\{Terminal bonus fund rate\}
+\\item\{\code{$profitParticipationScheme}\}\{Profit participation scheme (object of class [ProfitParticipation])\}
+\\item\{\code{$profitComponents}\}\{Profit components of the profit scheme. List containing one or more of \code{c("interest", "risk", "expense", "sum", "terminal")}\}
+\\item\{\code{$profitClass}\}\{String describing the profit class the tariff
+ is assigned to. Profit classes are used to bundle similar
+ contracts (e.g. following similar risks) together. Profit
+ participation rates are defined at the level of profit classes.\}
+\\item\{\code{$profitRates}\}\{General, company-wide profit rates, key columns are year and profitClass\}
+
+\\item\{\code{$scenarios}\}\{profit participation scenarios (list of overridden parameters for each scenario)\}
+}
+
+}
+}
+
+\subsection{Elements of sublist \code{InsuranceContract.ParameterDefault$Hooks}}{
+
+\describe{
+\item{\code{$adjustCashFlows}}{Function with signature \code{function(x, params, values, ...)} to adjust the benefit/premium cash flows after their setup.}
+\item{\code{$adjustCashFlowsCosts}}{Function with signature \code{function(x, params, values, ...)} to adjust the costs cash flows after their setup.}
+}
+}
}
\usage{
InsuranceContract.ParameterDefaults
diff --git a/man/InsuranceTarif.Rd b/man/InsuranceTarif.Rd
index ddf32c1de25818cf800c081da9b08dd6acc92ad6..1974ef3ec8732915feef12d0226d5bc7bb02295d 100644
--- a/man/InsuranceTarif.Rd
+++ b/man/InsuranceTarif.Rd
@@ -19,9 +19,9 @@ 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 \link{InsuranceTarif@initialize} and the cloning method
-\link{InsuranceTarif$createModification}. All other methods should never be called
+The only methods that are typically used for defining an insurance tariff are
+the constructor \code{\link[=InsuranceTarif$new]{InsuranceTarif$new()}} and the cloning method
+\code{\link[=InsuranceTarif$createModification]{InsuranceTarif$createModification()}}. All other methods should never be called
manually.
However, as overriding private methods is not possible in an R6 class, all the
@@ -189,13 +189,13 @@ 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 \link{tariffType}}
+\item{\code{type}}{An enum specifying the main characteristics of the tarif. See \link{TariffTypeEnum}}
-\item{\code{tarif}}{The tariff's public name. See \link{InsuranceTarif@tarif}}
+\item{\code{tarif}}{The tariff's public name. See \link{InsuranceTarif$tarif}}
-\item{\code{desc}}{A short human-readable description. See \link{InsuranceTarif@desc}}
+\item{\code{desc}}{A short human-readable description. See \link{InsuranceTarif$desc}}
-\item{\code{...}}{Parameters for the \link{InsuranceContract.ParametersStructure},
+\item{\code{...}}{Parameters for the \link{InsuranceContract.Parameterstructure},
defining the characteristics of the tariff.}
}
\if{html}{\out{</div>}}
@@ -262,9 +262,9 @@ 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 \link{InsuranceTarif@tarif}}
+\item{\code{tarif}}{The tariff's public name. See \link{InsuranceTarif$tarif}}
-\item{\code{desc}}{A short human-readable description. See \link{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 \link{tariffType}}
@@ -276,7 +276,7 @@ defining the characteristics of the tariff.}
}
\subsection{Details}{
This method \code{createModification} returns a copy of the tariff
-with all given arguments changed in the tariff's \link{InsuranceTarif@Parametrers}
+with all given arguments changed in the tariff's \link{InsuranceTarif$Parameters}
parameter list.
As InsuranceTarif is a R6 class with reference logic, simply assigning
@@ -540,7 +540,7 @@ Not to be called directly, but implicitly by the \link{InsuranceContract} object
\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 \link{InsuranceContract@tariffType} field
+of insurance given in the \link{InsuranceTarif$tariffType} field
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{InsuranceTarif$getBasicCashFlows(params, values)}\if{html}{\out{</div>}}
}
@@ -628,7 +628,7 @@ Returns the present values of the cash flows of the contract
\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
-\item{\code{cashFlows}}{data.frame of cash flows calculated by a call to \code{\link[=InsuranceTarif@getCashFlows]{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
@@ -649,7 +649,7 @@ Not to be called directly, but implicitly by the \link{InsuranceContract} object
\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 \code{\link[=InsuranceTarif@getCashFlowsCosts]{InsuranceTarif@getCashFlowsCosts()}}
+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>}}
diff --git a/man/ProfitParticipation.Rd b/man/ProfitParticipation.Rd
index 5a0a7891b4c2dd2aa037d093ba73197d56415317..ba5108b1d92fdca782a71f4d4f4e829517829313 100644
--- a/man/ProfitParticipation.Rd
+++ b/man/ProfitParticipation.Rd
@@ -28,11 +28,11 @@ 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
+of the \link{ProfitParticipation$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}
+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
@@ -124,7 +124,7 @@ Create a new profit participation scheme
\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}}
+\link{ProfitParticipation$Parameters} or calculation functions to be stored in \link{ProfitParticipation$Functions}}
}
\if{html}{\out{</div>}}
}
diff --git a/man/TariffTypeSingleEnum-class.Rd b/man/TariffTypeSingleEnum-class.Rd
new file mode 100644
index 0000000000000000000000000000000000000000..a5064195d53b84db6a8bd7a631a157a5256d9d66
--- /dev/null
+++ b/man/TariffTypeSingleEnum-class.Rd
@@ -0,0 +1,56 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/InsuranceTarif.R
+\docType{class}
+\name{TariffTypeSingleEnum-class}
+\alias{TariffTypeSingleEnum-class}
+\alias{TariffTypeEnum}
+\title{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.}
+}}
+\description{
+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.}
+}
+}
diff --git a/man/deathBenefit.annuityDecreasing.Rd b/man/deathBenefit.annuityDecreasing.Rd
index 672ca578c8612194a108411ec28e9474b042aae2..8eb7ac1b9e66ba91107409c88380272118fd9ab2 100644
--- a/man/deathBenefit.annuityDecreasing.Rd
+++ b/man/deathBenefit.annuityDecreasing.Rd
@@ -7,18 +7,25 @@
deathBenefit.annuityDecreasing(interest)
}
\arguments{
+\item{interest}{The interest rate of the loan, which is underlying the insurance.}
+}
+\description{
+The death benefit will be the full sumInsured for the first year after the
+deferral period and then decrease like an annuity to 0 at the end of the policyPeriod.
+This can be used with the \code{deathBenefit} parameter for insurance
+contracts, but should not be called directly.
+}
+\details{
+This function is a mere generator function, which takes the interest rate and
+generates a function that describes a decreasing annuity.
+
+The generated function has the following parameters:
+\describe{
\item{len}{The desired length of the Cash flow vector (can be shorter than
the policyPeriod, if q_x=1 before the end of the contract, e.g.
for life-long insurances)}
-
\item{params}{The full parameter set of the insurance contract (including
all inherited values from the tariff and the profit participation)}
-
\item{values}{The values calculated from the insurance contract so far}
}
-\description{
-The death benefit will be the full sumInsured for the first year after the
-deferral period and then decrease like an annuity to 0 at the end of the policyPeriod.
-This can be used with the \code{deathBenefit} parameter for insurance
-contracts, but should not be called directly.
}
diff --git a/man/exportInsuranceContract.xlsx.Rd b/man/exportInsuranceContract.xlsx.Rd
index 7c27311b3ce11d5cd237217101759456fb569a54..59c9177fa391eae989fe76e9a65d5e156e7d435b 100644
--- a/man/exportInsuranceContract.xlsx.Rd
+++ b/man/exportInsuranceContract.xlsx.Rd
@@ -28,7 +28,7 @@ stored in \code{contract$Values}.
library("MortalityTables")
mortalityTables.load("Austria_Annuities_AVOe2005R")
# A trivial deferred annuity tariff with no costs:
-tariff = InsuranceTarif$new(name="Test Annuity", type="annuity",
+tariff = InsuranceTarif$new(name = "Test Annuity", type = "annuity", tarif = "Annuity 1A",
mortalityTable = AVOe2005R.unisex, i=0.01)
contract = InsuranceContract$new(
tariff,
diff --git a/man/exportInsuranceContractExample.Rd b/man/exportInsuranceContractExample.Rd
index e27dbf9fa20253b32263cf4fc6bdbf438f467441..237a83c9d0dedebd5070be0b7758cf599df3a756 100644
--- a/man/exportInsuranceContractExample.Rd
+++ b/man/exportInsuranceContractExample.Rd
@@ -20,6 +20,16 @@ exportInsuranceContractExample(
\item{outdir}{The output directory (the file names are not configurable)}
+\item{basename}{The base output filename (sans .xlsx). If missing, a name of
+the form 2020-08-01_TARIFNAME_EXTRANAME_RZ0.01_x35_YoB1977_LZ45_PrZ20_VS100000
+is used. If given, the main contract without modification will be
+exported to basename.xlsx, while the example with premium waiver will be
+exported to basename_PremiumWaiver_t10.xlsx and the text file containing
+the examples required by the LV-VMGV is exported to basename_VmGlg.txt.}
+
+\item{extraname}{If basename is not given, this allows a suffix to distinguish
+multiple exports.}
+
\item{...}{Further parameters (passed on to \code{\link{showVmGlgExamples}})}
}
\description{
@@ -30,10 +40,10 @@ required by the Austrian regulation).
\details{
Three output files are generated:
\itemize{
-\item \link{DATE}_\link{TARIFF}_Example.xlsx: Full history/timeseries
-\item \link{DATE}_\link{TARIFF}_Example_PremiumWaiver_t10.xlsx: Full history/timeseries
+\item {DATE}_{TARIFF}_Example.xlsx: Full history/timeseries
+\item {DATE}_{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
+\item {DATE}_{TARIFF}_Examples_VmGlg.txt: Example calculation required for the
Austrian regulation (LV-VMGLV)
}
}
@@ -41,7 +51,7 @@ Austrian regulation (LV-VMGLV)
library("MortalityTables")
mortalityTables.load("Austria_Annuities_AVOe2005R")
# A trivial deferred annuity tariff with no costs:
-tariff = InsuranceTarif$new(name="Test Annuity", type="annuity",
+tariff = InsuranceTarif$new(name="Test Annuity", type="annuity", tarif = "Annuity 1A",
mortalityTable = AVOe2005R.unisex, i=0.01)
contract = InsuranceContract$new(
tariff,
diff --git a/man/fillNAgaps.Rd b/man/fillNAgaps.Rd
index 390aae417a08b6b8172aee39582467eb9a61a217..c330f85cc0d4019be8163f8461239a29ae952dfb 100644
--- a/man/fillNAgaps.Rd
+++ b/man/fillNAgaps.Rd
@@ -2,15 +2,27 @@
% Please edit documentation in R/HelperFunctions.R
\name{fillNAgaps}
\alias{fillNAgaps}
-\title{Taken from the R Cookbook:
-http://www.cookbook-r.com/Manipulating_data/Filling_in_NAs_with_last_non-NA_value/
-LICENSE (from that page): The R code is freely available for use without any restrictions.
-In other words: you may reuse the R code for any purpose (and under any license).}
+\title{Replace all \code{NA} entries of a vector with the previous non-NA value}
\usage{
fillNAgaps(x, firstBack = FALSE)
}
+\arguments{
+\item{x}{The vector where NA-values should be filled by repeating the last preceeding non-NA value}
+
+\item{firstBack}{if \code{TRUE}, leading NAs are replaced by the first non-NA
+value in the vector, otherwise leading NAs are left untouched.}
+}
\description{
-Taken from the R Cookbook:
+Sometimes one has a vector with some gaps (\code{NA}) values, which cause
+problems for several numeric functions. This function \code{fillNAgaps} fills
+these missing values by inserting the last preceeding non-NA-value. Leading
+NA values (at the start of the vector will not be modified). If the
+argument \code{firstBack = TRUE}, leading \code{NA}-values are replaced by
+the first non-NA value.
+Trailing NAs are always replaced by the last previous NA-value.
+}
+\details{
+This code was taken from the R Cookbook:
http://www.cookbook-r.com/Manipulating_data/Filling_in_NAs_with_last_non-NA_value/
LICENSE (from that page): The R code is freely available for use without any restrictions.
In other words: you may reuse the R code for any purpose (and under any license).
diff --git a/man/head0.Rd b/man/head0.Rd
index 815b9c94f353b1429fdb26b776b28d260bea3e6f..7f4b9aca8a8c4b250a5102e9acff3a9bc4c61531 100644
--- a/man/head0.Rd
+++ b/man/head0.Rd
@@ -6,6 +6,17 @@
\usage{
head0(v, start = 0)
}
+\arguments{
+\item{v}{the vector to modify}
+
+\item{start}{how many leading elements to zero out}
+}
+\value{
+the vector \code{v} with the first \code{start} elements replaced by 0.
+}
\description{
Set all entries of the given vector to 0 up until index 'start'
}
+\examples{
+head0(1:10, 3)
+}
diff --git a/man/initializeCosts.Rd b/man/initializeCosts.Rd
index 72b3b546c57d4965594d9c4c19f80ca0caf30b72..12af0c2ef88c188b33d49f218872e090773fdcf1 100644
--- a/man/initializeCosts.Rd
+++ b/man/initializeCosts.Rd
@@ -44,7 +44,7 @@ Initialize a cost matrix with dimensions: {CostType, Basis, Period}, where:
}
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.
+\link{InsuranceTarif} definitions.
}
\examples{
# empty cost structure (only 0 costs)
diff --git a/man/makeContractGridDimname.Rd b/man/makeContractGridDimname.Rd
index 531630030010e12572b2fde6df58fb1e09069856..92c729e96bdb58a974b2d53db7d0cb2d51f0b5ec 100644
--- a/man/makeContractGridDimname.Rd
+++ b/man/makeContractGridDimname.Rd
@@ -2,7 +2,7 @@
% 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}}
+\title{Generate a dimension label for the object passed as \code{value}, to be used in \link{contractGrid}}
\usage{
makeContractGridDimname(value)
}
@@ -10,5 +10,5 @@ makeContractGridDimname(value)
\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}
+Generate a dimension label for the object passed as \code{value}, to be used in \link{contractGrid}
}
diff --git a/man/pad0.Rd b/man/pad0.Rd
new file mode 100644
index 0000000000000000000000000000000000000000..522ed6ecf9984df44d4e6fb30ea6af62acc97cbe
--- /dev/null
+++ b/man/pad0.Rd
@@ -0,0 +1,36 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/HelperFunctions.R
+\name{pad0}
+\alias{pad0}
+\title{Pad a vector with 0 to a desired length}
+\usage{
+pad0(v, l, value = 0, start = 0)
+}
+\arguments{
+\item{v}{the vector to pad with 0}
+
+\item{l}{the desired (resulting) length of the vector}
+
+\item{value}{the value to pad with (if padding is needed). Default to 0, but
+can be overridden to pad with any other value.}
+
+\item{start}{the first \code{start} values are always set to 0 (default is 0),
+the vector \code{v} starts only after these leading zeroes. The number of
+leading zeroes counts towards the desired length}
+}
+\value{
+returns the vector \code{v} padded to length \code{l} with value \code{value} (default 0).
+}
+\description{
+Pad a vector with 0 to a desired length
+}
+\examples{
+pad0(1:5, 7) # Pad to length 7 with zeroes
+pad0(1:5, 3) # no padding, but cut at length 3
+
+# 3 leading zeroes, then the vector start (10 elements of vector, no additional padding needed):
+pad0(1:10, 13, start = 3)
+
+# padding with value other than zero:
+pad0(1:5, 7, value = "pad")
+}
diff --git a/man/padLast.Rd b/man/padLast.Rd
new file mode 100644
index 0000000000000000000000000000000000000000..6d9d7b81bade3455839850320bfd67cb64c69f81
--- /dev/null
+++ b/man/padLast.Rd
@@ -0,0 +1,26 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/HelperFunctions.R
+\name{padLast}
+\alias{padLast}
+\title{Pad the vector \code{v} to length \code{l} by repeating the last entry of the
+vector.}
+\usage{
+padLast(v, l, start = 0)
+}
+\arguments{
+\item{v}{the vector to pad by repeating the last element}
+
+\item{l}{the desired (resulting) length of the vector}
+
+\item{start}{the first \code{start} values are always set to 0 (default is 0),
+the vector \code{v} starts only after these leading zeroes. The number of
+leading zeroes counts towards the desired length}
+}
+\description{
+This function callc \code{\link[=pad0]{pad0()}} with the last element of the vector as padding value
+}
+\examples{
+padLast(1:5, 7) # 5 is repeated twice
+padLast(1:5, 3) # no padding needed
+
+}
diff --git a/man/showVmGlgExamples.Rd b/man/showVmGlgExamples.Rd
index 90bebf1deccd7877e6769bebc7268d57b17f60c9..b948d40a79d11e0e4e609f453a3e1b75c0ddd57a 100644
--- a/man/showVmGlgExamples.Rd
+++ b/man/showVmGlgExamples.Rd
@@ -25,6 +25,7 @@ as required by the Austrian regulation (LV-VMGLV, "LV
Versicherungsmathematische Grundlagen Verordnung").
}
\examples{
+library(MortalityTables)
mortalityTables.load("Austria_Annuities_AVOe2005R")
# A trivial deferred annuity tariff with no costs:
tariff = InsuranceTarif$new(name="Test Annuity", type="annuity",