The BasicTerm_M Model#

Overview#

The BasicTerm_M model is a faster reimplementation of the BasicTerm_S model.

The BasicTerm_M model reproduces the same results as BasicTerm_S much faster. Each formula to be applied to all the model points operates on the entire set of model points at once with the help of Numpy and Pandas.

The default product specs, assumptions and input data are the same as BasicTerm_S.

Speed comparison#

The main advantage of the BasicTerm_M model over the BasicTerm_S model is its speed. Below is the result of a simple speed comparison between the two models. The machine used for this comparison is a consumer PC equipped with Intel Core i5-6500T CPU and 16GB RAM.

100 model points with BasicTerm_S#

>>> timeit.timeit("[Projection[i].pv_net_cf() for i in range(1, 101)]",globals=globals(), number=1)
7.6481730999998945

10000 model points with BasicTerm_M#

>>> timeit.timeit("pv_net_cf()",globals=globals(), number=1)
1.3366562999999587

Note that only the first 100 model points were run with BasicTerm_S while all the 10000 model points were run with BasicTerm_M. While BasicTerm_S took about 7.6 seconds for the 100 model points, BasicTerm_M took only 1.3 seconds for the 10000 model points. This means BasicTerm_M runs about 580 times faster than BasicTerm_S.

Formula examples#

Most formulas in the BasicTerm_M model are the same as those in BasicTerm_S. However, some formulas are updated since they cannot be applied to vector operations without change. For example, below shows how pols_maturity, the number of maturing policies at time t, is defined differently in BasicTerm_S and in BasicTerm_M.

pols_maturity in BasicTerm_S#

 def pols_maturity(t):
     if t == policy_term() * 12:
         return pols_if(t-1) - pols_lapse(t-1) - pols_death(t-1)
     else:
         return 0

pols_maturity in BasicTerm_M#

 def pols_maturity(t):
     return (t == policy_term() * 12) * (pols_if(t-1) - pols_lapse(t-1) - pols_death(t-1))

In BasicTerm_S, policy_term() returns an integer, such as 10 indicating a policy term of the selected model point in years, so the if clause checks if the value of t is equal to the policy term in month:

In BasicTerm_S for model point 1#

>>> policy_term()
120

>>> pols_maturity(120)
0.6534679117893804

In contrast, policy_term() in BasicTerm_M returns a Series of policy terms of all the model points. If the if clause were defined in the same way as in the BasicTerm_S, it would result in an error, because the condition t == policy_term() * 12 for a certain t returns a Series of boolean values and it is ambiguous for the Series to be the if condition. Further more, whether the if branch or the else branch should be evaluated needs to be determined element-wise, but the if statement would not allow such element-wise branching. Instead of using the if statement, the formula in BasicTerm_M achieves the element-wise conditional operation by multiplication by a Series of boolean values. In the formula in BasicTerm_M, (pols_if(t-1) - pols_lapse(t-1) - pols_death(t-1)) returns the numbers of policies at time t for all the model points as a Series. Multiplying it by (t == policy_term() * 12) replaces the numbers of policies with 0 for model points whose policy terms in month are not equal to t. This operation is effectively an element-wise if operation:

In BasicTerm_M#

>>> policy_term()
point_id
      10
      20
      10
      20
      15
         ..
   20
   15
   20
   20
  15
Name: policy_term, Length: 10000, dtype: int64


>>> (120 == policy_term() * 12)
point_id
       True
      False
       True
      False
      False

   False
   False
   False
   False
  False
Name: policy_term, Length: 10000, dtype: bool


>>> pols_maturity(120)
point_id
      0.653468
      0.000000
      0.650917
      0.000000
      0.000000

   0.000000
   0.000000
   0.000000
   0.000000
  0.000000
Length: 10000, dtype: float64

Basic Usage#

Reading the model#

Create your copy of the basiclife library by following the steps on the Quick Start page. The model is saved as the folder named BasicTerm_M in the copied folder.

To read the model from Spyder, right-click on the empty space in MxExplorer, and select Read Model. Click the folder icon on the dialog box and select the BasicTerm_M folder.

Getting the results#

By default, the model has Cells for outputting projection results as listed in the Results section. result_cf() outputs total cashflows of all the model points, and result_pv() outputs the present values of the cashflows by model points. Both Cells outputs the results as pandas DataFrame.

