The Data Space#

Input data shared by every by-contract projection.

The seven 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/fixed_indexed_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 FIA_US_SEC folder without its parent’s CSVs produces a model that reads and then fails on first evaluation.

Five of the tables are FIA_US_S’s. The mortality table, the surrender charge and vesting schedule, the rollup schedules, the lifetime withdrawal percentage bands and the withdrawal programmes are the files FIA_US_S reads, read here in place: one copy of each table serves both models, so an edit to one reaches both. The other two are this model’s own, each generated from FIA_US_S and its inputs, never typed: model_point_table_sec.csv, beside FIA_US_S’s model_point_table.csv, and rate_scenario_sec.csv, the rate scenarios moved onto the valuation clock, beside FIA_US_S’s rate_scenario.csv. This model opens neither of FIA_US_S’s two.

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

surr_charge_file

surr_charge_table()

surr_charge_table.csv

rollup_file

rollup_table()

rollup_table.csv

payout_rate_file

payout_rate_table()

payout_rate_table.csv

rate_scenario_file

rate_scenario()

rate_scenario_sec.csv

withdrawal_file

withdrawal_table()

withdrawal_table.csv

The model point table is checked as it is read. Fourteen of its columns are the in-force interface: policy_count and duration_mth, as in basiclife.BasicTerm_SE, and the twelve columns of an in-force contract’s opening state. 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 scenario that sets no level by the point’s first month on the books, a rollup schedule, a withdrawal programme, 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.

So are the keys and values of the six assumption tables. Each reader above is FIA_US_S’s, unchanged, 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. Every array the projection reads is built from that checked table, and takes the table’s extents from the same checked keys, as int cells:

FIA_US_S’s reader

Checked cell

Its extents

mort_table()

mort_rates()

surr_charge_table()

surr_charge_scale()

surr_charge_last_year()

rollup_table()

rollup_steps()

payout_rate_table()

payout_rates()

payout_rate_first_age(), payout_rate_last_age()

rate_scenario()

rate_scenario_steps()

withdrawal_table()

wd_schedules()

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 FIA_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 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 cap, 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. A key is also refused unless it is below 2**53 in size, so that the int64 it is cast to holds it (The vectors, below).

Two tables are read as step functions, so a schedule is a handful of rows rather than one row per contract year or month. rollup_table is indexed by (rollup_id, contract_year) and each row states the guaranteed simple rollup rate that holds from its own contract year until the next row of the same schedule, which turns the blended 5.00%/2.00%/0% [S2] and the flat 3.00%/0% [S9] designs into three rows and two. rate_scenario is indexed by (scenario_id, t) and carries the index level I and the MVA reference yield i_t; there t is a valuation month, 0 at the valuation date, and each row holds from its month until the next row of the same scenario. The projection reads the level at each anniversary of the contract, at the valuation month that anniversary falls in, and differences consecutive anniversaries’ levels into R = I(y+1)/I(y) - 1, the return over the contract year, so holding a level flat is how a scenario says “no index credit this year”. FIA_US_S keys the same levels by anniversary number from issue, so on the valuation clock a contract needs them where its own anniversaries fall: the file holds FIA_US_S’s scenarios at t = 12 x anniversary, for the contracts issued at the valuation date, and a copy of a contract’s scenario re-based to its month for every row valued in force or issued later, under an id of its own, {id}-M{d} or {id}-F{k}. withdrawal_table is indexed by (wd_schedule_id, t), there an elapsed contract year count, on the policy clock, rather than a month, and is not a step function — a contract year with no row simply takes no ad hoc withdrawal.

surr_charge_table carries two contract-year vectors in one file, the surrender charge percentage and the bonus vesting percentage, because [S5] supplies them as a single schedule pair and both are read at the same key. payout_rate_table is banded rather than keyed: each row gives an inclusive attained-age band and the single-life and joint-life percentages, the joint column being the single column less 0.50% [S1][S3]. payout_rates() expands the bands to one row an age, so that the projection reads the percentage at the exercise age directly.

