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] |
|
duration_mth() |
int64 |
[point] |
|
wd_first_year() |
int64 |
[point] |
|
loan_first_year() |
int64 |
[point] |
|
is_mec_init() |
int64 |
[point] |
|
has_surr_charge() |
int64 |
[point] |
|
is_db_option_a() |
int64 |
[point] |
|
is_db_option_b() |
int64 |
[point] |
|
is_gpt() |
int64 |
[point] |
|
is_level_premium() |
int64 |
[point] |
|
is_single_premium() |
int64 |
[point] |
|
is_target_premium() |
int64 |
[point] |
|
is_annual_premium() |
int64 |
[point] |
|
is_monthly_premium() |
int64 |
[point] |
|
sum_assured() |
float64 |
[point] |
|
policy_count() |
float64 |
[point] |
|
premium_pp_ann() |
float64 |
[point] |
|
wd_pp() |
float64 |
[point] |
|
loan_new_pp_ann() |
float64 |
[point] |
|
mnlp_rate() |
float64 |
[point] |
|
gsp() |
float64 |
[point] |
|
glp() |
float64 |
[point] |
|
seven_pay_prem() |
float64 |
[point] |
|
load_prem_rate() |
float64 |
[point] |
|
index_alloc_rate() |
float64 |
[point] |
|
av_pp_init() |
float64 |
[point] |
|
loan_bal_init() |
float64 |
[point] |
|
fa_pp_init() |
float64 |
[point] |
|
lca_pp_init() |
float64 |
[point] |
|
sum_assured_init() |
float64 |
[point] |
|
cum_prem_init() |
float64 |
[point] |
|
cum_prem_net_init() |
float64 |
[point] |
|
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_countandduration_mth, the completed policy months at the valuation date, as inbasiclife.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_initandloan_bal_init: the account value and the loan entering month 0,IUL_US_S’s own columns;fa_pp_initandlca_pp_init: the fixed (holding) account and the loan collateral account entering month 0, whichIUL_US_Stakes 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_initandcum_prem_net_init: the premiums less withdrawals paid to date, and the same less loans, the no-lapse guarantee’s accumulator, each of whichIUL_US_Sopens 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 areIUL_US_S’s, exceptrow_kind,source_policy_idandsource_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: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_rateand the flaghas_surr_charge;no
point_idappears twice;policy_countis a number, zero or more;duration_mthis 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 below2**53months in size, where its int64 vector holds it (the Space docstring);no policy is issued more than
future_horizon_mthmonths after the valuation date, soduration_mthis-future_horizon_mthor more. At 0 the model takes no future new business, and the message says so; a negative horizon is itself refused;age_at_entryis a whole number of years, 0 or more: the projection counts its frame and every attained age on it. And it is below2**53in size, where its int64 vector holds it. A fraction is refused, as at stageE; an age the contract does not issue isProjection.proj_len’s to refuse;each of
wd_first_yearandloan_first_yearis a whole number of policy years, 1 or more:IUL_US_Stakes theint()of each and compares the policy year with it, so a fraction would move the first year without a word. And each is below2**53years, where its int64 vector holds it;sum_assuredis a number above 0, the face at issue, which every policy holds: it reaches the death benefit’smax, the per-unit charge and the surrender charge, and a blank one would reach them as a missing value;each of
premium_pp_ann,wd_pp,loan_new_pp_ann,mnlp_rate,gsp,glpandseven_pay_premis a number, zero or more:gspandglpare read by the guideline limit’smaxand the single premium’smin, which a blank one would be lost in;load_prem_rateandindex_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;has_surr_chargeisTrueorFalse, 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;each of
av_pp_initandfa_pp_initis a number, of either sign.IUL_US_Slapses 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 restatingIUL_US_Srestates those states, andinforce_segments()holds the two together;each of
lca_pp_init,loan_bal_initandsum_assured_initis 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, asIUL_US_Scarries it;each of
cum_prem_initandcum_prem_net_initis a number, of either sign: each is a tax or guarantee measure, not a balance, and withdrawals and loans can exceed the premiums paid;is_mec_initis 0 or 1, an int code, read by value, so that 1.0 is 1;a policy not yet in force,
duration_mth0 or less, has no opening state: each of the eight columns is 0, and the issue values come from the formulas;sum_assured_initis at mostsum_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;lca_pp_initis above 0 exactly whereloan_bal_initis: 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;cum_prem_net_initis at mostcum_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;is_mec_initis 1 where the 7-pay test has already failed in the month before the valuation date:cum_prem_initaboveseven_pay_premtimes the policy years to date, inside the first seven.
The text columns
sex,rate_class,db_option,qual_test,premium_type,premium_modeandsurr_charge_idare 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_idandslot, 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:slotis the months since the segment’s creation at the valuation date, 1 to 12, so the segment in slotkwas born in policy monthduration_mth - k, and the one in slot 12 matures att = 0. Its columns, per policy:seg_bal_pp_init: the segment’s balance;seg_ded_cum_pp_initandseg_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 isProjection.index_level_init;seg_index_cap_init: the cap declared at its creation.
point_idis 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 lastmin(12, duration_mth)months, a month that swept nothing included, whichProjection.proj_lenchecks, since the twelve isProjection.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:the seven columns are present;
each of
point_idandslotis a whole number, below2**53in size, which numpy would otherwise cast to the least int64 without a word;each
point_idis a point ofmodel_point_table();no
point_idandslotappear together twice;slotis from 1 to its point’sduration_mth: no segment predates issue, and a point not yet in force holds none;each of
seg_bal_pp_init,seg_ded_cum_pp_initandseg_wd_cum_pp_initis a number,-1e-8or 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, andProjection.check_seg_ladderholds every live balance to the same-1e-8,IUL_US_S’s tolerance;seg_index_start_initis a number above 0, the level the segment’s return divides by;seg_index_cap_initis a number, zero or more: the credited rate’sminreads the cap first, so a blank cap would credit the floor without a word;each point’s
av_pp_initis itsfa_pp_initplus itslca_pp_initplus the balances of its segments here, to half a cent an amount and half a cent more: the identityProjection.check_av_componentsholds 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
iis the count of the table’s point at positioni, 0 where the file holds none, read frominforce_segments(), which checks the file first.Projection.proj_lenholds it, withinforce_segment_last(), to the segments a policy in force holds: one for each of its lastmin(seg_term_mth, duration_mth)months. At stageEit was a Series bypoint_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
iis the last slot of the table’s point at positioni, 0 where the file holds no segment, read frominforce_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 whatProjection.proj_lenasks.
- 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 pointProjection.proj_lenprojects 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, whichproj_lenrefuses 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 of10**9on 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, whichDatacannot 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.
- 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_classandage_at_entrythe 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, andcoi_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_entryandpolicy_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 acoi_rate_guarthat 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_yeartakes a point’s extent fromcoi_rate_last_years(), and refuses a point whose cell the table lacks, beforeProjection.coi_rate_guar_pyreads its scale, so a projection meets the checks first.At stage
Ethis check wascoi_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
agecolumn is read by value, once, so an age written40.0is 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 acorridor_factorthat 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, sincecorridor_factor_array()is held from age 0, so that the age is the index;IUL_US_Sreads such a row, which no projection reaches.Projection.corridor_factor_at, the table’s one reader, takes both of its extents, this andcorridor_age_first(), before it reads a factor. A blank factor is a missing value toIUL_US_S, whose death benefit, themaxof 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, whichIUL_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 beingmort_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 andmort_age_first(), before it reads a rate. A blank rate is a missing value toIUL_US_S, whose mortality is then not a number, and toProjection.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, ascorridor_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_yearcolumn is read by value, once, as the lookup matches it, so a year written5.0is 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 alapse_rate_annthat 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 leaveProjection.lapse_rate_mth’s1 - (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 toIUL_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_classthat 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 afactorthat 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 toIUL_US_S, whose mortality is then not a number, and toProjection.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_idthat 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 asc_per_1000_initthat is blank, text, infinite or below 0, naming its lines, and arunoff_yearsthat 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, whereIUL_US_Sdivides by the float, takes theint()of a fraction for its lapse spike, and divides by zero at 0.Projection.surr_charge_rate_maxandProjection.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 toIUL_US_S, whose surrender charge rate, themaxof 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 themaxreads 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 eachsex,rate_classandage_at_entryit holds, numbered from 1 in the order of those keys, ascoi_rate_array()numbers its rows, whatever the order of the file’s lines. The point’s key is itssex, itsrate_classand itsage_at_entry, compared exactly, asIUL_US_Sslices the scale. A point whose key the table lacks gets schedule 0, a row of padding, and is not refused here:IUL_US_Sprojects such a point while it reads no COI rate, as one valued at or pastcharges_cease_agenever does, andProjection.coi_rate_last_yearrefuses it, naming it, when one is read. Askscoi_schedules()first, which checks the table.
- coi_rate_last_years()[source]#
The last policy year of each guaranteed COI scale: int64 [schedule].
Element
sis the lastpolicy_yearcoi_rates.csv holds for schedules, numbered ascoi_schedule()numbers it, read by value oncecoi_schedules()has checked the table: 76 on the shipped anchor cell. 0 at element 0, schedule 0, whichProjection.coi_rate_last_yearrefuses where it is read. At stageEthis was the table’s check, a Series by cell; the check iscoi_schedules()here.
- coi_rate_array()[source]#
The guaranteed maximum monthly COI rates by schedule and policy year: float64 [schedule, y].
Row
sis schedulesof coi_rates.csv, numbered from 1 in the order of its keys,sex,rate_classandage_at_entry, ascoi_schedule()numbers it, and columnyis policy yeary, 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, whichProjection.coi_rate_guar_pynever reads: it refuses a year below 1 and a point of schedule 0, and reads a later year at the schedule’s last. Askscoi_schedules()first, which checks the table.
- lapse_rate_array()[source]#
The base annual lapse rates by policy year: float64 [y].
Element
yis thelapse_rate_annof policy yearyin lapse_table.csv, so that the year is the index, to the last yearlapse_last_year()gives once it has checked the table. NaN at 0, before the first year, whichProjection.lapse_rate_base_pynever reads: it refuses a year below 1.
- corridor_factor_array()[source]#
The GPT corridor factors by attained age: float64 [age].
Element
ais thecorridor_factorof ageain corridor_factors.csv, so that the age is the index, to the last agecorridor_age_last()gives once it has checked the table, which refuses a negative age. NaN from 0 to below the first age, whichProjection.corridor_factor_atnever reads: it reads an age outside the table at the nearest row, asIUL_US_Sdoes.
- mort_table_array()[source]#
The best-estimate annual mortality rates by attained age: float64 [age].
Element
ais themort_rateof ageain mort_table.csv, held ascorridor_factor_array()holds its own table, to the last agemort_age_last()gives. NaN from 0 to below the first age, whichProjection.mort_rate_base_atnever reads.
- point_id()[source]#
The
point_idof every model point, in table order: int64 [point].Projectionis indexed by position,idx, so this is how a projection names its point:Projection.point_id()is the element atidx, and every refusal quotes it. A label that is not a whole number is refused, naming every such label, and so is one of2**53or 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_entrycolumn, whichmodel_point_table()holds to a whole number below2**53in size, 0 or more.
- duration_mth()[source]#
The completed policy months at the valuation date of every model point: int64 [point].
The
duration_mthcolumn, whichmodel_point_table()holds to a whole number below2**53in size.
- wd_first_year()[source]#
The first policy year of each model point’s withdrawals: int64 [point].
The
wd_first_yearcolumn, whichmodel_point_table()holds to a whole number of policy years, 1 or more, below2**53.
- loan_first_year()[source]#
The first policy year of each model point’s loans: int64 [point].
The
loan_first_yearcolumn, whichmodel_point_table()holds to a whole number of policy years, 1 or more, below2**53.
- is_mec_init()[source]#
Whether each model point is a MEC entering month 0: int64 [point].
The
is_mec_initcolumn, whichmodel_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_chargecolumn 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_optionis"A", compared element by element asIUL_US_Scompares 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 raisesIUL_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_optionis"B", decoded asis_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_testis"GPT", decoded asis_db_option_a()decodes A, and 0 elsewhere; a value no flag names raises"invalid qual_test"where a projection branches on it.
Whether the premium pattern is LEVEL, for each model point: int64 [point].
1 where
premium_typeis"LEVEL", decoded asis_db_option_a()decodes A, and 0 elsewhere; a value no flag names raises"invalid premium type"where a projection branches on it.
Whether the premium pattern is SINGLE, for each model point: int64 [point].
1 where
premium_typeis"SINGLE", decoded asis_db_option_a()decodes A, and 0 elsewhere; a value no flag names raises"invalid premium type"where a projection branches on it.
Whether the premium pattern is TARGET, for each model point: int64 [point].
1 where
premium_typeis"TARGET", decoded asis_db_option_a()decodes A, and 0 elsewhere; a value no flag names raises"invalid premium type"where a projection branches on it.
Whether the premium mode is ANNUAL, for each model point: int64 [point].
1 where
premium_modeis"ANNUAL", decoded asis_db_option_a()decodes A, and 0 elsewhere; a value no flag names raises"invalid premium mode"where a projection branches on it.
Whether the premium mode is MONTHLY, for each model point: int64 [point].
1 where
premium_modeis"MONTHLY", decoded asis_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_assuredcolumn, whichmodel_point_table()holds to a number above 0.
- policy_count()[source]#
The policies each model point stands for: float64 [point].
The
policy_countcolumn, whichmodel_point_table()holds to a number, zero or more.
The planned annual premium per policy of every model point: float64 [point].
The
premium_pp_anncolumn, whichmodel_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_ppcolumn, whichmodel_point_table()holds to a number, zero or more.Projection.wd_pp_mthreads it, sinceProjection.wd_ppis 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_anncolumn, whichmodel_point_table()holds to a number, zero or more.Projection.loan_new_pp_annreads it.
- mnlp_rate()[source]#
The minimum no-lapse premium per $1,000 a year of every model point: float64 [point].
The
mnlp_ratecolumn, whichmodel_point_table()holds to a number, zero or more.
- gsp()[source]#
The guideline single premium of every model point: float64 [point].
The
gspcolumn, whichmodel_point_table()holds to a number, zero or more.
- glp()[source]#
The guideline level premium of every model point: float64 [point].
The
glpcolumn, whichmodel_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_premcolumn, whichmodel_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_ratecolumn, whichmodel_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_ratecolumn, whichmodel_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_initcolumn, whichmodel_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_initcolumn, whichmodel_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_initcolumn, whichmodel_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_initcolumn, whichmodel_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_initcolumn, whichmodel_point_table()holds to a number, zero or more, at mostsum_assuredon a policy in force.
- cum_prem_init()[source]#
The premiums less withdrawals paid per policy entering month 0: float64 [point].
The
cum_prem_initcolumn, whichmodel_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_initcolumn, whichmodel_point_table()holds to a number, of either sign.
- class_factor()[source]#
The underwriting-class factor of each model point: float64 [point].
The
factorclass_factor_table.csv gives the point’srate_class, compared exactly, onceclass_count()has checked the table. A point reads its class factor in its first month in cover, soIUL_US_Sfails 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 stageErefused 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_initof the point’ssurr_charge_idin surr_charge_table.csv, oncesurr_charge_count()has checked the table, on every point whose id the table holds, with a charge or without, as stageE’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, andhas_surr_charge_schedule()0 there. The join refuses the table, naming every such point, only on a point with a charge, sinceIUL_US_Sreads the schedule in every month of such a point’s cover: an id the table lacks, whereIUL_US_S’s.locraisedKeyError; and arunoff_yearsof2**53years or more in size, the bound of every number read as an int, past which the compiledint()inProjection.lapse_shock_yearwould in time raiseOverflowError.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 inIUL_US_S, andProjection.surr_charge_rate_maxraises stageE’sValueErroron it where it is read, which no projection does. The same checks run insurr_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_yearsof the point’ssurr_charge_idin 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 assurr_charge_rate_max()joins and checks the charge, with its refusals. A float, asIUL_US_Sreads 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_idis asurr_charge_idof the table, compared exactly, asIUL_US_S’s.loccompares it, and 0 where it is not, blank included, oncesurr_charge_count()has checked the table. 0 only on a point without a charge, sincesurr_charge_rate_max()refuses the table where a point with a charge names an id it lacks: thereProjection.surr_charge_rate_maxandProjection.surr_charge_runoff_yearsraise stageE’sValueError, 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
iis the table’s point at positioniand columnkits slotkof inforce_segments_sec.csv, the columnseg_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 thatProjection.seg_bal_pp_initnever reads: it asksProjection.proj_lenfirst, 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, notProjection.seg_term_mth, whichDatacannot read, so a model run at another segment term reads a ladder written for it. Asksinforce_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_initof inforce_segments_sec.csv, per policy, held asseg_bal_pp_init()holds the balance, and read only byProjection.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_initof inforce_segments_sec.csv, per policy, held asseg_bal_pp_init()holds the balance, and read only byProjection.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_initof inforce_segments_sec.csv, per policy, held asseg_bal_pp_init()holds the balance, and read only byProjection.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_initof inforce_segments_sec.csv, per policy, held asseg_bal_pp_init()holds the balance, and read only byProjection.seg_index_cap_init, after its checks.