By following the same steps explained in the Quick Start page using this model, You can get the results in an MxConsole and show the results as tables in MxDataViewer.

Changing the model point#

By default, model_point() returns the entire model_point_table:

>>> Projection.model_point.formula
def model_point():
    return model_point_table

The calculations in Projection apply to all the model points in model_point_table. To limit the calculation target, change the model_point() formula so that model_point() returns a DataFrame that contains only the target rows. For example, to select only the model point 1:

>>> Projection.model_point.formula
def model_point():
    return model_point_table.loc[1:1]

There are many methods of DataFrame for selecting its rows. See the pandas documentation for details.

When selecting only one model point, make sure that model_point() returns the model point as a DataFrame not as a Series. In the code example above, model_point_table.loc[1:1] is specified instead of model_point_table.loc[1], because model_point_table.loc[1] would return the model point as a Series.

Also, you should be careful not to accidentally update the original DataFrame held as model_point_table.

Model Specifications#

The BasicTerm_M model has only one UserSpace, named Projection, and all the Cells and References are defined in the space.

The Projection Space#

The main Space in the BasicTerm_M model.

Projection is the only Space defined in the BasicTerm_M model, and it contains all the logic and data used in the model.

Parameters and References

(In all the sample code below, the global variable Projection refers to the Projection Space.)

model_point_table#

All model point data as a DataFrame. The sample model point data was generated by generate_model_points.ipynb included in the library. By default, model_point() returns this model_point_table. The DataFrame has columns labeled age_at_entry, sex, policy_term, policy_count and sum_assured. Cells defined in Projection with the same names as these columns return the corresponding columns. (policy_count is not used by default.)

>>> Projection.model_poit_table
           age_at_entry sex  policy_term  policy_count  sum_assured
point_id
1                    47   M           10             1       622000
2                    29   M           20             1       752000
3                    51   F           10             1       799000
4                    32   F           20             1       422000
5                    28   M           15             1       605000
                ...  ..          ...           ...          ...
9996                 47   M           20             1       827000
9997                 30   M           15             1       826000
9998                 45   F           20             1       783000
9999                 39   M           20             1       302000
10000                22   F           15             1       576000

[10000 rows x 5 columns]

The DataFrame is saved in the Excel file model_point_table.xlsx placed in the model folder. model_point_table is created by Projection’s new_pandas method, so that the DataFrame is saved in the separate file. The DataFrame has the injected attribute of _mx_dataclident:

>>> Projection.model_point_table._mx_dataclient
<PandasData path='model_point_table.xlsx' filetype='excel'>

Projection parameters#

This is a new business model and all model points are issued at time 0. The time step of the model is monthly. Cashflows and other time-dependent variables are indexed with t.

Cashflows and other flows that accumulate throughout a period indexed with t denotes the sums of the flows from t til t+1. Balance items indexed with t denotes the amount at t.

`proj_len`()	Projection length in months
`max_proj_len`()	The max of all projection lengths

Model point data#

The model point data is stored in an Excel file named model_point_table.xlsx under the model folder.

`model_point`()	Target model points
`sex`()	The sex of the model points
`sum_assured`()	The sum assured of the model points
`policy_term`()	The policy term of the model points.
`age`(t)	The attained age at time t.
`age_at_entry`()	The age at entry of the model points
`duration`(t)	Duration in force in years

Assumptions#

The mortality table is stored in an Excel file named mort_table.xlsx under the model folder, and is read into mort_table as a DataFrame. mort_rate() looks up mort_table and picks up the annual mortality rates to be applied for all the model point at time t and returns them in a Series. mort_rate_mth() converts mort_rate() to the monthly mortality rate to be applied during the month starting at time t.

The discount rate data is stored in an Excel file named disc_rate_ann.xlsx under the model folder, and is read into disc_rate_ann as a Series.

The lapse by duration is defined by a formula in lapse_rate(). expense_acq() holds the acquisition expense per policy at t=0. expense_maint() holds the maintenance expense per policy per annum. The maintenance expense inflates at a constant rate of inflation given as inflation_rate().

`mort_rate`(t)	Mortality rate to be applied at time t
`mort_rate_mth`(t)	Monthly mortality rate to be applied at time t
`disc_factors`()	Discount factors.
`disc_rate_mth`()	Monthly discount rate
`lapse_rate`(t)	Lapse rate
`expense_acq`()	Acquisition expense per policy
`expense_maint`()	Annual maintenance expense per policy
`inflation_factor`(t)	The inflation factor at time t
`inflation_rate`()	Inflation rate