To swap in the prescribed annuitant mortality — the 2012 IAM/IAR family with Projection Scale G2 [REG-R59][REG-R60], which may not be redistributed here — replace 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. The shipped table is the same illustrative Makeham annuitant curve as products/fixed_deferred_annuity, so the two annuity models sit on one mortality basis. Replacing a file changes FIA_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 two categorical columns FIA_US_S branches on, glwb_basis and credit_method, into a 0/1 flag, the is_* cells, the rider election into another, and a blank joint_age into the issue age. Each table keyed by more than a number becomes an integer-indexed array: the mortality table, the rollup schedules, the scenarios and the withdrawal programmes are numbered, each point carrying the number of its own, mort_schedule, rollup_number, scenario_number and wd_schedule_number, all four numbered from 1 in the sorted order of their keys; the mortality is held by attained age, the surrender charge, the vesting and the rollups by contract year, the payout bands by exercise age, the scenarios step-filled by valuation month and the programmes by elapsed contract year, so that the age, the year or the month is the index:

Cells

dtype

Shape

From

point_id()

int64

[point]

the table’s index

age_at_entry(), income_start_age()

int64

[point]

the two columns

joint_age()

int64

[point]

joint_age, blank the issue age

duration_mth()

int64

[point]

duration_mth

phase_prev_anniv_init()

int64

[point]

the phase code

glwb_elected()

int64

[point]

the checked flag

premium() .. mva_ref_yield_at_issue()

float64

[point]

premium, policy_count and seven more

av_pp_init() and ten more

float64

[point]

the eleven float columns of the opening state

is_single_basis() and six more

int64

[point]

the seven decodes, 1 on the value

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(), mort_age_held()

int

scalar

the array’s first and last ages

mort_table_array()

float64

[schedule, age]

mort_table.csv

surr_charge_rate_array(),

float64

[year]

surr_charge_table.csv

vest_rate_array()

rollup_count()

int

scalar

rollup_table.csv

rollup_number()

int64

[point]

rollup_id, joined

rollup_last_year()

int

scalar

read_last_mth’s year

rollup_rate_array()

float64

[schedule, year]

step-filled, 0.0 before the first row

payout_rate_held_age()

int

scalar

read_last_age

payout_rate_array()

float64

[age, basis]

payout_rate_table.csv

scenario_count()

int

scalar

the companion

scenario_number()

int64

[point]

scenario_id, joined

scenario_first_mths()

int64

[scenario]

each first t

scenario_last_mth()

int

scalar

read_last_mth

index_level_array(),

float64

[scenario, t]

step-filled

mva_ref_yield_array()

wd_schedule_count()

int

scalar

withdrawal_table.csv

wd_schedule_number()

int64

[point]

wd_schedule_id, joined

wd_last_year()

int

scalar

read_last_mth’s count

wd_amount_array()

float64

[programme, count]

wd_amount, 0.0 without a row

The table checks are what they were, model_point_table() and the six checked tables, beside their int extents. No copy of the numeric columns is read beside the table, as MYGA_US_SEC reads one: 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 FIA_US_S’s float() or int() reads it.

