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]

sa_pp_init_<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_set, joined

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]

scenario_id, joined

return_first_mths()

int64

[scenario, i]

each first t

return_array()

float64

[scenario, i, t]

step-filled

rate_scenario_count()

int

scalar

the companion

rate_scenario_number()

int64

[point]

scenario_id, joined, 0 if absent

rate_first_mths()

int64

[scenario]

each first t

vix_sq_array(), cmt10_array()

float64

[scenario, t]

step-filled

gawa_grid_count()

int

scalar

gawa_pct_table.csv

gawa_grid_number()

int64

[point]

glwb_option, joined

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_schedule, joined

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]

txn_id, joined

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]

sex, joined

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_count and duration_mth, the completed policy months at the valuation date, as in basiclife.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_1 and sa_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_init and adj_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_init and gmdb_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 the vix fee 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_init becomes duration_mth, pols_if_init policy_count, and gwb_init, bb_init, gawa_init, rb_init, np_init, rp_init and adj_init the _init of the cell each opens; av_init, the account value, gives way to the subaccount values, which VA_US_S derives by splitting it by the target allocation. The rest are VA_US_S’s, except row_kind, source_policy_id and source_mth, which record where the generator took each shipped row from and which no formula reads.

The checks run over the whole table at once, 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_id appears twice;

  • policy_count is a number, zero or more;

  • duration_mth is 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_age and bonus_end_init are whole numbers, 0 or more. VA_US_S reads each by int(), which would truncate a fraction without a word;

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

  • has_wd_init and wd_this_year_init are True or False, read by value, as True, False, 1 or 0: 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_init and phi_glwb_init numbers from 0 to 1;

  • a contract not yet in force, duration_mth 0 or less, has no opening state: every state column is 0, or False;

  • on a contract valued at a contract year’s start, duration_mth a multiple of 12, the year to date is empty, exactly: the three sums 0, the factor 1 and wd_this_year_init False; and rb_pp_prev_anniv_init equals rb_pp_init, the two being one instant;

  • before the contract year’s first quarterly anniversary, duration_mth % 12 below 3, no quarter of the year has ended, so stepup_base_pp_ytd_init is 0;

  • phi_glwb_init is 0 on a contract in force unless it is on the vix fee rule and past its first contract quarter, duration_mth 3 or more: before then, and off the rule, no quarter’s rate is the clip’s prior;

  • in the first policy year, duration_mth 1 to 11, the year opened at issue, so rb_pp_prev_anniv_init is 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_init is 1 or more: it is a contract year;

  • a contract that has withdrawn, has_wd_init True, has no GWB Adjustment: adj_pp_init is 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_init True needs has_wd_init True; withdrawals to date above 0 need wd_this_year_init True; 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_set is a set of fund_sets(), and each subaccount the set holds has its sa_pp_init_<i> column, a finite number, zero or more to within 1e-8, and 0 on a contract not yet in force; its scenario_id is a scenario of return_scenario_steps() that sets a return for each of those subaccounts by the first month the point is on the books, t = 0 or its issue month if later, and, on a point the vix fee or the cmt_linked roll-up reads it for, a scenario of rate_scenario_steps() that sets its levels by then; its txn_id is a programme of transactions(); its glwb_option a grid of gawa_pct_bands(), and, in force, has_wd_init True needs gawa_pct_init above 0 unless that grid gives 0% at an attained age the contract reached before the valuation month (the scan gawa_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 a gwb_pp_init and a gawa_pct_init above 0 need a gawa_pp_init above 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; its cdsc_schedule a schedule of cdsc_scale(); and mort_rates() gives a rate at its sex and 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_S runs 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, so Projection.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_len holds such an account to 0 within 1e-8, since the threshold is a Projection Reference.

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 or bonus_end_init written 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 Projection Reference, which Data cannot read, and refused by Projection.proj_len, naming the point: whether a point is still in cover, against omega_age; whether it is depleted at the valuation date, which the projection derives from its opening account value and av_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 the highest_quarterly_CV basis, 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 the vix fee rule, phi_glwb_init the first quarter’s rate, phi_glwb_curr, in the second contract quarter, and from the third at most vix_corridor_hi, and at least vix_corridor_lo where phi_glwb_curr is, 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.

mort_table()[source]#

Annual mortality by attained age and sex, read from mort_table.csv.

fund_table()[source]#

Subaccount allocations and fund expense ratios, from fund_table.csv.

return_scenario()[source]#

Gross subaccount returns, read from return_scenario_sec.csv.

Indexed by (scenario_id, sub_id, t), where t is a valuation month, 0 at the valuation date, and read as a step function of t: 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 through return_scenario_file.

The file is generated from VA_US_S’s return_scenario.csv, whose t is the elapsed policy month. Each of VA_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 month m reads a copy of its path re-based to m, {id}-M{m}: the returns VA_US_S set before month m collapse to the return in force at m, at t = 0, and the later rows move m months earlier, each subaccount on its own rows. Each row issued k months after the valuation date reads a copy moved k months 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 reproduces VA_US_S there.

rate_scenario()[source]#

The exogenous market rate series, read from rate_scenario_sec.csv.

Indexed by (scenario_id, t), where t is a valuation month, 0 at the valuation date, and read as a step function of t. 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 through rate_scenario_file.

The file is generated from VA_US_S’s rate_scenario.csv, whose t is the elapsed policy month, re-based as return_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 highest age_from at 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 written 61.0 is 61, as VA_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_S takes the raw ages’ largest for its last: one written as text raises Python’s own TypeError, naming no file.

mort_last_age()[source]#

The last attained age mort_rates() gives a rate for, an int.

Projection.mort_rate_base_at reads every older age at it, as VA_US_S caps the age at the table’s last. No attained age in cover is older than 119 at the shipped Projection.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, which Projection.sub_ids returns. Projection.sub_ids, alloc and fund_expense_rate, the table’s three readers, read it here, so a projection meets the check first. A blank fund_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 each t, 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 blank scenario_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 after t = 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), each t a 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 blank scenario_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 for return_scenario_steps(), and only on a point the vix fee or the cmt_linked roll-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 blank gawa_grid, an age_from that 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 its age_from until 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 blank cdsc_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_S takes int() 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), each t an elapsed policy month read by value, once, as VA_US_S’s exact-key lookup matches it, and sorted. Projection.prem_scheduled_pm and Projection.wd_scheduled_pm, the readers of its two columns, read it here, so a projection meets the check first; so does model_point_table(), for a programme’s month-0 premium. A blank txn_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_id of each row, an int64 vector, read by value from the table’s index.

