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.

Carriere1(; p₁=0.003, p₂=0.007, μ₁=2.7, μ₂=3, μ₃=88, σ₁=15, σ₂=6, σ₃=9.5)

Carrière's three-component survival mixture: Weibull, inverse Weibull, and Gompertz. For weights $w = (p₁, p₂, 1-p₁-p₂)$ and component survival functions $S_i$,

\[S(x) = \sum_{i=1}^3 w_i S_i(x), \qquad H(x) = -\log S(x), \qquad h(x) = \frac{\sum_{i=1}^3 w_i S_i(x) h_i(x)}{S(x)}.\]

The components are Weibull(m=μ₁, σ=σ₁), InverseWeibull(m=μ₂, σ=σ₂), and Gompertz2(μ=μ₃, σ=σ₃). Each is normalized to survival one at age zero. The hazard is an instantaneous force, not an annual mortality probability; use decrement(model, age, age + 1) for the latter.

Weights must be nonnegative with p₁ + p₂ ≤ 1; zero weights are allowed. All locations and scales must be finite and positive. Ages must be nonnegative. The hazard at zero is infinite when p₁ > 0 and μ₁ < σ₁ (an integrable Weibull singularity); survival there is one. The inverse-Weibull tail gives an infinite mean lifetime when p₂ > 0 and μ₂/σ₂ ≤ 1, as with the defaults. The defaults are inherited from MortalityLaws, not a calibrated mortality table: their hazard declines sharply at old ages as inverse-Weibull survivors dominate.

This implementation uses σ₂ for the inverse-Weibull component, following Carrière's paper. Older MortalityLaws implementations used σ₁ there and ignored σ₂; that wiring was corrected in MortalityLaws' v2.3.0 development commit 8f13abb. Parameters fitted with the older formula generally need refitting before use here. MortalityLaws also reports finite differences of cumulative hazard, whereas hazard here is the instantaneous force.

The zero-age limits above apply to ordinary numeric ages. ForwardDiff age derivatives at exactly zero are not reliable for InverseWeibull or the Carrière mixtures. They can return NaN where the right-hand derivative is finite, or where it is +Inf because of a singular Weibull component (as in both mixtures' defaults, including Carriere2, which has no inverse-Weibull component).

ASCII aliases are p1, p2, mu1 to mu3, and sigma1 to sigma3. Passing both spellings of a keyword is an ArgumentError.

See Carrière (1992), Parametric Models for Life Tables, Transactions of the Society of Actuaries 44, 77–99, and the MortalityLaws implementation.

Carriere2(; p₁=0.01, p₂=0.01, μ₁=1, μ₂=49, μ₃=49, σ₁=2, σ₂=7, σ₃=7)

Carrière's survival mixture of Weibull(m=μ₁, σ=σ₁), InverseGompertz(m=μ₂, σ=σ₂), and Gompertz2(μ=μ₃, σ=σ₃). With $w = (p₁,p₂,1-p₁-p₂)$, $S = ∑ᵢ wᵢ Sᵢ$, $H = -log(S)$, and $h = (∑ᵢ wᵢ Sᵢ hᵢ)/S$. Each component is normalized at age zero.

Parameter validation, ASCII keyword aliases, and the hazard's limit at age zero are as for Carriere1. Unlike Carriere1, this mixture has a finite mean lifetime for every allowed parameter set.

ConstantForce()

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

DeathDistribution

An abstract type used to form an assumption of how deaths occur throughout a year. See Balducci(), UniformDeaths(), and ConstantForce() 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)}$

gamma is an ASCII alias for γ.

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.