Every array is held to the last age or month a read reaches. Two References say where: read_last_mth, 1,093, the last element of Projection’s t cache, 12 x (maturity_age - issue_age_min + 1) + future_horizon_mth + 1, and read_last_age, 122, the last element of its a cache, maturity_age + 2, both derived in spec_sec.py, since Data cannot read Projection’s References; a test holds each to the spec. The scenarios are held by valuation month to read_last_mth, the rollups by contract year to the year a month to it falls in, and the programmes by the count to the count it falls in, a schedule’s last row holding to the end, as FIA_US_S’s step function holds it; the mortality and the payout bands are held by age to read_last_age, the last band holding to the end. So a key far past any read, which FIA_US_S holds and never reaches, neither widens an array nor refuses a point FIA_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. The payout array is indexed from the first band’s age, however low, and the mortality 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, which FIA_US_S projects beside, and none widens an array. A change to maturity_age, issue_age_min or future_horizon_mth needs both 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 from another reads the table’s column, or the other cell element by element, and a width comes from a table or a count cell, never from another cell’s array. 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 FIA_US_S’s reading: a point_id that is not a whole number. A decode compares the text exactly, element by element, as FIA_US_S compares it, so a value written in another case or with a space, Cap, or cap with a leading space, is no flag, and the projection answers as FIA_US_S answers it, raising invalid credit_method where it raises it. A table without glwb_basis or credit_method raises pandas’ KeyError at the decode’s first read, as FIA_US_S raises it where a point first reads the column; a point without the rider never reads the basis, and projects. A join number maps the point’s key as FIA_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 FIA_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 contract year below 1 in surr_charge_rate_py and vest_rate_py, and a month before the scenario’s first in scenario_value, each a ValueError where FIA_US_S raised KeyError or its own message. A year before a rollup schedule’s first row, and a count a programme has no row at, are no rollup and no 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 FIA_US_S’s reading of it: duration_mth, the issue age, income_start_age and joint_age (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 bound, a contract year, a month or a count. Each is a whole number already, so no fraction truncates. FIA_US_S projects a point whose income_start_age or joint_age is 1e20, so the first is a refusal it lacks.

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. Fourteen 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 twelve columns of the opening state, per contract. Entering month 0, before any month-0 event:

  • av_pp_init and av_fixed_pp_init: the account value and the fixed account within it;

  • benefit_base_pp_init, rollup_base_pp_init and lw_pp_init: the benefit base, the rollup base and the lifetime withdrawal, each flat between anniversaries;

  • mgsv_pp_init: the Model #805 floor;

  • wd_cum_pp_init: the gross withdrawals taken from issue to the valuation date.

At the anniversary on or before the valuation date, the one that opened the contract year under way:

  • av_pp_prev_anniv_init and av_fixed_pp_prev_anniv_init: the account value and the fixed account, the year’s index-credit, fixed-interest and free-withdrawal bases;

  • phase_prev_anniv_init: the phase, as a code, 1 ACCUM, 2 INCOME or 3 DEPLETED, and 0 on a contract not yet in force;

  • payout_rate_locked_prev_anniv_init: the lifetime withdrawal percentage locked at the first exercise, 0 before it;

  • index_level_prev_anniv_init: the index level, where the year’s index segment started.

Seven are FIA_US_S’s columns renamed: av_initial, bb_initial, rb_initial, mgv_initial and lw_initial become the _init of the cell each opens, phase_initial, text in FIA_US_S, becomes the code, and payout_rate_initial the locked rate. The rest are FIA_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 fourteen in-force columns are present;

  • 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 and income_start_age are whole numbers of years, and joint_age is blank or a whole number of years, 0 or more. FIA_US_S reads each by int(), which would truncate a fraction without a word;

  • duration_mth, age_at_entry, income_start_age and joint_age, where given, are each below 2**53 in size, so that the int64 vector each is read into (duration_mth() and its neighbours) holds FIA_US_S’s reading of it: past int64 a float casts to the least int64 without a word. FIA_US_S projects a point whose income_start_age or joint_age is 1e20, so this is a refusal it lacks;

  • 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;

  • glwb_elected is True or False, read by value: one cell written as text turns the column to text as pandas reads it, every flag with it, so "True" and "False" are read as the flags they name, and the table is returned holding bools, where FIA_US_S’s bool() would read "False" as elected;

  • the premium, the bonus rate, the utilization, the cap, the stacking factor and the share of the index credit reaching the account value are each a finite number, zero or more; alloc_indexed is a number from 0 to 1; and mva_ref_yield_at_issue is a finite number above -1, the base of the MVA’s power;

  • the nine money columns of the opening state are each a finite number, zero or more; the locked payout percentage is a number from 0 to 1; the index level is a finite number, zero or more; and the phase is a whole number;

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

  • a contract in force, duration_mth 1 or more, is in phase 1, 2 or 3: TERMINATED is a deemed surrender of every contract, so none is in force in it;

  • its index level is above 0, since the year’s index return divides by it;

  • it is in INCOME or DEPLETED only under the rider, and without the rider its benefit base, rollup base, lifetime withdrawal and locked percentage are all 0;

  • under the rider its benefit base is above 0: an anniversary that takes the base to 0 terminates the contract;

  • in ACCUM its lifetime withdrawal and locked percentage are 0, before the first lifetime withdrawal, and in INCOME or DEPLETED its lifetime withdrawal is 0 exactly where its locked percentage is: the withdrawal is the locked percentage of a benefit base above 0, and a reduction that took it to 0 would have taken the base to 0 too. A percentage of 0 is locked where the contract exercises below the first age band, as it can where Projection.min_income_age is below the band’s first age, both 50 as shipped, or in a band at 0%, which payout_rates() accepts. The withdrawal is then 0 for life, in INCOME and, once the account value is exhausted, in DEPLETED, so INCOME or DEPLETED with both 0 is read;

  • in DEPLETED its account value and fixed account, entering month 0 and at the anniversary, are all 0, and in ACCUM or INCOME its account value at the anniversary is above 0: the anniversary that exhausts the account value leaves both;

  • the fixed account is part of the account value, at each instant, to a cent;

  • in the first policy year, duration_mth 1 to 11, the year opened at issue, so the values at the anniversary are the issue values, to a cent: the account value premium x (1 + bonus_rate), the fixed account (1 - alloc_indexed) of it, the benefit and rollup bases the premium under the rider and 0 without it; the withdrawals to date are 0; and the phase is ACCUM;

  • on a point valued on a policy anniversary, duration_mth a multiple of 12, the account value and the fixed account at the anniversary equal those entering month 0, exactly: the two are one instant;

  • off an anniversary, the indexed account, av_pp_init - av_fixed_pp_init, equals its value at the anniversary to three cents, since it moves only at an anniversary, and the fixed account has not fallen below its value at the anniversary by more than a cent, since between anniversaries it only accrues;

  • last, each point’s keys into the tables it is joined with: its scenario_id is a scenario of rate_scenario_steps() that sets its levels by the first month the point is on the books, t = 0 or its issue month if later; on a point valued on an anniversary, the index level at the anniversary is the one its scenario sets at t = 0, exactly, since the model reads the scenario there and not the column; its rollup_id is a schedule of rollup_steps(); its wd_schedule_id is a programme of wd_schedules(); and mort_rates() gives a rate at its sex and its attained age in that first month. So reading the table reads those four tables, 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. The indexed account is compared to three cents, being the difference of two such amounts at each of two instants. Two columns that hold one amount at instants that coincide, on an anniversary, are compared exactly.

Accepted, because a contract can be in each state: an account value of 0 in DEPLETED, where the rider pays on; a lifetime withdrawal and a locked percentage of 0 in INCOME or DEPLETED, where the contract exercised below the first age band or in a band at 0%; a blank joint_age on the joint basis, which reads the annuitant’s own age; and a duration_mth, an age or a phase code written as a float, read as the whole number it holds.

Left to the projection, because it needs maturity_age, a Projection Reference, which Data cannot read: whether a point is still in cover, which Projection.proj_len checks, naming the point. On the shipped tables the mortality check refuses an attained age past 120 first, the table’s last age. The index level at an anniversary before the valuation date is history, which nothing here can check beyond its being above 0.

mort_table()[source]#

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

surr_charge_table()[source]#

Surrender charge and bonus vesting percentages by contract year [S5].

Read from surr_charge_table.csv. One file because [S5] states the two vectors as a single contract-year schedule pair, read at the same key.

rollup_table()[source]#

The guaranteed simple rollup schedules, read from rollup_table.csv.

Indexed by (rollup_id, contract_year) and read as a step function of the contract year: each row states the rate that holds from its own year until the next row of the same schedule.

payout_rate_table()[source]#

The lifetime withdrawal percentage bands, read from payout_rate_table.csv.

Banded rather than keyed: each row gives an inclusive attained-age band with the single-life and joint-life percentages [S3].

rate_scenario()[source]#

The exogenous scenarios, read from rate_scenario_sec.csv.

Indexed by (scenario_id, t), where t is a valuation month, 0 at the valuation date, the month at which an anniversary’s level takes effect: each row states the index level and the MVA reference yield that hold from that month until the next row of the same scenario, so a flat path is one row. FIA_US_S’s reader, unchanged and pointed at this model’s own file through rate_scenario_file.

The file is generated from FIA_US_S’s rate_scenario.csv, whose t is an anniversary number from issue. Each of FIA_US_S’s scenarios is here under its own id at t = 12 x anniversary, which is where the anniversaries of a contract issued at the valuation date fall. Each row of the model point table valued in force at policy month d reads a copy of its scenario re-based to d, {id}-M{d}: the levels FIA_US_S set before month d collapse to the level in force at d, at t = 0, and the later rows move d months earlier. Each row issued k months after the valuation date reads a copy moved k months later, {id}-F{k}, which sets no level before its issue month. So every row reads each anniversary’s level at the valuation month its own anniversary falls in, step-filled forward, and the model reproduces FIA_US_S at every anniversary.

withdrawal_table()[source]#

Scheduled ad hoc gross withdrawals, read from withdrawal_table.csv.

Indexed by (wd_schedule_id, t), where t is an elapsed contract year count rather than a month, on the policy clock: a row keyed k is withdrawn at the anniversary closing contract year k + 1, read at duration(t), however old the contract is at the valuation date. A contract year with no row takes no ad hoc withdrawal. Lifetime withdrawals are not scheduled here — they are generated by the rider from utilization_intensity and the locked payout percentage.

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 FIA_US_S’s lookup matches it. Projection.mort_rate_base_at, the table’s one reader, reads it here, 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. The projection caps the annual rate it builds on this one at 1, min(q, 1.0), and a blank rate never reaches the cap.

surr_charge_scale()[source]#

The surrender charge and vesting schedule, as surr_charge_table() reads it, checked.

Indexed by contract_year, read by value, once, as FIA_US_S’s lookup matches it. Projection.surr_charge_rate_py and Projection.vest_rate_py, the two readers of its two columns, read it here, and take its last year, surr_charge_last_year(), from the same checked years, so a projection meets the check first. A year that is not a whole number, text and a blank among them, a rate that is not a number from 0 to 1, and years that do not run from 1, 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 1 or repeated, with its lines, and each year or span of years missing from 1 to the last, every one of them in one message. The last row holds for every later year. FIA_US_S takes int() of the raw years for its last one: one written as text raises Python’s own message, naming no file.

surr_charge_last_year()[source]#

The last contract year surr_charge_scale() gives a rate for, an int.

rollup_steps()[source]#

The rollup schedules, as rollup_table() reads them, checked.

Indexed by (rollup_id, contract_year), the year read by value, once, as FIA_US_S’s step function compares it. Projection.rollup_rate_py, the table’s one reader, reads it here, so a projection meets the check first. A contract year that is not a whole number, 1 or more, text and a blank among them, a blank rollup_id, a rate that is not a finite number, zero or more, and a schedule that sets two rates in one year are refused, naming the file, the column and the lines they are on. A schedule is a step function, so its years need not run one a year: each row holds until the next of the same schedule. FIA_US_S’s step function compares the raw years with the contract year: one written as text raises Python’s own TypeError, and a blank one is a rate that never holds.

payout_rates()[source]#

The lifetime withdrawal percentages, one row an attained age, from the bands of payout_rate_table(), checked.

Indexed by attained age, from the first band’s age_lo to the last band’s age_hi, each age carrying its band’s single-life and joint-life percentages. Projection.payout_rate_at, the table’s one reader, reads it here, and takes its extents, payout_rate_first_age() and payout_rate_last_age(), from the same checked ages, so a projection meets the check first. An age bound that is not a whole number, text and a blank among them, a percentage that is not a number from 0 to 1, and bands that do not run one after another, each from its age_lo to its age_hi, without a gap or an overlap, are refused, naming the file, the column and the lines: for the last, each age or span of ages two bands hold, with their lines, each age or span no band holds between the first age and the last, and each band that ends below its start, with its line, every one of them in one message. FIA_US_S walks the bands at each read and takes int() of each bound: one written as text raises Python’s own message, and an age in a gap between two bands reads 0.

payout_rate_first_age()[source]#

The first attained age payout_rates() gives a percentage for, an int.

Below it no lifetime withdrawal is permitted, and the percentage is 0.

payout_rate_last_age()[source]#

The last attained age payout_rates() gives a percentage for, an int.

Its band holds for every older age, as in FIA_US_S.

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. Projection.scenario_value, 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, an index level that is not a finite number above 0, whose ratio the index return takes, a reference yield that is not a finite number above -1, the base of the MVA’s power, and a scenario that sets two levels 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 level by the first month the point is on the books.

wd_schedules()[source]#

The withdrawal programmes, as withdrawal_table() reads them, checked.

Indexed by (wd_schedule_id, t), each t an elapsed contract year count read by value, once, as FIA_US_S’s exact-key lookup matches it. Projection.wd_scheduled_at, the table’s one reader, reads it here, so a projection meets the check first. A year that is not a whole number, 0 or more, text and a blank among them, a blank wd_schedule_id, an amount that is not a finite number, zero or more, and a programme that withdraws twice in one year are refused, naming the file, the column and the lines they are on. FIA_US_S’s lookup matches the raw years: one written as text turns them all to text, and every 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: FIA_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).

