Projection#

The main Space of CashValue_ME_G2PP: CashValue_ME_EX4 driven by G2++ scenarios.

This space is lifelib’s CashValue_ME_EX4 Projection space with its economic inputs taken from the space ESG, a copy of the G2PP space of BasicG2PP:

  • scen_index() is ESG’s: scen_id 0 is the certainty-equivalent (CE) scenario and 1 to N are stochastic, so model_point() repeats every model point N+1 times.

  • inv_return_table() is the market-value return of the bond fund chosen by fund_id in the ESG input, instead of EX4’s lognormal returns.

  • disc_factors() are ESG’s deflators, instead of EX4’s flat discount rate.

  • result_tvog() gives the TVOG of the GMAB, the GMDB and the net cash flow, and formula_gmab_g2pp() the closed-form GMAB cost it can be checked against.

  • check_pv_net_cf() discounts each month’s net cash flows with the deflators of their scenarios. check_margin() is unchanged and returns False here as in EX4, because the margins leave out the GMAB claims.

EX4’s scen_size, scen_id, std_norm_rand, disc_rate_ann, disc_rate_mth and formula_option_put are removed. The rest of the original description follows.

The main Space in the CashValue_ME model.

Projection is the only Space defined in the CashValue_ME 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.)

esg#

The ESG space, a copy of the G2PP space of BasicG2PP. It reads g2pp_input.xlsx next to the model folder and supplies scen_index(), the fund returns of inv_return_table() and the deflators of disc_factors().

model_point_table#

All model points as a DataFrame. By default, 4 model points are defined. The DataFrame has an index named point_id.

  • spec_id

  • age_at_entry

  • sex

  • policy_term

  • policy_count

  • sum_assured

  • duration_mth

  • premium_pp

  • av_pp_init

Cells defined in Projection with the same names as these columns return the corresponding column’s values for the selected model point.

>>> Projection.model_poit_table
         spec_id  age_at_entry sex  ...  premium_pp  av_pp_init
poind_id                            ...
1              A            20   M  ...      500000           0
2              B            50   M  ...      500000           0
3              C            20   M  ...        1000           0
4              D            50   M  ...        1000           0

[4 rows x 10 columns]

The DataFrame is saved in the Excel file model_point_samples.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_samples.xlsx' filetype='excel'>
model_point_10000#

Alternative model point table

This model point table contains 10000 model points and is saved as the Excel file model_point_10000.xlsx placed in the folder. To use this table, assign it to model_point_table:

>>> Projection.model_point_table = Projection.model_point_10000
mort_table#

Mortality table by age and duration as a DataFrame. See basic_term_sample.xlsx included in this library for how the sample mortality rates are created.

>>> Projection.mort_table
            0         1         2         3         4         5
Age
18   0.000231  0.000254  0.000280  0.000308  0.000338  0.000372
19   0.000235  0.000259  0.000285  0.000313  0.000345  0.000379
20   0.000240  0.000264  0.000290  0.000319  0.000351  0.000386
21   0.000245  0.000269  0.000296  0.000326  0.000359  0.000394
22   0.000250  0.000275  0.000303  0.000333  0.000367  0.000403
..        ...       ...       ...       ...       ...       ...
116  1.000000  1.000000  1.000000  1.000000  1.000000  1.000000
117  1.000000  1.000000  1.000000  1.000000  1.000000  1.000000
118  1.000000  1.000000  1.000000  1.000000  1.000000  1.000000
119  1.000000  1.000000  1.000000  1.000000  1.000000  1.000000
120  1.000000  1.000000  1.000000  1.000000  1.000000  1.000000

[103 rows x 6 columns]

The DataFrame is saved in the Excel file mort_table.xlsx placed in the model folder. mort_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.mort_table._mx_dataclient
<PandasData path='mort_table.xlsx' filetype='excel'>
surr_charge_table#

Surrender charge rates by duration

A DataFrame of multiple patterns of surrender charge rates by duration. The column labels indicate surr_charge_id(). By default, "type_1", "type_2" and "type_3" are defined.

