Tables

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.

table(id)
table(name)

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

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.

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

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

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.

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)

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

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

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.

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

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

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.

Balducci()

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

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.

ConstantForce()

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

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.