LifeContingencies API Reference
LifeContingencies.ContingencyLifeContingencies.FrasierLifeContingencies.InsuranceLifeContingencies.JointAssumptionLifeContingencies.JointLifeLifeContingencies.LastSurvivorLifeContingencies.LifeContingencyLifeContingencies.SingleLifeLifeContingencies.APVLifeContingencies.AnnuityDueLifeContingencies.AnnuityImmediateLifeContingencies.CLifeContingencies.DLifeContingencies.MLifeContingencies.NLifeContingencies.benefitLifeContingencies.cashflowsLifeContingencies.lLifeContingencies.premium_netLifeContingencies.probabilityLifeContingencies.reserve_premium_netLifeContingencies.timepoints
Exported API
LifeContingencies.Frasier — TypeFrasier()The assumption of independent lives in a joint life calculation. Is a subtype of JointAssumption.
LifeContingencies.Insurance — MethodInsurance(lc::LifeContingency, term)
+Insurance(life,interest, term)
+Insurance(lc::LifeContingency)
+Insurance(life,interest)Life insurance with a term period of term. If term is nothing, then whole life insurance.
Issue age is based on the issue_age in the LifeContingency lc.
Examples
ins = Insurance(
+ SingleLife(mortality = UltimateMortality([0.5,0.5]),issue_age = 0),
+ FinanceModels.Yield.Constant(0.05),
+ 1 # 1 year term
+) LifeContingencies.JointLife — Typestruct JointLife
+ lives
+ contingency
+ joint_assumption
+end
+
+A `Life` object containing the necessary assumptions for contingent maths related to a joint life insurance. Use with a `LifeContingency` to do many actuarial present value calculations.Keyword arguments:
livesis a tuple of twoSingleLifescontingencydefault isLastSurvivor(). It is the trigger for contingent benefits. See?Contingency.joint_assumptionDefault value isFrasier(). It is the assumed relationship between the mortality of the two lives. See?JointAssumption.
Examples
using MortalityTables
+mortality = MortalityTables.table("2001 VBT Residual Standard Select and Ultimate - Male Nonsmoker, ANB")
+
+l1 = SingleLife(
+ mortality = mortality.select[30],
+ issue_age = 30
+)
+l2 = SingleLife(
+ mortality = mortality.select[30],
+ issue_age = 30
+)
+
+jl = JointLife(
+ lives = (l1,l2),
+ contingency = LastSurvivor(),
+ joint_assumption = Frasier()
+)LifeContingencies.LastSurvivor — TypeLastSurvivor()The contingency whereupon benefits are payable upon both lives passing. Is a subtype of Contingency
LifeContingencies.LifeContingency — Typestruct LifeContingency
+ life::LifeLifeContingencies.SingleLife — Typestruct SingleLife
+ mortality
+ issue_age::Int
+ alive::Bool
+ fractional_assump::MortalityTables.DeathDistribution
+endA Life object containing the necessary assumptions for contingent maths related to a single life. Use with a LifeContingency to do many actuarial present value calculations.
Keyword arguments:
mortalitypass a mortality vector, which is an array of applicable mortality rates indexed by attained ageissue_ageis the assumed issue age for theSingleLifeand is the basis of many contingency calculations.aliveDefault value istrue. Useful for joint insurances with different status on the lives insured.fractional_assump. Default value isUniform(). This is aDeathDistributionfrom theMortalityTables.jlpackage and is the assumption to use for non-integer ages/times.
Examples
using MortalityTables
+mortality = MortalityTables.table("2001 VBT Residual Standard Select and Ultimate - Male Nonsmoker, ANB")
+
+SingleLife(
+ mort = mort.select[30],
+ issue_age = 30
+)FinanceCore.discount — Methoddiscount(Insurance)The discount vector for the given insurance.
To get the fully computed and allocated vector, call collect(discount(...)).
FinanceCore.present_value — Methodpresent_value(Insurance)The actuarial present value of the given insurance benefits.
FinanceCore.present_value — Methodpresent_value(Insurance,`time`)The actuarial present value of the given insurance benefits, as if you were standing at time.
For example, if the given Insurance has decremented payments [1,2,3,4,5] at times [1,2,3,4,5] and you call pv(ins,3), you will get the present value of the payments [4,5] at times [1,2].
To get an undecremented present value, divide by the survivorship to that timepoint:
present_value(ins,10) / survival(ins,10)LifeContingencies.APV — MethodAPV(lc::LifeContingency,to_time)The actuarial present value which is the survival times the discount factor for the life contingency.
LifeContingencies.AnnuityDue — MethodAnnuityDue(lc::LifeContingency; n=nothing, start_time=0; certain=nothing,frequency=1)
+AnnuityDue(life, interest; n=nothing, start_time=0; certain=nothing,frequency=1)Annuity due with the benefit period starting at start_time and ending after n periods with frequency payments per year of 1/frequency amount and a certain period with non-contingent payments.
Examples
ins = AnnuityDue(
+ SingleLife(mortality = UltimateMortality([0.5,0.5]),issue_age = 0),
+ FinanceModels.Yield.Constant(0.05),
+ 1, # term of policy
+) LifeContingencies.AnnuityImmediate — MethodAnnuityImmediate(lc::LifeContingency; term=nothing, start_time=0; certain=nothing,frequency=1)
+AnnuityImmediate(life, interest; term=nothing, start_time=0; certain=nothing,frequency=1)Annuity immediate with the benefit period starting at start_time and ending after term periods with frequency payments per year of 1/frequency amount and a certain period with non-contingent payments.
Examples
ins = AnnuityImmediate(
+ SingleLife(mortality = UltimateMortality([0.5,0.5]),issue_age = 0),
+ FinanceModels.Yield.Constant(0.05),
+ 1 # term of policy
+) LifeContingencies.benefit — Methodbenefit(Insurance)The unit benefit for the given insurance.
LifeContingencies.cashflows — Methodcashflows(Insurance)The vector of decremented benefit cashflows for the given insurance.
To get the fully computed and allocated vector, call collect(cashflows(...)).
LifeContingencies.premium_net — Methodpremium_net(lc::LifeContingency)
+premium_net(lc::LifeContingency,to_time)The net premium for a whole life insurance (without second argument) or a term life insurance through to_time.
The net premium is based on 1 unit of insurance with the death benfit payable at the end of the year and assuming annual net premiums.
LifeContingencies.probability — Methodprobability(Insurance)The vector of contingent benefit probabilities for the given insurance.
To get the fully computed and allocated vector, call collect(probability(...)).
LifeContingencies.reserve_premium_net — Method reserve_premium_net(lc::LifeContingency,time)The net premium reserve at the end of year time.
LifeContingencies.timepoints — Methodtimepoints(Insurance)The vector of times corresponding to the cashflow vector for the given insurance.
To get the fully computed and allocated vector, call collect(timepoints(...)).
MortalityTables.omega — Methodomega(lc::LifeContingency)
+omega(l::Life)
+omega(i::InterestRate)Lifes and LifeContingencys
Returns the last defined timeperiod for both the interest rate and mortality table. Note that this is different than calling omega on a MortalityTable, which will give you the last `attainedage`.
Example: if the LifeContingency has issue age 60, and the last defined attained age for the MortalityTable is 100, then omega of the MortalityTable will be 100 and omega of the LifeContingency will be 40.
InterestRates
The last period that the interest rate is defined for. Assumed to be infinite (Inf) for functional and constant interest rate types. Returns the lastindex of the vector if a vector type.
MortalityTables.survival — Methodsurvival(Insurance)The survivorship vector for the given insurance.
To get the fully computed and allocated vector, call collect(survival(...)).
MortalityTables.survival — Methodsurvival(lc::LifeContingency,from_time,to_time)
+survival(lc::LifeContingency,to_time)Return the probability of survival for the given LifeContingency, with decrements beginning at time zero.
Examples
```julia-repl julia> q = [.1,.2,.3,.4];
julia> l = SingleLife(mortality=q);
julia> survival(l,1) 0.9
julia> decrement(l,1) 0.09999999999999998
julia> survival(l,1,2) 0.8
julia> decrement(l,1,2) 0.19999999999999996
julia> survival(l,1,3) 0.5599999999999999
julia> decrement(l,1,3) 0.44000000000000006
```MortalityTables.survival — Methodsurvival(life)Return a survival vector for the given life.
MortalityTables.survival — Methodsurvival(Insurance,time)The survivorship for the given insurance from time zero to time.
Unexported API
LifeContingencies.Contingency — TypeContingency()An abstract type representing the different triggers for contingent benefits. Available options to use include:
LastSurvivor()
LifeContingencies.JointAssumption — TypeJointAssumption()An abstract type representing the different assumed relationship between the survival of the lives on a JointLife. Available options to use include:
Frasier()
LifeContingencies.C — MethodC(lc::LifeContingency, to_time)$C_x$ is a retrospective actuarial commutation function which is the product of the discount factor and the difference in l ($l_x$).
LifeContingencies.D — MethodD(lc::LifeContingency, to_time)$D_x$ is a retrospective actuarial commutation function which is the product of the survival and discount factor.
LifeContingencies.M — MethodM(lc::LifeContingency, from_time)The $M_x$ actuarial commutation function where the from_time argument is x. Issue age is based on the issue_age in the LifeContingency lc.
LifeContingencies.N — MethodN(lc::LifeContingency, from_time)$N_x$ is a prospective actuarial commutation function which is the sum of the D ($D_x$) values from the given time to the end of the mortality table.
LifeContingencies.l — Methodl(lc::LifeContingency, to_time)$l_x$ is a retrospective actuarial commutation function which is the survival up to a certain point in time. By default, will have a unitary basis (ie 1.0), but you can specify basis keyword argument to use something different (e.g. 1000 is common in the literature.)
MortalityTables.decrement — Methoddecrement(lc::LifeContingency,to_time)
+decrement(lc::LifeContingency,from_time,to_time)Return the probability of death for the given LifeContingency, with decrements beginning at time zero.
Examples
julia> q = [.1,.2,.3,.4];
+
+julia> l = SingleLife(mortality=q);
+
+julia> survival(l,1)
+0.9
+
+julia> decrement(l,1)
+0.09999999999999998
+
+julia> survival(l,1,2)
+0.8
+
+julia> decrement(l,1,2)
+0.19999999999999996
+
+julia> survival(l,1,3)
+0.5599999999999999
+
+julia> decrement(l,1,3)
+0.44000000000000006Please open an issue if you encounter any issues or confusion with the package.