\[\begin{aligned} \mu_1 &= a^{\left( {\rm age} + b \right)^{c}} + g \cdot h^{{\rm age}} \\ \mu_2 &= d \cdot \exp\left( -e \cdot \left( \log\left( \frac{{\rm age}}{f} \right) \right)^{2} \right) \\ \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 = .0005
b = .004
c = .08
d = .001
e = 10
f = 17
g = .00005
h = 1.1

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 \exp\left( -e \cdot \left( \log\left( \frac{{\rm age}}{f} \right) \right)^{2} \right) \\ \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 \exp\left( -e \cdot \left( \log\left( \frac{{\rm age}}{f} \right) \right)^{2} \right) \\ \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 \exp\left( -e \cdot \left( \log\left( \frac{{\rm age}}{f} \right) \right)^{2} \right) \\ \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(;m,σ)

Construct a mortality model following InverseGompertz's law.

\[\begin{aligned} \mathrm{hazard} \left( {\rm age} \right) &= \frac{1}{\sigma} \cdot \frac{e^{\frac{ - \left( {\rm age} - m \right)}{\sigma}}}{e^{e^{\frac{ - \left( {\rm age} - m \right)}{\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}\]

sigma is an ASCII alias for σ.

Default args:

m = 49
σ = 7.7

InverseWeibull(;m,σ)

Construct a mortality model following the Inverse-Weibull 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( {\rm age} \right)} \end{aligned}\]

sigma is an ASCII alias for σ.

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) &= \frac{1}{b} \log\left( \frac{1 + a \cdot e^{b \cdot {\rm age}}}{1 + a} \right) \\ \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

Makeham2(; μ=49, σ=7.692308, c=0.001)

Makeham's law in location/scale parameters, with force of mortality $h(x) = e^{(x-μ)/σ}/σ + c$. It is equivalent to Makeham(a=exp(-μ/σ)/σ, b=1/σ, c=c).

μ must be finite, σ finite and positive, and c finite and nonnegative. mu and sigma are ASCII aliases for μ and σ; passing both spellings of a keyword is an ArgumentError. Ages must be nonnegative.

The location and scale are retained as fields: transforming them to a and b can underflow a even when mortality near age μ is representable.

MakehamBeard(;a,b,c,k)

Construct a mortality model following MakehamBeard'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}}} + 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::TableMetaData)

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=TableMetaData(...) 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]);
matrix = rand(50,10); # random(!) rates for issue ages 0 to 49, 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) = \max\left( \frac{a}{\sqrt{{\rm age} + 1}} - b + c \cdot \sqrt{{\rm age} + 1}, 0 \right)$

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}}$

a0, a1, a2 and a3 are ASCII aliases for a₀, a₁, a₂ and a₃.

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 \exp\left( -b \cdot {\rm age} \right) + c + d \cdot \exp\left( e \cdot {\rm age} \right)$

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}}$

v0 is an ASCII alias for v₀.

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

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 Thiele's law of mortality.

\[\begin{aligned} \mu_1 &= a \cdot \exp\left( -b \cdot {\rm age} \right) \\ \mu_2 &= c \cdot \exp\left( -\frac{d}{2} \left( {\rm age} - e \right)^{2} \right) \\ \mu_3 &= f \cdot \exp\left( g \cdot {\rm age} \right) \\ \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

UniformDeaths()

A DeathDistribution type that assumes deaths are spread uniformly over the year of age (UDD), which gives 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

The law is defined up to age n, where the hazard has a pole; omega returns n. An age past n is a DomainError.

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

The law is defined up to age n, where the hazard has a pole; omega returns n. An age past n is a DomainError.

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( {\rm age} \right)} \end{aligned}\]

sigma is an ASCII alias for σ.

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

The law is defined up to age m, which omega returns. An age past m is a DomainError.

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

Gompertz2(; μ=49, σ=7.7)

Gompertz's law in location/scale parameters, with force of mortality $h(x) = e^{(x-μ)/σ}/σ$. Returns a Makeham2 with c=0, equivalent to Gompertz(a=exp(-μ/σ)/σ, b=1/σ). mu and sigma are ASCII keyword aliases.

SelectMortality(select, ultimate; start_age=0)

Given a matrix of rates, where each row holds the select rates for one issue age, creates an OffsetArray that is indexed by issue age, containing a vector of rates 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.

Any AbstractVector is accepted (a Vector, a range, a view, or a vector containing missing); the input is wrapped without copying.

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

age_last_to_age_nearest(rates)

Convert age-last-birthday mortality rates to age-nearest-birthday rates, assuming a uniform distribution of deaths. The returned vector has the same age indices as rates.