product_spec_table#

Table of product specs

A DataFrame of product spec parameters by spec_id. model_point_table and product_spec_table columns are joined in model_point_table_ext(), and the product_spec_table columns become part of the model point attributes. The product_spec_table columns are read by the Cells with the same names as the columns:

>>> Projection.product_spec_table
        premium_type  has_surr_charge surr_charge_id  load_prem_rate  is_wl
spec_id
A             SINGLE            False            NaN            0.10  False
B             SINGLE             True         type_1            0.00  False
C              LEVEL            False            NaN            0.10   True
D              LEVEL             True         type_3            0.05   True
np#

The numpy module.

pd#

The pandas module.

Cells

age(t)

The attained age at time t.

age_at_entry()

The age at entry of the model points

av_at(t, timing)

Account value in-force

av_change(t)

Change in account value

av_pp_at(t, timing)

Account value per policy

av_pp_init()

Initial account value per policy

check_av_roll_fwd()

Check account value roll-forward

check_margin()

Check consistency between net cashflow and margins

check_pv_net_cf()

Check present value summation

claim_net_pp(t, kind)

claim_pp(t, kind)

Claim per policy

claims(t[, kind])

Claims

claims_from_av(t, kind)

Account value taken out to pay claim

claims_over_av(t, kind)

Claim in excess of account value

coi(t)

Cost of insurance charges

coi_pp(t)

Cost of insurance charges per policy

coi_rate(t)

Cost of insurance rate per account value

commissions(t)

Commissions

disc_factors(t)

Discount factors for cash flows at t, by model point and scenario: the ESG deflators

duration(t)

Duration of model points at t in years

duration_mth(t)

Duration of model points at t in months

expense_acq()

Acquisition expense per policy

expense_maint()

Annual maintenance expense per policy

expenses(t)

Expenses

formula_gmab_g2pp(t)

Closed-form GMAB cost of the single-premium model points maturing at month t

has_surr_charge()

Whether surrender charge applies

inflation_factor(t)

The inflation factor at time t

inflation_rate()

Inflation rate

inv_income(t)

Investment income on account value

inv_income_pp(t)

Investment income on account value per policy

inv_return_mth(t)

Rate of investment return

inv_return_table()

Monthly investment returns by model point and scenario, from the ESG space

is_wl()

Whether the model point is whole life

lapse_rate(t)

Lapse rate

load_prem_rate()

Rate of premium loading

maint_fee(t)

Maintenance fee deducted from account value

maint_fee_pp(t)

Maintenance fee per policy

maint_fee_rate()

Maintenance fee per account value

margin_expense(t)

Expense margin

margin_mortality(t)

Mortality margin

max_proj_len()

The max of all projection lengths

model_point()

Target model points

model_point_table_ext()

Extended model point table

mort_rate(t)

Mortality rate to be applied at time t

mort_rate_mth(t)

Monthly mortality rate to be applied at time t

mort_table_last_age()

The last age of mortality tables

mort_table_reindexed()

MultiIndexed mortality table

net_amt_at_risk(t)

Net amount at risk per policy

net_cf(t)

Net cashflow

point_size()

policy_term()

The policy term of the model points.

pols_death(t)

Number of death

pols_if(t)

Number of policies in-force

pols_if_at(t, timing)

Number of policies in-force

pols_if_init()

Initial number of policies in-force

pols_lapse(t)

Number of lapse

pols_maturity(t)

Number of maturing policies

pols_new_biz(t)

Number of new business policies

prem_to_av(t)

Premium portion put in account value

prem_to_av_pp(t)

Per-policy premium portion put in the account value

premium_pp(t)

Premium amount per policy

premium_type()

Type of premium payment

premiums(t)

Premium income

proj_len()

Projection length in months

pv_av_change()

Present value of change in account value

pv_claims([kind])

Present value of claims

pv_claims_from_av([kind])

Present value of claims

