The Data Space#

Input data shared by every by-policy projection.

The eight input CSVs are read here, once per model, and referenced from Projection as data. Projection is parameterized by idx, the position of a model point in the table, so each Projection[i] is a separate ItemSpace with its own cells cache; if the readers lived there, every model point would re-read every file. Holding them in an unparameterized Space reads each file once no matter how many policies are projected.

Inputs are external files: plain CSVs in the model folder’s parent directory, products/indexed_ul/, rather than data stored inside the model. The model folder therefore holds nothing but formulas – no _data/, no IOSpec, no embedded values – so a diff of the model shows logic changes only. This follows annuallife.TradLife_A; contrast basiclife.BasicTerm_S, which keeps its inputs inside the model through modelx’s IOSpec machinery.

The consequence worth knowing: the model is not portable on its own. Copying the IUL_US_SEC folder without its parent’s CSVs produces a model that reads and then fails on first evaluation.

Six of the tables are IUL_US_S’s. The guaranteed COI scale, the corridor factors, the mortality table, the class factors, the lapse table and the surrender charge schedules are the files IUL_US_S reads, read here in place: one copy of each table serves both models, so an edit to one reaches both. The model point table and the segment ladder are this model’s own, model_point_table_sec.csv and inforce_segments_sec.csv; the first sits beside IUL_US_S’s model_point_table.csv, which this model never opens.

input_dir() resolves the directory from _model.path.parent at run time, so the model works wherever the repository is checked out. Each table has a filename Reference and a reader Cells:

Reference

Cells

File

model_point_file

model_point_table()

model_point_table_sec.csv

inforce_segments_file

inforce_segments()

inforce_segments_sec.csv

coi_rates_file

coi_rates()

coi_rates.csv

corridor_file

corridor_factors()

corridor_factors.csv

mort_table_file

mort_table()

mort_table.csv

class_factor_file

class_factor_table()

class_factor_table.csv

lapse_table_file

lapse_table()

lapse_table.csv

surr_charge_file

surr_charge_table()

surr_charge_table.csv

The model point table is checked as it is read. Ten of its columns are the in-force interface: policy_count and duration_mth, as in basiclife.BasicTerm_SE, and eight columns of an in-force policy’s opening state, the account value and the loan, which are IUL_US_S’s own, the fixed account and the loan collateral apart from the loan, the face in force, the premiums paid to date, the no-lapse accumulator and the MEC latch. model_point_table() refuses a table that lacks any of them, or any column of IUL_US_S’s own that the projection reads as a number or a flag, repeats a point_id, holds a count, a duration, an age, a policy year or an amount no policy can have, a share of the premium or of the fixed account outside 0 to 1, a flag that is not True or False, or an opening state no policy can be in. The checks run in turn, by 20 rules, and the first that fails raises, naming the missing column or every point that fails it. It also refuses a policy to be issued more than future_horizon_mth months after the valuation date, 120 months as shipped: future new business is written over a stated horizon, so that no frame runs longer than the projection from issue plus that horizon. Set to 0, the Reference refuses future new business altogether. Whether a point is still inside the projection at the valuation date, issued at an age with any cover, withdrawing less than its fee, or holding one ladder row for each live segment is a rule of the product rather than of the table, and Projection.proj_len checks it.

So is the segment ladder. IUL_US_S opens a point with no live segment, its whole account value outside the collateral in the fixed account, which re-opening a policy in force restates wrongly. So each live segment of a point in force is a row of inforce_segments_sec.csv, keyed by point_id and slot, the months since the segment’s creation at the valuation date, with its balance, the deductions and draws charged to it, the index level at its creation and the cap declared then. inforce_segments() refuses a row that names no point of the table, repeats a slot, has a slot outside its point’s life, or holds a value no segment can, and a point whose account value is not its fixed account, its collateral and its segments, to the cent. inforce_segment_count() and inforce_segment_last() give each point’s row count and last slot, which Projection.proj_len holds to the segments a policy in force holds, one a month for its last twelve.

So are the six assumption tables. Each table read at an attained age or a policy year has one reader in Projection, keyed by the age or the year, and that reader takes the table’s extent – the first and last ages, or the last policy year, beyond which it reads the nearest row – from a cell here that reads the key column by value, once, and checks the table: corridor_age_first() and corridor_age_last(), mort_age_first() and mort_age_last(), lapse_last_year(), and, for the COI scale, whose issue-age cells are numbered as schedules, coi_schedules(), which every COI vector asks first. A key that is blank, text or not a whole number is refused, naming the file, the column and the lines it is on, and so is an age below 0 in the corridor and mortality tables, since each is indexed by the age. So are keys that do not run one row an age or a year, without a gap or a repeat, policy years from 1, the message naming each key that repeats, with its lines, and each that is missing. And so is a rate that is blank, text or infinite, naming the column and its lines, and a lapse or mortality rate outside 0 to 1: each is a probability, and the monthly rate 1 - (1 - q)^(1/12) has no real value past 1. class_count() and surr_charge_count() check the class factors and the surrender-charge schedules the same way, for the per-point joins that read them, and surr_charge_count() refuses a run-off that is not a whole number of years, 1 or more, which the projection divides by. A class factor, a guaranteed COI rate and a surrender charge below 0 are refused too: each would project, with every check passing, a negative death, a credit for the insurance, or a surrender charge that rises once its schedule has run off. So is a corridor factor below 0, which no statutory percentage is, and which IUL_US_S’s death benefit, the max of the face and the corridor’s amount with no floor on the account value, would turn above the face on an exhausted account. Each reader asks for its extent or its count before it reads a value, so a projection meets the checks first.