income_start_age()[source]#

The age each point takes its first lifetime withdrawal at, an int64 vector.

joint_age()[source]#

The joint covered person’s issue age, an int64 vector; the annuitant’s if blank.

FIA_US_S’s rule, decoded element by element: a blank joint_age reads the point’s own age_at_entry, and any other is the whole number it holds, which model_point_table() has checked.

duration_mth()[source]#

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

phase_prev_anniv_init()[source]#

The phase code at the anniversary on or before the valuation date, int64.

glwb_elected()[source]#

Whether each point elects the rider, 1 or 0, an int64 vector.

model_point_table() has read the column by value into bools, so "False" written as text is 0, not bool("False").

premium()[source]#

P, the single premium of each point, a float64 vector.

policy_count()[source]#

The contracts each point stands for, a float64 vector.

bonus_rate()[source]#

b, the premium bonus rate of each point, a float64 vector.

alloc_indexed()[source]#

The indexed account’s share of each point’s account value, a float64 vector.

utilization_intensity()[source]#

The share of the lifetime withdrawal each point takes, a float64 vector.

cap_rate()[source]#

c, the declared annual cap of each point, a float64 vector.

stack_factor()[source]#

m, the stacking factor of each point, a float64 vector.

av_int_factor()[source]#

kappa, the index credit’s share reaching each point’s account value, float64.