pv_claims_over_av([kind])

Present value of claims

pv_commissions()

Present value of commissions

pv_expenses()

Present value of expenses

pv_inv_income()

Present value of investment income

pv_net_cf()

Present value of net cashflows.

pv_pols_if()

Present value of policies in-force

pv_premiums()

Present value of premiums

result_cf()

Result table of cashflows

result_pols()

Result table of policy decrement

result_pv()

Result table of present value of cashflows

result_tvog()

Time value of options and guarantees (TVOG) by model point

scen_index()

Scenario IDs from the ESG space: 0 is the CE scenario, 1 to N are stochastic

sex()

The sex of the model points

sum_assured()

The sum assured of the model points

surr_charge(t)

Surrender charge

surr_charge_id()

ID of surrender charge pattern

surr_charge_max_idx()

maximum index of surrender charge table

surr_charge_rate(t)

Surrender charge rate

surr_charge_table_column()

surr_charge_table_stacked()

Stacked surrender charge table

age(t)[source]#

The attained age at time t.

Defined as:

age_at_entry() + duration(t)
age_at_entry()[source]#

The age at entry of the model points

The age_at_entry column of the DataFrame returned by model_point().

av_at(t, timing)[source]#

Account value in-force

av_at(t, timing) calculates the total amount of account value at time t for the policies represented by a model point.

At each t, the events that change the account value balance occur in the following order:

  • Maturity

  • New business and premium payment

  • Fee deduction

The second parameter timing takes a string to indicate the timing of the account value, which is either "BEF_MAT", "BEF_NB" or "BEF_FEE".

BEF_MAT

The amount of account value before maturity, defined as:

av_pp_at(t, "BEF_PREM") * pols_if_at(t, "BEF_MAT")

BEF_NB

The amount of account value before new business after maturity, defined as:

av_pp_at(t, "BEF_PREM") * pols_if_at(t, "BEF_NB")

BEF_FEE

The amount of account value before lapse and death after new business, defined as:

av_pp_at(t, "BEF_FEE") * pols_if_at(t, "BEF_DECR")
av_change(t)[source]#

Change in account value

Change in account value during each period, defined as:

av_at(t+1, 'BEF_MAT') - av_at(t, 'BEF_MAT')

See also

av_pp_at(t, timing)[source]#

Account value per policy

av_at(t, timing) calculates the total amount of account value at time t for the policies in-force.

At each t, the events that change the account value balance occur in the following order:

  • Premium payment

  • Fee deduction

Investment income is assumed to be earned throughout each month, so at the middle of the month when death and lapse occur, half the investment income for the month is credited.

The second parameter timing takes a string to indicate the timing of the account value, which is either "BEF_PREM", "BEF_FEE", "BEF_INV" or "MID_MTH".

BEF_PREM

Account value before premium payment. At the start of the projection (i.e. when t=0), the account value is set to av_pp_init().

BEF_FEE

Account value after premium payment before fee deduction

BEF_INV

Account value after fee deduction before crediting investemnt return

MID_MTH

Account value at middle of month (t+0.5) when half the investment retun for the month is credited

av_pp_init()[source]#

Initial account value per policy

For existing business at time 0, returns initial per-policy accout value read from the av_pp_init column in model_point(). For new business, 0 should be entered in the column.

check_av_roll_fwd()[source]#

Check account value roll-forward

Returns Ture if av_at(t+1, "BEF_NB") equates to the following expression for all t, otherwise returns False:

av_at(t, "BEF_MAT")
      + prem_to_av(t)
      - maint_fee(t)
      - coi(t)
      + inv_income(t)
      - claims_from_av(t, "DEATH")
      - claims_from_av(t, "LAPSE")
      - claims_from_av(t, "MATURITY"))
check_margin()[source]#

Check consistency between net cashflow and margins

Returns True if net_cf() equates to the sum of margin_expense() and margin_mortality() for all t, otherwise, returns False.

check_pv_net_cf()[source]#

Check present value summation