Projection is 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 below 2**53 in size, is refused, naming it: VA_US_S keys its points by any label pandas reads.

age_at_entry()[source]#

The issue age of each point, an int64 vector (Projection.age_at_entry).

duration_mth()[source]#

The policy months completed at the valuation date, an int64 vector.

wd_start_age()[source]#

The attained age each point’s GLWB withdrawals begin at, an int64 vector.

bonus_end_init()[source]#

The contract year each point’s Bonus Period ends, carried in, an int64 vector.

policy_count()[source]#

The contracts each point stands for, a float64 vector.

premium()[source]#

The single purchase payment of each point, a float64 vector.

premium_tax_rate()[source]#

tau, the premium tax rate of each point, a float64 vector.

wd_intensity()[source]#

The share of the annual limit each point withdraws once activated, float64.

gwb_pp_init()[source]#

The GWB entering month 0, per contract, a float64 vector.

gawa_pp_init()[source]#

The GAWA entering month 0, per contract, a float64 vector.

gawa_pct_init()[source]#

The GAWA% locked by the valuation date, a float64 vector.

bb_pp_init()[source]#

The Bonus Base entering month 0, per contract, a float64 vector.

rb_pp_init()[source]#

The GMDB Benefit Base entering month 0, per contract, a float64 vector.