IUL_US_S’s readers take each extent from the key column as pandas reads it, where a blank key is a missing value the extent skips: the table is cut short, and every later age or year reads the last good row, without a word. A blank value is a missing value to it too, which shows in its flows or is lost in a min or a max: a blank lapse rate reaches the lapse cap’s min and is read as the cap, a blank corridor factor reads as no corridor, and a blank surrender charge as none. Here each is refused, by name, and so is a blank, text or infinite amount in the model point table.

coi_rates.csv carries the guaranteed maximum monthly rate per $1,000 of net amount at risk; the notes set that basis at 2017 CSO ANB ultimate [REG-R17], which may not be reproduced here, and the current scale is the guaranteed scale times Projection.coi_curr_factor (65% [std]) because carrier COI tables are not public. mort_table.csv is a small illustrative best-estimate table [std], not the 2015 VBT the notes recommend [REG-R18]; it is the same illustrative table shipped with UL_US_S, so the chassis and this model share a basis.

There is deliberately no premium persistency table. The universal life chassis reads one, because its notes give a 16-row schedule; these notes instead give a closed form – expected premium_y = planned x 0.98^(y-1) – which is implemented as prem_persistency() with the rate in a Reference. Nor is there an index scenario file: the base deterministic run generates index_level() from a level annual return on the valuation clock, and a stochastic or historical path is substituted by overriding that one cell, a formula override, which only modelx can make; compiled, the path is changed by editing the formula and rebuilding.

To swap in a licensed mortality basis, replace mort_table.csv with a same-schema file, or point mort_table_file at a different name before the model computes anything: a compiled model clears no cache, so there the name is set on a package just imported, before anything is read. No formula changes. Replacing the file changes IUL_US_S too, which reads the same one.

The vectors. The readers return what the files hold, and no Projection cell but model_point, a reporting cell, reads them. The others read the arrays below instead, one element at a time, a model point’s attribute being the element at its position, data.sum_assured()[idx]. That is what lets the model compile to C, as basiclife.BasicTerm_SC does: each array is a numpy vector or table of int64 or float64, which compiles to a typed memoryview, never one of bools, objects or text, and each count or extent is an int.

Text the projection needs is decoded here, into the number it selects: each value of the death benefit option, the qualification test, the premium pattern and the premium mode a monthly cell branches on into a 0/1 flag, and the surrender-charge flag into another. Each table keyed by more than a number becomes an integer-indexed array or a join. The COI scales, keyed by sex, class and issue age, are numbered, each point carrying the number of its own, and tabled by schedule and policy year. The lapse table is held by policy year, the corridor and mortality tables by attained age, each padded from 0, so that the year or the age is the index. The segment ladder, keyed by point and slot, is held by the point’s position and the slot, so that the slot is the column. The class factor and the surrender-charge schedule, each one number a point, are joined to the points:

Cells

dtype

Shape

From

point_id()

int64

[point]

the table’s index

age_at_entry()

int64

[point]

age_at_entry

duration_mth()

int64

[point]

duration_mth

wd_first_year()

int64

[point]

wd_first_year

loan_first_year()

int64

[point]

loan_first_year

is_mec_init()

int64

[point]

is_mec_init, by value

has_surr_charge()

int64

[point]

has_surr_charge, 1 on True

is_db_option_a()

int64

[point]

db_option, 1 on A

is_db_option_b()

int64

[point]

db_option, 1 on B

is_gpt()

int64

[point]

qual_test, 1 on GPT

is_level_premium()

int64

[point]

premium_type, 1 on LEVEL

is_single_premium()

int64

[point]

premium_type, 1 on SINGLE

is_target_premium()

int64

[point]

premium_type, 1 on TARGET

is_annual_premium()

int64

[point]

premium_mode, 1 on ANNUAL

is_monthly_premium()

int64

[point]

premium_mode, 1 on MONTHLY

sum_assured()

float64

[point]

sum_assured

policy_count()

float64

[point]

policy_count

premium_pp_ann()

float64

[point]

premium_pp_ann

wd_pp()

float64

[point]

wd_pp

loan_new_pp_ann()

float64

[point]

loan_new_pp_ann

mnlp_rate()

float64

[point]

mnlp_rate

gsp()

float64

[point]

gsp

glp()

float64

[point]

glp

seven_pay_prem()

float64

[point]

seven_pay_prem

load_prem_rate()

float64

[point]

load_prem_rate

index_alloc_rate()

float64

[point]

index_alloc_rate

av_pp_init()

float64

[point]

av_pp_init

loan_bal_init()

float64

[point]

loan_bal_init

fa_pp_init()

float64

[point]

fa_pp_init

lca_pp_init()

float64

[point]

lca_pp_init

sum_assured_init()

float64

[point]

sum_assured_init

cum_prem_init()

float64

[point]

cum_prem_init

cum_prem_net_init()

float64

[point]

cum_prem_net_init

class_factor()

float64

[point]

class_factor_table.csv, joined

surr_charge_rate_max()

float64

[point]

surr_charge_table.csv, joined

surr_charge_runoff_years()

float64

[point]

surr_charge_table.csv, joined

has_surr_charge_schedule()

int64

[point]

the same, 1 where the table holds the id

coi_schedules()

int

scalar

coi_rates.csv, checked

coi_schedule()

int64

[point]

sex, class and issue age, joined

coi_rate_last_years()

int64

[schedule]

coi_rates.csv

coi_rate_array()

float64

[schedule, y]

coi_rates.csv

lapse_rate_array()

float64

[y]

lapse_table.csv

corridor_factor_array()

float64

[age]

corridor_factors.csv

mort_table_array()

float64

[age]

mort_table.csv

inforce_segment_count()

int64

[point]

inforce_segments_sec.csv

inforce_segment_last()

int64

[point]

inforce_segments_sec.csv

inforce_segment_max()

int

scalar

inforce_segments_sec.csv, checked

seg_bal_pp_init()

float64

[point, slot]

inforce_segments_sec.csv