Check if the present value of net_cf() matches the sum of the present values of each cash flow, pv_net_cf(). Returns the check result as True or False.

Changed from CashValue_ME_EX4, whose discount factors are the same in every scenario: this one multiplies each month’s net cash flows by that month’s disc_factors(), which differ by model point and scenario.

claim_pp(t, kind)[source]#

Claim per policy

The claim amount per policy. The second parameter is to indicate the type of the claim, and it takes a string, which is either "DEATH", "LAPSE" or "MATURITY".

The death benefit as denoted by "DEATH", is the greater of sum_assured() and mid-month account value (av_pp_at(t, "MID_MTH")).

The surrender benefit as denoted by "LAPSE" and the maturity benefit as denoted by "MATURITY" are equal to the mid-month account value.

claims(t, kind=None)[source]#

Claims

The claim amount during the period from t to t+1. The optional second parameter is for indicating the type of the claim, and it takes a string, which is either "DEATH", "LAPSE" or "MATURITY", or defaults to None to indicate the total of all the types of claims during the period.

The death benefit as denoted by "DEATH" is defined as:

claim_pp(t) * pols_death(t)

The surrender benefit as denoted by "LAPSE" is defined as:

claims_from_av(t, "LAPSE") - surr_charge(t)

The maturity benefit as denoted by "MATURITY" is defined as:

claims_from_av(t, "MATURITY")
claims_from_av(t, kind)[source]#

Account value taken out to pay claim

The part of the claim amount that is paid from account value. The second parameter takes a string indicating the type of the claim, which is either "DEATH", "LAPSE" or "MATURITY".

Death benefit is denoted by "DEATH", is defined as:

av_pp_at(t, "MID_MTH") * pols_death(t)

When the account value is greater than the death benefit, the death benefit equates to the account value.

Surrender benefit as denoted by "LAPSE" is defined as:

av_pp_at(t, "MID_MTH") * pols_lapse(t)

As the surrender benefit is defined as account value less surrender charge, when there is no surrender charge the surrender benefit equates to the account value.

Maturity benefit as denoted by "MATURITY" is defined as:

av_pp_at(t, "BEF_PREM") * pols_maturity(t)

By default, the maturity benefit equates to the account value of maturing policies.

claims_over_av(t, kind)[source]#

Claim in excess of account value

The amount of death benefits in excess of account value. coi() net of this amount represents mortality margin.

coi(t)[source]#

Cost of insurance charges

The cost of insurance charges deducted from acccount values each period.

coi_pp(t)[source]#

Cost of insurance charges per policy

The cost of insurance charges per policy. Defined as the coi charge rate times net amount at risk per policy.

coi_rate(t)[source]#

Cost of insurance rate per account value

The cost of insuranc rate per account value per month. By default, it is set to 1.1 times the monthly mortality rate.

commissions(t)[source]#

Commissions

By default, 100% premiums for the first year, 0 otherwise.

disc_factors(t)[source]#

Discount factors for cash flows at t, by model point and scenario: the ESG deflators

Column t of esg.disc_factor_paths(), tiled over model points in the row order of model_point(). The CE scenario discounts with the initial curve.

Returns:

numpy array of shape (point_size() * (N+1),)

duration(t)[source]#

Duration of model points at t in years

See also

duration_mth()

duration_mth(t)[source]#

Duration of model points at t in months

Indicates how many months the policies have been in-force at t. The initial values at time 0 are read from the duration_mth column in model_point_table through model_point(). Increments by 1 as t increments. Negative values of duration_mth() indicate future new business policies. For example, If the duration_mth() is -15 at time 0, the model point is issued at t=15.

See also

model_point()

expense_acq()[source]#

Acquisition expense per policy

5000 by default.

expense_maint()[source]#

Annual maintenance expense per policy

500 by default.

expenses(t)[source]#

Expenses

Expenses during the period from t to t+1 defined as the sum of acquisition expenses and maintenance expenses. The acquisition expenses are modeled as expense_acq() times pols_new_biz(). The maintenance expenses are modeled as expense_maint() times inflation_factor() times pols_if_at() before decrement.

