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] |
|
duration_mth() |
int64 |
[point] |
|
phase_prev_anniv_init() |
int64 |
[point] |
the phase code |
glwb_elected() |
int64 |
[point] |
the checked flag |
premium() .. mva_ref_yield_at_issue() |
float64 |
[point] |
|
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] |
|
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_last_year() |
int |
scalar |
|
rollup_rate_array() |
float64 |
[schedule, year] |
step-filled, 0.0 before the first row |
payout_rate_held_age() |
int |
scalar |
|
payout_rate_array() |
float64 |
[age, basis] |
payout_rate_table.csv |
scenario_count() |
int |
scalar |
the companion |
scenario_number() |
int64 |
[point] |
|
scenario_first_mths() |
int64 |
[scenario] |
each first |
scenario_last_mth() |
int |
scalar |
|
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_last_year() |
int |
scalar |
|
wd_amount_array() |
float64 |
[programme, count] |
|
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_countandduration_mth, the completed policy months at the valuation date, as inbasiclife.BasicTerm_SE, and the twelve columns of the opening state, per contract. Entering month 0, before any month-0 event:av_pp_initandav_fixed_pp_init: the account value and the fixed account within it;benefit_base_pp_init,rollup_base_pp_initandlw_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_initandav_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, 1ACCUM, 2INCOMEor 3DEPLETED, 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_initialandlw_initialbecome the_initof the cell each opens,phase_initial, text inFIA_US_S, becomes the code, andpayout_rate_initialthe locked rate. The rest areFIA_US_S’s, exceptrow_kind,source_policy_idandsource_mth, which record where the generator took each shipped row from and which no formula reads.The checks run over the whole table at once, and the first that fails raises
ValueError, naming the missing column or every point it fails on:the fourteen in-force columns are present;
no
point_idappears twice;policy_countis a number, zero or more;duration_mthis a whole number of months: positive for a contract in force, 0 for one issued at the valuation date, negative for one issued later;age_at_entryandincome_start_ageare whole numbers of years, andjoint_ageis blank or a whole number of years, 0 or more.FIA_US_Sreads each byint(), which would truncate a fraction without a word;duration_mth,age_at_entry,income_start_ageandjoint_age, where given, are each below2**53in size, so that the int64 vector each is read into (duration_mth()and its neighbours) holdsFIA_US_S’s reading of it: past int64 a float casts to the least int64 without a word.FIA_US_Sprojects a point whoseincome_start_ageorjoint_ageis1e20, so this is a refusal it lacks;no contract is issued more than
future_horizon_mthmonths after the valuation date, soduration_mthis-future_horizon_mthor more. At 0 the model takes no future new business, and the message says so; a negative horizon is itself refused;glwb_electedis 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, whereFIA_US_S’sbool()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_indexedis a number from 0 to 1; andmva_ref_yield_at_issueis 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_mth0 or less, has no opening state: every state column is 0, the phase code included;a contract in force,
duration_mth1 or more, is in phase 1, 2 or 3:TERMINATEDis 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
INCOMEorDEPLETEDonly 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
ACCUMits lifetime withdrawal and locked percentage are 0, before the first lifetime withdrawal, and inINCOMEorDEPLETEDits 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 whereProjection.min_income_ageis below the band’s first age, both 50 as shipped, or in a band at 0%, whichpayout_rates()accepts. The withdrawal is then 0 for life, inINCOMEand, once the account value is exhausted, inDEPLETED, soINCOMEorDEPLETEDwith both 0 is read;in
DEPLETEDits account value and fixed account, entering month 0 and at the anniversary, are all 0, and inACCUMorINCOMEits 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_mth1 to 11, the year opened at issue, so the values at the anniversary are the issue values, to a cent: the account valuepremium 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 isACCUM;on a point valued on a policy anniversary,
duration_mtha 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_idis a scenario ofrate_scenario_steps()that sets its levels by the first month the point is on the books,t = 0or its issue month if later; on a point valued on an anniversary, the index level at the anniversary is the one its scenario sets att = 0, exactly, since the model reads the scenario there and not the column; itsrollup_idis a schedule ofrollup_steps(); itswd_schedule_idis a programme ofwd_schedules(); andmort_rates()gives a rate at itssexand 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 inINCOMEorDEPLETED, where the contract exercised below the first age band or in a band at 0%; a blankjoint_ageon the joint basis, which reads the annuitant’s own age; and aduration_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, aProjectionReference, whichDatacannot read: whether a point is still in cover, whichProjection.proj_lenchecks, 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.
- 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), wheretis 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 throughrate_scenario_file.The file is generated from
FIA_US_S’s rate_scenario.csv, whosetis an anniversary number from issue. Each ofFIA_US_S’s scenarios is here under its own id att = 12 xanniversary, 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 monthdreads a copy of its scenario re-based tod,{id}-M{d}: the levelsFIA_US_Sset before monthdcollapse to the level in force atd, att = 0, and the later rows movedmonths earlier. Each row issuedkmonths after the valuation date reads a copy movedkmonths 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 reproducesFIA_US_Sat every anniversary.
- withdrawal_table()[source]#
Scheduled ad hoc gross withdrawals, read from withdrawal_table.csv.
Indexed by
(wd_schedule_id, t), wheretis an elapsed contract year count rather than a month, on the policy clock: a row keyedkis withdrawn at the anniversary closing contract yeark + 1, read atduration(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 fromutilization_intensityand 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 written61.0is 61, asFIA_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, asFIA_US_S’s lookup matches it.Projection.surr_charge_rate_pyandProjection.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_Stakesint()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, asFIA_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 blankrollup_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 ownTypeError, 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_loto the last band’sage_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()andpayout_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 itsage_loto itsage_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_Swalks the bands at each read and takesint()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), eachta 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 blankscenario_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 aftert = 0, for business issued later, so the month a scenario must start by is the point’s:model_point_table()refuses a point whose scenario sets no 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), eachtan elapsed contract year count read by value, once, asFIA_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 blankwd_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_idof each row, an int64 vector, read by value from the table’s index.Projectionis indexed by position,idx, and reads its point’s label here, so that every refusal names the point by the label a reader finds in the table. A label that is not a whole number, or not below2**53in size, is refused, naming it:FIA_US_Skeys its points by any label pandas reads.
- 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 blankjoint_agereads the point’s ownage_at_entry, and any other is the whole number it holds, whichmodel_point_table()has checked.
- 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, notbool("False").
P, the single premium 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.
- 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_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.
- 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_basisissingle, else 0, an int64 vector.FIA_US_S’s comparison, made element by element, exactly:Singleorsinglewith a space is 0, and so is a blank. A table without the column raises pandas’KeyErrorhere, at the first read, asFIA_US_Sraises it where a rider point first asks the basis, and a point without the rider never asks.
- is_joint_basis()[source]#
1 where
glwb_basisisjoint, else 0, an int64 vector.The other decode of the column, as
is_single_basis()is.
- is_credit_cap()[source]#
1 where
credit_methodiscap, else 0, an int64 vector.FIA_US_S’s comparison, made element by element, exactly, asis_single_basis()’s is; a table without the column raises pandas’KeyErrorat the first read, asFIA_US_Sraises it at a point’s first credit.
- mort_schedule_count()[source]#
The number of sexes
mort_rates()holds, an int.
- mort_schedule()[source]#
The row of
mort_table_array()each point reads, by itssex, int64.The sexes are numbered from 1 in their sorted order, the order
groupbytakes, and each point carries its own sex’s number, matched by the value pandas read, asFIA_US_S’s.locmatches it.model_point_table()refuses a point whose sex the table lacks, so 0, the number of no sex, is never a point’s.
- mort_age_firsts()[source]#
Each sex’s first age in
mort_rates(), by its number, 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_lenrefuses a point whose sex’s last age is belowmaturity_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_Sholds 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; columnjis attained agemort_age_base() + j, tomort_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 pastread_last_ageis held nowhere, so a row far past it, whichFIA_US_Sholds 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(), whichsurr_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 itsrollup_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_mthcan 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, asFIA_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, whereFIA_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
jis exercise agepayout_rate_first_age() + j, topayout_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 inFIA_US_S, and an age pastread_last_ageis 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_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 itswd_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_mthcan fall in,read_last_mth // 12, past any count a read reaches: a row past it is held nowhere.