MortalityTables.jl

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.

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.

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.

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.

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.

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.

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.

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

Default args:

m = 5
σ = 10

Kannisto(a,b)

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

Default args:

a = 0.5
b = 0.13

KannistoMakeham(a,b,c)

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

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.

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

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

Makeham(;a,b,c)

Construct a mortality model following Makeham's law.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Default args:

m = 1
σ = 2

Wittstein(a,b,m,n)

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

Default args:

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

Gompertz(a,b)

Construct a mortality model following Gompertz' law of mortality.

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

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

get_SOA_table!(dict,id)

Will lookup the given mortality table and add it to the given dict, with the name of the table acting as the added key in the dictionary.

This modifies the given dict (as is indicated by the conventional ! at the end of the function name).

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

get_SOA_table(id)

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

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

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.

ω is aliased to omega, but unexported. 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](https://mort.soa.org/About.aspx) (the SOA XML data format for mortality tables) stored at the given path and returns a `MortalityTable`.

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 surived 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

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.

μ(m::ParametricMortality,age)

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