has_surr_charge()[source]#

Whether surrender charge applies

True if surrender charge on account value applies upon lapse, False if other wise. By default, the value is read from the has_surr_charge column in model_point().

See also

inflation_factor(t)[source]#

The inflation factor at time t

See also

inflation_rate()[source]#

Inflation rate

The inflation rate to be applied to the expense assumption. By defualt it is set to 0.01.

inv_income(t)[source]#

Investment income on account value

Investment income earned on account value during each period. For the plicies decreased by lapse and death, half the investment income is credited.

inv_income_pp(t)[source]#

Investment income on account value per policy

Investment income on account value defined as:

inv_return_mth(t) * av_pp_at(t, "BEF_INV")
inv_return_mth(t)[source]#

Rate of investment return

Rate of monthly investment return at t, by model point and scenario, read from inv_return_table()

inv_return_table()[source]#

Monthly investment returns by model point and scenario, from the ESG space

The fund earns the market-value return of the bond fund chosen by fund_id in the ESG input (esg.fund_return_paths()), with row 0 the CE scenario, which earns the one-month forwards of the initial curve. The array is tiled over model points in the row order of model_point(). Raises ValueError if the projection is longer than the ESG scenarios.

Returns:

numpy array of shape (point_size() * (N+1), n)

is_wl()[source]#

Whether the model point is whole life

True if the model point is whole life, False if other wise. By default, the value is read from the is_wl column in model_point(). This attribute is used to determin policy_term(). If True, policy_term() is defined as mort_table_last_age() minus age_at_entry(). If False, policy_term() is read from model_point().

See also

lapse_rate(t)[source]#

Lapse rate

By default, the lapse rate assumption is defined by duration as:

max(0.1 - 0.02 * duration(t), 0.02)

See also

duration()

load_prem_rate()[source]#

Rate of premium loading

This rate times premium_pp() is collected from each premium and the rest is added to the account value.

By default, the value is read from the load_prem_rate column in model_point().

See also

maint_fee(t)[source]#

Maintenance fee deducted from account value

See also

maint_fee_pp(t)[source]#

Maintenance fee per policy

maint_fee_rate()[source]#

Maintenance fee per account value

The rate of maintenance fee on account value each month. Set to 0.01 / 12 by default.

See also

margin_expense(t)[source]#

Expense margin

Expense margin is defined as the sum of premium loading, surrender charge and maintenance fees net of commissions and expenses.

The sum of the expense margin and mortality margin add up to the net cashflow.

margin_mortality(t)[source]#

Mortality margin

Mortality margin is defined coi() net of claims_over_av().

The sum of the expense margin and mortality margin add up to the net cashflow.

max_proj_len()#

The max of all projection lengths

Defined as max(proj_len())

See also

proj_len()

model_point()[source]#

Target model points

Returns as a DataFrame the model points to be in the scope of calculation. By default, this Cells returns the entire model_point_table_ext() without change. model_point_table_ext() is the extended model point table, which extends model_point_table by joining the columns in product_spec_table. Do not directly refer to model_point_table in this formula. To select model points, change this formula so that this Cells returns a DataFrame that contains only the selected model points.

Examples

To select only the model point 1:

def model_point():
    return model_point_table_ext().loc[1:1]

To select model points whose ages at entry are 40 or greater:

def model_point():
    return model_point_table[model_point_table_ext()["age_at_entry"] >= 40]

Note that the shape of the returned DataFrame must be the same as the original DataFrame, i.e. model_point_table_ext().

When selecting only one model point, make sure the returned object is a DataFrame, not a Series, as seen in the example above where model_point_table_ext().loc[1:1] is specified instead of model_point_table_ext().loc[1].

Be careful not to accidentally change the original table held in model_point_table_ext().

model_point_table_ext()[source]#

Extended model point table

Returns an extended model_point_table by joining product_spec_table on the spec_id column.