seg_ded_cum_pp_init()

float64

[point, slot]

inforce_segments_sec.csv

seg_wd_cum_pp_init()

float64

[point, slot]

inforce_segments_sec.csv

seg_index_start_init()

float64

[point, slot]

inforce_segments_sec.csv

seg_index_cap_init()

float64

[point, slot]

inforce_segments_sec.csv

The table checks are the ints they were: lapse_last_year(), the four age extents, class_count() and surr_charge_count(). The COI table’s check, which at stage E returned a Series of last policy years by cell, is the int coi_schedules(), holding every message it held, and inforce_segment_count() and inforce_segment_last(), which at stage E were Series by point_id, are vectors by position.

An array is read by element, never whole, in this Space as in Projection. The compiler types an array cell as a memoryview only once it has seen that every use of it, in either Space, is an element read: one len(), slice, loop over it or numpy call on it anywhere, and the cell compiles as a Python object. So an array derived here from another reads the table’s column or the reader’s frame, and a width comes from a table or a check, never from another cell’s array. Each table’s check is one cell that every array, extent and schedule number of the table reads first, coi_schedules() for the COI scale and inforce_segment_max() for the ladder, so that a projection, which reads an extent or a schedule number first, meets the same refusal as a reader of the array. The column keywords of a DataFrame.assign are passed as **{...}, since a keyword named as a cell of this Space, age_at_entry, point_id, would be rewritten by the export.

What cannot be decoded or joined is refused when the array is first read, naming every point at fault: a point_id that is not a whole number; a rate_class the class factors lack; and on a point that has_surr_charge a surr_charge_id the schedules lack, or one whose runoff_years is 2**53 or more. IUL_US_S fails every projection of a point of the first two kinds, since it reads its class factor in its first month in cover, and of the third its cash flows, which read the schedule in every month of a point with a charge; here that refusal is the table’s, so every point is refused with it, as Term_US_SEC’s refusals at the first read are. A point without a charge is never refused a projection for its schedule, whatever its id, as IUL_US_S never reads it: its schedule is read where the table holds its id, as at stage E, and where it does not, Projection.surr_charge_rate_max raises stage E’s ValueError. A sex, rate_class and age_at_entry the COI scale lacks is schedule 0, and Projection.coi_rate_last_year refuses it where a rate is read, which a point valued at or past charges_cease_age never does. A value of db_option, qual_test, premium_type or premium_mode none of the flags names is no flag, and the cell that branches on it raises IUL_US_S’s message, as in IUL_US_S. Every decode and join compares the text exactly, as IUL_US_S does, so "level" or "GPT " is not "LEVEL" or "GPT". A read beyond a table’s extent is refused where IUL_US_S’s lookup raised KeyError, by the one Projection cell that reads the table, naming the point: a policy year below 1 in lapse_rate_base_py and coi_rate_guar_py, and a slot the point does not hold in the five ladder readers. An age outside the corridor or mortality table reads the nearest row, as in IUL_US_S, so no padding is read.

A table is held from age or year 0 to its last key, so a key far past any a policy reaches, an age of 10**9 say, makes an array of that many elements, where IUL_US_S reads the row without one. No rule bounds the keys from above: a table’s last key is its own, and each shipped table ends at an age or a year the projection reaches. The ladder is as wide as the most segments one point holds, not as its largest slot, so a row in a far slot refuses only its own point (inforce_segment_max()).

An int64 holds what it is read from. A float past int64 casts to the least int64 without a word, so a number read into an int64 vector is first refused unless it is below 2**53 in size, where the int64 holds IUL_US_S’s reading of it: the issue age, duration_mth and the first years of the withdrawal and the loan (model_point_table()’s rules 4, 6 and 7) and the point_id (point_id()). modelx and the compiled model refuse alike, before any cast. The run-off of a charged point’s schedule, which Projection.lapse_shock_year takes the int() of, is held below 2**53 years by the join. Every other number is read into a float64, as IUL_US_S reads it.

Cells Descriptions#

input_dir()[source]#

The directory holding the input CSVs: the model folder’s parent.

Inputs are external files, not data stored inside the model, so the model folder is pure formulas. The path is resolved at run time from where the model was read, following annuallife.TradLife_A.

model_point_table()[source]#

The model point table, read from model_point_table_sec.csv and checked.

Indexed by point_id. Ten columns are the in-force interface: policy_count and duration_mth, the completed policy months at the valuation date, as in basiclife.BasicTerm_SE; and eight columns of the opening state, per policy, as the policy stands at the start of month 0, before any month-0 event:

  • av_pp_init and loan_bal_init: the account value and the loan entering month 0, IUL_US_S’s own columns;

  • fa_pp_init and lca_pp_init: the fixed (holding) account and the loan collateral account entering month 0, which IUL_US_S takes as the account value less the loan and as the loan;

  • sum_assured_init: the face in force entering month 0, after every Option A withdrawal cut to date;

  • cum_prem_init and cum_prem_net_init: the premiums less withdrawals paid to date, and the same less loans, the no-lapse guarantee’s accumulator, each of which IUL_US_S opens at 0;

  • is_mec_init: 1 where the 7-pay test failed before the valuation date, 0 otherwise, an int code.

The live index segments are the companion inforce_segments(). The rest are IUL_US_S’s, except row_kind, source_policy_id and source_mth, which record where the generator took each shipped row from and which no formula reads.