mva_ref_yield_at_issue()[source]#

i0, the MVA reference yield locked at each point’s issue, a float64 vector.

av_pp_init()[source]#

The account value entering month 0, per contract, a float64 vector.

av_fixed_pp_init()[source]#

The fixed account entering month 0, per contract, a float64 vector.

av_pp_prev_anniv_init()[source]#

The account value at the anniversary on or before the valuation date, float64.

av_fixed_pp_prev_anniv_init()[source]#

The fixed account at that anniversary, per contract, a float64 vector.

benefit_base_pp_init()[source]#

The benefit base entering month 0, per contract, a float64 vector.

rollup_base_pp_init()[source]#

The rollup base entering month 0, per contract, a float64 vector.

mgsv_pp_init()[source]#

The Model #805 floor entering month 0, per contract, a float64 vector.

lw_pp_init()[source]#

The lifetime withdrawal entering month 0, per contract, a float64 vector.

payout_rate_locked_prev_anniv_init()[source]#

The payout percentage locked at the anniversary on or before the valuation date.

index_level_prev_anniv_init()[source]#

The index level at the anniversary on or before the valuation date, float64.

wd_cum_pp_init()[source]#

The gross withdrawals from issue to the valuation date, per contract, float64.

is_single_basis()[source]#

1 where glwb_basis is single, else 0, an int64 vector.

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