mort_rate(t)[source]#

Mortality rate to be applied at time t

Returns a Series of the mortality rates to be applied at time t. The index of the Series is point_id, copied from model_point().

mort_rate_mth(t)[source]#

Monthly mortality rate to be applied at time t

mort_table_last_age()[source]#

The last age of mortality tables

Returns the last age whose mortality rates are all 1. If no such age is found, return the last index of the tables

See also

mort_table_reindexed()[source]#

MultiIndexed mortality table

Returns a Series of mortlity rates reshaped from mort_table. The returned Series is indexed by age and duration capped at 5.

net_amt_at_risk(t)[source]#

Net amount at risk per policy

Return sum assured net of account value per policy.

net_cf(t)[source]#

Net cashflow

Net cashflow for the period from t to t+1 defined as:

premiums(t) - claims(t) - expenses(t) - commissions(t)
policy_term()[source]#

The policy term of the model points.

The policy_term column of the DataFrame returned by model_point().

pols_death(t)[source]#

Number of death

Number of policies decreased by death between t and t+1

pols_if(t)[source]#

Number of policies in-force

pols_if(t) is an alias for pols_if_at(t, "BEF_MAT").

See also

pols_if_at(t, timing)[source]#

Number of policies in-force

pols_if_at(t, timing) calculates the number of policies in-force at time t. The second parameter timing takes a string value to indicate the timing of in-force, which is either "BEF_MAT", "BEF_NB" or "BEF_DECR".

BEF_MAT

The number of policies in-force before maturity after lapse and death. At time 0, the value is read from pols_if_init(). For time > 0, defined as:

pols_if_at(t-1, "BEF_DECR") - pols_lapse(t-1) - pols_death(t-1)

BEF_NB

The number of policies in-force before new business after maturity. Defined as:

pols_if_at(t, "BEF_MAT") - pols_maturity(t)

BEF_DECR

The number of policies in-force before lapse and death after new business. Defined as:

pols_if_at(t, "BEF_NB") + pols_new_biz(t)
pols_if_init()[source]#

Initial number of policies in-force

Number of in-force policies at time 0 referenced from pols_if_at(0, "BEF_MAT").

pols_lapse(t)[source]#

Number of lapse

Number of policies decreased by lapse during t and t+1.

pols_maturity(t)[source]#

Number of maturing policies

The policy maturity occurs when duration_mth() equals 12 times policy_term(). The amount is equal to pols_if_at(t, "BEF_MAT").

otherwise 0.

pols_new_biz(t)[source]#

Number of new business policies

The number of new business policies. The value duration_mth(0) for the selected model point is read from the policy_count column in model_point(). If the value is 0 or negative, the model point is new business at t=0 or at t when duration_mth(t) is 0, and the pols_new_biz(t) is read from the policy_count in model_point().

See also

prem_to_av(t)[source]#

Premium portion put in account value

The amount of premiums net of loadings, which is put in the accoutn value.

prem_to_av_pp(t)[source]#

Per-policy premium portion put in the account value

The amount of premium per policy net of loading, which is put in the accoutn value.

premium_pp(t)[source]#

Premium amount per policy

Single premium amount if premium_type() is "SINGLE", monthly premium amount if premium_type() is "LEVEL".

premium_type()[source]#

Type of premium payment

Returns a string indicating the payment type, which is either "LEVEL" if level payment, or "SINGLE" if single payment.

premiums(t)[source]#

Premium income

Premium income during the period from t to t+1 defined as:

premium_pp() * pols_if_at(t, "BEF_DECR")
proj_len()[source]#

Projection length in months

proj_len() returns how many months the projection for each model point should be carried out for all the model point. Defined as:

np.maximum(12 * policy_term() - duration_mth(0) + 1, 0)

Since this model carries out projections for all the model points simultaneously, the projections are actually carried out from 0 to max_proj_len for all the model points.

pv_av_change()[source]#

Present value of change in account value

pv_claims(kind=None)[source]#