The inverse is calculated backward from a terminal rate of one.

age_nearest_to_age_last(rates)

Convert age-nearest-birthday mortality rates to age-last-birthday rates, assuming a uniform distribution of deaths. The returned vector has the same age indices as rates.

The terminal rate must be one because the conversion at the final age would otherwise require the next age's rate.

complete_life_expectancy(rates, age, dist = UniformDeaths())
complete_life_expectancy(law, age, dist = UniformDeaths(); rtol, atol, maxevals)

The complete expectation of life at age: the expected remaining lifetime, $\mathring{e}_x = \int_0^{\omega - x} {}_tp_x \, dt$, where ${}_tp_x$ is survival(m, age, age + t).

For a vector of rates, survival within each year of age follows the DeathDistribution dist, and survival is integrated one year of age at a time. A fractional age conditions on survival to age, as survival does. The integral runs to the table's last age, where the expectancy is zero. An age outside the table is a BoundsError.

For a parametric law, survival is integrated with QuadGK up to omega(law). dist is accepted and ignored, since a law is continuous. With a finite omega, survival left at omega counts as death there, so the expectancy at omega is zero. An age past omega is a DomainError. rtol, atol and maxevals go to QuadGK, with its defaults: atol = 0, rtol the square root of the machine epsilon of the integration interval's type when atol is zero, and maxevals = 10^7. The tolerances must be finite and nonnegative and maxevals a positive integer, or an ArgumentError names the one that is not. The integral is returned only if it and QuadGK's error estimate are finite and the estimate is at most max(atol, rtol * abs(integral)); the estimate is QuadGK's, not a proof of accuracy. Otherwise an ArgumentError reports that the integration did not converge: the expectancy may be infinite, as for a law whose survival falls too slowly, or the integral may need a larger maxevals.

See also curtate_life_expectancy.

Examples

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

julia> complete_life_expectancy(qs, 0) # 0.95 + 0.9 * 0.85 + 0.9 * 0.7 * 0.7
2.156

julia> complete_life_expectancy(qs, 0.5, ConstantForce())
1.7198453593325438

cumhazard(model,age)
cumhazard(model,from_age,to_age)

The integrated hazard up to age, $H(x) = \int_0^x \mu_s \, ds$, equivalently $-\log S(x)$, so that survival(model, age) == exp(-cumhazard(model, age)). The two-age form integrates from from_age to to_age: $-\log(S(\text{to})/S(\text{from}))$.

The generic method integrates hazard numerically from age zero. A law may override the one-argument form with a closed-form expression; the two-age form is the difference of the one-argument form, so a closed form is used automatically wherever it exists.

curtate_life_expectancy(rates, age)
curtate_life_expectancy(law, age; rtol, atol)

The curtate expectation of life at age: the expected number of whole years lived after age, $e_x = \sum_{k \ge 1} {}_kp_x$, where ${}_kp_x$ is survival(m, age, age + k).

For a vector of rates, age is a whole age in the table. The sum runs to the table's last age, where the expectancy is zero, even if the table does not end with a rate of one. An age outside the table is a BoundsError.

For a parametric law, age is any real age up to omega(law). An age past omega is a DomainError.

• With a finite omega, the sum runs to $k = \lfloor \omega - x \rfloor$. Survival left at omega counts as death there, so the expectancy at omega is zero.
• With omega = Inf, the first K terms are summed and the rest is estimated from the integral of survival $S(t) = {}_tp_x$. Survival does not increase (the hazard is not negative), so the rest lies between $\int_{K+1}^\infty S$ and $\int_K^\infty S$, an interval no wider than $S(K)$. The estimate uses its midpoint, integrated with QuadGK. K grows until $S(K)/2$ plus QuadGK's error estimate is at most max(atol, rtol * abs(estimate)). This is an estimated accuracy, not a certified bound. If 100,000 terms are not enough, it throws an ArgumentError.

rtol defaults to sqrt(eps(T)), where T is the type of the survival values, and atol to 0. They apply only to a law with omega = Inf, and must be finite and nonnegative (either may be zero), or an ArgumentError names the one that is not.

