Actuarial Tables: Creating Tables, Part 1

Share on:

Overview

Introduction

Based on the shape and lookup method, there are three types of actuarial tables: one-dimensional, two-dimensional or a composite form involveing both of the above. In this article, I will focus on the first category: one-dimensional tables.

When looking up a one-dimensional table, you only need one lookup key. Rgogo Framework implements the following three classes of one-dimensional table:

  1. Attained age table

Attained age table is a one-dimensional table in which the lookup key is attained age. Common examples of attained age tables include yearly renewable term premium rate tables and some mortality tables.

  1. Issue age table

Issue age table is a one-dimensional table in which the lookup key is issue age. The most common use of issue age table is the premium rate table of a long-term insurance product.

  1. Policy year table

Policy year table is another one-dimensional table in which the lookup key is policy year. An example of the use of a policy year table is to store the lapse rates which vary by policy years.

A table shall be created by using a constructor. A constructor is a special function that creates and return a specific type of table. When calling a constructor, you specify the attributes of the table by passing values to the function's arguments.

The three table classes and their constructors described in this article are summarized below:

Class Description Constructor
Table.AA Attained age table Table.AA(...)
Table.IA Issue age table Table.IA(...)
Table.PY Policy year table Table.PY(...)

All the code snippets and other supporting files in this article can be found in the sample project SampleTables. You can download it from GitHub. If you haven't done so, click here for details.

Launch RStudio and open SampleTables project. After the project is opened, attach Rgogo package from RStudio console:

1library(Rgogo)

Creating Attained Age Table

Assume that I want to create a premium table for an accidental death benefit. The premium rates are available for an insured aged between 18 and 70. The rate is 0.75 per thousand face amount for all attained ages.

The codes for creating the above premium table are illustrated below:

 1tbl <- Table.AA(
 2    minAge = 18L, 
 3    maxAge = 70L, 
 4    tValue = 0.75,
 5    tBase = 1000, 
 6    source = "SampleTables Project", 
 7    createdBy = "Edward Kuo",
 8    id = "Prem.ADB", 
 9    descrip = "Accidental death benefit premium rates"
10)
11
12SaveAsRda(tbl, overwrite = TRUE)

In the first statement, I called a function Table.AA to create an attained age table.

Table.AA is the constructor of an attained age table object. When calling the constructor, you set the argument values to specify the properties of the table. The arguments of Table.AA include the following.

Argument Data Type Description
minAge Non-negative integer The minimum attained age at which the table value is available.
maxAge Non-negative integer The maximum attained age at which the table value is available.
tValue Numeric Table value data. tValue must be able to be coerced into a numeric matrix with one column and maxAge - minAge + 1 rows.
tBase Positive numeric scalar Unit base of table values. For example, if the table values represent rates per thousand, tBase is set to 1000.
source character Information regarding the source of the table. (Optional)
createdBy character Name of the creator of the table object. (Optional)
id character Table identifier.
descrip character Description of the table. (Optional)

In the above code snippet, an attained age table was created by constructor Table.AA and assigned to the variable tbl.

In the second statement, I called the method SaveAsRda to save tbl to an R data file named Prem.ADB.rda under data folder of the project. Note that the name of the file (ignoring the extension) is the same as the table identifier. The second argument overwrite = TRUE simply indicates that any exiting file with the same name would be overwritten.

The above example illustrates the simplest case in which the table values of all attained ages are identical. However, this is rarely the case. Most tables contain table values varying by values of lookup key. It is impractical to enter all the values in the constructor. Instead, it is likely more convenient to import the table values from external sources.

If you have a table stored in Excel, Rgogo has a function ImportTableValuesFromExcel allowing you to import the table values from an Excel worksheet easily.

In the example below, I am going to create a mortality table. The table values are stored in an Excel file named Sample Mortality table.xlsx, located under data-raw folder. This table contains mortality rates per thousand for attained ages from 0 to 110.

I will follow the steps below:

  1. Using constructor Table.AA to create an empty attained age table.

  2. Reading table values from an Excel worksheet.

  3. Saving the table object as an R data file.

The following codes will carry out the above steps:

 1tbl <- Table.AA(
 2    minAge = 0L, 
 3    maxAge = 110L, 
 4    tBase = 1000, 
 5    source = "Actuarial Mathematics (Bowers Jr, Gerber, Hickman, Jones, Nesbit)", 
 6    createdBy = "Edward Kuo",
 7    id = "Mort.Sample.AA", 
 8    descrip = "Sample mortality table"
 9)