np_pp_init()[source]#

The cumulative Net Premiums entering month 0, per contract, a float64 vector.

rp_pp_init()[source]#

The Remaining Premium entering month 0, per contract, a float64 vector.

adj_pp_init()[source]#

The GWB Adjustment entering month 0, per contract, 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.

phi_glwb_init()[source]#

On the vix fee rule, the last quarter’s rate 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, not bool("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(), as has_wd_init() is.

is_stepup_annual()[source]#

1 where glwb_stepup_basis is annual_CV, else 0, an int64 vector.

VA_US_S’s comparison, made element by element, exactly: Annual_CV, or annual_CV with a space, is 0, and so is a blank. A table without the column raises pandas’ KeyError here, at the first read, as VA_US_S raises it where a point first asks the basis.

is_stepup_highest_quarterly()[source]#

1 where glwb_stepup_basis is highest_quarterly_CV, else 0, int64.

The other decode of the column, as is_stepup_annual() is.

is_gmdb_rollup()[source]#

1 where gmdb_option is rollup, else 0, an int64 vector.

VA_US_S’s comparison, element by element, exactly, as is_stepup_annual()’s is.

is_gmdb_ratchet()[source]#

1 where gmdb_option is ratchet, else 0, an int64 vector.

is_gmdb_basic()[source]#

1 where gmdb_option is basic, else 0, an int64 vector.

is_fee_reset_none()[source]#

1 where fee_reset_rule is none, else 0, an int64 vector.

VA_US_S’s comparison, element by element, exactly, as is_stepup_annual()’s is.

is_fee_reset_quinquennial()[source]#

1 where fee_reset_rule is quinquennial, else 0, an int64 vector.

is_fee_reset_vix()[source]#

1 where fee_reset_rule is vix, else 0, an int64 vector.

is_rollup_fixed()[source]#

1 where rollup_rule is fixed, else 0, an int64 vector.

VA_US_S’s comparison, element by element, exactly, as is_stepup_annual()’s is.

is_rollup_cmt_linked()[source]#

1 where rollup_rule is cmt_linked, else 0, an int64 vector.

sa_pp_init_array()[source]#

The subaccount values of the opening state, [point, subaccount id], float64.

Column i, from 1 to read_last_sub_id, is the checked table’s sa_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_option grid of gawa_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 largest age_from at 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 scan model_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 needs Projection.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, as VA_US_S’s .loc matches 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’s sub_ids returns them in and its sums run in; a set’s ids from 1 to read_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 past read_last_sub_id is not held, and fund_sub_id_last() keeps it, by which Projection.proj_len refuses 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_len refuses a point whose set holds an id above Projection.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 its scenario_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 past read_last_mth: either way Projection.inv_return_mth refuses 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, as VA_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 past read_last_mth, and a subaccount past read_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 where rate_scenario_steps() lacks the id, which model_point_table() accepts on a point no level is read for, and which Projection.scenario_rate refuses 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 + 1 in 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 past read_last_mth is 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 its glwb_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 to read_last_age.

Each age reads the band starting at the largest age_from at 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 past read_last_age is held nowhere, and gawa_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_age reads an older age at read_last_age where 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 its cdsc_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_S caps 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 to read_last_mth can 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 to read_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 its sex, int64.

The sexes are numbered from 1 in their sorted order, the order groupby takes, and each point carries its own sex’s number, matched by the value pandas read, as VA_US_S’s .loc matches 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_S holds 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; column j is attained age mort_age_base() + j, to read_last_age, the oldest age a read reaches. Every cell outside a sex’s ages, and row 0, is NaN, and an age past read_last_age is held nowhere, so a row far past it, which VA_US_S holds and never reads, neither widens the array nor refuses a point.