Reference

Balducci()

A DeathDistribution type that assumes a decreasing force of mortality over the year.

Beard(;a,b,k)

Construct a mortality model following Beard's law of mortality.

$\mathrm{hazard} \left( {\rm age} \right) = \frac{a \cdot e^{b \cdot {\rm age}}}{1 + k \cdot a \cdot e^{b \cdot {\rm age}}}$

Default args:

a = 0.002
b = 0.13
k = 1.

Constant()

A DeathDistribution type that assumes a constant force of mortality over the year.

DeathDistribution

An abstract type used to form an assumption of how deaths occur throughout a year. See Balducci(), Uniform(), and Constant() for concrete assumption types.

GammaGompertz(;a,b,γ)

Construct a mortality model following GammaGompertz law of mortality.

$\mathrm{hazard} \left( {\rm age} \right) = \frac{a \cdot e^{b \cdot {\rm age}}}{1 + \frac{a \cdot \gamma}{b} \cdot \left( e^{b \cdot {\rm age}} - 1 \right)}$

Default args:

a = 0.002
b = 0.13
γ = 1

HeligmanPollard(;a,b,c,d,e,f,g,h)

Construct a mortality model following HeligmanPollard law of mortality with 8 parameters.

$\mathrm{hazard} \left( {\rm age} \right) = a \cdot e^{\left( - b \right) \cdot {\rm age}} + c + d \cdot e^{e \cdot {\rm age}}$

Default args:

a = 0.0002
b = 0.13
c = 0.001
d = 0.001
e = 0.013

HeligmanPollard2(;a,b,c,d,e,f,g,h)

Construct a mortality model following HeligmanPollard (alternate) law of mortality with 8 parameters.

\[\begin{aligned} \mu_1 &= a^{\left( {\rm age} + b \right)^{c}} + \frac{g \cdot h^{{\rm age}}}{1 + g \cdot h^{{\rm age}}} \\ \mu_2 &= d \cdot e^{\left( - e \right) \cdot \left( \log\left( \frac{{\rm age}}{f} \right) \right)^{2}} \\ \mathrm{hazard}\left( {\rm age} \right) &= \begin{cases} \mu_1 & \text{if } \left( {\rm age} = 0 \right)\\ \mu_1 + \mu_2 & \text{otherwise} \end{cases} \end{aligned}\]

Default args:

a = .0005
b = .004
c = .08
d = .001
e = 10
f = 17
g = .00005
h = 1.1

HeligmanPollard3(;a,b,c,d,e,f,g,h,k)

Construct a mortality model following HeligmanPollard (alternate) law of mortality with 9 parameters.

\[\begin{aligned} \mu_1 &= a^{\left( {\rm age} + b \right)^{c}} + \frac{g \cdot h^{{\rm age}}}{1 + k \cdot g \cdot h^{{\rm age}}} \\ \mu_2 &= d \cdot e^{\left( - e \right) \cdot \left( \log\left( \frac{{\rm age}}{f} \right) \right)^{2}} \\ \mathrm{hazard}\left( {\rm age} \right) &= \begin{cases} \mu_1 & \text{if } \left( {\rm age} = 0 \right)\\ \mu_1 + \mu_2 & \text{otherwise} \end{cases} \end{aligned}\]

Default args:

a = .0005
b = .004
c = .08
d = .001
e = 10
f = 17
g = .00005
h = 1.1
k= 1.

HeligmanPollard4(;a,b,c,d,e,f,g,h,k)

Construct a mortality model following HeligmanPollard (alternate) law of mortality with 9 parameters.

\[\begin{aligned} \mu_1 &= a^{\left( {\rm age} + b \right)^{c}} + \frac{g \cdot h^{{\rm age}^{k}}}{1 + g \cdot h^{{\rm age}^{k}}} \\ \mu_2 &= d \cdot e^{\left( - e \right) \cdot \left( \log\left( \frac{{\rm age}}{f} \right) \right)^{2}} \\ \mathrm{hazard}\left( {\rm age} \right) &= \begin{cases} \mu_1 & \text{if } \left( {\rm age} = 0 \right)\\ \mu_1 + \mu_2 & \text{otherwise} \end{cases} \end{aligned}\]

