The Data Space#
Input data shared by every by-contract projection.
The eight input CSVs are read here, once per model, and referenced from
Projection as data. Projection is parameterized
by idx, a point’s position 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 contracts are projected.
Inputs are external files: plain CSVs in the model folder’s parent directory,
products/variable_annuity/, 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
VA_US_SEC folder without its parent’s CSVs produces a model that reads and then fails
on first evaluation.
Five of the tables are VA_US_S’s. The mortality table, the fund table, the GAWA% grid,
the withdrawal charge scale and the transaction programmes are the files
VA_US_S reads, read here in place: one copy of each table serves both models, so
an edit to one reaches both. The other three are this model’s own, each generated from
VA_US_S and its inputs, never typed: model_point_table_sec.csv, beside
VA_US_S’s model_point_table.csv, and return_scenario_sec.csv and
rate_scenario_sec.csv, the two scenarios moved onto the valuation clock, beside
VA_US_S’s return_scenario.csv and rate_scenario.csv. This model opens none of
VA_US_S’s three.
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 |
mort_table_file |
mort_table() |
mort_table.csv |
fund_file |
fund_table() |
fund_table.csv |
return_scenario_file |
return_scenario() |
return_scenario_sec.csv |
rate_scenario_file |
rate_scenario() |
rate_scenario_sec.csv |
gawa_pct_file |
gawa_pct_table() |
gawa_pct_table.csv |
cdsc_file |
cdsc_table() |
cdsc_table.csv |
transaction_file |
transaction_table() |
transaction_table.csv |
The model point table is checked as it is read. Twenty-two of its columns are the
in-force interface: policy_count and duration_mth, as in
basiclife.BasicTerm_SE, and the twenty columns of an in-force contract’s opening
state, the two subaccount values among them. model_point_table() refuses a table that
lacks any of them, repeats a point_id, holds a count, a duration, an age or a contract
parameter no contract can have, holds an opening state no contract can be in, or holds a
key that the table it joins lacks: a fund set, a scenario that sets no level by the
point’s first month on the books, a programme, a grid, a withdrawal charge schedule, or a
sex and an attained age the mortality table gives no rate at. 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 contract 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 cover from issue plus that horizon. Set to 0,
the Reference refuses future new business altogether. Whether a point is still in cover at
the valuation date is a rule of the product rather than of the table, and
Projection.proj_len checks it. sa_pp_init_array() reads the subaccount values out
of the checked table, one column a subaccount.
So are the keys and values of the seven assumption tables. The reader of each in the
table above is VA_US_S’s, unchanged, model_point_table() alone being rewritten,
and beside it a cell reads the table’s keys by value, once, checks them and its values,
and returns the table indexed by the checked keys. The projection reads each table there
and nowhere else, and takes the mortality table’s last age from the same checked keys, as
an int cell:
VA_US_S’s reader |
Checked cell |
Its extents |
|---|---|---|
mort_table() |
mort_rates() |
mort_last_age() |
fund_table() |
fund_sets() |
|
return_scenario() |
return_scenario_steps() |
|
rate_scenario() |
rate_scenario_steps() |
|
gawa_pct_table() |
gawa_pct_bands() |
|
cdsc_table() |
cdsc_scale() |
|
transaction_table() |
transactions() |
A key that is not a whole number, text and a blank among them, is refused, naming the
file, the column and the lines it is on, and so are a blank text key, a value that is not
a number in its range, blank, text and infinite values among them, a repeated key, and,
where the projection reads every year or age between a table’s first and last, keys that
do not run one row a year or an age: the message names each repeated key with its lines
and each key or span of keys missing. A key written as a float, 1.0, is the whole
number it holds, as VA_US_S’s lookups match it. Those lookups take the keys as pandas
reads them: one key written as text turns its whole column to text, so that every
scheduled premium and withdrawal is then zero without a word, and every other lookup on
the column raises Python’s own TypeError, KeyError or ValueError, naming no
file. And every value a min or a max reads is refused blank, as text or infinite,
because min and max lose a NaN in a later argument without a word.
All seven carry a compound key. mort_table is indexed by (age, sex);
fund_table by (fund_set, sub_id), so one row per subaccount describes an
allocation set; return_scenario by (scenario_id, sub_id, t) and rate_scenario
by (scenario_id, t), both read as step functions of t so a flat path is one row
per subaccount; gawa_pct_table by (gawa_grid, age_from), read as a banded lookup
on the attained age; cdsc_table by (cdsc_schedule, completed_years); and
transaction_table by (txn_id, t), a month with no row taking neither premium nor
withdrawal.
The two scenarios run on the valuation clock: the t of return_scenario_sec.csv
and rate_scenario_sec.csv is a valuation month, 0 at the valuation date, and each row
holds from its month until the next row of the same scenario (and subaccount). A market
path is a path in calendar time, shared by every point of a block, so a projection reads
it at its own t. VA_US_S keys the same paths by the elapsed policy month, so on
the valuation clock a contract needs them where its own policy months fall: each file
holds VA_US_S’s scenarios under their own ids, for the contracts issued at the
valuation date, whose policy month is t, and a copy of a contract’s path re-based to
its duration_mth for every row valued in force or issued later, under an id of its
own, {id}-M{m} or {id}-F{k}. The transaction programmes stay on the policy clock:
the t of transaction_table.csv is the elapsed policy month, 0-based, read as
Projection.duration_mth(t). completed_years in cdsc_table.csv is an elapsed
count too, read as Projection.duration(t), and is 0-based already.
The mortality table shipped here is an illustrative [std] annuitant curve, not a
published basis. The prescribed basis is the 2012 IAM Basic Table improved to
December 31, 2017 on Projection Scale G2 [R1][REG-R59], which may not be redistributed
here; swap it in by replacing mort_table.csv with a same-schema file, or point
mort_table_file at a different name, before the model computes anything. No formula
changes. Replacing a file changes VA_US_S too, which reads the same ones. A
compiled model clears no cache, so there the name is set on a package just imported,
before anything is read.
The vectors. The readers and the checked tables 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.premium()[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 and extent is an int.
Text the projection needs is decoded here, into the number it selects: each value of the
four switch columns VA_US_S branches on, glwb_stepup_basis, gmdb_option,
fee_reset_rule and rollup_rule, into a 0/1 flag, the is_* cells, and the two
withdrawal flags into 0/1 too. Each table keyed by more than a number becomes an
integer-indexed array: the mortality, the fund sets, the two scenarios, the grids, the
withdrawal charge schedules and the programmes are numbered, each point carrying the
number of its own, mort_schedule, fund_set_number, return_scenario_number,
rate_scenario_number, gawa_grid_number, cdsc_number and txn_number, each
numbered from 1 in the sorted order of its keys, the order its checked table holds them
in, but the fund sets, numbered in the order fund_sets() holds them, the file’s,
which it keeps unsorted; row 0 is the number of no key. The mortality is held by attained
age, the GAWA% by attained age, the withdrawal charge by completed years, the scenarios
step-filled by valuation month, the programmes by elapsed policy month, and the fund
sets, the returns and the opening subaccount values by subaccount id, so that the age,
the year, the month or the id is the index:
Cells |
dtype |
Shape |
From |
|---|---|---|---|
point_id() |
int64 |
[point] |
the table’s index |
age_at_entry(), duration_mth(), |
int64 |
[point] |
the four columns |
wd_start_age(), bonus_end_init() |
|||
policy_count(), premium(), |
float64 |
[point] |
the four columns |
premium_tax_rate(), wd_intensity() |
|||
gwb_pp_init() and fourteen more |
float64 |
[point] |
the fifteen float columns of the opening state |
has_wd_init(), wd_this_year_init() |
int64 |
[point] |
the checked flags |
is_stepup_annual() and nine more |
int64 |
[point] |
the ten decodes, 1 on the value |
sa_pp_init_array() |
float64 |
[point, i] |
|
gawa_pct_zero_by_point() |
int64 |
[point] |
the GAWA% grids |
fund_set_count() |
int |
scalar |
fund_table.csv |
fund_set_number() |
int64 |
[point] |
|
fund_sub_count(), fund_sub_id_last() |
int64 |
[set] |
each set’s ids |
fund_sub_ids() |
int64 |
[set, position] |
each set’s ids, in file order |
fund_held() |
int64 |
[set, i] |
1 where held |
alloc_array(), fund_expense_array() |
float64 |
[set, i] |
fund_table.csv |
return_scenario_count() |
int |
scalar |
the companion |
return_scenario_number() |
int64 |
[point] |
|
return_first_mths() |
int64 |
[scenario, i] |
each first |
return_array() |
float64 |
[scenario, i, t] |
step-filled |
rate_scenario_count() |
int |
scalar |
the companion |
rate_scenario_number() |
int64 |
[point] |
|
rate_first_mths() |
int64 |
[scenario] |
each first |
vix_sq_array(), cmt10_array() |
float64 |
[scenario, t] |
step-filled |
gawa_grid_count() |
int |
scalar |
gawa_pct_table.csv |
gawa_grid_number() |
int64 |
[point] |
|
gawa_pct_array() |
float64 |
[grid, a] |
banded, 0.0 below the first band |
gawa_last_band() |
int64 |
[grid] |
each last band’s age |
cdsc_count() |
int |
scalar |
cdsc_table.csv |
cdsc_number() |
int64 |
[point] |
|
cdsc_last_years() |
int64 |
[schedule] |
each last year |
surr_charge_rate_array() |
float64 |
[schedule, k] |
cdsc_table.csv |
txn_count() |
int |
scalar |
the programmes |
txn_number() |
int64 |
[point] |
|
prem_amount_array(), |
float64 |
[programme, n] |
0.0 without a row |
wd_amount_array() |
|||
mort_schedule_count() |
int |
scalar |
mort_table.csv |
mort_schedule() |
int64 |
[point] |
|
mort_age_firsts(), mort_age_lasts() |
int64 |
[schedule] |
each sex’s ages |
mort_age_base() |
int |
scalar |
the array’s first age |
mort_table_array() |
float64 |
[schedule, age] |
mort_table.csv |
The table checks are what they were, model_point_table() and the seven checked
tables, beside mort_last_age(). No copy of the numeric columns is read beside the
table: model_point_table() refuses every numeric column the projection reads, by
column and point, where it is blank, text or out of range, so each vector is the checked
column, read as VA_US_S’s float(), int() or bool() reads it.
Every array is held to the last age, month or subaccount id a read reaches. Three
References say where: read_last_mth, 1,141, the last element of Projection’s t
cache, 12 x (omega_age - issue_age_min) + future_horizon_mth + 1; read_last_age,
120, the last element of its a cache, omega_age; and read_last_sub_id, 9, the
last element of its i cache, subaccount_id_max, each derived in spec_sec.py,
since Data cannot read Projection’s References; a test holds each to the spec. The
scenarios and the programmes are held by month to read_last_mth, a scenario’s last row
holding to the end, as VA_US_S’s step function holds it, and the withdrawal charge to
the years a month to it can complete; the mortality and the GAWA% grids by age to
read_last_age, the last band holding to the end; the fund sets, the returns and the
opening values by id to read_last_sub_id. So a key far past any read, which
VA_US_S holds and never reaches, neither widens an array nor refuses a point
VA_US_S projects, and a read past an array, which no projection makes, is refused by
its reader in Projection, naming the point, rather than clamped. A
fund set holding an id past read_last_sub_id keeps its other ids, and its true count
and last id, by which Projection.proj_len refuses its points. The mortality is indexed
from the table’s first age, or from 0 where that is below 0, since no attained age is: so
no age a table holds is refused, a negative one among them, and none widens an array. A
change to omega_age, issue_age_min, future_horizon_mth or subaccount_id_max
needs the three References recomputed with the spec.
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 reads a checked table, never another cell’s array, and a
width comes from a table, a count cell or a Reference. Each table’s check is one 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. A
keyword named as a cell of this Space would be rewritten by the export, so none is passed,
and a local of a formula is named apart from the cells.
What cannot be decoded is refused, when the vector is first read, naming every point
at fault, where it is not VA_US_S’s reading: a point_id that is not a whole
number. A decode compares the text exactly, element by element, as VA_US_S compares
it, so a value written in another case or with a space is no flag, and the projection
answers as VA_US_S answers it, raising invalid stepup_basis and the others where it
raises them. A table without one of the four switch columns raises pandas’ KeyError at
the decode’s first read, for every point, where VA_US_S raises it where a point first
asks the column. A join number maps the point’s key as VA_US_S’s .loc matches it,
by the value pandas read, and model_point_table() has refused a key its table lacks.
A read beyond a table’s extent is refused where VA_US_S’s lookup raised, by the one
Projection cell that reads the table, naming the point: an attained age
outside the sex’s in mort_rate_base_at, a completed year below 0 in
surr_charge_rate_at, a subaccount the set does not hold in alloc and
fund_expense_rate, and a month before the scenario’s first in inv_return_mth and
scenario_rate, each a ValueError where VA_US_S raised KeyError or its own
message. An age below a grid’s first band, and a month a programme has no row at, are
0%, and no premium or withdrawal, as there.
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 VA_US_S’s reading of it:
duration_mth, the issue age, wd_start_age and bonus_end_init
(model_point_table()), the point_id (point_id()), and each assumption
table’s key, refused by the table’s check, naming the file, the column and the lines: an
age, a band’s first age, a subaccount, a completed year or a month. Each is a whole number
already, so no fraction truncates.
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. Twenty-two columns are the in-force interface:policy_countandduration_mth, the completed policy months at the valuation date, as inbasiclife.BasicTerm_SE, and the twenty columns of the opening state, per contract, as the contract stands at the start of month 0, before any month-0 event:sa_pp_init_1andsa_pp_init_2: the value of each subaccount, one column for every subaccount a fund set holds;gwb_pp_init,bb_pp_init,gawa_pp_init,rb_pp_init,np_pp_init,rp_pp_initandadj_pp_init: the GWB, the Bonus Base, the GAWA, the GMDB Benefit Base, the cumulative Net Premiums, the Remaining Premium and the GWB Adjustment;gawa_pct_init: the GAWA% locked at the first withdrawal or at depletion, 0 before either;bonus_end_init: the contract year the Bonus Period ends;has_wd_init: whether a withdrawal has been taken;sum_wd_pp_ytd_init,free_wd_used_cum_pp_ytd_init,gmdb_dfd_acc_pp_ytd_initandgmdb_factor_acc_ytd_init: the contract year to date, the withdrawals, the free allowance they used, the GMDB’s dollar-for-dollar reduction and its proportional factor, empty (0, 0, 0 and 1) at a year’s start;wd_this_year_init: whether a withdrawal was taken in the year under way;rb_pp_prev_anniv_init: the Benefit Base at the anniversary that opened the year under way, the base of the year’s dollar-for-dollar allowance;stepup_base_pp_ytd_init: the largest account value at the year’s quarterly anniversaries before the valuation month, 0 where none has passed;phi_glwb_init: on thevixfee rule, the rate of the last contract quarter to end before the valuation month, the clip’s prior for the first fee on the books.
Nine are
VA_US_S’s columns renamed:duration_mth_initbecomesduration_mth,pols_if_initpolicy_count, andgwb_init,bb_init,gawa_init,rb_init,np_init,rp_initandadj_initthe_initof the cell each opens;av_init, the account value, gives way to the subaccount values, whichVA_US_Sderives by splitting it by the target allocation. The rest areVA_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, the subaccount values apart, which are checked with the fund sets below;
no
point_idappears twice;policy_countis a number, zero or more;duration_mthis a whole number of months: positive for a contract in force, 0 for one issued at the valuation date, negative for one issued later;age_at_entry,wd_start_ageandbonus_end_initare whole numbers, 0 or more.VA_US_Sreads each byint(), which would truncate a fraction without a word;no contract 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;has_wd_initandwd_this_year_initare True or False, read by value, asTrue,False,1or0: one cell written as text turns the column to text as pandas reads it, so"True"and"False"are read as the flags they name, and the table is returned holding bools;the premium and the withdrawal intensity are each a finite number, zero or more, and the premium tax rate a number from 0 to below 1;
the twelve money columns of the opening state are each a finite number, zero or more, and
gawa_pct_init,gmdb_factor_acc_ytd_initandphi_glwb_initnumbers from 0 to 1;a contract not yet in force,
duration_mth0 or less, has no opening state: every state column is 0, or False;on a contract valued at a contract year’s start,
duration_mtha multiple of 12, the year to date is empty, exactly: the three sums 0, the factor 1 andwd_this_year_initFalse; andrb_pp_prev_anniv_initequalsrb_pp_init, the two being one instant;before the contract year’s first quarterly anniversary,
duration_mth % 12below 3, no quarter of the year has ended, sostepup_base_pp_ytd_initis 0;phi_glwb_initis 0 on a contract in force unless it is on thevixfee rule and past its first contract quarter,duration_mth3 or more: before then, and off the rule, no quarter’s rate is the clip’s prior;in the first policy year,
duration_mth1 to 11, the year opened at issue, sorb_pp_prev_anniv_initis the issue value, to a cent: the premium credited at issue,(premium + the programme's month-0 premium) x (1 - premium_tax_rate);in force,
bonus_end_initis 1 or more: it is a contract year;a contract that has withdrawn,
has_wd_initTrue, has no GWB Adjustment:adj_pp_initis 0, any withdrawal voiding it;a GAWA above 0 has a locked percentage above 0, the GAWA being the locked percentage of a base;
off a contract year’s start, a withdrawal this year is a withdrawal, so
wd_this_year_initTrue needshas_wd_initTrue; withdrawals to date above 0 needwd_this_year_initTrue; the free allowance used and the dollar-for-dollar reduction are each part of the withdrawals to date, so neither exceeds them by more than a cent; and the proportional factor is below 1 only where the year has withdrawals;last, each point’s keys into the tables it is joined with: its
fund_setis a set offund_sets(), and each subaccount the set holds has itssa_pp_init_<i>column, a finite number, zero or more to within 1e-8, and 0 on a contract not yet in force; itsscenario_idis a scenario ofreturn_scenario_steps()that sets a return for each of those subaccounts by the first month the point is on the books,t = 0or its issue month if later, and, on a point thevixfee or thecmt_linkedroll-up reads it for, a scenario ofrate_scenario_steps()that sets its levels by then; itstxn_idis a programme oftransactions(); itsglwb_optiona grid ofgawa_pct_bands(), and, in force,has_wd_initTrue needsgawa_pct_initabove 0 unless that grid gives 0% at an attained age the contract reached before the valuation month (the scangawa_pct_zero_by_point()makes, written here again over the table being checked), since the first withdrawal locks the percentage of the age it is taken at, and agwb_pp_initand agawa_pct_initabove 0 need agawa_pp_initabove 0 unless the grid did, since the withdrawal or the depletion that locked the percentage set the GAWA to it times the GWB, and nothing after takes the GAWA to 0 while a GWB is left; itscdsc_schedulea schedule ofcdsc_scale(); andmort_rates()gives a rate at itssexand its attained age in its first month on the books. So reading the table reads every assumption table, checked.
Amounts of money are compared to a cent, so that an extract may carry each to the cent, as an administration system holds it: each amount so carried is within half a cent of its exact value. Two columns that hold one amount at instants that coincide, on a year’s start, are compared exactly. A subaccount value is held to 0 or more to within 1e-8, not a cent:
VA_US_Sruns an account down by scaling each subaccount by one less the share of the account a charge or a withdrawal takes, so a depletion can close on a rounding of either sign about 0, of the order of 1e-14, the one amount of the opening state its arithmetic leaves below 0, the bases being held at 0 or more by its floors; an extract carries such a rounding to the cent as 0.00. A contract whose account value is at or below the depletion threshold opens depleted, its account released in month 0 with no flow, soProjection.check_av_roll_fwd, at 1e-6 a contract, would miss by the account a cent below 0 left there (§7.4, Record — M6, Carried into M13);Projection.proj_lenholds such an account to 0 within 1e-8, since the threshold is aProjectionReference.Accepted, because a contract can be in each state: an account value of 0 in force, where the GLWB pays on and the projection reads the contract as depleted from month 0, or the rounding about 0 that a depletion closed on, above 0 or below it, within 1e-8, which the same test reads as depleted; a locked percentage above 0 with no withdrawal taken, where the account value ran out first, which the projection checks; free allowance used and a dollar-for-dollar reduction above the allowance the month allows at the valuation date, since the allowance is recomputed every month from the earnings and the Remaining Premium; and a
duration_mth, an age orbonus_end_initwritten as a float, and a flag written as 1 or 0, read as the value each holds.Left to the projection, because each needs a
ProjectionReference, whichDatacannot read, and refused byProjection.proj_len, naming the point: whether a point is still in cover, againstomega_age; whether it is depleted at the valuation date, which the projection derives from its opening account value andav_depletion_threshold, and then an account value of 0 within 1e-8, and the GAWA% that goes with each: 0 on a contract that has neither withdrawn nor depleted, and above 0 on one depleted without a withdrawal unless its grid gave 0% at an age it reached (gawa_pct_zero_by_point()); on thehighest_quarterly_CVbasis, a step-up history above the threshold on a contract not depleted and three months or more into its contract year, since every quarter end of the year closed above it; and, on thevixfee rule,phi_glwb_initthe first quarter’s rate,phi_glwb_curr, in the second contract quarter, and from the third at mostvix_corridor_hi, and at leastvix_corridor_lowherephi_glwb_curris, the clip holding every rate after the first there. The rest of the year to date, the step-up base and the VIX prior are history, which nothing here can check beyond these rules.
- return_scenario()[source]#
Gross subaccount returns, read from return_scenario_sec.csv.
Indexed by
(scenario_id, sub_id, t), wheretis a valuation month, 0 at the valuation date, and read as a step function oft: each row states the monthly gross fund return that holds from that month until the next row for the same scenario and subaccount.VA_US_S’s reader, unchanged and pointed at this model’s own file throughreturn_scenario_file.The file is generated from
VA_US_S’s return_scenario.csv, whosetis the elapsed policy month. Each ofVA_US_S’s scenarios is here under its own id, which is where the policy months of a contract issued at the valuation date fall. Each row of the model point table valued in force at policy monthmreads a copy of its path re-based tom,{id}-M{m}: the returnsVA_US_Sset before monthmcollapse to the return in force atm, att = 0, and the later rows movemmonths earlier, each subaccount on its own rows. Each row issuedkmonths after the valuation date reads a copy movedkmonths later,{id}-F{k}, which sets no return before its issue month. Rows that move alike share a copy. So every row reads each policy month’s return at the valuation month that policy month falls in, and the model reproducesVA_US_Sthere.
- rate_scenario()[source]#
The exogenous market rate series, read from rate_scenario_sec.csv.
Indexed by
(scenario_id, t), wheretis a valuation month, 0 at the valuation date, and read as a step function oft. It carries the quarterly average of daily VIX-squared driving the optional non-discretionary fee reset [S4][S6] and the 10-year Constant Maturity Treasury rate driving the optional formula-linked GMDB roll-up [S7]. Neither is used by the base run.VA_US_S’s reader, unchanged and pointed at this model’s own file throughrate_scenario_file.The file is generated from
VA_US_S’s rate_scenario.csv, whosetis the elapsed policy month, re-based asreturn_scenario()is:VA_US_S’s scenarios under their own ids, and a copy{id}-M{m}or{id}-F{k}for each row valued in force or issued later.
- gawa_pct_table()[source]#
The GAWA% grid by attained age band, read from gawa_pct_table.csv.
Indexed by
(gawa_grid, age_from); the applicable row is the highestage_fromat or below the attained age at the first withdrawal [S3].
- cdsc_table()[source]#
The withdrawal charge scale, read from cdsc_table.csv.
Indexed by
(cdsc_schedule, completed_years), where the key is completed years since receipt of the premium being withdrawn, not the contract year [S2].
- transaction_table()[source]#
Scheduled policyholder transactions, read from transaction_table.csv.
Indexed by
(txn_id, t), the elapsed policy month (0-based), with a gross premium and a gross withdrawal per month; a month with no row takes neither. Scheduled withdrawals are added to the utilization withdrawal the base run derives from the GLWB, which is how the excess algebra is exercised.
- mort_rates()[source]#
Annual mortality by attained age and sex, as
mort_table()reads it, checked.Indexed by
(age, sex), the age read by value, once, so that an age written61.0is 61, asVA_US_S’s lookup matches it, and sorted.Projection.mort_rate_base_at, the table’s one reader, reads it here, and takes its last age,mort_last_age(), from the same checked ages, so a projection meets the check first. An age that is not a whole number, text and a blank among them, a blank sex, a rate that is not a number from 0 to 1, blank and text among them, and a sex whose ages do not run one row an age, without a gap or a repeat, are refused, naming the file, the column and the lines they are on: for the last, each age a sex repeats, with its lines, and each age or span of ages it lacks between its first and its last, every one of them in one message.VA_US_Stakes the raw ages’ largest for its last: one written as text raises Python’s ownTypeError, naming no file.
- mort_last_age()[source]#
The last attained age
mort_rates()gives a rate for, an int.Projection.mort_rate_base_atreads every older age at it, asVA_US_Scaps the age at the table’s last. No attained age in cover is older than 119 at the shippedProjection.omega_age, 120, where cover ends, and the shipped table runs to 120.
- fund_sets()[source]#
The fund sets, as
fund_table()reads them, checked.Indexed by
(fund_set, sub_id), the subaccount read by value, once, and kept in file order, whichProjection.sub_idsreturns.Projection.sub_ids,allocandfund_expense_rate, the table’s three readers, read it here, so a projection meets the check first. A blankfund_set, a subaccount that is not a whole number, 1 or more, text and a blank among them, an allocation or a fund expense ratio that is not a number from 0 to 1, blank and text among them, a set that holds a subaccount twice, and a set whose allocations do not sum to 1 within 1e-12 are refused, naming the file, the column and the lines, or the sets, they are on.
- return_scenario_steps()[source]#
The return scenarios, as
return_scenario()reads them, checked.Indexed by
(scenario_id, sub_id, t), each subaccount and eacht, a valuation month, read by value, once, and sorted.Projection.inv_return_mth, the table’s one reader, reads it here, so a projection meets the check first. A month that is not a whole number, 0 or more, text and a blank among them, a blankscenario_id, a subaccount that is not a whole number, 1 or more, a gross return that is not a finite number above -1, blank and text among them, and a scenario that sets two returns for one subaccount at one month are refused, naming the file, the column and the lines they are on. A scenario may start aftert = 0, for business issued later, so the month a scenario must start by is the point’s:model_point_table()refuses a point whose scenario sets no return for a subaccount of its fund set by the first month the point is on the books.
- rate_scenario_steps()[source]#
The rate scenarios, as
rate_scenario()reads them, checked.Indexed by
(scenario_id, t), eachta valuation month read by value, once, and sorted.Projection.scenario_rate, the table’s one reader, reads it here, so a projection meets the check first. A month that is not a whole number, 0 or more, text and a blank among them, a blankscenario_id, a VIX-squared average that is not a finite number, zero or more, a CMT rate that is not a finite number above -1, and a scenario that sets two levels at one month are refused, naming the file, the column and the lines they are on. The month a scenario must start by is the point’s, as forreturn_scenario_steps(), and only on a point thevixfee or thecmt_linkedroll-up reads it for: on any other point no level is read.
- gawa_pct_bands()[source]#
The GAWA% grids, as
gawa_pct_table()reads them, checked.Indexed by
(gawa_grid, age_from), each band’s first age read by value, once, and sorted.Projection.gawa_pct_at_age, the table’s one reader, reads it here, so a projection meets the check first. A blankgawa_grid, anage_fromthat is not a whole number, 0 or more, text and a blank among them, a percentage that is not a number from 0 to 1, blank and text among them, and a grid that starts a band twice at one age are refused, naming the file, the column and the lines they are on. A grid is banded, so its ages need not run one a year: each band holds from itsage_fromuntil the next band of the same grid, and an age below the first band reads 0%.
- cdsc_scale()[source]#
The withdrawal charge schedules, as
cdsc_table()reads them, checked.Indexed by
(cdsc_schedule, completed_years), the years read by value, once, and sorted.Projection.surr_charge_rate_at, the table’s one reader, reads it here, and takes each schedule’s last year from the same checked years, so a projection meets the check first. A blankcdsc_schedule, a year that is not a whole number, text and a blank among them, a charge that is not a number from 0 to 1, blank and text among them, and years that do not run from 0, one row a year, without a gap or a repeat, are refused, naming the file, the column and the lines they are on: for the last, each year below 0 or repeated, with its lines, and each year or span of years a schedule lacks from 0 to its last, every one of them in one message. Each schedule’s last row holds for every later year.VA_US_Stakesint()of the raw years’ largest: one written as text raises Python’s own message, naming no file.
- transactions()[source]#
The transaction programmes, as
transaction_table()reads them, checked.Indexed by
(txn_id, t), eachtan elapsed policy month read by value, once, asVA_US_S’s exact-key lookup matches it, and sorted.Projection.prem_scheduled_pmandProjection.wd_scheduled_pm, the readers of its two columns, read it here, so a projection meets the check first; so doesmodel_point_table(), for a programme’s month-0 premium. A blanktxn_id, a month that is not a whole number, 0 or more, text and a blank among them, an amount that is not a finite number, zero or more, blank and text among them, and a programme that holds two rows at one month are refused, naming the file, the column and the lines they are on.VA_US_S’s lookup matches the raw months: one written as text turns them all to text, and every scheduled premium and withdrawal of every programme is then zero.
- point_id()[source]#
The
point_idof each row, an int64 vector, read by value from the table’s index.Projectionis indexed by position,idx, and reads its point’s label here, so that every refusal names the point by the label a reader finds in the table. A label that is not a whole number, or not below2**53in size, is refused, naming it:VA_US_Skeys its points by any label pandas reads.
- bonus_end_init()[source]#
The contract year each point’s Bonus Period ends, carried in, an int64 vector.
The single purchase payment of each point, a float64 vector.
tau, the premium tax rate of each point, a float64 vector.
- sum_wd_pp_ytd_init()[source]#
The withdrawals of the contract year to date, entering month 0, float64.
- free_wd_used_cum_pp_ytd_init()[source]#
The free allowance used in the contract year to date, entering month 0, float64.
- gmdb_dfd_acc_pp_ytd_init()[source]#
The GMDB dollar-for-dollar reduction of the year to date, entering month 0.
- gmdb_factor_acc_ytd_init()[source]#
The GMDB proportional factor of the year to date, entering month 0, float64.
- rb_pp_prev_anniv_init()[source]#
The Benefit Base at the anniversary opening the year under way, float64.
- stepup_base_pp_ytd_init()[source]#
The year’s highest quarterly account value before month 0, float64.
- has_wd_init()[source]#
Whether each point has withdrawn before the valuation date, 1 or 0, int64.
model_point_table()has read the column by value into bools, so"False"written as text is 0, notbool("False").
- wd_this_year_init()[source]#
Whether the year under way took a withdrawal before month 0, 1 or 0, int64.
Read by value into bools by
model_point_table(), ashas_wd_init()is.
- is_stepup_annual()[source]#
1 where
glwb_stepup_basisisannual_CV, else 0, an int64 vector.VA_US_S’s comparison, made element by element, exactly:Annual_CV, orannual_CVwith a space, is 0, and so is a blank. A table without the column raises pandas’KeyErrorhere, at the first read, asVA_US_Sraises it where a point first asks the basis.
- is_stepup_highest_quarterly()[source]#
1 where
glwb_stepup_basisishighest_quarterly_CV, else 0, int64.The other decode of the column, as
is_stepup_annual()is.
- is_gmdb_rollup()[source]#
1 where
gmdb_optionisrollup, else 0, an int64 vector.VA_US_S’s comparison, element by element, exactly, asis_stepup_annual()’s is.
- is_fee_reset_none()[source]#
1 where
fee_reset_ruleisnone, else 0, an int64 vector.VA_US_S’s comparison, element by element, exactly, asis_stepup_annual()’s is.
- is_fee_reset_quinquennial()[source]#
1 where
fee_reset_ruleisquinquennial, else 0, an int64 vector.
- is_rollup_fixed()[source]#
1 where
rollup_ruleisfixed, else 0, an int64 vector.VA_US_S’s comparison, element by element, exactly, asis_stepup_annual()’s is.
- sa_pp_init_array()[source]#
The subaccount values of the opening state,
[point, subaccount id], float64.Column
i, from 1 toread_last_sub_id, is the checked table’ssa_pp_init_<i>column, per contract, entering month 0, before any month-0 event; column 0, which no subaccount has, is NaN.model_point_table()has required the column of every subaccount a point’s set holds, a finite number, zero or more to within 1e-8, and 0 on a contract not yet in force; a cell of a subaccount the point’s set lacks, blank or text, which no projection reads, is 0.0 here, read as a number where it is one, and so is every cell of a column the table lacks.
- gawa_pct_zero_by_point()[source]#
Whether each point’s grid gave 0% at an attained age it reached before month 0.
An int64 vector by position, 1 or 0: on a contract in force, 1 where its
glwb_optiongrid ofgawa_pct_bands()gives 0% at an attained age from its issue age to its age in the month before the valuation month, each age read at the band starting at the largestage_fromat or below it, an age below the grid’s first band reading 0%, by an explicit loop over the checked bands; 0 on one not yet in force, which has reached no age. The same scanmodel_point_table()’s rules of the locked GAWA% make.Projection.proj_len, its one reader, checks against it the GAWA% of a depleted contract that has not withdrawn, a rule that needsProjection.av_depletion_threshold: a vector built here from inputs that live here (R2), so that the projection reads the grid at no age before its first on the books.
- fund_set_count()[source]#
The number of fund sets
fund_sets()holds, an int.
- fund_set_number()[source]#
The row of the fund arrays each point reads, by its
fund_set, int64.The sets are numbered from 1 in the order
fund_sets()first holds them, the file’s, which it keeps unsorted, so that a table mixing text and numeric keys reads as at stage E; each point carries its own set’s number, matched by the value pandas read, asVA_US_S’s.locmatches it.model_point_table()refuses a point whose set the table lacks, so 0, the number of no set, is never a point’s.
- fund_sub_count()[source]#
The number of subaccounts each fund set holds, by its number, int64; row 0 is 0.
- fund_sub_ids()[source]#
Each fund set’s subaccount ids in file order,
[set, position], int64.The order
VA_US_S’ssub_idsreturns them in and its sums run in; a set’s ids from 1 toread_last_sub_id, the subaccount axis of every array, at positions 0 on, and -1 after them and in row 0, which no read reaches. An id pastread_last_sub_idis not held, andfund_sub_id_last()keeps it, by whichProjection.proj_lenrefuses the set’s points before any read.
- fund_sub_id_last()[source]#
Each fund set’s largest subaccount id, by its number, int64; row 0 is 0.
The set’s own, however far past
read_last_sub_id:Projection.proj_lenrefuses a point whose set holds an id aboveProjection.subaccount_id_max.
- fund_held()[source]#
1 where a fund set holds subaccount
i,[set, i], int64; else 0.The subaccount axis runs from 0 to
read_last_sub_id, column 0 and row 0 holding nothing.
- alloc_array()[source]#
The allocation of net premium by fund set and subaccount id,
[set, i].NaN where the set holds no subaccount
i, in column 0 and in row 0.
- fund_expense_array()[source]#
The annual fund expense ratio by fund set and subaccount id,
[set, i].As
alloc_array(), from the table’s other column.
- return_scenario_count()[source]#
The number of scenarios
return_scenario_steps()holds, an int.
- return_scenario_number()[source]#
The row of
return_array()each point reads, by itsscenario_id, int64.Numbered from 1 in the sorted order of the ids, the order
return_scenario_steps()holds them in;model_point_table()refuses an id the table lacks.
- return_first_mths()[source]#
Each scenario’s first month for each subaccount id,
[scenario, i], int64.read_last_mth + 1, past every month the array holds, where the scenario sets no return for the subaccount, in column 0 and in row 0, and where its first month is pastread_last_mth: either wayProjection.inv_return_mthrefuses a read before it.
- return_array()[source]#
The gross monthly return by scenario, subaccount id and month,
[scenario, i, t].Each scenario’s rows for each subaccount step-filled from their month to the next row’s, the last to
read_last_mth, asVA_US_S’s step function holds it; NaN before a subaccount’s first month, for a subaccount the scenario lacks, in column 0 and in row 0. A row pastread_last_mth, and a subaccount pastread_last_sub_id, are held nowhere.
- rate_scenario_count()[source]#
The number of scenarios
rate_scenario_steps()holds, an int.
- rate_scenario_number()[source]#
The row of the rate arrays each point reads, by its
scenario_id, int64.Numbered from 1 in the sorted order of the ids, as
return_scenario_number()numbers the returns. 0 whererate_scenario_steps()lacks the id, whichmodel_point_table()accepts on a point no level is read for, and whichProjection.scenario_raterefuses where it is read:rate_first_mths()holds row 0 past every month.
- rate_first_mths()[source]#
Each rate scenario’s first month, by its number, int64;
read_last_mth + 1in row 0, and where a scenario’s first month is past it.
- vix_sq_array()[source]#
The quarterly average of daily VIX-squared by scenario and month,
[scenario, t].Each scenario’s rows step-filled from their month to the next row’s, the last to
read_last_mth; NaN before a scenario’s first month and in row 0. A row pastread_last_mthis held nowhere.
- cmt10_array()[source]#
The 10-year CMT rate by scenario and month,
[scenario, t].As
vix_sq_array(), from the table’s other column.
- gawa_grid_count()[source]#
The number of grids
gawa_pct_bands()holds, an int.
- gawa_grid_number()[source]#
The row of
gawa_pct_array()each point reads, by itsglwb_option, int64.Numbered from 1 in the sorted order of the grids;
model_point_table()refuses a grid the table lacks.
- gawa_pct_array()[source]#
The GAWA% by grid and attained age,
[grid, a], ages 0 toread_last_age.Each age reads the band starting at the largest
age_fromat or below it, and an age below the grid’s first band reads 0.0,VA_US_S’s value there, not padding; row 0 is NaN. A band starting pastread_last_ageis held nowhere, andgawa_last_band()keeps where each grid’s last band starts.
- gawa_last_band()[source]#
The age each grid’s last band starts at, by its number, int64; row 0 is 0.
The grid’s own, however far past
read_last_age:Projection.gawa_pct_at_agereads an older age atread_last_agewhere the last band starts at or below it, and refuses one where it does not.
- cdsc_count()[source]#
The number of withdrawal charge schedules
cdsc_scale()holds, an int.
- cdsc_number()[source]#
The row of
surr_charge_rate_array()each point reads, by itscdsc_schedule, int64.Numbered from 1 in the sorted order of the schedules;
model_point_table()refuses a schedule the table lacks.
- cdsc_last_years()[source]#
Each schedule’s last completed year, by its number, int64; row 0 is 0.
The schedule’s own, whose row holds for every later year, as
VA_US_Scaps the year at the table’s largest.
- surr_charge_rate_array()[source]#
The withdrawal charge rate by schedule and completed years,
[schedule, k].Years 0 to
read_last_mth // 12, 95, the most a month toread_last_mthcan have completed;cdsc_scale()holds each schedule’s years from 0 to its last without a gap, so the year is the index. NaN past a schedule’s last year, which no read reaches, and in row 0; a year past 95 is held nowhere.
- txn_count()[source]#
The number of programmes
transactions()holds, an int.
- txn_number()[source]#
The row of the programme arrays each point reads, by its
txn_id, int64.Numbered from 1 in the sorted order of the ids;
model_point_table()refuses a programme the table lacks.
- prem_amount_array()[source]#
The scheduled gross premium by programme and elapsed policy month,
[p, n].0.0 at a month a programme has no row for, a value, as
VA_US_S’s exact-key lookup answers it, not padding; row 0, which no point reads, is NaN. Months 0 toread_last_mth; a row past it is held nowhere.
- wd_amount_array()[source]#
The scheduled gross withdrawal by programme and elapsed policy month,
[p, n].As
prem_amount_array(), from the table’s other column.
- mort_schedule_count()[source]#
The number of sexes
mort_rates()holds, an int.
- mort_schedule()[source]#
The row of
mort_table_array()each point reads, by itssex, int64.The sexes are numbered from 1 in their sorted order, the order
groupbytakes, and each point carries its own sex’s number, matched by the value pandas read, asVA_US_S’s.locmatches it.model_point_table()refuses a point whose sex the table lacks, so 0, the number of no sex, is never a point’s.
- mort_age_firsts()[source]#
Each sex’s first age in
mort_rates(), by its number, int64; row 0 is 1.
- mort_age_lasts()[source]#
Each sex’s last age in
mort_rates(), by its number, int64; row 0 is 0.The table’s own last age, however far past
read_last_age.
- mort_age_base()[source]#
The age of
mort_table_array()’s first column, an int.The table’s first age, of any sex, or 0 where that is below 0: an attained age is never below the youngest issue age, so no read reaches a negative age, and a row at a negative age, which
VA_US_Sholds and never reads, is not held. So neither a negative age nor one far below every other widens the array.
- mort_table_array()[source]#
The annual mortality by sex and attained age,
[sex, age - mort_age_base()].Row
mort_schedule()of a point holds its sex’s rates, row 0 none; columnjis attained agemort_age_base() + j, toread_last_age, the oldest age a read reaches. Every cell outside a sex’s ages, and row 0, is NaN, and an age pastread_last_ageis held nowhere, so a row far past it, whichVA_US_Sholds and never reads, neither widens the array nor refuses a point.