Actuarial Tables: Using Tables

Share on:



If you have followed the previous articles of the series about actuarial tables, you have learned the types of actuarial tables implemented in Rgogo Framework and how to create those tables.

In this article, we will continue to the following topics:

  1. Creating Table Package: I will demonstrate how to make the actuarial tables created in a project shareable among other projects.

  2. Looking up Table: I will explain what the required lookup keys are for each type of table and how to look up the table values.

  3. Exporting Table: I will show how to export a table object in R to an Excel file.

Building Table Package

We normally have certain actuarial tables that would be used in many modeling projects. Instead of creating them every time when needed, it is more efficient to build a table package containing those commonly-used tables and make the package shareable among projects.

This can be easily done by building an R package for your table projecct. I use the the SampleTables project that I've been working on to illustrate this.

Open the SampleTables project in RStudio. If you browse the data folder, you can find the tables that I have created so far. To build the package, click menu Build > Install and Restart. Once the command is completed successfully, a package named SampleTable is created and installed in your local R environment. When you need any of the tables in other projects later on, all you need to do is to attach the SampleTables package:


Looking Up Table, Method 1

To lookup a table, you need to specify the values of lookup keys. Different table classes require different lookup keys:

Class Description Lookup Key
Table.AA Attained age table Attained age
Table.IA Issue age table Issue age
Table.PY Policy year table Policy year
Table.IAPY Issue age by policy year table Issue age and policy year
Table.AABY Attained age by birth year table Attained age and birth year
Table.SU Select and ultimate table Issue age and policy year

The method for looking up a table is LookUp. The syntax is:

1LookUp(tbl, lookUpKey)

The first argument tbl is a table object. It can be any of the six classes.

The second argument lookUpKey is a list. list is a data type of R. I assume that you already know the basics of list.

When the lookup key is a list, you need to know the class of tbl. The required items in the lookUpKey depend on the class of tbl and are summarized below:

Class of tbl Required list items in lookUpKey
Table.AA AttAge: attained age
Table.IA IssAge: issue age
Table.PY PolYear: policy year
Table.IAPY IssAge: issue age
PolYear: policy year
Table.AABY AttAge: attained age
BirthYear: birth year
Table.SU IssAge: issue age
PolYear: policy year

Looking up One-Dimensional Table

We start with looking up a one-dimensional table. In SampleTables project, we created a sample mortality table Mort.Sample.AA. It is an attained age table.

4# Look up the mortality rate at attained age 40:
5LookUp(Mort.Sample.AA, list(AttAge = 40))
7# Look up the mortality rates for the range of attained ages from 40 to 60:
8LookUp(Mort.Sample.AA, list(AttAge = 40:60))

In the above example, Mort.Sample.AA is an attained age table. Therefore, the lookup key must have an item named AttAge.

The first lookup statement returns the mortality rate at attained age 40. The second lookup statement returns a numeric vector of length 21. The vector contains the mortality rates for each attained age between 40 and 60.

Looking up Two-Dimensional Table

The next example is to look up a 20-year endowment insurance cash value table CV.E20. It is an issue age by policy year table. Therefore, the lookup key must contain IssAge and PolYear.

1# Look up the cash value per thousand face amount of issue age 30:
2LookUp(CV.E20, list(IssAge = 30, PolYear = 1:20))
4# Look up the cash value per thousand face amount of issue ages between 30 and 40 during the first ten policy years:
5LookUp(CV.E20, list(IssAge = 30:40, PolYear = 1:10))

Looking up Select and Ultimate Table

In SampleTables projects, we careated 2017 Loaded CSO Female Nonsmoker ALB Mortality Rates per 1000 table object. It is a 25-year select and ultimate table.

1# Lookup CSO mortality rate vector for female nonsmoker aged 35 at issue:
2LookUp(Mort.CSO2017LL.FN, list(IssAge = 35))
4# Look up mortality rates for issue age 35 during the first 20 policy years:
5LookUp(Mort.CSO2017LL.FN, list(IssAge = 35, PolYear = 1:10))
7# Look up mortality rates for issue ages between 35 and 40 during the first 10 policy years:
8LookUp(Mort.CSO2017LL.FN, list(IssAge = 35:40, PolYear = 1:10))

Looking Up Table, Method 2

If we look up a table and use a list as the lookup key, we will need to know the class of the table in advance. This is because different classes of table object require different items in the list. If any of the items is missing, the lookup will fail. This lookup method is easy to understand, but have drawbacks.

For example, let's consider the case of looking up mortality tables. A mortality table can be an attained age table or a select and ultimate table. In the process of modeling, if you change the mortality table from one type to the other, you will also need to modify the lookup key. This makes your model difficult to maintain and prone to execution error. Change of mortality table is simply a change in assumption. Why should we check and modify the codes every time when we change the assumption?

Rgogo resolves the above issue by providing another lookup method using a coverage object as the lookup key. When you use a coverage object for the lookup key, you do not need to know the table class in advance. The LookUp method will take care of the table class issue automatically and return the desired results.

Coverage: a Brief Introduction

A coverage object in Rgogo contains information of an insurance contract. The constructor for creating a coverage object is Cov. The codes below creates a coverage object in its simplest form.

1cov <- Cov(
2   issDate = as.Date("2021-01-01"), 
3   issAge = 35L, 
4   riskClass = "", 
5   faceAmt = 0,
6   premMode = integer()

In the above codes, I created a coverage object with issue date at January 1, 2021 and issue age 35. These two arguments are the only information required for looking up a table.

Although I also initialized other arguments including risk class, face amount and premium mode, their values will not affect lookup results. Let's ignore them for now.

Looking up Table

The benefit of using a coverage object as the lookup key can be seen from the examples below:

1# Look up an attained age mortality table:
2LookUp(Mort.Sample.AA, cov)
4# Look up a select and ultimate mortality table:
5LookUp(Mort.CSO2017LL.FN, cov)
7# Look up a issue age by policy year cash value table:
8LookUp(CV.E20, cov)

In the above examples, we used the same method and the same lookup key to look up a table, no matter what class of table it was.

Exporting Table

If you would like to export a table to an Excel file, you can do so by using ExportToExcel method. For example:

1# Export sample mortality table
2ExportToExcel(Mort.Sample.AA, "export/SampleMortTable.xlsx")
4# Export CSO mortality table
5ExportToExcel(Mort.CSO2017LL.FN, "export/CSO2017FN.xlsx")
7# Export 20-year endowment insurance cash value table
8ExportToExcel(CV.E20, "export/CVE20.xlsx", overwrite = TRUE)

When calling ExportToExcel method, the first argument is the table object that you would like to export, and the second argument is the path of the destination Excel file. In above examples, the exported files were located in the project export folder.

You can also add a third argument overwrite = TRUE. This tells ExportToExcel method to automatically overwrite any existing file with the same name. If you do not specify overwrite argument, the default is not to overwrite. In this case, the method will return an error if a file with the same name exists.


In this article, I have shown you how to work with tables in Rgogo.

By building a package for a project containing table objects, you can share the tables in other projects without recreating them.

The method to look up a table is LookUp(tbl, lookUpKey). lookUpKey can be a list or a coverage object.

You can use ExportToExcel(object, path, overwrite) method to export a table object to an Excel file.

You can find a summary of how to work with actuarial tables in Rgogo in the how-to guide: How to Work with Tables.

Previous article: Actuarial Table: Creating Tables, Part 2

How-to Guide: How to Work with Tables