Default args:

a = .0005
b = .004
c = .08
d = .001
e = 10
f = 17
g = .00005
h = 1.1
k= 1.

InverseGompertz(;a,b,c)

Construct a mortality model following InverseGompertz's law.

\[\begin{aligned} \mathrm{hazard} \left( {\rm age} \right) &= \frac{1}{\sigma}e^\frac{age-m}{\sigma}/e^{e^\frac{-(age-m)}{\sigma}-1}`` \\ \mathrm{survival} \left( {\rm age} \right) &= \frac{1 - e^{ - e^{\frac{ - \left( {\rm age} - m \right)}{\sigma}}}}{1 - e^{ - e^{\frac{m}{\sigma}}}}`` \end{aligned}\]

Default args:

m = 49
σ = 7.7

InverseWeibull(;m,σ)

Construct a mortality model following Weibull's law of mortality.

The Inverse-Weibull proves useful for modelling the childhood and teenage years, because the logarithm of h(x) is a concave function.

• m >0 is a measure of location
• σ >0 is measure of dispersion

\[\begin{aligned} \mathrm{hazard} \left( {\rm age} \right) &= \frac{\frac{1}{\sigma} \cdot \left( \frac{{\rm age}}{m} \right)^{\frac{ - m}{\sigma} - 1}}{e^{\left( \frac{{\rm age}}{m} \right)^{\frac{ - m}{\sigma}}} - 1} \\ \mathrm{cumhazard}\left( {\rm age} \right) &= - \log\left( 1 - e^{ - \left( \frac{{\rm age}}{m} \right)^{\frac{ - m}{\sigma}}} \right) \\ \mathrm{survival}\left( {\rm age} \right) &= e^{ - \mathrm{cumhazard}\left( m, {\rm age} \right)} \end{aligned}\]

Default args:

m = 5
σ = 10

Kannisto(;a,b)

Construct a mortality model following Kannisto's law of mortality.

\[\begin{aligned} \mathrm{hazard}\left( {\rm age} \right) &= \frac{a \cdot e^{b \cdot {\rm age}}}{1 + a \cdot e^{b \cdot {\rm age}}} \\ \mathrm{cumhazard}\left( {\rm age} \right) &= 1/a * log((1 + b*exp(b*age)) / (1 + a)) \\ \mathrm{survival}\left( {\rm age} \right) &= e^{ - \mathrm{cumhazard}\left( m, {\rm age} \right)} \end{aligned}\]

Default args:

a = 0.5
b = 0.13

KannistoMakeham(;a,b,c)

Construct a mortality model following KannistoMakeham's law of mortality.

$\mathrm{hazard}\left( {\rm age} \right) = \frac{a \cdot e^{b \cdot {\rm age}}}{1 + a \cdot e^{b \cdot {\rm age}}} + c$

Default args:

a = 0.5
b = 0.13
c = 0.001

Kostaki(;a,b,c,d,e1,e2,f,g,h)

Construct a mortality model following Kostaki's law of mortality. A nine-parameter adaptation of HeligmanPollard.

\[\begin{aligned} \mu_1 &= a^{\left( {\rm age} + b \right)^{c}} + g \cdot h^{{\rm age}} \\ \mu_2 &= \begin{cases} d \cdot e^{ - \left( e1 \cdot \log\left( \frac{{\rm age}}{f} \right) \right)^{2}} & \text{if } \left( {\rm age} \leq f \right)\\ d \cdot e^{ - \left( e2 \cdot \log\left( \frac{{\rm age}}{f} \right) \right)^{2}} & \text{otherwise} \end{cases} \\ \eta &= \begin{cases} \mu_1 & \text{if } \left( {\rm age} = 0 \right)\\ \mu_1 + \mu_2 & \text{otherwise} \end{cases} \\ \mathrm{hazard}\left( {\rm age} \right) &= \frac{\eta}{1 + \eta} \end{aligned}\]

Default args:

