Model points

Model points are one of the the actuarial cash flow model's inputs. In this post, we will discuss what model points are and how to set them up.

List of content:

1. What are model points?
2. Cheatsheet
• Define model point set
• Change the identifier name
• Read data from model point

What are model points?

In short, a model point represents an object for which the actuarial cash flow model will be evaluated.

Actuarial cash flow models have two main types of inputs: assumptions and model points. If you model life insurance, assumptions include mortality rates, lapse rates and interest rates. Model points are policy data which contain information on policyholders (age, sum insured, fund value etc.). If you model assets, model points can include characteristics of financial assets such as bonds.

In the past, it was common to group multiple objects (e.g. multiple policyholders) with similar characteristics into one model point. Thanks to that, the model could run faster. Nowadays, it's not so common, because grouping requires additional work and computers just got faster.

In Python framework for actuarial cash flow models cashflower, the following naming convention is used:

• model point set - a group of model points; it can have a form of a file or a database query result,
• model point - one or multiple records that contain data on the given object (e.g. a policyholder or a financial asset),
• record - a single row of data.

Each actuarial cash flow model must have a model point set named main. The main model point set must have one record per model point. The model point set contains a column that contains an identification of an object (id).

In this example, there are 5 policyholders. The policyholder with the identifier 2 is a 64-year old male who pays €270 premium.

A cash flow model can have multiple model point sets. Model point sets other than main can have multiple records per model point.

The above model has 3 model point sets: main, coverage and fund. The model point for the identifier 2 has 5 records (1 in main, 2 in coverage and 2 in fund).

Cheatsheet

Cheatsheet for working with model points in the cashflower package.

Define model point set

Model point sets are defined in the input.py script. There must be a model point set assigned to the main variable. In the main model point set, each record must be a unique model point. The id column contains identifier for model point objects.

To create a model point set, use the ModelPointSet class and provide a pandas data frame as an argument for the data parameter.

from cashflower import ModelPointSet

main = ModelPointSet(data=pd.DataFrame({
    "id": [1, 2, 3, 4, 5],
    "age": [27, 64, 45, 33, 82]
    "sex": ["F", "M", "M", "F", "F"],
    "premium": [500, 270, 340, 650, 120],
}))

coverage = ModelPointSet(data=pd.DataFrame({
    "id": [1, 2, 2, 3, 4, 5, 5],
    "sum_assured": [100_000, 80_000, 25_000, 120_000, 30_000, 120_000, 10_0000],
    "type": ["DEATH", "DEATH", "ILLNESS", "DEATH", "DEATH", "DEATH", "ILLNESS"],
}))

fund = ModelPointSet(data=pd.DataFrame({
    "id": [1, 1, 2, 2, 3, 4, 5],
    "code": ["AC", "X9", "D7", "BB", "EF", "T6", "ZE"],
    "units": [50, 25, 30, 10, 40, 100, 15],
}))

Change the identifier name

Each model point set must have a column which identifies model points. By default, this column is named id.

settings = {
    ...
    "ID_COLUMN": "id",
    ...
}

main = ModelPointSet(data=pd.DataFrame({
    "id": [1, 2, 3, 4, 5],
    ...
}))

coverage = ModelPointSet(data=pd.DataFrame({
    "id": [1, 2, 2, 3, 4, 5, 5],
    ...
}))

fund = ModelPointSet(data=pd.DataFrame({
    "id": [1, 1, 2, 2, 3, 4, 5],
    ...
}))

You can change the name of the identifier column using the ID_COLUMN setting.

settings = {
    ...
    "ID_COLUMN": "POLICY_ID",
    ...
}

main = ModelPointSet(data=pd.DataFrame({
    "POLICY_ID": [1, 2, 3, 4, 5],
    ...
}))

coverage = ModelPointSet(data=pd.DataFrame({
    "POLICY_ID": [1, 2, 2, 3, 4, 5, 5],
    ...
}))

fund = ModelPointSet(data=pd.DataFrame({
    "POLICY_ID": [1, 1, 2, 2, 3, 4, 5],
    ...
}))

Remember that Python is case-sensitive!

Read data from model point

To read a value from a model point, use the get() method of the ModelPointSet class. Provide a name of the attribute as an argument.

main.get("age")

The model will read the value of the model point which is currently calculated.

from cashflower import variable
from input import assumption, main

@variable()
def mortality_rate(t):
    age = main.get("age")
    sex = main.get("sex")
    return assumption["mortality"].loc[age, sex]["rate"]

The main model point set must have a unique row per model point but the other model point sets don’t.

If the model point has multiple records, you can read them like this:

fund.get("fund_value", record_num=1)

This code will get the value of fund_value for the second record of the currently evaluated model point (counting starts with 0 in Python!).

If model points have varying number of records, you can use e.g. fund.model_point_data.shape[0] to determine the number of records of the model point.

For example, to calculate the total value of fund value, use:

@variable()
def total_fund_value(t):
    total_value = 0
    for i in range(0, fund.model_point_data.shape[0]):
        total_value += fund.get("fund_value", i)
    return total_value

If you prefer to work on each value separetely, you can use a list structure. A list can also be an output of the model variable.

@variable()
def fund_values(t):
    fund_values = []
    for i in range(0, fund.model_point_data.shape[0]):
        fund_values.append(fund.get("fund_value", i))
    return fund_values