Policy values#

By default, the amount of death benefit for each policy (claim_pp()) is set equal to sum_assured.

The payment method is monthly whole term payment for all model points. The monthly premium per policy (premium_pp()) is calculated for each policy as (1 + loading_prem()) times net_premium_pp(). The net premium is calculated so that the present value of the net premiums equates to the present values of claims.

This product is assumed to have no surrender value.

`claim_pp`(t)	Claim per policy
`net_premium_pp`()	Net premium per policy
`loading_prem`()	Loading per premium
`premium_pp`()	Monthly premium per policy

Policy decrement#

The initial number of policies is set to 1 per model point by default, and decreases through out the policy term by lapse and death. At the end of the policy term the remaining number of policies mature.

`pols_death`(t)	Number of death occurring at time t
`pols_if`(t)	Number of policies in-force
`pols_if_init`()	Initial Number of Policies In-force
`pols_lapse`(t)	Number of lapse occurring at time t
`pols_maturity`(t)	Number of maturing policies

Cashflows#

An acquisition expense at t=0 and maintenance expenses thereafter comprise expense cashflows.

Commissions are assumed to be paid out during the first year and the commission amount is assumed to be 100% premium during the first year and 0 afterwards.

`claims`(t)	Claims
`commissions`(t)	Commissions
`premiums`(t)	Premium income
`expenses`(t)	Acquisition and maintenance expenses
`net_cf`(t)	Net cashflow

Present values#

The Cells whose names start with pv_ are for calculating the present values of the cashflows indicated by the rest of their names. pols_if() is not a cashflow, but used as annuity factors in calculating net_premium_pp().

`pv_claims`()	Present value of claims
`pv_commissions`()	Present value of commissions
`pv_expenses`()	Present value of expenses
`pv_net_cf`()	Present value of net cashflows.
`pv_pols_if`()	Present value of policies in-force
`pv_premiums`()	Present value of premiums

Results#

result_cf() outputs the total cashflows of all the model points as a DataFrame:

>>> result_cf()
          Premiums         Claims      Expenses    Commissions  Net Cashflow
  828052.400000  240181.385376  3.000000e+06  828052.400000 -3.240181e+06
  820758.893595  238066.700397  4.956055e+04  820758.893595 -2.876273e+05
  813529.629362  235970.634461  4.912497e+04  813529.629362 -2.850956e+05
  806364.041439  233893.023631  4.869321e+04  806364.041439 -2.825862e+05
  799261.568951  231833.705414  4.826525e+04  799261.568951 -2.800990e+05
..             ...            ...           ...            ...           ...
175639.935592  255080.430556  1.065127e+04       0.000000 -9.009177e+04
175262.324017  254523.319976  1.063033e+04       0.000000 -8.989132e+04
174885.540149  253967.449257  1.060943e+04       0.000000 -8.969133e+04
174509.582137  253412.815586  1.058857e+04       0.000000 -8.949180e+04
     0.000000       0.000000  0.000000e+00       0.000000  0.000000e+00

[241 rows x 5 columns]

result_pv() outputs the present values of the cashflows by model points:

>>> result_pv()
           PV Premiums     PV Claims  ...  PV Commissions  PV Net Cashflow
point_id                              ...
1          8251.931435   5501.074678  ...     1084.601434       917.951731
2          8934.647903   5956.375886  ...      699.317588      1190.137329
3         13785.154420   9190.166764  ...     1814.196468      2033.119958
4          5771.417165   3847.385432  ...      452.022146       383.742941
5          4951.158886   3300.643396  ...      474.220266       245.572689
               ...           ...  ...             ...              ...
9996      27755.139250  18503.269117  ...     2189.101714      5980.458717
9997       7338.893087   4892.682575  ...      703.088993       812.566152
9998      22878.042022  15252.462621  ...     1801.701611      4740.283791
9999       6029.228626   4019.657332  ...      473.273387       449.939683
10000      3804.512116   2536.489758  ...      364.193562       -27.270550

[10000 rows x 5 columns]

`result_cf`()	Result table of cashflows
`result_pv`()	Result table of present value of cashflows