is_joint_basis()[source]#

1 where glwb_basis is joint, else 0, an int64 vector.

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

is_credit_cap()[source]#

1 where credit_method is cap, else 0, an int64 vector.

FIA_US_S’s comparison, made element by element, exactly, as is_single_basis()’s is; a table without the column raises pandas’ KeyError at the first read, as FIA_US_S raises it at a point’s first credit.

is_credit_par()[source]#

1 where credit_method is par, else 0, an int64 vector.

is_credit_par_cap()[source]#

1 where credit_method is par_cap, else 0, an int64 vector.

is_credit_spread()[source]#

1 where credit_method is spread, else 0, an int64 vector.

is_credit_trigger()[source]#

1 where credit_method is trigger, else 0, an int64 vector.

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 FIA_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, an int64 vector.

mort_age_lasts()[source]#

Each sex’s last age in mort_rates(), by its number, an int64 vector.

The table’s own last age, however far past read_last_age: Projection.proj_len refuses a point whose sex’s last age is below maturity_age, the age the last contract year is entered at.

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 FIA_US_S holds and never reads, is not held. So neither a negative age nor one far below every other widens the array.

mort_age_held()[source]#

The age of mort_table_array()’s last column, read_last_age, an int.

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 mort_age_held(), 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 FIA_US_S holds and never reads, neither widens the array nor refuses a point.

