The Data Space#
Input data shared by every by-policy projection.
The five input CSVs are read here, once per model, and referenced from
Projection as data. Projection is
parameterized by idx, the position of a model point in the table, so each
Projection[i] is a separate ItemSpace with its own cells cache; if the readers lived
there, every model point would re-read every file. Holding them in an unparameterized
Space reads each file once no matter how many policies are projected.
Inputs are external files: plain CSVs in the model folder’s parent directory,
products/term_life/, 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
Term_US_SEC folder without its parent’s CSVs produces a model that reads and then
fails on first evaluation.
Four of the tables are Term_US_S’s. The premium schedule, the mortality table, the
class factors and the shock-lapse buckets are the files Term_US_S reads, read
here in place: one copy of each table serves both models, so an edit to one reaches
both. The model point table is this model’s own, model_point_table_sec.csv; it sits
beside Term_US_S’s model_point_table.csv, which this model never opens.
input_dir() resolves the directory from _model.path.parent at run time, so
the model works wherever the repository is checked out. Each table has a filename
Reference and a reader Cells:
Reference |
Cells |
File |
|---|---|---|
model_point_file |
model_point_table() |
model_point_table_sec.csv |
premium_rates_file |
premium_rates() |
premium_rates.csv |
mort_table_file |
mort_table() |
mort_table.csv |
class_factor_file |
class_factor_table() |
class_factor_table.csv |
shock_lapse_file |
shock_lapse_table() |
shock_lapse_table.csv |
The model point table is checked as it is read. Two of its columns are the
in-force interface, policy_count and duration_mth, and model_point_table()
refuses a table that lacks either, repeats a point_id, or holds a count or a
duration no policy can have. The checks run in turn, and the first that fails raises,
naming the missing column or every point that fails it. It also refuses a policy to be
issued more than future_horizon_mth months after the valuation date, 120 months as
shipped: future new business is written over a stated horizon, so that no frame runs
longer than cover from issue plus that horizon. Set to 0, the Reference refuses future
new business altogether. A longer horizon projects in modelx, but the compiled model’s
caches are sized for the shipped 120 months (spec_sec.py): it needs t there raised
to 12 x 77 + the horizon + 2 and a rebuild, or a frame longer than 1,044 months raises
IndexError compiled, naming nothing, at the first month past the caches. Whether a
point is still in cover at the valuation date, and whether the contract issues it, are
rules of the product rather than of the table, and Projection.proj_len checks them,
against three Projection References the caches are sized from as they are from the
horizon: expiry_age, issue_age_min and policy_term_min.
To swap in a licensed mortality basis, replace mort_table.csv with a same-schema
file, or point mort_table_file at a different name, then clear the cache. No formula
changes. 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 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.age_at_entry()[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 of buckets or extent of a table is an int.
Text the projection needs is decoded here, into the number it selects: the plan into the level period, the premium mode into the months between instalments, the underwriting class into its mortality factor, and the face amount into its band. A blank M(1) override becomes a 0/1 flag beside a value, so no NaN reaches a formula. And each table keyed by more than a number becomes an integer-indexed array. The premium schedules, keyed by plan, sex, class and band, are numbered, each point carrying the number of its own, and tabled by schedule and policy year. The mortality table is padded from age 0, so that the index is the attained age:
Cells |
dtype |
Shape |
From |
|---|---|---|---|
point_id() |
int64 |
[point] |
the table’s index |
age_at_entry() |
int64 |
[point] |
|
sum_assured() |
float64 |
[point] |
|
policy_count() |
float64 |
[point] |
|
duration_mth() |
int64 |
[point] |
|
policy_term() |
int64 |
[point] |
|
prem_cycle() |
int64 |
[point] |
|
band() |
int64 |
[point] |
|
class_factor() |
float64 |
[point] |
|
plt_mort_factor_override() |
float64 |
[point] |
the override, 0.0 where blank |
has_plt_mort_factor_override() |
int64 |
[point] |
1 where given, 0 where blank |
premium_schedule() |
int64 |
[point] |
plan, sex, class and band, joined |
premium_schedules() |
int |
scalar |
premium_rates.csv, checked |
premium_rates_array() |
float64 |
[schedule, y] |
premium_rates.csv |
premium_first_year() |
int64 |
[schedule] |
premium_rates.csv |
premium_last_year() |
int64 |
[schedule] |
premium_rates.csv |
mort_table_array() |
float64 |
[age] |
mort_table.csv |
mort_age_first() |
int |
scalar |
mort_table.csv |
mort_age_last() |
int |
scalar |
mort_table.csv |
shock_lapse_buckets() |
int |
scalar |
shock_lapse_table.csv |
shock_lapse_jump_lo() |
float64 |
[bucket] |
shock_lapse_table.csv |
shock_lapse_jump_hi() |
float64 |
[bucket] |
shock_lapse_table.csv |
shock_lapse_bucket_rate() |
float64 |
[bucket] |
shock_lapse_table.csv |
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, as
band() reads sum_assured, or the other cell element by element, as
premium_schedule() reads band(); and a width comes from a table, never from
another cell’s array.
What cannot be decoded is refused when the array is first read, naming every point
at fault: a point_id that is not a whole number, a plan whose number of years int
cannot read, a premium mode other than A, SA, Q or M, a class class_factor_table.csv
lacks. So is a table the arrays cannot hold: a premium schedule whose policy years are
not whole, leave a gap, repeat or start below 1; a mortality table with an age that is
not whole, a gap, a repeated or negative age; a shock-lapse table with no bucket.
Term_US_S met each of these only when a projection reached it. A key written as a
float, a policy year 1.0 or an age 35.0, is read by its value, as Term_US_S’s
lookups match it, and so is every key an extent is taken from: a key written as text is
not whole, and the table’s extents refuse it as its array does. A read beyond a table’s
extent is refused where Term_US_S’s lookup raised KeyError, by the one
Projection cell that reads the table, naming the point:
premium_pp_ann_py and mort_rate_base.
A value a capped rate, a min or a max reads is a finite number, or it is refused
when its array is first read, naming the file, the column and every line or point at
fault. Projection.mort_rate caps the annual rate with min, and the notes’ M(1)
rule and the post-level-term grading bound theirs with min and max. Each keeps
its first argument unless a later one compares smaller, or larger, and no comparison
with NaN holds, so each is written with the value first and the bound second, and a NaN
would stay NaN; but an infinity is a number, which the cap reads as 1, certain death. So
every value they read is checked, over its whole column, and a blank, text or infinite
one is refused: a factor of class_factor_table.csv, by rate_class, whether or not
a point carries the class; a rate of mort_table.csv, by age; a premium of
premium_rates.csv, by schedule and policy year, whether or not a point carries the
schedule; an age_at_entry and a plt_mort_factor_override, by point_id. A blank
override is the notes’ rule, and is left so, and so is the padding, which no formula reads.
Term_US_S met each only when a projection reached it: it raised on text and on a blank
or infinite age, read an infinite factor, base rate or M(1) override as certain death at its
cap and a negative infinite override as its grading’s floor, 2.0, without a word, and
projected NaN or an infinity from any other such value.
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. Two columns are the in-force interface, as inbasiclife.BasicTerm_SE:policy_count, andduration_mth, the completed policy months at the valuation date. The rest areTerm_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:both 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 policy in force, 0 for one issued at the valuation date, negative for one issued later;no policy is issued more than
future_horizon_mthmonths after the valuation date, soduration_mthis-future_horizon_mthor more. At 0 the model takes no future new business, and the message says so; a negative horizon is itself refused.
The guaranteed premium schedule, read from premium_rates.csv.
Keyed by the contractual, 1-based
policy_year(1 = the issue year), not by the 0-based projection index;Projection.premium_pp_ann_py(y)looks it up at policy yeary:premium_pp_ann(t)atpolicy_year(t) = duration(t) + 1, the policy year containing montht, andjump_ratio()at yearsnandn + 1.
- shock_lapse_table()[source]#
The shock-lapse buckets by jump ratio, read from shock_lapse_table.csv.
- point_id()[source]#
The
point_idof every model point, in table order: int64 [point].Projectionis indexed by position,idx, so this is how a projection names its point:Projection.point_id()is the element atidx, and every refusal quotes it. A label that is not a whole number is refused, naming every such label.
- age_at_entry()[source]#
The issue age (ANB) of every model point: int64 [point].
Read as
Term_US_Sreads it,intof the number. The attained age it opens indexes mort_table.csv, whose rateProjection.mort_ratecaps, so an age that is not a finite number, blank, text or infinite, is refused, naming every point that carries one: numpy would read a blank or infinite age as the least int64, without a word.
- policy_count()[source]#
The
policy_countof every model point: float64 [point].model_point_table()has checked it: a number, zero or more.
- duration_mth()[source]#
The
duration_mthof every model point, in whole months: int64 [point].model_point_table()has checked that each is whole, so a duration written as12.0is the int 12.
- policy_term()[source]#
The level period of every model point in years, decoded from
plan: int64 [point].The number after the plan’s letter,
T1010, read on each point exactly asTerm_US_Sreads it,int(plan[1:]). A plan thatintcannot read so, such asTXorT10.0, is refused, naming every point that carries one.
- prem_cycle()[source]#
Months between premium instalments, decoded from
premium_mode: int64 [point].A 12, SA 6, Q 3, M 1, the arithmetic of the mode, as
Term_US_S’sprem_cyclehas it, andProjection.modal_factorselects the mode’s factor by it. Any other mode is refused, naming every point that carries it.
- band()[source]#
Face-amount band 1-4 of every model point: int64 [point].
Term_US_S’s rule, point by point: boundaries at $250,000 / $500,000 / $1,000,000 [S5], the four-band choice [std], so a face below the first boundary is band 1 and one at it band 2.premium_schedule()joins the schedule by it.
- class_factor()[source]#
The underwriting-class factor of every model point [std]: float64 [point].
Each point’s
rate_classjoined to class_factor_table.csv, the factorTerm_US_Slooks up.Projection.mort_ratecaps the rate the factor scales, so every factor in the table must be a finite number: a blank, text or infinite one is refused, naming every class that carries one, whether or not a point carries it. A class the table lacks is refused too, naming every point that carries it.
- plt_mort_factor_override()[source]#
M(1) where a model point overrides it, 0.0 where it leaves it blank: float64 [point].
A blank is
has_plt_mort_factor_override()’s 0, andProjectionasks the flag, never the value, whether a point overrides M(1), so no NaN reaches a formula. A blank is the column’s own meaning, the notes’ rule, and is left so. An override is read by themaxofProjection.plt_mort_factorand the cap ofProjection.mort_rate, so one that is neither a finite number nor blank, text or infinite, is refused, naming every point that carries one.
- has_plt_mort_factor_override()[source]#
Whether each model point overrides M(1): int64 [point], 1 where it does, 0 blank.
An int, not a bool: a numpy bool array compiles as a Python object, not a memoryview.
Each model point’s premium schedule, its row of
premium_rates_array(): int64 [point].A schedule is the rows of premium_rates.csv for one plan, sex, class and band, numbered from 1 in the order of those keys, and a point’s is the one of its plan, sex,
rate_classandband(), the keyTerm_US_Slooks the premium up by. A point whose key has no schedule has 0, a schedule whose extent holds no policy year, so thatProjection.premium_pp_ann_pyrefuses every year of it, naming the point, whereTerm_US_S’s lookup raisedKeyError.
The number of premium schedules in premium_rates.csv, each checked: an int.
A schedule is the table’s rows for one plan, sex, class and band, numbered from 1 in the order of those keys, as
premium_schedule()numbers them. Its policy years are read by their value, asTerm_US_S’s lookup matches them, so a year written1.0is year 1. A schedule whose policy years are not whole numbers, text among them, leave a gap, repeat or start below 1 is refused, naming it. Once every schedule’s years are checked, a premium that is not a finite number, blank, text or infinite, is refused, naming every schedule that holds one, whether or not a point carries it, and every such policy year in it:Projection.jump_ratioreads two premiums of a schedule, and theminof the notes’ M(1) rule reads their ratio.premium_rates_array()and both of its extents,premium_first_year()andpremium_last_year(), are sized by this count, so each meets the refusal first, whichever of them a projection reads first.
AP by premium schedule and policy year, from premium_rates.csv: float64 [schedule, policy year].
Row
sis schedules(premium_schedule()) and columnypolicy yeary, soProjection.premium_pp_ann_pyreads a point’s AP at[premium_schedule(), y]. The width is the table’s last policy year plus one. Row 0, no schedule, and column 0, no policy year, hold NaN, and so do the years outside a schedule’spremium_first_year()andpremium_last_year(); no formula reads them. Each schedule’s years are read by value, andpremium_schedules()refuses a schedule this array cannot hold.
The first policy year of each premium schedule: int64 [schedule].
1 for row 0, no schedule, whose last year is 0, so that no year lies between them. The years are read by value, from the schedules
premium_schedules()has checked.
The last policy year of each premium schedule: int64 [schedule], 0 for no schedule.
Read as
premium_first_year()reads the first.
- mort_age_first()[source]#
The first attained age mort_table.csv gives a rate for.
An age is read by its value, as
Term_US_S’s lookup matches it, so one written35.0is 35. One that is not a whole number, text among them, is refused, naming every such age, here and inmort_age_last(), either of which a projection may read first.
- mort_age_last()[source]#
The last attained age mort_table.csv gives a rate for, read as
mort_age_first()reads the first.
- mort_table_array()[source]#
Base mortality by attained age, from mort_table.csv: float64 [age].
Padded from age 0, so that the index is the age, as
basiclife.BasicTerm_SC.Data.mort_table_arraypads its table; the ages below the table’s first, 0 to 34 as shipped, hold NaN, which no formula reads. The ages must run frommort_age_first()tomort_age_last()without a gap or a repeat, none negative, or the table is refused.Projection.mort_ratecaps the rate, so each must be a finite number: a blank, text or infinite one is refused, naming every age that carries one.Projection.mort_rate_baserefuses an age outside the table, naming the point.
- shock_lapse_buckets()[source]#
The number of jump-ratio buckets in shock_lapse_table.csv: one or more, or the table is refused.
- shock_lapse_jump_lo()[source]#
Each bucket’s lower bound on the jump ratio, exclusive: float64 [bucket].