The checks run over the whole table at once, by 20 rules in turn, and the first that fails raises ValueError, naming the missing column or every point it fails on:

  1. the in-force columns are present, and so are the columns of IUL_US_S’s own that the projection reads as a number or a flag: age_at_entry, wd_first_year, loan_first_year, sum_assured, premium_pp_ann, wd_pp, loan_new_pp_ann, mnlp_rate, gsp, glp, seven_pay_prem, load_prem_rate, index_alloc_rate and the flag has_surr_charge;

  2. no point_id appears twice;

  3. policy_count is a number, zero or more;

  4. duration_mth is a whole number of months: positive for a policy in force, 0 for one issued at the valuation date, negative for one issued later; and below 2**53 months in size, where its int64 vector holds it (the Space docstring);

  5. no policy is issued more than future_horizon_mth months after the valuation date, so duration_mth is -future_horizon_mth or more. At 0 the model takes no future new business, and the message says so; a negative horizon is itself refused;

  6. age_at_entry is a whole number of years, 0 or more: the projection counts its frame and every attained age on it. And it is below 2**53 in size, where its int64 vector holds it. A fraction is refused, as at stage E; an age the contract does not issue is Projection.proj_len’s to refuse;

  7. each of wd_first_year and loan_first_year is a whole number of policy years, 1 or more: IUL_US_S takes the int() of each and compares the policy year with it, so a fraction would move the first year without a word. And each is below 2**53 years, where its int64 vector holds it;

  8. sum_assured is a number above 0, the face at issue, which every policy holds: it reaches the death benefit’s max, the per-unit charge and the surrender charge, and a blank one would reach them as a missing value;

  9. each of premium_pp_ann, wd_pp, loan_new_pp_ann, mnlp_rate, gsp, glp and seven_pay_prem is a number, zero or more: gsp and glp are read by the guideline limit’s max and the single premium’s min, which a blank one would be lost in;

  10. load_prem_rate and index_alloc_rate, the share of each premium the load takes and the share of the fixed account each month’s sweep moves into a segment, are numbers from 0 to 1;

  11. has_surr_charge is True or False, as pandas reads those words in any case. A blank, a number or any other text is refused: one text value turns the whole column into text, where "False" is a true string, so every point would read as carrying a surrender charge;

  12. each of av_pp_init and fa_pp_init is a number, of either sign. IUL_US_S lapses no policy for insufficiency and charges an exhausted policy on, its fixed account carrying every deduction and draw the segments cannot, so the fixed account and then the account value run below zero, as its point 5’s do, from policy months 383 and 604; a model restating IUL_US_S restates those states, and inforce_segments() holds the two together;

  13. each of lca_pp_init, loan_bal_init and sum_assured_init is a number, zero or more. The face in force may be 0: withdrawals under Option A can cut it to nothing while the policy stays in force, as IUL_US_S carries it;

  14. each of cum_prem_init and cum_prem_net_init is a number, of either sign: each is a tax or guarantee measure, not a balance, and withdrawals and loans can exceed the premiums paid;

  15. is_mec_init is 0 or 1, an int code, read by value, so that 1.0 is 1;

  16. a policy not yet in force, duration_mth 0 or less, has no opening state: each of the eight columns is 0, and the issue values come from the formulas;

  17. sum_assured_init is at most sum_assured, the face at issue, on a policy in force, since face increases are not modelled. A face below it is accepted, whether a withdrawal cut it or an elective decrease the model does not implement, and is projected from the value given;

  18. lca_pp_init is above 0 exactly where loan_bal_init is: a standard loan moves value into the collateral account on the day it is taken, and the model takes no repayment, so the two are held together from the loan’s first day, each at its own rate;

  19. cum_prem_net_init is at most cum_prem_init, to a cent and a half – half a cent for each of the two and half a cent more – since loans only lower it;

  20. is_mec_init is 1 where the 7-pay test has already failed in the month before the valuation date: cum_prem_init above seven_pay_prem times the policy years to date, inside the first seven.

The text columns sex, rate_class, db_option, qual_test, premium_type, premium_mode and surr_charge_id are keys and labels, which the projection decodes or joins on at their first read, naming the point where none fits.

inforce_segments()[source]#

The live index segments of each point in force, from inforce_segments_sec.csv.

Indexed by point_id and slot, both read by value as ints. One row per live segment of a point in force at the valuation date, as it stands entering month 0: slot is the months since the segment’s creation at the valuation date, 1 to 12, so the segment in slot k was born in policy month duration_mth - k, and the one in slot 12 matures at t = 0. Its columns, per policy:

  • seg_bal_pp_init: the segment’s balance;

  • seg_ded_cum_pp_init and seg_wd_cum_pp_init: the monthly deductions, and the withdrawals and loan transfers, charged to it since its creation, which with the balance are its credit base;

  • seg_index_start_init: the index level at its creation, on the valuation-clock path, whose level at the valuation date is Projection.index_level_init;

  • seg_index_cap_init: the cap declared at its creation.

point_id is the only key to a point, and nothing else in the file names one. A point not yet in force holds no row; a point in force holds one for each of its last min(12, duration_mth) months, a month that swept nothing included, which Projection.proj_len checks, since the twelve is Projection.seg_term_mth.

The checks run over the whole file at once, by 9 rules in turn, and the first that fails raises ValueError, naming the missing column or the lines, the header line 1, or the points it fails on:

  1. the seven columns are present;

  2. each of point_id and slot is a whole number, below 2**53 in size, which numpy would otherwise cast to the least int64 without a word;

  3. each point_id is a point of model_point_table();

  4. no point_id and slot appear together twice;

  5. slot is from 1 to its point’s duration_mth: no segment predates issue, and a point not yet in force holds none;

  6. each of seg_bal_pp_init, seg_ded_cum_pp_init and seg_wd_cum_pp_init is a number, -1e-8 or more: a balance a draw or a deduction took to exactly nothing can close on a rounding about zero of either sign, which an extract carried to the cent writes as 0, and Projection.check_seg_ladder holds every live balance to the same -1e-8, IUL_US_S’s tolerance;

  7. seg_index_start_init is a number above 0, the level the segment’s return divides by;

  8. seg_index_cap_init is a number, zero or more: the credited rate’s min reads the cap first, so a blank cap would credit the floor without a word;

  9. each point’s av_pp_init is its fa_pp_init plus its lca_pp_init plus the balances of its segments here, to half a cent an amount and half a cent more: the identity Projection.check_av_components holds every month, the opening state being the close of the month before. The projection opens the account value from the parts, so the column is held to them, not read.