a = 0.0005
b = 0.01
c = 0.10
d = 0.001
e1 = 3.
e2 = 0.1
f = 25.
g = .00005
h = 1.1

Kostaki, A. (1992). A nine‐parameter version of the Heligman‐Pollard formula. Mathematical Population Studies, 3(4), 277–288. doi:10.1080/08898489209525346

Makeham(;a,b,c)

Construct a mortality model following Makeham's law.

$\mathrm{hazard} \left( {\rm age} \right) = ae^{bx} + c$

Default args:

a = 0.0002
b = 0.13
c = 0.001

MakehamBeard(;a,b,c,k)

Construct a mortality model following MakehamBeard's law of mortality.

$\mathrm{hazard} \left( {\rm age} \right) =\left( {\rm age} \right) = \frac{a \cdot e^{b \cdot {\rm age}}}{1 + k \cdot a \cdot e^{b \cdot {\rm age}}} + c$

Default args:

a = 0.002
b = 0.13
c = 0.01
k = 1.

Martinelle(;a,b,c,d,k)

Construct a mortality model following Martinelle's law of mortality.

$\mathrm{hazard}\left( {\rm age} \right) = \frac{a \cdot e^{b \cdot {\rm age}} + c}{1 + d \cdot e^{b \cdot {\rm age}}} + k \cdot e^{b \cdot {\rm age}}$

Default args:

a = 0.001
b = 0.13
c = 0.001
d = 0.1
k = 0.001

MortalityTable(ultimate)
MortalityTable(select, ultimate)
MortalityTable(select, ultimate; metadata::MetaData)

Constructs a container object which can hold either: - ultimate-only rates (an UltimateTable) - select and ultimate rates (a SelectUltimateTable)

Also pass a keyword argument metadata=MetaData(...) to store relevant information (source, notes, etc) about the table itself.

Examples

# first construct the underlying data
ult = UltimateMortality([x / 100 for x in 0:100]); # first ma
matrix = rand(10,50); # represents random mortality rates with a select period of 10 years
sel = SelectMortality(matrix,ult,start_age=0);

table = MortalityTable(sel,ult)

# can now get rates, indexed by attained age:

table.select[10] # the vector of rates for a risk issued select at age 10 

table.ultimate[99] # 0.99

Opperman(;a,b,c)

Construct a mortality model following Opperman's law of mortality.

$\mathrm{hazard} \left( {\rm age} \right) = \frac{a}{\sqrt{age}} + b +c\sqrt[3]{age}$

Default args:

a = 0.04
b = 0.0004
c = 0.001

Perks(;a,b,c,d)

Construct a mortality model following Perks' law of mortality.

$\mathrm{hazard} \left( {\rm age} \right) = \frac{a + b \cdot c^{{\rm age}}}{b \cdot c^{ - {\rm age}} + 1 + d \cdot c^{{\rm age}}}$

Default args:

a = 0.002
b = 0.13
c = 0.01
d = 0.01

Quadratic(;a,b,c)

Construct a mortality model following Quadratic law of mortality.

$\mathrm{hazard} \left( {\rm age} \right) = a + b \cdot {\rm age} + c \cdot {\rm age}^{2}$

Default args:

a = 0.01
b = 1.
c = 0.01

RogersPlanck(;a₀, a₁, a₂, a₃, a, b, c, d, u)

Construct a mortality model following RogersPlanck law of mortality.

$\mathrm{hazard}\left( {\rm age} \right) = a_0 + a_1 \cdot e^{\left( - a \right) \cdot {\rm age}} + a_2 \cdot e^{b \cdot \left( {\rm age} - u \right) - e^{\left( - c \right) \cdot \left( {\rm age} - u \right)}} + a_3 \cdot e^{d \cdot {\rm age}}$

Default args:

a₀ = 0.0001
a₁ = 0.02
a₂ = 0.001
a₃ = 0.0001
a  = 2.
b  = 0.001
c  = 100.
d  = 0.1
u  = 0.33

Siler(;a,b,c,d,e)

Construct a mortality model following Siler law of mortality.

