Actuarial Tables: Creating Tables, Part 1
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:
- 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.
- 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.
- 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:
|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:
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.
||Non-negative integer||The minimum attained age at which the table value is available.|
||Non-negative integer||The maximum attained age at which the table value is available.|
||Numeric||Table value data.
||Positive numeric scalar||Unit base of table values. For example, if the table values represent rates per thousand,
||character||Information regarding the source of the table. (Optional)|
||character||Name of the creator of the table object. (Optional)|
||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
In the second statement, I called the method
SaveAsRda to save
tbl to an R data file named
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:
Table.AAto create an empty attained age table.
Reading table values from an Excel worksheet.
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
maxAge represent the minimum attained age and the maximum attained age of the mortality table. I set
1000 because the values in the table are rates per thousand. I set
Mort.Sample.AA. The identifier of a mortality table must start with
Mort., followed by your chosen name. The rest of the arguments
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:
||Non-negative integer||The minimum issue age at which the table value is available.|
||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
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)
Table.PY has an argument
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.
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
After a table object is created, we use
SaveAsRda function to save the object in R data format.