The Data Space#
Input data shared by every by-policy projection.
The ten 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/variable_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
VUL_US_SEC folder without its parent’s CSVs produces a model that reads and then
fails on first evaluation.
Nine of the tables are VUL_US_S’s. The subaccount lineup, the return scenario, the
guaranteed COI scale, the corridor factors, the mortality table, the class factors, the
lapse table, the premium persistency scale and the surrender charge schedules are the
files VUL_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 is this model’s own,
model_point_table_sec.csv; it sits beside VUL_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 |
subaccount_file |
subaccount_table() |
subaccount_table.csv |
scenario_file |
scenario_table() |
scenario_table.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 |
prem_persistency_file |
prem_persistency_table() |
prem_persistency.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, with the shipped lineup of two subaccounts: policy_count and
duration_mth, as in basiclife.BasicTerm_SE; six columns of an in-force policy’s
opening state, one sa_pp_init_<i> for each subaccount, the value of the fixed option
and of the loan account, the debt and the face in force; and VUL_US_S’s two
first-month pins, which are not state. model_point_table() refuses a table that lacks
any of them, or any column of VUL_US_S’s own that the projection reads as a number,
repeats a point_id, holds a count, a duration, an issue age or an amount no policy can
have, a surrender-charge flag that is not True or False, or an opening state no
policy can be in. The checks run in turn, 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 is a rule of the product rather than of the table, and Projection.proj_len
checks it.
So are the nine assumption tables. Each table read at a policy year or an attained
age has one reader in Projection, keyed by the year or the age, and that reader takes
the table’s extent – the last policy year, or the first and last ages, beyond which it
reads the nearest row – from a cell here that reads the key column by value, once, and
checks the table: prem_persistency_last_year(), lapse_last_year(),
corridor_age_first() and corridor_age_last(), mort_age_first() and
mort_age_last(), 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 a negative age, since an age table is held from age 0. So are keys that do
not run one row a year or an age, 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 and counts policy years on. A class factor, a guaranteed COI rate, a fund
expense, a premium persistency factor, a surrender charge and a corridor factor below 0
are refused too: each would project, with every check passing, a count or a charge no
policy can have, a negative death or premium, a credit for the insurance or the fund, a
surrender charge that rises once its schedule has run off, or a death benefit past the
option’s amount on an account value below 0.
subaccount_count() checks the lineup, whose ids name the model point table’s
columns, and scenario_count() the return scenario, whose months run one row a month
for each scenario and subaccount. Each reader asks for its extent, the count or the
lineup before it reads a value, so a projection meets the checks first.
VUL_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
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 corridor
factor reads as no corridor, a blank surrender charge as none, and a blank COI rate, fund
expense or return reaches the account value as a missing value, which the cash value’s
floor at zero then reads as nothing to pay on a surrender. Here each is refused, by name,
and so is a blank, text or infinite amount in the model point table.
scenario_table.csv is the separate-account return scenario: monthly gross
subaccount returns keyed by scenario_id, subaccount_id and the month t, the
same index as Projection’s t, which counts months from the valuation date: a
scenario is a path of the economy from that date, one path for every point of a block,
however old the policy, with the last month of a scenario repeating for the rest of the
projection. Fund expenses and the M&E charge are applied on top of these in
inv_return_mth(), so the table holds gross returns only. A
stochastic set is a data change – more scenario_id values – not a formula change.
The shipped scenarios are deterministic: WE is the worked example’s month (+1.00%
equity, -0.50% bond) followed by a level 6% a year gross path, and LEVEL6 is that
level path throughout. A scenario’s months may start after month 0 – a path re-based to
a policy issued after the valuation date holds nothing before its issue month – and a
read before a scenario’s first month raises. The scenario’s vectors hold its months to
return_horizon_mth, 1,585 as shipped, the last month a frame the contract allows can
read, however far the table runs (gross_return_array()), and a read past it raises.
coi_rates.csv carries the guaranteed maximum monthly rate per $1,000 of net
amount at risk; the current scale is that times
Projection.coi_curr_factor, or the model point’s first-month pin. The notes require
the 2017 CSO ultimate ANB table for the guaranteed maximum and the 2015 VBT for
best-estimate mortality; both are licensed and may not be reproduced here, so
coi_rates.csv and mort_table.csv ship small illustrative [std] tables
instead – the COI scale anchored on the one disclosed guaranteed point in the notes
(male 45 standard non-tobacco, policy year 1 = $0.22 [S4]) and the mortality table well
below it, because the notes insist the COI charge basis and the death decrement
basis must never be conflated. To swap in a licensed basis, replace either file with a
same-schema one, or point mort_table_file at a different name before the model
computes anything. No formula changes. Replacing the file changes VUL_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], and a subaccount’s the
element at its position in the lineup, data.alloc()[idx, i]. 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 check of a table 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 and the premium pattern a monthly cell
branches on into a 0/1 flag, the surrender-charge flag into another, and each first-month
pin into its value, NaN where blank as VUL_US_S reads it, and a flag that says whether
the point gives one. 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 return
scenarios, keyed by their ID, are numbered too, each point carrying the number of its
own, and tabled by scenario, subaccount and month. The subaccounts are positions in the
lineup, from 0, in the file’s order, their ids kept in a vector for the reports. The
persistency and lapse tables are held by policy year, and the corridor and mortality
tables by attained age, each padded from 0, so that the year or the age is the index.
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] |
|
sum_assured() |
float64 |
[point] |
|
policy_count() |
float64 |
[point] |
|
premium_pp_ann() |
float64 |
[point] |
|
wd_pp() |
float64 |
[point] |
|
load_prem_rate() |
float64 |
[point] |
|
alloc_fixed() |
float64 |
[point] |
|
alloc() |
float64 |
[point, sa] |
|
sa_pp_init() |
float64 |
[point, sa] |
|
fa_pp_init() |
float64 |
[point] |
|
la_pp_init() |
float64 |
[point] |
|
loan_bal_init() |
float64 |
[point] |
|
sum_assured_init() |
float64 |
[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] |
|
corridor_override_m1() |
float64 |
[point] |
the pin, NaN where blank |
has_corridor_override_m1() |
int64 |
[point] |
the pin, 1 where given |
coi_rate_override_m1() |
float64 |
[point] |
the pin, NaN where blank |
has_coi_rate_override_m1() |
int64 |
[point] |
the pin, 1 where given |
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 |
subaccount_count() |
int |
scalar |
subaccount_table.csv, checked |
subaccounts() |
int64 |
[sa] |
|
fund_expense_ann() |
float64 |
[sa] |
|
coi_schedules() |
int |
scalar |
coi_rates.csv, checked |
coi_schedule() |
int64 |
[point] |
sex, class and issue age, joined; 0 where not |
coi_rate_last_years() |
int64 |
[schedule] |
coi_rates.csv |
coi_rate_array() |
float64 |
[schedule, y] |
coi_rates.csv |
scenario_count() |
int |
scalar |
scenario_table.csv, checked |
scenario_index() |
int64 |
[point] |
|
scenario_first_mths() |
int64 |
[scenario, sa] |
scenario_table.csv |
scenario_last_mths() |
int64 |
[scenario, sa] |
scenario_table.csv |
gross_return_array() |
float64 |
[scenario, sa, t] |
scenario_table.csv |
prem_persistency_array() |
float64 |
[y] |
prem_persistency.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 |
The table checks are the ints they were, prem_persistency_last_year(),
lapse_last_year(), the four age extents, class_count() and
surr_charge_count(), and the three that were Series and DataFrames are now ints,
each the check of its table: subaccount_count() the lineup’s, scenario_count()
the return scenario’s and coi_schedules() the COI scale’s. scenario_rows stays
the scenario table’s reader, a plain DataFrame, and scenario_table its indexed copy.
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 other
cell element by element, subaccounts()[k], and a width comes from a table or a
check’s int, never from another cell’s array, nor from an index that calls one. Each
table’s check is one int cell that every array, extent and number of the table reads
first, so that a projection, which reads an extent or a 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, 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; a scenario_id the return scenario lacks, or one without a row for
a subaccount of the lineup; and on a point that has_surr_charge a surr_charge_id
the schedules lack, or a run-off of 2**53 years or more in size (below). VUL_US_S
fails every projection of a point whose class, scenario or charged schedule the tables
lack, since it reads its class factor and every subaccount’s return in its first month
on the books, and its schedule in every month of a point with a charge; here the table is
refused, as in the family’s other compiled models. A point without a charge is never
refused for its schedule, whatever its id, as VUL_US_S never reads it: its schedule
is read where the table holds its id, and where it does not,
Projection.surr_charge_rate_max raises KeyError, as at stage E. A point whose
COI cell the scale lacks is another matter: it reads its scale only while charges run,
and a point valued or issued at or past charges_cease_age never does, so VUL_US_S
projects it. It is given schedule 0, and Projection.coi_rate_last_year refuses it,
naming it, where a rate is read. A value of db_option, qual_test or
premium_type none of the flags names is no flag, and the cell that branches on them
raises VUL_US_S’s message, as in VUL_US_S. A read beyond a table’s extent is
refused where VUL_US_S’s lookup raised KeyError, by the one
Projection cell that reads the table, naming the point: a policy year
below 1 in prem_persistency_py, lapse_rate_base_py and coi_rate_guar_at, a
month before a scenario’s first in gross_return_mth, and a subaccount’s position past
the lineup in the four cells that read a subaccount’s input. An age outside its table
reads the nearest row, as in VUL_US_S, so no padding is read.
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 VUL_US_S’s reading of it: the issue age
and duration_mth (model_point_table()) and the point_id (point_id()).
A charged point’s run-off is held to the same bound, though no cast is silent there: its
int(), in Projection.lapse_shock_month, compiles to a Python int converted to a C
long long, exact below 2**63 and raising OverflowError past it, where
VUL_US_S projects a charge that never runs off. modelx and the compiled model refuse
alike, before any cast. A fractional issue age stays refused, as at stage E: Data
refuses it with the other values no policy can have, where UL_US_SEC’s truncates as
UL_US_S’s int does.
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, with the shipped lineup of two subaccounts:policy_countandduration_mth, the completed policy months at the valuation date, as inbasiclife.BasicTerm_SE; six columns of the opening state, per policy, as the policy stands at the start of month 0, before any month-0 event, onesa_pp_init_<i>for each subaccount among them; andVUL_US_S’s two first-month pins, which are not state:sa_pp_init_<i>, one for each idsubaccounts()lists, andfa_pp_init: the value of each subaccount and of the fixed option entering month 0,VUL_US_S’s own columns;la_pp_init: the loan account, the collateral the loan has moved out of the investment options, entering month 0;loan_bal_init: the policy debt entering month 0,VUL_US_S’s own column;sum_assured_init: the face in force entering month 0, after every Option A withdrawal cut to date;corridor_override_m1andcoi_rate_override_m1:VUL_US_S’s first-month pins, which apply in the valuation month,t = 0, blank where a point pins nothing.
The rest are
VUL_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, 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
age_at_entry, the surrender-charge flaghas_surr_charge, the amounts the projection reads as numbers,sum_assured,premium_pp_annandwd_pp, and the shares it reads,load_prem_rate, eachalloc_<i>andalloc_fixed;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 takes itsint()and 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, whereUL_US_SEC’s truncates; an age the contract does not issue isProjection.proj_len’s to refuse;sum_assuredis a number above 0, the face at issue, which every policy holds; each ofpremium_pp_annandwd_ppis a number, zero or more; and each ofload_prem_rate,alloc_<i>andalloc_fixed, the share of each premium the load takes and the shares of each net premium the accounts take, is a number from 0 to 1. Each reaches the account value, and a blank one would reach it as a missing value, which the cash value’s floor, the net amount at risk’s and the corridor’smaxthen lose without a word: inVUL_US_Sa blank face projects no death claim on Option A, and a missing value on Option B. A load past 1 would credit the accounts a net premium below 0, every check passing, and allocations past 1 more than the net premium;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 subaccount, the fixed option, the loan account, the debt and the face in force is a number, zero or more. A balance is never negative in force.
VUL_US_Slets a subaccount fall below zero once the point is in permanent shortfall, because it does not implement the grace cascade that would end such a policy; no policy in force can hold that balance, so a point in permanent shortfall is restated no later than the last month its subaccounts are still zero or more;a policy not yet in force,
duration_mth0 or less, has no opening state: it is issued with none, at the facesum_assured();sum_assured_initis above 0 on a policy in force, which holds a face, so an extract that leaves the column at zero is refused rather than projected on the corridor alone;sum_assured_initis at mostsum_assured, the face at issue, 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;the loan account is above 0 exactly where the debt is: a loan moves value out of the investment options into the loan account, and the model takes no new loan and no repayment, so the two are held together from the loan’s first day, each at its own rate;
each pin is blank, or a number, zero or more;
each pin is blank on a policy issued after the valuation date: a pin applies in the valuation month,
t = 0, before such a policy is issued, so it would never apply.
- subaccount_table()[source]#
The separate-account subaccount lineup, read from subaccount_table.csv.
One row per subaccount, giving its name and its annual fund operating expense ratio. The two-subaccount lineup is a [std] collapse of the observed menus. The projection reads it through
subaccounts(), its checked copy.
- subaccount_count()[source]#
The number of subaccounts in the lineup, subaccount_table.csv checked.
The lineup’s one check, which every vector of the lineup asks first:
subaccounts(),fund_expense_ann(),alloc()andsa_pp_init(), andmodel_point_table(), which names the columns it checks from the ids. Thesubaccount_idcolumn is read by value, once, as an int: an id written1.0is subaccount 1, and names the model point table’salloc_1andsa_pp_init_1, whereVUL_US_S, which names the column from the id as pandas reads it, asks a projection forsa_pp_init_1.0and raises. An id that is blank, text or not a whole number is refused, naming the file and the lines it is on; so is a table with no subaccount, and an id on more than one row, naming each such id with its lines; and so is afund_expense_annthat is blank, text, infinite or below 0, naming its lines.Projection.subaccount_countreads it, andProjection.proj_lenrefuses a lineup of more thansubaccount_maxsubaccounts, the most the compiled model’s caches hold. Rows keep the file’s order, and a subaccount’s position in it, from 0, is theieveryProjectioncell of a subaccount takes.
- subaccounts()[source]#
The
subaccount_idof each subaccount of the lineup, in file order: int64 [sa].Element
iis the id of the subaccount at positioniof subaccount_table.csv, read by value oncesubaccount_count()has checked the lineup, so an id written1.0is 1. The ids name the model point table’salloc_<id>andsa_pp_init_<id>columns, whichalloc()andsa_pp_init()read by position, andProjection.result_av’s columns; no projection cell reads an id.
- fund_expense_ann()[source]#
The annual fund operating expense ratio of each subaccount: float64 [sa].
The
fund_expense_anncolumn of subaccount_table.csv, in file order, so that the subaccount’s position is the index, oncesubaccount_count()has checked the lineup, which refuses a ratio that is blank, text, infinite or below 0.
- scenario_rows()[source]#
Monthly gross subaccount returns, read from scenario_table.csv in the file’s order.
The table’s one read, a plain table on a default index, so that a refusal can name the lines a fault is on:
scenario_count()checks it, the scenario’s vectors,scenario_index(),scenario_first_mths(),scenario_last_mths()andgross_return_array(), are built from it, andscenario_table()indexes it asVUL_US_Sreads it.
- scenario_table()[source]#
Monthly gross subaccount returns, from scenario_table.csv, indexed for lookup.
Keyed by
scenario_id,subaccount_idand the montht, counted from the valuation date, 0-based; months past a scenario’s last row repeat it. Returns are gross: fund expenses and the M&E charge are applied on top of them in the projection, so a table row is the fund’s own return before any charge. The index is sorted so partial slices of the three-level key are lexsorted. It isscenario_rows()indexed, the same frameVUL_US_S’s reader reads, kept for a reader who wants the table so; no projection cell reads it, andProjection.gross_return_mthreadsgross_return_array()instead.
- scenario_count()[source]#
The number of scenarios scenario_table.csv holds, the table checked.
The return scenario’s one check, which every vector of the scenario asks first:
scenario_index(),scenario_first_mths(),scenario_last_mths()andgross_return_array(), each of which numbers the scenarios from 1 in the order of theirscenario_id, asgroupbysorts them, whatever the order of the file’s lines. Each cell of the table is the rows of one scenario and subaccount, the return path one subaccount is read from on that scenario, months past the last repeating it.scenario_idmay not be blank, and the two numeric keys,subaccount_idandt, 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, andreturn_horizon_mth, the last month the scenario’s vectors hold, must be 0 or more. A cell whose months do not run one row a month, from 0 or later, without a gap or a repeat is refused: the message names the cell, each month that repeats or falls below 0, with its lines, and each month missing between the cell’s first and its last. A cell may start after month 0: a path re-based to a policy issued after the valuation date holds nothing before its issue month, so that a read there raises. And agross_return_mththat is blank, text or infinite is refused, naming its lines. A subaccount the lineup does not hold is checked as any other, and not read.
- scenario_last_mths()[source]#
The last month of each scenario and subaccount of scenario_table.csv: int64 [scenario, sa].
Row
sis scenarios, numbered from 1 in the order of the table’sscenario_id, asscenario_index()numbers it, and columnithe subaccount at positioniof the lineup,subaccounts(): the lasttthe table holds for the cell, read by value oncescenario_count()has checked it, or, where the cell runs pastreturn_horizon_mth, the last monthgross_return_array()holds, which falls below the cell’s first month,scenario_first_mths(), where the cell starts past the horizon. -1 where the scenario holds no row for the subaccount, and in row 0, padding, which no point is given:scenario_index()refuses a point whose scenario lacks a subaccount of the lineup.Projection.scenario_last_mthreads it, andProjection.gross_return_mthreads a month past it, to the horizon, at the last.
- scenario_first_mths()[source]#
The first month of each scenario and subaccount of scenario_table.csv: int64 [scenario, sa].
Numbered as
scenario_last_mths()numbers its rows and columns: the firsttthe table holds for the cell, 0 on a scenario that starts at the valuation date and later on one re-based to a policy issued after it. 0 where the scenario holds no row for the subaccount, and in row 0, padding no point is given.Projection.gross_return_mthrefuses a month before it, naming the point, whereVUL_US_S’s.locraisedKeyError, so that the padding before a cell’s first month is never read.
- gross_return_array()[source]#
The gross monthly return of each scenario, subaccount and month: float64 [scenario, sa, t].
Row
sand columniare numbered asscenario_last_mths()numbers them, and the third index is the monthtfrom the valuation date, so that the month is the index, to the lasttthe table holds at or beforereturn_horizon_mth, oncescenario_count()has checked the table. NaN in row 0, before each cell’s first month, after its last, and where a scenario holds no row for a subaccount, all padding, whichProjection.gross_return_mthnever reads: it reads a month past a cell’s last at the last, to the horizon, refuses one before its first and one past the horizon, andscenario_index()refuses a point whose scenario lacks a subaccount.The months stop at
return_horizon_mth, 1,585 as shipped, the last month a compiled cache keyed bytholds (spec_sec.py), and no frame the contract allows reads past it. So the array is no larger than the months the contract reads, whatever months the table holds: a cell that starts or runs past the horizon, as a path re-based far ahead may, adds nothing to it, where an array to the table’s lasttwould grow with that month alone. A cell that runs past the horizon is held to it, andscenario_last_mths()gives it that month as its last; a cell that starts past it holds nothing, its last month falling below its first, every month a frame reads being before its first, whichProjection.gross_return_mthrefuses asVUL_US_S’s lookup raised there. A month past the horizon, which only a call outside every frame makes,Projection.gross_return_mthrefuses, naming the point and the scenario’s number, as it refuses every month of a cell whose last falls below its first, so that no read meets the padding past a cell’s last month. A longer horizon, a higheromega_ageor a lowerissue_age_minneeds it raised witht’s size inspec_sec.py.
- 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. An illustrative [std] stand-in for the licensed 2017 CSO ultimate ANB table.
- corridor_factors()[source]#
The GPT corridor factor table by attained age, read from corridor_factors.csv.
- prem_persistency_table()[source]#
Premium persistency (paid/planned) by policy year, from prem_persistency.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 policy years over which it runs off linearly.
- prem_persistency_last_year()[source]#
The last policy year prem_persistency.csv gives a factor 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 aprem_persistencyfactor that is blank, text, infinite or below 0, naming its lines: a fraction of the planned premium, which below 0 would pay a negative premium, every check passing.Projection.prem_persistency_py, the table’s one reader, takes its extent from here before it reads a factor, so a projection meets the checks first. Only the behaviour module reads the table, so a run withdyn_behavior_onoff never asks for it.
- lapse_last_year()[source]#
The last policy year lapse_table.csv gives a rate for, the table checked.
Read and checked as
prem_persistency_last_year()reads and checks its own table, the rate checked beinglapse_rate_ann, which must be from 0 to 1, as a probability:Projection.lapse_rate_mth’s1 - (1 - q)^(1/12)has no real value past 1, and below 0 the count would grow by its lapses.Projection.lapse_rate_base_py, the table’s one reader, takes its extent from here before it reads a rate.
- 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, and so is a negative age, naming its lines:corridor_factor_array()holds the table from age 0, so that the age is the index, andVUL_US_S, which reads the nearest row, projects such a table. 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.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 toVUL_US_S, whose death benefit, themaxof the option’s amount and the corridor’s, then reads it as no corridor at all; and one below 0 is a corridor no policy has, which, once an account value runs below 0 in a shortfall the model does not end, takes the death benefit past the option’s amount, every check passing. The model point’s corridor pin is held to 0 or more by the same rule (model_point_table()).
- 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, a negative age refused as there, sincemort_table_array()holds the table from age 0, the rate checked beingmort_rate, which must also be from 0 to 1, as a probability; 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 toVUL_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.
- 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()the last policy year of each, 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 72, but is never a credit.Projection.coi_rate_last_yearreads a point’s extent beforeProjection.coi_rate_guar_atreads its scale, so a projection meets the checks first. A blank rate is a missing value toVUL_US_S, whose account value is then not a number, and whose cash value and net amount at risk, each floored at zero by amax, then read it as nothing.
- 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, a whole number, asVUL_US_Sslices the scale. A point whose key the table lacks gets schedule 0, a row of padding, and is not refused here:VUL_US_Sprojects such a point while it reads no COI rate, as one valued, or issued, 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, in the sorted order of its keys, whatever the order of the file’s lines, read by value oncecoi_schedules()has checked the table: 77 on the shipped anchor cell, whose scale runs to attained age 121. 0 in element 0, schedule 0, which a point the table has no scale for is given, and whichProjection.coi_rate_last_yearrefuses where it is read. A vector by schedule, read at the point’scoi_schedule(), rather thanUL_US_SEC’s by point.
- 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, sorted, whatever the order of the file’s lines, 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_atnever 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.
- 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 toVUL_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, whereVUL_US_Struncates a fraction withint()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 toVUL_US_S, whose surrender charge rate, themaxof 0 and the charge left, is then 0 in every policy year, as though the schedule had run off. 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 policy year, every check passing: the shipped schedule written at -18.00 charges $1.29 per $1,000 in policy year 16.
- prem_persistency_array()[source]#
The premium persistency factors by policy year: float64 [y].
Element
yis theprem_persistencyof policy yearyin prem_persistency.csv, so that the year is the index, to the last yearprem_persistency_last_year()gives once it has checked the table. NaN at 0, before the first year, whichProjection.prem_persistency_pynever reads.
- lapse_rate_array()[source]#
The base annual lapse rates by policy year: float64 [y].
Element
yis thelapse_rate_annof policy yearyin lapse_table.csv, held asprem_persistency_array()holds its own table, to the last yearlapse_last_year()gives. NaN at 0, whichProjection.lapse_rate_base_pynever reads.
- 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, 18 as shipped, whichProjection.corridor_factor_atnever reads: it reads an age outside the table at the nearest row, asVUL_US_Sdoes, so an issue age below 18 reads age 18’s factor.
- 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, 0 or more and below2**53, where the int64 holds it exactly.
- 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 of months below2**53in size.
- 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.
- load_prem_rate()[source]#
The current premium load rate of every model point: float64 [point].
The
load_prem_ratecolumn, whichmodel_point_table()holds to a number from 0 to 1.
- alloc_fixed()[source]#
The share of each net premium allocated to the fixed option: float64 [point].
The
alloc_fixedcolumn, whichmodel_point_table()holds to a number from 0 to 1.
- alloc()[source]#
The share of each net premium allocated to each subaccount: float64 [point, sa].
Element
[p, i]is pointp’salloc_<id>column,idthe id of the subaccount at positioniof the lineup,subaccounts(), read by element, so that the position is the index.model_point_table()holds each such column to a number from 0 to 1, and askssubaccount_count()first, which checks the lineup.
- sa_pp_init()[source]#
The value of each subaccount per policy entering month 0: float64 [point, sa].
Element
[p, i]is pointp’ssa_pp_init_<id>column, read asalloc()readsalloc_<id>.model_point_table()holds each such column to a number, zero or more, and to 0 on a policy not yet in force.
- fa_pp_init()[source]#
The fixed-option value per policy entering month 0: float64 [point].
The
fa_pp_initcolumn of the opening state, checked bymodel_point_table().
- la_pp_init()[source]#
The loan-account collateral per policy entering month 0: float64 [point].
The
la_pp_initcolumn of the opening state, checked bymodel_point_table().
- loan_bal_init()[source]#
The policy debt per policy entering month 0: float64 [point].
The
loan_bal_initcolumn of the opening state, checked bymodel_point_table().
- sum_assured_init()[source]#
The face in force entering month 0: float64 [point].
The
sum_assured_initcolumn of the opening state, checked bymodel_point_table().
- 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 each model point’s death benefit is Option A: int64 [point].
1 where
db_optionis"A", compared element by element asVUL_US_Scompares it, and 0 elsewhere. A value neither A nor B is not refused here: it is no flag, andProjection.db_ppraisesVUL_US_S’s message on it.
- is_db_option_b()[source]#
Whether each model point’s death benefit is Option B: int64 [point].
1 where
db_optionis"B", asis_db_option_a()decodes A.
- is_gpt()[source]#
Whether each model point elected the Guideline Premium Test: int64 [point].
1 where
qual_testis"GPT", and 0 elsewhere, whereProjection.corridor_factorraisesVUL_US_S’s message.
Whether each model point’s premium pattern is LEVEL: int64 [point].
1 where
premium_typeis"LEVEL", and 0 elsewhere. A pattern neither LEVEL nor SINGLE is no flag, andProjection.premium_ppraisesVUL_US_S’s message on it.
Whether each model point’s premium pattern is SINGLE: int64 [point].
1 where
premium_typeis"SINGLE", asis_level_premium()decodes LEVEL.
- corridor_override_m1()[source]#
Each model point’s first-month corridor factor pin: float64 [point].
The
corridor_override_m1column, whichmodel_point_table()holds to blank or a number, zero or more: the number, and NaN where it is blank, asProjection.corridor_override_m1read it at stageE. The flaghas_corridor_override_m1(), never this value, says whether a point pins its factor, so no NaN reaches a formula.
- has_corridor_override_m1()[source]#
Whether each model point pins its corridor factor: int64 [point].
1 where the
corridor_override_m1column holds a number and 0 where it is blank: the decodeProjection.has_corridor_override_m1made withpd.isnaat stageE, made here once for every point.
- coi_rate_override_m1()[source]#
Each model point’s first-month current COI rate pin: float64 [point].
The
coi_rate_override_m1column, held and read ascorridor_override_m1()is: NaN where blank, and the flaghas_coi_rate_override_m1()decides.
- has_coi_rate_override_m1()[source]#
Whether each model point pins its current COI rate: int64 [point].
1 where the
coi_rate_override_m1column holds a number and 0 where it is blank, ashas_corridor_override_m1()decodes its own.
- class_factor()[source]#
The underwriting-class factor of each model point: float64 [point].
The
factorclass_factor_table.csv gives the point’srate_class, joined exactly, onceclass_count()has checked the table. A point reads its class factor in every month on the books, soVUL_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.
- 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, asVUL_US_SEC’s accessor read it at stageE: a point without a charge reads its schedule, though no cell reads it there. On a point without a charge whose id the table lacks, blank included, it is NaN, andhas_surr_charge_schedule()0: the point projects, andProjection.surr_charge_rate_maxraisesKeyErroron it, as the.locdid at stageE. The join refuses, naming every such point with a charge, and only on a point with one, sinceVUL_US_Sreads the schedule in every month of such a point’s cover: an id the table lacks, whereVUL_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_monthwould raiseOverflowErrorin time. A run-off that is not a whole number of years, 1 or more,surr_charge_count()has refused already. 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 point without a charge reads the run-off as written,2**53years or more included, which no cell reads there.
- 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, asVUL_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_yearsraiseKeyError, naming the point.
- scenario_index()[source]#
The number of each model point’s return scenario, in table order: int64 [point].
The point’s row of
gross_return_array(),scenario_first_mths()andscenario_last_mths(): the scenarios of scenario_table.csv, numbered from 1 in the order of theirscenario_id, asgroupbysorts them, whatever the order of the file’s lines, and each point given the number of its ownscenario_id, matched as pandas matches the two columns, so that a scenario written1in one file matches1.0in the other. Every projection reads every subaccount’s return in its first month in cover, soVUL_US_Sfails every projection of a point whose scenario the table lacks, or holds no row for a subaccount of the lineup: such a point is refused here, at the first read, naming every such point. Asksscenario_count()first, which checks the table.