$\mathrm{hazard} \left( {\rm age} \right) = a \cdot e^{\left( - b \right) \cdot {\rm age}} + c + d \cdot e^{e \cdot {\rm age}}$

Default args:

a = 0.0002
b = 0.13
c = 0.001
d = 0.001
e = 0.013

StrehlerMildvan(;k,v₀,b,d)

Construct a mortality model following StrehlerMildvan's law of mortality.

$\mathrm{hazard} \left( {\rm age} \right) = k \cdot e^{\frac{\left( - v_0 \right) \cdot \left( 1 - b \cdot {\rm age} \right)}{d}}$

Default args:

k   = 0.01
v₀  = 2.5
b   = 0.2
d   = 6.0

TableMetaData(kwargs...)

Has the following fields, which default to nothing if not specified with a keyword:

• name - a name for the table
• id - if a mort.SOA.org sourced table, will be the identifying table ID
• provider - Where the rates came from
• reference - Source for more info on table
• content_type
• description
• comments
• source_path

When you call a MortalityTable interactively, it will nicely print this summary infomration.

Example content from mort.SOA.org:

• Table Identity: 1076
• Provider Domain: actuary.org
• Provider Name: American Academy of Actuaries
• Table Reference: Tillinghast, “American Council of Life Insurers: Preferred Version of 2001 CSO Mortality Tables”, ...
• Content Type: CSO/CET
• Table Name: 2001 CSO Super Preferred Select and Ultimate - Male Nonsmoker, ANB
• Table Description: 2001 Commissioners Standard Ordinary (CSO) Super Preferred Select and Ultimate Table – Male Nonsmoker. Basis: Age Nearest Birthday. Minimum Select Age: 0. Maximum Select Age: 99. Minimum Ultimate Age: 16. Maximum Ultimate Age: 120
• Comments: Study Data: A preferred version of the 2001 Commissioners Standard Ordinary (CSO) table ...

And the source_path would be: https://mort.soa.org/ViewTable.aspx?&TableIdentity=1076

Example usage:

julia-repl> TableMetaData(name="My Table Name")
TableMetaData("My Table Name", nothing, nothing, nothing, nothing, nothing, nothing, nothing)

Thiele(;a,b,c,d,e,f,g)

Construct a mortality model following Opperman's law of mortality.

\[\begin{aligned} \mu_1 &= a \cdot e^{\left( - b \right) \cdot {\rm age}} \\ \mu_2 &= c \cdot e^{-0.5 \cdot d \cdot \left( {\rm age} - e \right)^{2}} \\ \mu_3 &= f \cdot e^{g \cdot {\rm age}} \\ \mathrm{hazard} \left( {\rm age} \right) &= \begin{cases} \mu_1 + \mu_3 & \text{if } \left( {\rm age} = 0 \right)\\ \mu_1 + \mu_2 + \mu_3 & \text{otherwise} \end{cases} \end{aligned}\]

Default args:

a = 0.02474 
b = 0.3
c = 0.004
d = 0.5
e = 25
f = 0.0001
g = 0.13

Uniform()

A DeathDistribution type that assumes an increasing force of mortality over the year.

VanderMaen(;a,b,c,i,n)

Construct a mortality model following VanderMaen's law of mortality.

$\mathrm{hazard} \left( {\rm age} \right) = a + b \cdot {\rm age} + c \cdot {\rm age}^{2} + \frac{i}{n - {\rm age}}$

Default args:

a = 0.01
b = 1
c = 0.01
i = 100
n = 200

VanderMaen2(;a,b,i,n)

Construct a mortality model following VanderMaen2's law of mortality.

$\mathrm{hazard} \left( {\rm age} \right) = a + b \cdot {\rm age} + \frac{i}{n - {\rm age}}$

Default args:

a = 0.01
b = 1
i = 100
n = 200

Weibull(;m,σ)

Construct a mortality model following Weibull's law of mortality.

Note that if σ > m, then the mode of the density is 0 and hx is a non-increasing function of x, while if σ < m, then the mode is greater than 0 and hx is an increasing function.

• m >0 is a measure of location
• σ >0 is measure of dispersion

