# LifeContingencies API Reference

`LifeContingencies.Contingency`

`LifeContingencies.Frasier`

`LifeContingencies.Insurance`

`LifeContingencies.JointAssumption`

`LifeContingencies.JointLife`

`LifeContingencies.LastSurvivor`

`LifeContingencies.LifeContingency`

`LifeContingencies.SingleLife`

`LifeContingencies.APV`

`LifeContingencies.AnnuityDue`

`LifeContingencies.AnnuityImmediate`

`LifeContingencies.C`

`LifeContingencies.D`

`LifeContingencies.M`

`LifeContingencies.N`

`LifeContingencies.benefit`

`LifeContingencies.cashflows`

`LifeContingencies.l`

`LifeContingencies.premium_net`

`LifeContingencies.probability`

`LifeContingencies.reserve_premium_net`

`LifeContingencies.timepoints`

## Exported API

`LifeContingencies.Frasier`

— Type`Frasier()`

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

.

`LifeContingencies.Insurance`

— Method```
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
)
```

`LifeContingencies.JointLife`

— Type```
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`SingleLife`

s`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()
)
```

`LifeContingencies.LastSurvivor`

— Type`LastSurvivor()`

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

`LifeContingencies.LifeContingency`

— Type```
struct LifeContingency
life::Life
```

`LifeContingencies.SingleLife`

— Type```
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
)
```

`FinanceCore.discount`

— Method`discount(Insurance)`

The discount vector for the given insurance.

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

.

`FinanceCore.present_value`

— Method`present_value(Insurance)`

The actuarial present value of the given insurance benefits.

`FinanceCore.present_value`

— Method`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)`

`LifeContingencies.APV`

— Method`APV(lc::LifeContingency,to_time)`

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

`LifeContingencies.AnnuityDue`

— Method```
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
)
```

`LifeContingencies.AnnuityImmediate`

— Method```
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
)
```

`LifeContingencies.benefit`

— Method`benefit(Insurance)`

The unit benefit for the given insurance.

`LifeContingencies.cashflows`

— Method`cashflows(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`

— Method```
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.

`LifeContingencies.probability`

— Method`probability(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`

— Method`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(...))`

.

`MortalityTables.omega`

— Method```
omega(lc::LifeContingency)
omega(l::Life)
omega(i::InterestRate)
```

`Life`

s and `LifeContingency`

s

Returns the last defined time*period 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 `attained*age`.

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`

.

`InterestRate`

s

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`

— Method`survival(Insurance)`

The survivorship vector for the given insurance.

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

.

`MortalityTables.survival`

— Method```
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

`````

`MortalityTables.survival`

— Method`survival(life)`

Return a survival vector for the given life.

`MortalityTables.survival`

— Method`survival(Insurance,time)`

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

.

## Unexported API

`LifeContingencies.Contingency`

— Type`Contingency()`

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

`LastSurvivor()`

`LifeContingencies.JointAssumption`

— Type`JointAssumption()`

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`

— Method`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$).

`LifeContingencies.D`

— Method`D(lc::LifeContingency, to_time)`

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

`LifeContingencies.M`

— Method`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`

.

`LifeContingencies.N`

— Method`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.

`LifeContingencies.l`

— Method`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.)

`MortalityTables.decrement`

— Method```
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
```

Please open an issue if you encounter any issues or confusion with the package.