Present value of claims

See claims() for the parameter kind.

pv_claims_from_av(kind=None)[source]#

Present value of claims

See claims() for the parameter kind.

pv_claims_over_av(kind=None)[source]#

Present value of claims

See claims() for the parameter kind.

pv_commissions()[source]#

Present value of commissions

pv_expenses()[source]#

Present value of expenses

pv_inv_income()[source]#

Present value of investment income

The discounted sum of monthly investment income.

pv_net_cf()[source]#

Present value of net cashflows.

Defined as:

pv_premiums() + pv_inv_income()
- pv_claims() - pv_expenses() - pv_commissions() - pv_av_change()
pv_pols_if()[source]#

Present value of policies in-force

Note

This cells is not used by default.

The discounted sum of the number of in-force policies at each month. It is used as the annuity factor for calculating net_premium_pp().

pv_premiums()[source]#

Present value of premiums

result_cf()[source]#

Result table of cashflows

result_pols()[source]#

Result table of policy decrement

result_pv()[source]#

Result table of present value of cashflows

scen_index()[source]#

Scenario IDs from the ESG space: 0 is the CE scenario, 1 to N are stochastic

model_point() repeats every model point for each of these scenarios.

Returns:

pandas.RangeIndex named scen_id

sex()[source]#

The sex of the model points

Note

This cells is not used by default.

The sex column of the DataFrame returned by model_point().

sum_assured()[source]#

The sum assured of the model points

The sum_assured column of the DataFrame returned by model_point().

surr_charge(t)[source]#

Surrender charge

Surrender charge rate times account values of lapsed policies

surr_charge_id()[source]#

ID of surrender charge pattern

A string to indicate the ID of the surrender charge pattern. The ID should be one of the column names in surr_charge_table if has_surr_charge() is True.

surr_charge_max_idx()[source]#

maximum index of surrender charge table

The maximum index(duration) of surr_charge_table.

surr_charge_rate(t)[source]#

Surrender charge rate

Surrender charge rate to be applied for lapsed policies

surr_charge_table_stacked()[source]#

Stacked surrender charge table

surr_charge_table converted to a Series indexed with surrender charge ID and duration.

result_tvog()[source]#

Time value of options and guarantees (TVOG) by model point

For the GMAB cost (pv_claims_over_av("MATURITY")), the GMDB cost (pv_claims_over_av("DEATH")) and the present value of net cash flows (pv_net_cf()):

  • CE: the present value in the CE scenario (scen_id 0),

  • mean: the mean over the stochastic scenarios 1 to N,

  • TVOG: mean - CE,

  • SE: the standard error of mean, from antithetic pair means when the ESG uses antithetic variates.

Returns:

pandas.DataFrame indexed by point_id, with columns (measure, statistic)

formula_gmab_g2pp(t)[source]#

Closed-form GMAB cost of the single-premium model points maturing at month t

For a single-premium policy with no fees or decrements, whose fund is all cash or holds zero-coupon bonds of a single maturity, \(\ln D(T)\) and the log of the deflated account value are jointly Gaussian, and the exchange-option formula gives

\[PV = SA\,P^M(0, T)\,\Phi(d_1) - AV_0\,\Phi(d_1 - s), \quad d_1 = \frac{\ln(SA\,P^M(0, T)/AV_0) + s^2/2}{s}\]

where SA is the sum assured of the policies maturing at \(T = t/12\), \(AV_0\) their account value after the premium at time 0 (av_at(0, "BEF_FEE")) and \(s^2\) the variance of \(\ln(AV(T)/AV_0)\), esg.fund_logvar(t). For an all-cash fund this is EX1’s Black-Scholes put (formula_option_put) with \(e^{-rT}\) replaced by \(P^M(0, T)\) and \(\sigma^2 T\) by \(V(0, T)\). esg.fund_logvar raises ValueError for a fund with several maturities, which has no exact closed form.

Returns:

pandas.Series indexed by point_id of the single-premium points maturing at t