\[\begin{aligned} \mathrm{hazard} \left( {\rm age} \right) = \frac{1}{\sigma} \cdot \left( \frac{{\rm age}}{m} \right)^{\frac{m}{\sigma} - 1} \\ \mathrm{cumhazard} \left( {\rm age} \right) = \left( \frac{{\rm age}}{m} \right)^{\frac{m}{\sigma}} \\ \mathrm{survival} \left( {\rm age} \right) = e^{ - \mathrm{cumhazard} \left( m, {\rm age} \right)} \end{aligned}\]

Default args:

m = 1
σ = 2

Wittstein(;a,b,m,n)

Construct a mortality model following Wittstein's law of mortality.

$\mathrm{hazard} \left( {\rm age} \right) = \frac{1}{b} \cdot a^{ - \left( b \cdot {\rm age} \right)^{n}} + a^{ - \left( m - {\rm age} \right)^{n}}$

Default args:

a = 1.5
b = 1.
n = 0.5
m = 100

Gompertz(;a,b)

Construct a mortality model following Gompertz' law of mortality.

$\mathrm{hazard} \left( {\rm age} \right) = ae^{bx}$

This is a special case of Makeham's law and will Makeham model where c=0.

Default args:

a = 0.0002
b = 0.13

SelectMortality(select, ultimate; start_age=0)

Given a matrix rates, where the first row represents the select rates for a risk, will create a an OffsetArray that is indexed by issue age, containing a vector of rate indexed by attained age. The ultimate mortality vector is used for rates in the post-select period.

Give the optional keyword argument to start the indexing at an age other than zero.

Examples

julia> ult = UltimateMortality([x / 100 for x in 0:100]);

julia> matrix = rand(50,10); # represents random(!) mortality rates with a select period of 10 years

julia> sel = SelectMortality(matrix,ult,start_age=0);

julia> sel[0] # the mortality vector for a select life with issue age 0
 0.12858960119349439
 0.1172480189376135
 0.8237661916705163
 ⋮
 0.98
 0.99
 1.0

julia> sel[0][95] # the mortality rate for a life age 95, that was issued at age 0
0.95

UltimateMortality(vector; start_age=0)

Given a vector of rates, returns an OffsetArray that is indexed by attained age.

Give the optional keyword argument to start the indexing at an age other than zero.

Examples

julia> m = UltimateMortality([0.1,0.3,0.6,1]);

julia> m[0]
0.1

julia> m = UltimateMortality([0.1,0.3,0.6,1], start_age = 18);

julia> m[18]
0.1

cumhazard(model,age)

The cumulative force of mortality at age. More precisely: the ratio of the cumulative probability of failure/death to the survival function.

decrement(mortality_vector,to_age)
decrement(mortality_vector,from_age,to_age)

Returns the cumulative decrement through attained age to_age. The start of the calculation is either the start of the vector, or attainedage `fromage.fromageandtoage` need to be Integers. Add a DeathDistribution as the last argument to handle floating point and non-whole ages:

decrement(mortality_vector,to_age,::DeathDistribution)
decrement(mortality_vector,from_age,to_age,::DeathDistribution)

Examples

julia> qs = UltimateMortality([0.1,0.3,0.6,1]);
    
julia> decrement(qs,0)
0.0
julia> decrement(qs,1)
0.1

julia> decrement(qs,1,1)
0.0
julia> decrement(qs,1,2)
0.3

julia> decrement(qs,0.5,Uniform())
0.05

dukesmacdonald1(pointinscale, selectrate, baselapses, totallapses, effectiveness)

dukesmacdonald1(selectultimate, issueage, attainedage, baselapses, total_lapses, effectiveness)

Two methods are available, one takes the pointinscale and selectrate directly. See https://www.soa.org/globalassets/assets/library/newsletters/product-development-news/2003/july/pdn-2003-iss56-doll-a.pdf for information on terminology. The other method takes a SelectUltimateTable from MortalityTable.jl and calculates the pointinscale and selectrate from the table.

dukesmacdonald2(pointinscale, selectrate, baselapses, totallapses, effectiveness)