inforce_segment_count()[source]#

The number of live segments inforce_segments_sec.csv holds for each point: int64 [point].

Element i is the count of the table’s point at position i, 0 where the file holds none, read from inforce_segments(), which checks the file first. Projection.proj_len holds it, with inforce_segment_last(), to the segments a policy in force holds: one for each of its last min(seg_term_mth, duration_mth) months. At stage E it was a Series by point_id; it is a vector here, read at the point’s position, as every vector is.

inforce_segment_last()[source]#

The last slot inforce_segments_sec.csv holds for each point: int64 [point].

Element i is the last slot of the table’s point at position i, 0 where the file holds no segment, read from inforce_segments(), which checks the file first and refuses a slot below 1 or held twice. So a point whose last slot equals its count holds slots 1 to that count, one each, which is what Projection.proj_len asks.

inforce_segment_max()[source]#

The most segments any one point holds in inforce_segments_sec.csv, 0 if none.

Read from inforce_segments(), which checks the file first: the ladder’s check, an int, which each ladder array asks bare, and one less than their width, so that a slot is its own column. It counts rows, not slots: a point Projection.proj_len projects holds slots 1 to its count, so its every slot is a column, and a row in a slot past the widest count belongs to a point holding a gap, which proj_len refuses before any of its slots is read. So the width is bounded by the file’s length, not by the largest slot a row may name: a slot of 10**9 on a point in force that long refuses that point, by name, where an array that wide would refuse every point, out of memory, at its first read. 12 on the shipped ladder, Projection.seg_term_mth, which Data cannot read.

coi_rates()[source]#

Guaranteed maximum monthly COI rates, read from coi_rates.csv.

Per $1,000 of net amount at risk, keyed by issue-age cell and policy year.

corridor_factors()[source]#

The GPT corridor factor table by attained age, read from corridor_factors.csv.

The IRC 7702(d)(2) applicable percentages [R4]: 250% to attained age 40, grading to 100% at 90-95.

mort_table()[source]#

The best-estimate annual mortality table by age, read from mort_table.csv.

class_factor_table()[source]#

The underwriting-class factors, read from class_factor_table.csv.

lapse_table()[source]#

The base annual lapse rates by policy year, read from lapse_table.csv.

surr_charge_table()[source]#

The surrender charge schedules, read from surr_charge_table.csv.

One row per surr_charge_id, giving the initial charge per $1,000 of initial face and the number of years over which it runs off linearly.

coi_schedules()[source]#

The number of issue-age cells coi_rates.csv gives a scale for, the table checked.

One schedule a cell, each sex, rate_class and age_at_entry the table holds: coi_rate_array() holds each schedule in a row, numbered from 1 in the order of those keys, coi_rate_last_years() each schedule’s last policy year, and coi_schedule() gives each point its number. The table’s one check, which each of them asks first. The two text keys may not be blank, and the two numeric keys, age_at_entry and policy_year, are read by value, once: a key that is blank, text or not a whole number is refused, naming the file, the column and the lines it is on. So is a cell whose policy years do not run from 1, one row a year, without a gap or a repeat: the message names the cell, each year that repeats or falls below 1, with its lines, and each year missing from 1 to the last. And so is a coi_rate_guar that is blank, text, infinite or below 0, naming its lines: a charge per $1,000 of net amount at risk, which may pass 1, as the current scale does from attained age 69, but is never a credit. Projection.coi_rate_last_year takes a point’s extent from coi_rate_last_years(), and refuses a point whose cell the table lacks, before Projection.coi_rate_guar_py reads its scale, so a projection meets the checks first.

At stage E this check was coi_rate_last_years(), which returned the last years as a Series by cell; a check is an int here, the number of schedules, and the arrays ask it, so every message is the one it was.

corridor_age_last()[source]#

The last attained age corridor_factors.csv gives a factor for, the table checked.

The age column is read by value, once, so an age written 40.0 is 40. A key that is blank, text or not a whole number is refused, naming the file, the column and the lines it is on. So are ages that do not run one row an age, without a gap or a repeat: the message names each age that repeats, with its lines, and each age missing between the first and the last. And so is a corridor_factor that is blank, text, infinite or below 0, naming its lines: a multiple of the account value, which the statute’s applicable percentages hold to 100% or more. And so is an age below 0, naming its lines, since corridor_factor_array() is held from age 0, so that the age is the index; IUL_US_S reads such a row, which no projection reaches. Projection.corridor_factor_at, the table’s one reader, takes both of its extents, this and corridor_age_first(), before it reads a factor. A blank factor is a missing value to IUL_US_S, whose death benefit, the max of the face and the corridor’s amount, then reads it as no corridor at all. A factor below 1 only makes the corridor bind later, or never; below 0 it would make the corridor’s amount on an account value below 0 a positive one, which IUL_US_S’s death benefit, with no floor on the account value, would pay: at -0.5 from attained age 95, its point 5 pays 58,155,653.50 on a face of 92,200 at its month 800, every account check passing.

corridor_age_first()[source]#

The first attained age corridor_factors.csv gives a factor for.

Counted back from corridor_age_last(), which checks the table’s keys first: the ages run one row an age, so the first is the last less the rows after it.

mort_age_last()[source]#

The last attained age mort_table.csv gives a rate for, the table checked.