See also complete_life_expectancy.

Examples

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

julia> curtate_life_expectancy(qs, 0) # 0.9 + 0.9 * 0.7 + 0.9 * 0.7 * 0.4
1.782

julia> curtate_life_expectancy(qs, 3)
0.0

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,UniformDeaths())
0.05

The decrement is accumulated directly ($d \leftarrow q + d(1 - q)$) rather than computed as one minus the survival product, so a small decrement keeps its precision. A reversed interval gives the negative decrement 1 - survival(v, from_age, to_age) of the reverse factor, computed as -d / S from the forward decrement d and forward survival S, so it keeps its precision both for a small decrement and for a small forward survival.

A type that defines only survival gets decrement as 1 - survival; define decrement too where that complement would lose precision.

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

hazard(model,age)

The force of mortality at age: the density of the age at death divided by the probability of surviving to age, $\mu_x = f(x)/S(x) = -S'(x)/S(x)$.

Every parametric law implements hazard; cumhazard, survival, and decrement follow from it.

mortality_vector(vec; start_age=0)

An alias for UltimateMortality: wraps vec in an OffsetArray indexed by attained age, starting at start_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.

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.

For a parametric model (see ParametricMortality), omega is the last age at which its law is defined: Inf for a law defined at every age, m for Wittstein (where its formula ends), and n for VanderMaen and VanderMaen2 (whose hazard has a pole there). An age past omega is a DomainError. Survival need not reach zero at omega (for Wittstein it does not), so a projection that stops at omega truncates such a law. omega does not validate a law's parameters either: some parameters give a negative hazard at ages inside the domain.

ω 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

parseXTbMLTable(str, path)

Parse the XTbML document in str (read from path, which is recorded in the metadata) into the labeled rates (select, ultimate, metadata) that _table_from_labels assembles. ultimate is a vector of (age, rate); select is nothing for an ultimate-only table, or a vector of (issue_age, rates) where rates is a vector of (duration, rate), missing for an empty cell.

readXTbML(path)

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

The result is cached by path, so calling this twice with the same path returns the identical object.

read_tables(dir=nothing)

Loads the XTbML files (the SOA XML data format for mortality tables) stored in the given directory and returns a Dict of the tables by name. If no directory is given, it loads the tables bundled with the package.

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)

Survival from a fractional from_age is conditional on surviving to from_age: it equals survival(v, to_age, dd) / survival(v, from_age, dd) under the same assumption, so survival over consecutive intervals multiplies. Where the assumption gives zero survival to a fractional from_age (after a rate of one under ConstantForce or Balducci) there is nothing to condition on; the formulas are still evaluated as written and give finite values.

When to_age is before from_age, the result is the reverse factor 1 / survival(v, to_age, from_age): the number expected alive at the earlier age for each life alive at the later one, as used to project a population backward or to accumulate with the benefit of survivorship. It is not a probability (it can exceed one, and the corresponding decrement is negative), and it is an expected-value back-calculation rather than a reconstruction of realized deaths. It is defined where the forward survival is positive; a zero forward survival gives Inf. With it, survival composes over any three ages whose factors are positive and representable: survival(v, a, c) == survival(v, a, b) * survival(v, b, c), whatever their order. (A zero factor has no inverse: 0 * Inf is not one.) Ages outside the table (such as a negative to_age for a table starting at zero) are a BoundsError.

Results have the numeric type of the rates, promoted with the ages' type for fractional ages, including the exact one of an empty interval: a BigFloat table gives BigFloat survival, and a Float32 table gives Float32 survival at whole ages. A vector whose element type doesn't name the rates' number type (such as Any, Real, or Missing for a column with no rates) has Float64 identities, as in version 2: an empty interval gives 1.0, and a nonempty result takes the type its rates' arithmetic gives. Use a concretely typed vector for type-consistent and fast results.

Parametric models (see ParametricMortality) are continuous and need no fractional-age assumption, so they accept a trailing DeathDistribution and ignore it.

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,UniformDeaths())
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.

μ(model,age)

$\mu_x$: the force of mortality at age. An alias for hazard.