dukesmacdonald2(selectultimate, issueage, attainedage, baselapses, total_lapses, effectiveness)

Two methods are available, one takes the pointinscale and selectrate directly. See https://www.soa.org/globalassets/assets/library/newsletters/product-development-news/2003/july/pdn-2003-iss56-doll-a.pdf for information on terminology. The other method takes a SelectUltimateTable from MortalityTable.jl and calculates the pointinscale and selectrate from the table.

dukesmacdonald3(pointinscale, selectrate, baselapses, totallapses, effectiveness)

dukesmacdonald3(selectultimate, issueage, attainedage, baselapses, total_lapses, effectiveness)

Two methods are available, one takes the pointinscale and selectrate directly. See https://www.soa.org/globalassets/assets/library/newsletters/product-development-news/2003/july/pdn-2003-iss56-doll-a.pdf for information on terminology. The other method takes a SelectUltimateTable from MortalityTable.jl and calculates the pointinscale and selectrate from the table.

get_SOA_table(id)
get_SOA_table(table_name)

Given the id or name of a mort.SOA.org table, grab it and return it as a MortalityTable.

!!! Remember that not all tables have been tested to work.

hazard(model,age)

The force of mortality at age. More precisely: the ratio of the probability of failure/death to the survival function.

life_expectancy(table,age)
life_expectancy(table,age,DeathDistribution)

Calcuate the remaining life expectancy. Assumes curtate life expectancy for tables if not Parametric or DeathDistribution given.

The life_expectancy of the last age defined in the table is set to be 0.0, even if the table does not end with a rate of 1.0.

mortality_vector(vec; start_age=0)

A convenience constructor to create an OffsetArray which has the array indexed by attained age rather than always starting from 1. The package and JuliaActuary ecosystem assume that the rates are indexed by attained age and this allows transformation of tables without a direct dependency on OffsetArrays.jl.

Equivalent to doing:

using OffsetArrays
OffsetArray(vec,start_age-1)

omega(x)
ω(x)

Returns the last index of the given vector. For mortality vectors this means the last attained age for which a rate is defined.

Note that omega can vary depending on the issue age for a select table, and that a select omega may differ from the table's ultimate omega.

ω is aliased to omega, but un-exported. To use, do using MortalityTables: ω when importing or call MortalityTables.ω()

Examples

julia> qs = UltimateMortality([0.1,0.3,0.6,1]);
julia> omega(qs)
3

julia> qs = UltimateMortality([0.1,0.3,0.6,1],start_age=10);
julia> omega(qs)
13

readXTbML(path)

Loads the XtbML (the SOA XML data format for mortality tables) stored at the given path and returns a MortalityTable.

read_tables(dir=nothing)

Loads the XtbML (the SOA XML data format for mortality tables) stored in the given path. If no path is specified, will load the packages in the MortalityTables package directory. To see where your system keeps packages, run DEPOT_PATH from a Julia REPL.

survival(mortality_vector,to_age)
survival(mortality_vector,from_age,to_age)

Returns the survival through attained age to_age. The start of the calculation is either the start of the vector, or attainedage `fromage.fromageandtoage` need to be Integers. Add a DeathDistribution as the last argument to handle floating point and non-whole ages:

survival(mortality_vector,to_age,::DeathDistribution)
survival(mortality_vector,from_age,to_age,::DeathDistribution)

If given a negative to_age, it will return 1.0. Aside from simplifying the code, this makes sense as for something to exist in order to decrement in the first place, it must have existed and survived to the point of being able to be decremented.

Examples

julia> qs = UltimateMortality([0.1,0.3,0.6,1]);
    
julia> survival(qs,0)
1.0
julia> survival(qs,1)
0.9

julia> survival(qs,1,1)
1.0
julia> survival(qs,1,2)
0.7

julia> survival(qs,0.5,Uniform())
0.95

table(id)
table(name)

Given the id or name of a mort.SOA.org table, grab it and return it as a MortalityTable.

!!! Remember that not all tables have been tested to work.

μ(;m::ParametricMortality,age)

$\mu_x$: Return the force of mortality at the given age.