Read and checked as corridor_age_last() reads and checks its own table, the rate checked being mort_rate, which must also be from 0 to 1, as a probability, and an age below 0 refused, as there; the shipped table reaches 1.0 at attained age 119. Projection.mort_rate_base_at, the table’s one reader, takes both of its extents, this and mort_age_first(), before it reads a rate. A blank rate is a missing value to IUL_US_S, whose mortality is then not a number, and to Projection.mort_rate, whose cap, min(q, 1.0), keeps it missing; a negative one would project negative deaths.

mort_age_first()[source]#

The first attained age mort_table.csv gives a rate for.

Counted back from mort_age_last(), which checks the table’s keys first, as corridor_age_first() counts its own.

lapse_last_year()[source]#

The last policy year lapse_table.csv gives a rate for, the table checked.

The policy_year column is read by value, once, as the lookup matches it, so a year written 5.0 is year 5. A key that is blank, text or not a whole number is refused, naming the file, the column and the lines it is on. So are policy years that do not run from 1, one row a year, without a gap or a repeat: the message names each year that repeats or falls below 1, with its lines, and each year missing from 1 to the last. And so is a lapse_rate_ann that is blank, text or outside 0 to 1, naming its lines: a probability, which below 0 would grow the count by its lapses, and past 1 would leave Projection.lapse_rate_mth’s 1 - (1 - q)^(1/12) no real value. Projection.lapse_rate_base_py, the table’s one reader, takes its extent from here before it reads a rate. A blank rate is a missing value to IUL_US_S, which its lapse cap, min(lapse_rate_cap, rate), a bound written first, then reads as the cap.

class_count()[source]#

The number of classes class_factor_table.csv gives a factor for, the table checked.

A rate_class that is blank is refused, naming the file and the lines it is on, and so is one on more than one row, naming each such class with its lines; and so is a factor that is blank, text, infinite or below 0, naming its lines: a multiple of the base mortality, which below 0 would project negative deaths. Projection.class_factor, the table’s one reader, asks for the count before it reads a factor, so a projection meets the checks first. A blank factor is a missing value to IUL_US_S, whose mortality is then not a number, and to Projection.mort_rate, whose cap, min(q, 1.0), keeps it missing.

surr_charge_count()[source]#

The number of schedules surr_charge_table.csv gives, the table checked.

A surr_charge_id that is blank is refused, naming the file and the lines it is on, and so is one on more than one row, naming each such schedule with its lines. So is a sc_per_1000_init that is blank, text, infinite or below 0, naming its lines, and a runoff_years that is not a whole number of years, 1 or more – blank, text, infinite, a fraction or below 1 alike – naming its lines: the projection divides the charge by the run-off and counts policy years on it, where IUL_US_S divides by the float, takes the int() of a fraction for its lapse spike, and divides by zero at 0. Projection.surr_charge_rate_max and Projection.surr_charge_runoff_years, the table’s two readers, ask for the count before they read a value, so a projection meets the checks first. A blank charge is a missing value to IUL_US_S, whose surrender charge rate, the max of 0 and the charge left, then reads it as no charge at all. A charge below 0 leaves a charge below 0 through the schedule’s years, which the max reads as none, and after them, where the share of the run-off left turns negative, a charge above 0 that rises each month, every check passing.

coi_schedule()[source]#

The number of each model point’s guaranteed COI scale, in table order: int64 [point].

The point’s row of coi_rate_array(): the schedules of coi_rates.csv, one for each sex, rate_class and age_at_entry it holds, numbered from 1 in the order of those keys, as coi_rate_array() numbers its rows, whatever the order of the file’s lines. The point’s key is its sex, its rate_class and its age_at_entry, compared exactly, as IUL_US_S slices the scale. A point whose key the table lacks gets schedule 0, a row of padding, and is not refused here: IUL_US_S projects such a point while it reads no COI rate, as one valued at or past charges_cease_age never does, and Projection.coi_rate_last_year refuses it, naming it, when one is read. Asks coi_schedules() first, which checks the table.

coi_rate_last_years()[source]#

The last policy year of each guaranteed COI scale: int64 [schedule].

Element s is the last policy_year coi_rates.csv holds for schedule s, numbered as coi_schedule() numbers it, read by value once coi_schedules() has checked the table: 76 on the shipped anchor cell. 0 at element 0, schedule 0, which Projection.coi_rate_last_year refuses where it is read. At stage E this was the table’s check, a Series by cell; the check is coi_schedules() here.

coi_rate_array()[source]#

The guaranteed maximum monthly COI rates by schedule and policy year: float64 [schedule, y].

Row s is schedule s of coi_rates.csv, numbered from 1 in the order of its keys, sex, rate_class and age_at_entry, as coi_schedule() numbers it, and column y is policy year y, so that the year is the index: one more column than the table’s last policy year, one more row than its schedules. Per $1,000 of net amount at risk. NaN in row 0, schedule 0, which no point the table holds is given, in column 0, before any policy year, and past each schedule’s last year, all padding, which Projection.coi_rate_guar_py never reads: it refuses a year below 1 and a point of schedule 0, and reads a later year at the schedule’s last. Asks coi_schedules() first, which checks the table.

lapse_rate_array()[source]#

The base annual lapse rates by policy year: float64 [y].

Element y is the lapse_rate_ann of policy year y in lapse_table.csv, so that the year is the index, to the last year lapse_last_year() gives once it has checked the table. NaN at 0, before the first year, which Projection.lapse_rate_base_py never reads: it refuses a year below 1.

corridor_factor_array()[source]#

The GPT corridor factors by attained age: float64 [age].

Element a is the corridor_factor of age a in corridor_factors.csv, so that the age is the index, to the last age corridor_age_last() gives once it has checked the table, which refuses a negative age. NaN from 0 to below the first age, which Projection.corridor_factor_at never reads: it reads an age outside the table at the nearest row, as IUL_US_S does.

mort_table_array()[source]#

The best-estimate annual mortality rates by attained age: float64 [age].