surr_charge_rate_array()[source]#

The surrender charge percentage by contract year, [year]; year 0 NaN.

Years 1 to surr_charge_last_year(), which surr_charge_scale() holds without a gap, so the year is the index.

vest_rate_array()[source]#

The bonus vesting percentage by contract year, [year]; year 0 NaN.

As surr_charge_rate_array(), from the schedule’s other column.

rollup_count()[source]#

The number of schedules rollup_steps() holds, an int.

rollup_number()[source]#

The row of rollup_rate_array() each point reads, by its rollup_id, int64.

Numbered from 1 in the sorted order of the ids, as mort_schedule() numbers the sexes; model_point_table() refuses an id the table lacks.

rollup_last_year()[source]#

The last contract year rollup_rate_array() holds, an int.

The contract year a month to read_last_mth can fall in, read_last_mth // 12 + 1, past any contract year a read reaches, whatever the table’s keys: a schedule’s last row holds to there, as FIA_US_S’s step function holds it, and a row past it is held nowhere.

rollup_rate_array()[source]#

The guaranteed rollup rate by schedule and contract year, [schedule, year].

Each schedule’s rows step-filled from its year to the next row’s, the last to rollup_last_year(), and 0.0 in the years before its first row, where FIA_US_S’s step function finds no row and answers 0.0. Row 0 and year 0, which no read reaches, are NaN.

payout_rate_held_age()[source]#

The last exercise age payout_rate_array() holds, read_last_age, an int.

payout_rate_array()[source]#

The lifetime withdrawal percentage by exercise age and basis, [age, basis].

Row j is exercise age payout_rate_first_age() + j, to payout_rate_held_age(), read_last_age; column 0 is the single-life percentage, column 1 the joint-life. Ages past the last band’s hold its percentages, as in FIA_US_S, and an age past read_last_age is held nowhere, so bands far past it neither widen the array nor refuse a point. Ages below the first band, which read 0, have no row: the array is indexed from the first age, however low.

scenario_count()[source]#

The number of scenarios rate_scenario_steps() holds, an int.

scenario_number()[source]#

The row of the scenario arrays each point reads, by its scenario_id, int64.

Numbered from 1 in the sorted order of the ids, as mort_schedule() numbers the sexes; model_point_table() refuses an id the companion lacks.

scenario_first_mths()[source]#

Each scenario’s first month, by its number, an int64 vector.

scenario_last_mth()[source]#

The last valuation month the scenario arrays hold, read_last_mth, an int.

The last month any read reaches, whatever the companion’s keys: a scenario’s last row holds to there, as FIA_US_S’s step function holds it, and a row past it is held nowhere.

index_level_array()[source]#

The index level by scenario and valuation month, [scenario, t].

Each scenario’s rows step-filled from its month to the next row’s, the last to scenario_last_mth(); NaN before a scenario’s first month and in row 0.

mva_ref_yield_array()[source]#

The MVA reference yield by scenario and valuation month, [scenario, t].

As index_level_array(), from the companion’s other column.

wd_schedule_count()[source]#

The number of programmes wd_schedules() holds, an int.

wd_schedule_number()[source]#

The row of wd_amount_array() each point reads, by its wd_schedule_id.

Numbered from 1 in the sorted order of the ids, int64, as mort_schedule() numbers the sexes; model_point_table() refuses an id the table lacks.

wd_last_year()[source]#

The last elapsed contract year count wd_amount_array() holds, an int.

The count a month to read_last_mth can fall in, read_last_mth // 12, past any count a read reaches: a row past it is held nowhere.

wd_amount_array()[source]#

The ad hoc withdrawal by programme and elapsed contract years, [programme, k].

0.0 at a count a programme has no row for, a value, as FIA_US_S’s lookup answers it, not padding; row 0, which no point reads, is NaN.