LifeContingencies API Reference

Frasier()

The assumption of independent lives in a joint life calculation. Is a subtype of JointAssumption.

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

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

• lives is a tuple of two SingleLifes
• contingency default is LastSurvivor(). It is the trigger for contingent benefits. See ?Contingency.
• joint_assumption Default value is Frasier(). 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()
)

LastSurvivor()

The contingency whereupon benefits are payable upon both lives passing. Is a subtype of Contingency

struct LifeContingency
    life::Life

struct SingleLife
    mortality
    issue_age::Int
    alive::Bool
    fractional_assump::MortalityTables.DeathDistribution
end

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

• mortality pass a mortality vector, which is an array of applicable mortality rates indexed by attained age
• issue_age is the assumed issue age for the SingleLife and is the basis of many contingency calculations.
• alive Default value is true. Useful for joint insurances with different status on the lives insured.
• fractional_assump. Default value is Uniform(). This is a DeathDistribution from the MortalityTables.jl package 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          
)

discount(Insurance)

The discount vector for the given insurance.

To get the fully computed and allocated vector, call collect(discount(...)).

present_value(Insurance)

The actuarial present value of the given insurance benefits.

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

APV(lc::LifeContingency,to_time)

The actuarial present value which is the survival times the discount factor for the life contingency.

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

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

benefit(Insurance)

The unit benefit for the given insurance.

cashflows(Insurance)

The vector of decremented benefit cashflows for the given insurance.

To get the fully computed and allocated vector, call collect(cashflows(...)).

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

probability(Insurance)

The vector of contingent benefit probabilities for the given insurance.

To get the fully computed and allocated vector, call collect(probability(...)).

 reserve_premium_net(lc::LifeContingency,time)

The net premium reserve at the end of year time.

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

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

survival(Insurance)

The survivorship vector for the given insurance.

To get the fully computed and allocated vector, call collect(survival(...)).

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

```

survival(life)

Return a survival vector for the given life.

survival(Insurance,time)

The survivorship for the given insurance from time zero to time.

Contingency()

An abstract type representing the different triggers for contingent benefits. Available options to use include:

• LastSurvivor()

JointAssumption()

An abstract type representing the different assumed relationship between the survival of the lives on a JointLife. Available options to use include:

• Frasier()

C(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$).

D(lc::LifeContingency, to_time)

$D_x$ is a retrospective actuarial commutation function which is the product of the survival and discount factor.

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

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

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

decrement(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.44000000000000006