Element a is the mort_rate of age a in mort_table.csv, held as corridor_factor_array() holds its own table, to the last age mort_age_last() gives. NaN from 0 to below the first age, which Projection.mort_rate_base_at never reads.

point_id()[source]#

The point_id of every model point, in table order: int64 [point].

Projection is indexed by position, idx, so this is how a projection names its point: Projection.point_id() is the element at idx, and every refusal quotes it. A label that is not a whole number is refused, naming every such label, and so is one of 2**53 or more in size, which numpy would read as the least int64 once past int64. pandas reads a column of whole labels as int64 exactly, so the bound refuses some labels the vector could hold, none of them a label a table needs.

age_at_entry()[source]#

The issue age (ANB) of every model point: int64 [point].

The age_at_entry column, which model_point_table() holds to a whole number below 2**53 in size, 0 or more.

duration_mth()[source]#

The completed policy months at the valuation date of every model point: int64 [point].

The duration_mth column, which model_point_table() holds to a whole number below 2**53 in size.

wd_first_year()[source]#

The first policy year of each model point’s withdrawals: int64 [point].

The wd_first_year column, which model_point_table() holds to a whole number of policy years, 1 or more, below 2**53.

loan_first_year()[source]#

The first policy year of each model point’s loans: int64 [point].

The loan_first_year column, which model_point_table() holds to a whole number of policy years, 1 or more, below 2**53.

is_mec_init()[source]#

Whether each model point is a MEC entering month 0: int64 [point].

The is_mec_init column, which model_point_table() holds to 0 or 1, an int code, read by value, so that 1.0 is 1.

has_surr_charge()[source]#

Whether a surrender charge schedule applies to each model point: int64 [point].

1 where the has_surr_charge column reads True, in any case, and 0 where it reads False: model_point_table() refuses any other value.

is_db_option_a()[source]#

Whether the death benefit option is A, the level face, for each model point: int64 [point].

1 where db_option is "A", compared element by element as IUL_US_S compares it, so that "a" or "A " is not, and 0 elsewhere. A value no flag of its column names is not refused here: it is no flag, and the projection cell that branches on the column raises IUL_US_S’s message on it, "invalid db_option".

is_db_option_b()[source]#

Whether the death benefit option is B, the face plus the account value, for each model point: int64 [point].

1 where db_option is "B", decoded as is_db_option_a() decodes A, and 0 elsewhere; a value no flag names raises "invalid db_option" where a projection branches on it.

is_gpt()[source]#

Whether the point elects the guideline premium test, for each model point: int64 [point].

1 where qual_test is "GPT", decoded as is_db_option_a() decodes A, and 0 elsewhere; a value no flag names raises "invalid qual_test" where a projection branches on it.

is_level_premium()[source]#

Whether the premium pattern is LEVEL, for each model point: int64 [point].

1 where premium_type is "LEVEL", decoded as is_db_option_a() decodes A, and 0 elsewhere; a value no flag names raises "invalid premium type" where a projection branches on it.

is_single_premium()[source]#

Whether the premium pattern is SINGLE, for each model point: int64 [point].

1 where premium_type is "SINGLE", decoded as is_db_option_a() decodes A, and 0 elsewhere; a value no flag names raises "invalid premium type" where a projection branches on it.

is_target_premium()[source]#

Whether the premium pattern is TARGET, for each model point: int64 [point].

1 where premium_type is "TARGET", decoded as is_db_option_a() decodes A, and 0 elsewhere; a value no flag names raises "invalid premium type" where a projection branches on it.

is_annual_premium()[source]#

Whether the premium mode is ANNUAL, for each model point: int64 [point].

1 where premium_mode is "ANNUAL", decoded as is_db_option_a() decodes A, and 0 elsewhere; a value no flag names raises "invalid premium mode" where a projection branches on it.

is_monthly_premium()[source]#

Whether the premium mode is MONTHLY, for each model point: int64 [point].

1 where premium_mode is "MONTHLY", decoded as is_db_option_a() decodes A, and 0 elsewhere; a value no flag names raises "invalid premium mode" where a projection branches on it.

sum_assured()[source]#

The face at issue of every model point: float64 [point].

The sum_assured column, which model_point_table() holds to a number above 0.

policy_count()[source]#

The policies each model point stands for: float64 [point].

The policy_count column, which model_point_table() holds to a number, zero or more.

premium_pp_ann()[source]#

The planned annual premium per policy of every model point: float64 [point].

The premium_pp_ann column, which model_point_table() holds to a number, zero or more.

wd_pp()[source]#

The planned monthly withdrawal per policy of every model point: float64 [point].

The wd_pp column, which model_point_table() holds to a number, zero or more. Projection.wd_pp_mth reads it, since Projection.wd_pp is the month’s withdrawal.

loan_new_pp_ann()[source]#

The planned annual loan per policy of every model point: float64 [point].

The loan_new_pp_ann column, which model_point_table() holds to a number, zero or more. Projection.loan_new_pp_ann reads it.

mnlp_rate()[source]#

The minimum no-lapse premium per $1,000 a year of every model point: float64 [point].

The mnlp_rate column, which model_point_table() holds to a number, zero or more.

gsp()[source]#

The guideline single premium of every model point: float64 [point].

The gsp column, which model_point_table() holds to a number, zero or more.

glp()[source]#

The guideline level premium of every model point: float64 [point].

The glp column, which model_point_table() holds to a number, zero or more.

seven_pay_prem()[source]#

The 7-pay premium of every model point: float64 [point].

The seven_pay_prem column, which model_point_table() holds to a number, zero or more.

load_prem_rate()[source]#

The current premium load of every model point: float64 [point].

The load_prem_rate column, which model_point_table() holds to a number from 0 to 1.

index_alloc_rate()[source]#

The indexed allocation share of every model point: float64 [point].