10
11tbl <- ImportTableValuesFromExcel(tbl, "data-raw/Sample Mortality Table.xlsx", "Sheet1", "B2:B112")
12
13SaveAsRda(tbl, overwrite = TRUE)

In the first statement, I used the table constructor Table.AA to create an attained age table object. Unlike the previous example, this object only has a table structure but has no values in it. Note that the statement does not contain tValue argument. The arguments minAge and maxAge represent the minimum attained age and the maximum attained age of the mortality table. I set tBase to 1000 because the values in the table are rates per thousand. I set id to Mort.Sample.AA. The identifier of a mortality table must start with Mort., followed by your chosen name. The rest of the arguments source, createdBy and descrip provide additional information regarding the table.

In the second statement, I used the function ImportTableValuesFromExcel to import the table values. The function has four arguments. The first argument is the table object that I created using the constructor. The second to the forth arguments contain the location of the source data including path of the Excel file (the second argument), the name of the sheet (the third argument) and the range of the table values (the fourth argument).

In setting the range argument (the fourth argument) in the above ImportTableValuesFromExcel function, the range should correspond to the location of the table values only. It should not include any title row or title column in the worksheet.

ImportTableValuesFromExcel returned a table object filled with the table values. This returned table object was assigned to tbl variable in the second statement.

The last statement used SaveAsRda to save the table object in an R data format under data folder.

Creating Issue Age Table

The process of creating an issue age table is very similar to that of creating an attained age table.

Assume that I want to create an issue age table for a premium rate table of a 10-year level term insurance. The table information is stored in an Excel file. It contains male's premium rates per thousand face amount. The minimum and maximum issue ages are 18 and 55 respectively.

 1tbl <- Table.IA(
 2    minAge = 18L, 
 3    maxAge = 55L, 
 4    tBase = 1000, 
 5    source = "Rgog Sample Project", 
 6    createdBy = "Edward Kuo",
 7    id = "Prem.LT10.M", 
 8    descrip = "10-Year Level Term Premium Rates, Male"
 9)
10
11tbl <- ImportTableValuesFromExcel(tbl, "data-raw/Sample LT10 Premium Table.xlsx", "Sheet1", "C6:C43")
12
13SaveAsRda(tbl, overwrite = TRUE)

The constructor for creating an issue age table is Table.IA. Its arguments are very similar to those of the attained age table constructor Table.AA with the following differences:

Argument Data Type Description
minAge Non-negative integer The minimum issue age at which the table value is available.
maxAge Non-negative integer The maximum issue age at which the table value is available.

In the above example, I set the id argument value to Prem.LT10.M. The identifier of a premium table must start with Prem., followed by a chosen name.

Can you create the female's premium rate table of this sample 10-year level term insurance?

Creating Policy Year Table

The constructor for creating a policy year table is Table.PY.

Assume that I want to create a lapse rate table that will be used for setting the lapse assumption of a modeling exercise. The lapse rates are 20% in the first policy year, 10% in the second policy year, 7.5% in the third policy year, and 5% in the fourth policy year and thereafter. I also assume that the length of the projection period is ten years.

I can create such a table with the following codes:

 1tbl <- Table.PY(
 2    maxPolYear = 10L, 
 3    tValue = c(20, 10, 7.5, 5, 5, 5, 5, 5, 5, 5),
 4    tBase = 100, 
 5    source = "Rgog Sample Project", 
 6    createdBy = "Edward Kuo",
 7    id = "Lapse.Sample", 
 8    descrip = "Sample lapse rate table"
 9)
10
11SaveAsRda(tbl, overwrite = TRUE)

The constructor Table.PY has an argument maxPolYear. maxPolYear is the maximum policy year of a policy year table, which is the 10th policy year in this example. There is no argument for setting the minimum policy year because the minimum policy year is always 1, the first policy year.

In the above example, I provided the table values inside the constructor by setting tValue argument. You can also import table values from Excel using ImportTableValuesFromExcel function. The way to do this is exactly the same as the previous examples for importing the table values of an attainded age table or an issue age table.

Summary

In this article, we have learned that there are three classes of one-dimensional actuarial tables implemented in Rgogo Framework, namely Table.AA (attained age table), Table.IA (issue age table) and Table.PY (policy year table).

Each table class has its own constructor. The name of the constructor is the same as the class name, but the arguments are somewhat different.

We can either specify table values in the constructor or import the values from an Excel file using ImportTableValuesFromExcel function.

After a table object is created, we use SaveAsRda function to save the object in R data format.

Previous article: Actuarial Tables: Overview

Next article: Actuarial Table: Creating Tables, Part 2