Package 'mortSOA'

Title: Obtain Data from the Society of Actuaries 'Mortality and Other Rate Tables' Site
Description: The Society of Actuaries (SOA) provides an extensive online database called 'Mortality and Other Rate Tables' ('MORT') at <https://mort.soa.org/>. This database contains mortality, lapse, and valuation tables that cover a variety of product types and nations. Users of the database can download any tables in 'Excel', 'CSV', or 'XML' formats. This package provides convenience functions that read 'XML' formats from the database and return R objects.
Authors: Matt Heaphy [aut, cre, cph]
Maintainer: Matt Heaphy <[email protected]>
License: MIT + file LICENSE
Version: 0.1.0
Built: 2026-05-08 06:22:26 UTC
Source: https://github.com/mattheaphy/mortsoa

Help Index

Filter the inventory of tables

Description

Filter the table_inventory by keywords to find table identification numbers quickly.

Usage

filter_inventory(..., type = c("and", "or"))

Arguments

...

Keywords or regular expressions used to filter the table_inventory data set by the name column. Alternatively, the first argument passed to ... can be a data frame containing a column called name. This feature allows filter_inventory() to be called in succession using the pipe operator.
type

Type of filtering performed. If "and", names must match all expressions passed to .... If "or", names must match at least one expression passed to ....

Details

The mort.soa.org site contains a large number of tables indexed by identification numbers. The mortSOA package includes a data set called table_inventory that contains all available tables as of 2026-01-24. This function can be used to filter that table by name using keywords passed to the ... argument. Filtering is accomplished using grepl(), so regular expressions are accepted.

Multiple calls to filter_inventory() can be chained together using the pipe operator.

Value

A data frame (tibble)

References

Society of Actuaries Mortality and Other Rate Tables https://mort.soa.org

Examples

filter_inventory("2012 IAM", "Female")
# Same result using a regular expression
filter_inventory("2012 IAM.*Female")
# Chained version with type = "or"
filter_inventory("Pri-2012", "Retiree") |>
  filter_inventory("Blue", "White", type = "or")

Read data from mort.soa.org and return a list of data frames

Description

Read data from mort.soa.org and return a list of data frames

Usage

read_mort_soa(table_id)

Arguments

table_id

An identification number for a mortality table on <mort.soa.org>

Details

This function first checks if the provided table_id is available on mort.soa.org. If not found, an error is returned.

If a match is found, a list containing all tables underneath table_id is returned. The list contains several attributes that can be queried using ⁠attr({list}, "{attribute})⁠. Available attributes include:

  • name - Name of the table

  • table_id

  • description - A detailed description of the table

  • usage - Intended usage

  • layout - Table layout

  • nation - Nation of origin

  • sub_descriptions - A character vector containing detailed descriptions for each sub-table underneath table_id

Most tables have either an "Aggregate" or "Select and Ultimate" structure.

  • Aggregate structures contains a single table with one dimension (usually Age).

  • Select and Ultimate structures contain two tables. The first table contains two dimensions for Age and Duration. The second table contains a single dimension for Age.

For convenience, any two-dimensional tables are pivoted longer into a "tidy" format with 3 columns: Age, Duration, and the mortality (or other) rate.

Value

A list containing any tables associated with table_id plus the metadata attributes described above. Individual tables are data frames (tibbles).

References

Society of Actuaries Mortality and Other Rate Tables https://mort.soa.org

See Also

filter_inventory()

Examples

# Get table #2586: 2012 IAM Period Table – Female, ANB
read_mort_soa(2586)

Inventory of tables from mort.soa.org

Description

A complete inventory of available tables on mort.soa.org last updated on 2026-01-24.

Format

A 3,034 x 6 data frame containing an inventory of available tables with the following columns:

  • table_id

  • name - Name of the table

  • description - A detailed description of the table

  • layout - Table layout

  • usage - Intended usage

  • nation - Nation of origin