The index_alloc_rate column, which model_point_table() holds to a number from 0 to 1.

av_pp_init()[source]#

The account value per policy entering month 0: float64 [point].

The av_pp_init column, which model_point_table() holds to a number, of either sign.

loan_bal_init()[source]#

The loan per policy entering month 0: float64 [point].

The loan_bal_init column, which model_point_table() holds to a number, zero or more.

fa_pp_init()[source]#

The fixed account per policy entering month 0: float64 [point].

The fa_pp_init column, which model_point_table() holds to a number, of either sign.

lca_pp_init()[source]#

The loan collateral account per policy entering month 0: float64 [point].

The lca_pp_init column, which model_point_table() holds to a number, zero or more.

sum_assured_init()[source]#

The face in force per policy entering month 0: float64 [point].

The sum_assured_init column, which model_point_table() holds to a number, zero or more, at most sum_assured on a policy in force.

cum_prem_init()[source]#

The premiums less withdrawals paid per policy entering month 0: float64 [point].

The cum_prem_init column, which model_point_table() holds to a number, of either sign.

cum_prem_net_init()[source]#

The premiums less withdrawals and loans per policy entering month 0: float64 [point].

The cum_prem_net_init column, which model_point_table() holds to a number, of either sign.

class_factor()[source]#

The underwriting-class factor of each model point: float64 [point].

The factor class_factor_table.csv gives the point’s rate_class, compared exactly, once class_count() has checked the table. A point reads its class factor in its first month in cover, so IUL_US_S fails every projection of a point whose class the table lacks: such a point is refused here, at the first read, naming every such point, where stage E refused it, by name, at its own first read.

surr_charge_rate_max()[source]#

The surrender charge per $1,000 of initial face of each model point, before any of it runs off: float64 [point].

The sc_per_1000_init of the point’s surr_charge_id in surr_charge_table.csv, once surr_charge_count() has checked the table, on every point whose id the table holds, with a charge or without, as stage E’s accessor read it: a point without a charge reads its schedule, though no cell reads it there. NaN where the table lacks the id, and has_surr_charge_schedule() 0 there. The join refuses the table, naming every such point, only on a point with a charge, since IUL_US_S reads the schedule in every month of such a point’s cover: an id the table lacks, where IUL_US_S’s .loc raised KeyError; and a runoff_years of 2**53 years or more in size, the bound of every number read as an int, past which the compiled int() in Projection.lapse_shock_year would in time raise OverflowError. surr_charge_count() already refuses a run-off that is not a whole number of years, 1 or more, so the division by it never meets 0. A point without a charge whose id the table lacks projects, as in IUL_US_S, and Projection.surr_charge_rate_max raises stage E’s ValueError on it where it is read, which no projection does. The same checks run in surr_charge_runoff_years(), the join’s other vector, so that whichever a projection reads first refuses the point.

surr_charge_runoff_years()[source]#

The run-off, in policy years, of each model point’s surrender charge: float64 [point].

The runoff_years of the point’s surr_charge_id in surr_charge_table.csv, on every point whose id the table holds, NaN on a point without a charge whose id it lacks, joined and checked as surr_charge_rate_max() joins and checks the charge, with its refusals. A float, as IUL_US_S reads it, whole by the table’s check.

has_surr_charge_schedule()[source]#

Whether surr_charge_table.csv holds each model point’s schedule: int64 [point].

1 where the point’s surr_charge_id is a surr_charge_id of the table, compared exactly, as IUL_US_S’s .loc compares it, and 0 where it is not, blank included, once surr_charge_count() has checked the table. 0 only on a point without a charge, since surr_charge_rate_max() refuses the table where a point with a charge names an id it lacks: there Projection.surr_charge_rate_max and Projection.surr_charge_runoff_years raise stage E’s ValueError, naming the point.

seg_bal_pp_init()[source]#

The balance of each live segment entering month 0, by point and slot: float64 [point, slot].

Row i is the table’s point at position i and column k its slot k of inforce_segments_sec.csv, the column seg_bal_pp_init, per policy, so that the slot is the index: inforce_segment_max() plus one wide, 13 on the shipped ladder. NaN in column 0, which is no slot, and wherever the point holds no row, padding that Projection.seg_bal_pp_init never reads: it asks Projection.proj_len first, which refuses a point whose slots are not 1 to its count, one each, and then refuses a slot below 1 or past the point’s last. A row in a slot past the width belongs to such a point and is left out. The width is the file’s, not Projection.seg_term_mth, which Data cannot read, so a model run at another segment term reads a ladder written for it. Asks inforce_segment_max() first, which checks the file.

seg_ded_cum_pp_init()[source]#

The deductions charged to each live segment since its creation, by point and slot: float64 [point, slot].

The column seg_ded_cum_pp_init of inforce_segments_sec.csv, per policy, held as seg_bal_pp_init() holds the balance, and read only by Projection.seg_ded_cum_pp_init, after its checks.

seg_wd_cum_pp_init()[source]#

The draws out of each live segment since its creation, by point and slot: float64 [point, slot].

The column seg_wd_cum_pp_init of inforce_segments_sec.csv, per policy, held as seg_bal_pp_init() holds the balance, and read only by Projection.seg_wd_cum_pp_init, after its checks.

seg_index_start_init()[source]#

The index level at each live segment’s creation, by point and slot: float64 [point, slot].

The column seg_index_start_init of inforce_segments_sec.csv, per policy, held as seg_bal_pp_init() holds the balance, and read only by Projection.seg_index_start_init, after its checks.

seg_index_cap_init()[source]#

The cap declared at each live segment’s creation, by point and slot: float64 [point, slot].

The column seg_index_cap_init of inforce_segments_sec.csv, per policy, held as seg_bal_pp_init() holds the balance, and read only by Projection.seg_index_cap_init, after its checks.