The Data Space#
Input data shared by every by-policy projection.
The eight 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/guaranteed_ul/, 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
ULSG_US_SEC folder without its parent’s CSVs produces a model that reads and then
fails on first evaluation.
Seven of the tables are ULSG_US_S’s. The guaranteed COI scale, the corridor
factors, the mortality table, the class factors, the lapse table, the surrender charge
schedules and the return-of-premium windows are the files ULSG_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 ULSG_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 cell:
Reference |
Cells |
File |
|---|---|---|
model_point_file |
model_point_table() |
model_point_table_sec.csv |
coi_rates_file |
coi_rates() |
coi_rates.csv |
corridor_file |
corridor_factors() |
corridor_factors.csv |
mort_table_file |
mort_table() |
mort_table.csv |
class_factor_file |
class_factor_table() |
class_factor_table.csv |
lapse_table_file |
lapse_table() |
lapse_table.csv |
surr_charge_file |
surr_charge_table() |
surr_charge_table.csv |
rop_file |
rop_table() |
rop_table.csv |
The model point table is checked as it is read. Seven of its columns are the
in-force interface: policy_count and duration_mth, as in
basiclife.BasicTerm_SE, and five columns of an in-force policy’s opening state, the
account value, the shadow account, the loan and the premiums paid to date, which are
ULSG_US_S’s own, and the months already spent in grace. model_point_table()
refuses a table that lacks any of them, or any column of ULSG_US_S’s own that the
projection reads as a number or a flag, repeats a point_id, holds a count, a
duration, an age or an amount no policy can have, a share of the premium or a
probability outside 0 to 1, a quoting precision that is not a whole number, a flag that
is not True or False, or an opening state no policy can be in. The checks run in
turn, by 19 rules, 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 the
projection 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 (charges_cease_age - issue_age_min) + the horizon + 2 and a rebuild, or a frame of
more than 1,357 months, the longest the caches hold with the month after it, raises
IndexError compiled, naming nothing, at the first month past the caches. Whether a point
is still inside the projection at the valuation date, issued at an age with any cover, or
past the end of its grace is a rule of the product rather than of the table, and
Projection.proj_len checks it, against two Projection References the caches are sized
from as they are from the horizon: charges_cease_age and issue_age_min.
So are the seven assumption tables. Each table read at an attained age or a policy year
has one reader in Projection, keyed by the age or the year, and that reader takes the
table’s extent – the first and last ages, or the last policy year, beyond which it reads
the nearest row – from a cell here that reads the key column by value, once, and checks the
table: corridor_age_first() and corridor_age_last(), mort_age_first() and
mort_age_last(), lapse_last_year(), and, for the COI scale, whose sex and rate
class cells are numbered as schedules, coi_schedules(), which every COI vector asks
first. A key that is blank, text or not a whole number is refused, naming the file, the
column and the lines it is on, and so is an age below 0, since an age table is indexed by
the age. So are keys that do not run one row an age or a year, without a gap or a repeat,
policy years from 1, the message naming each key that repeats, with its lines, and each that
is missing. And so is a rate that is blank, text or infinite, naming the column and its
lines, and a lapse or mortality rate outside 0 to 1: each is a probability, and the monthly
rate 1 - (1 - q)^(1/12) has no real value past 1. class_count() and
surr_charge_count() check the class factors and the surrender-charge schedules the
same way, for the per-point joins that read them, and surr_charge_count() refuses a
run-off that is not a whole number of years, 1 or more, which the projection divides by.
rop_count() checks the return-of-premium windows, read by membership of their
anniversaries: an anniversary that is not a whole number of years, 1 or more, or that is on
more than one row, is refused, and so is a refund ratio or an exercise rate outside 0 to 1.
A class factor, a guaranteed COI rate and a surrender charge below 0 are refused too: each
would project, with every check passing, a negative death, a credit for the insurance, or a
surrender charge that rises once its schedule has run off. So is a corridor factor below 0,
which no statutory percentage is. Each reader asks for its extent or its count before it
reads a value, so a projection meets the checks first. rop_last_anniv(), which asks
rop_count(), is the windows’ extent.
ULSG_US_S’s readers take each extent from the key column as pandas reads it, where a
blank key is a missing value the extent skips: the table is cut short, and every later
age or year reads the last good row, without a word. A blank value is a missing value
to it too, which shows in its flows or is lost in a min or a max: a blank lapse
rate reaches the lapse rate’s floor and is read as it, a blank corridor factor reads as
no corridor, a blank surrender charge as none, and a blank COI rate reaches the account
value’s floor at zero, which reads it as an exhausted account. Here each is refused, by
name, and so is a blank, text or infinite amount in the model point table.
coi_rates.csv carries the guaranteed maximum annual rate per $1,000, by
attained age; Projection.coi_rate_guar divides it by twelve, which is the notes’
simple-twelfth conversion and one of their named pitfalls. The current scale is that
rate times Projection.coi_curr_factor (65%) and the shadow scale times
Projection.coi_sg_factor (55%), because no carrier publishes either [std].
Both mortality tables are small illustrative ones [std], not published tables:
the notes forbid hard-coding the licensed 2017 CSO and 2015 VBT families, so
coi_rates.csv ships a Perks curve fitted to the two figures the notes state – the
8.615 per $1,000 per month guaranteed maximum at attained age 85, and a solved level
lifetime no-lapse premium near $10,800 for the anchor cell – and mort_table.csv
ships the same curve at 72% of the guaranteed basis. To swap in a licensed basis,
replace a file with a same-schema one, or point its filename Reference at a different
name before the model computes anything: a compiled model clears no cache, so there the
name is set on a package just imported, before anything is read. No formula changes.
Replacing the file changes ULSG_US_S too, which reads the same one.
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.sum_assured()[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 or extent is an int.
Text the projection needs is decoded here, into the number it selects: each value of the
premium pattern a monthly cell branches on into a 0/1 flag, the premium mode into its
payments a year, and the surrender-charge and return-of-premium flags into two more. The
model point’s two pins become numbers: the persistency pin a value, NaN where blank, and
a flag of whether the point gives one, and the COI precision an int, -1 where blank,
ULSG_US_S’s own “exact”. Each table keyed by more than a number becomes an
integer-indexed array or a join. The COI scales, keyed by sex and class, are numbered,
each point carrying the number of its own, and tabled by schedule and attained age. The
lapse table is held by policy year, the corridor and mortality tables by attained age,
each padded from 0, so that the year or the age is the index, and the return-of-premium
windows by anniversary, a flag of membership and the two values, so that the
anniversary is the index. The class factor and the surrender-charge schedule, each one
number a point, are joined to the points:
Cells |
dtype |
Shape |
From |
|---|---|---|---|
point_id() |
int64 |
[point] |
the table’s index |
age_at_entry() |
int64 |
[point] |
|
guarantee_age() |
int64 |
[point] |
|
duration_mth() |
int64 |
[point] |
|
grace_mth_init() |
int64 |
[point] |
|
coi_rate_dp() |
int64 |
[point] |
|
sum_assured() |
float64 |
[point] |
|
policy_count() |
float64 |
[point] |
|
premium_pp_ann() |
float64 |
[point] |
|
wd_pp() |
float64 |
[point] |
|
load_prem_rate() |
float64 |
[point] |
|
av_pp_init() |
float64 |
[point] |
|
sg_pp_init() |
float64 |
[point] |
|
loan_bal_init() |
float64 |
[point] |
|
cum_prem_init() |
float64 |
[point] |
|
prem_persistency_override() |
float64 |
[point] |
|
has_prem_persistency_override() |
int64 |
[point] |
the same, 1 where not blank |
has_surr_charge() |
int64 |
[point] |
|
rop_elected() |
int64 |
[point] |
|
is_level_premium() |
int64 |
[point] |
|
is_single_premium() |
int64 |
[point] |
|
is_ten_pay_premium() |
int64 |
[point] |
|
premium_freq() |
int64 |
[point] |
|
class_factor() |
float64 |
[point] |
class_factor_table.csv, joined |
surr_charge_rate_max() |
float64 |
[point] |
surr_charge_table.csv, joined |
surr_charge_runoff_years() |
float64 |
[point] |
surr_charge_table.csv, joined |
has_surr_charge_schedule() |
int64 |
[point] |
the same, 1 where the table holds the id |
coi_schedules() |
int |
scalar |
coi_rates.csv, checked |
coi_schedule() |
int64 |
[point] |
sex and class, joined |
coi_rate_first_ages() |
int64 |
[schedule] |
coi_rates.csv |
coi_rate_last_ages() |
int64 |
[schedule] |
coi_rates.csv |
coi_rate_array() |
float64 |
[schedule, age] |
coi_rates.csv |
corridor_factor_array() |
float64 |
[age] |
corridor_factors.csv |
mort_table_array() |
float64 |
[age] |
mort_table.csv |
lapse_rate_array() |
float64 |
[y] |
lapse_table.csv |
rop_last_anniv() |
int |
scalar |
rop_table.csv |
rop_anniv_flags() |
int64 |
[anniversary] |
rop_table.csv, 1 at a window |
rop_ratio_array() |
float64 |
[anniversary] |
rop_table.csv |
rop_rate_array() |
float64 |
[anniversary] |
rop_table.csv |
The table checks are the ints they were: lapse_last_year(), the four age extents,
class_count(), surr_charge_count() and rop_count(). The COI table’s
check, which at stage E returned a Series of last ages, is the int
coi_schedules(), holding every message it held.
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, and a width
comes from a table or a check, never from another cell’s array. Each table’s check is one
cell that every array, extent and schedule number of the table reads first,
coi_schedules() for the COI scale, so that a projection, which reads an extent or a
schedule number first, meets the same refusal as a reader of the array. The column
keywords of a DataFrame.assign are passed as **{...}, since a keyword named as a
cell of this Space, age, age_at_entry, would be rewritten by the export.
What cannot be decoded or joined is refused when the array is first read, naming every
point at fault: a point_id that is not a whole number; a rate_class the class
factors lack; a sex and rate_class the COI scale lacks; and on a point that
has_surr_charge a surr_charge_id the schedules lack. ULSG_US_S fails every
projection of a point of the first two kinds, since it reads its class factor and its COI
scale in its first month in cover, and of the third its cash flows and margin check, which
read the schedule in every month of a point with a charge (its counts, accounts and
guarantee report do not); here that refusal is the table’s, so every point with a charge is
refused those two reports with it, as Term_US_SEC’s refusals at the first read are; a
point without a charge is never refused a projection for its schedule, whatever its id, as
ULSG_US_S never reads it: its schedule is read where the table holds its id, and where
it does not, Projection.surr_charge_rate_max raises KeyError, as at stage E. A
value of premium_type none of the flags names, or of premium_mode none of the
frequencies, is no flag and frequency 0, and the cell that branches on it raises
ULSG_US_S’s message, as in ULSG_US_S, so a SINGLE point, which never reads its mode,
projects whatever it is. Every decode and join compares the text exactly, as ULSG_US_S
does, so "level" or "StdNT " is not "LEVEL" or "StdNT". A read beyond a
table’s extent is refused where ULSG_US_S’s lookup raised KeyError, by the one
Projection cell that reads the table, naming the point: a policy year
below 1 in lapse_rate_base_py, an age below the scale’s first in coi_rate_guar_at,
and an anniversary without a window in rop_ratio_anniv and rop_rate_anniv. An age
outside the corridor or mortality table reads the nearest row, as in ULSG_US_S, and an
anniversary outside the windows’ is in none, so no padding is read.
A table is held from age, year or anniversary 0 to its last key, so a key far past any a
policy reaches, an anniversary of 10**9 say, makes an array of that many elements, where
ULSG_US_S reads the row or tests the membership without one. No rule bounds the keys
from above: a table’s last key is its own, and each shipped table ends at an age or a
year the projection reaches.
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 ULSG_US_S’s reading of it: the issue
age, the guarantee age, duration_mth, the months in grace and the COI precision
(model_point_table()’s rule 19) and the point_id (point_id()). modelx
and the compiled model refuse alike, before any cast. Every other number is read into a
float64, as ULSG_US_S reads it, and no int() of a float is taken in a projection.
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. Seven columns are the in-force interface:policy_countandduration_mth, the completed policy months at the valuation date, as inbasiclife.BasicTerm_SE; and five columns of the opening state, per policy, as the policy stands at the start of month 0, before any month-0 event:av_pp_init,sg_pp_init,loan_bal_initandcum_prem_init: the account value, the shadow account, the loan and the premiums paid to date entering month 0,ULSG_US_S’s own columns;grace_mth_init: the months already spent in grace entering month 0, whichULSG_US_Sreads as 0 at the start of its frame.
The rest are
ULSG_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, by 19 rules in turn, and the first that fails raises
ValueError, naming the missing column or every point it fails on:the in-force columns are present, and so are the columns of
ULSG_US_S’s own that the projection reads as a number or a flag:age_at_entry,sum_assured,guarantee_age,premium_pp_ann,wd_pp,load_prem_rate, the two pinsprem_persistency_overrideandcoi_rate_dp, and the flagshas_surr_chargeandrop_elected;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;age_at_entryis a whole number of years, 0 or more: the projection takes itsint()and counts its frame and every attained age on it;so is
guarantee_age, whichULSG_US_Stakes theint()of, truncating 95.5 to 95, and which decides the lifetime lapse multiplier;sum_assuredis a number above 0, the face, which every policy holds: it reaches the death benefit, the per-unit charges and the surrender charge, and a blank one would reach them as a missing value, which the death benefit’smaxthen loses without a word;each of
premium_pp_annandwd_ppis a number, zero or more;load_prem_rate, the share of each premium the load takes, is a number from 0 to 1: past 1 the account would be credited a net premium below 0, which the account value’s floor at zero absorbs, and at a load of 1.5ULSG_US_S’s account-value and margin checks fail on each of its points;prem_persistency_overrideis blank, where the point takes the rule, or a number from 0 to 1, a probability;coi_rate_dpis blank, where the point quotes its scales exact, or a whole number of decimal places, 0 or more:ULSG_US_Stakes theint()of 2.5;each of
has_surr_chargeandrop_electedisTrueorFalse, as pandas reads those words in any case. A blank, a number or any other text is refused: one text value turns the whole column into text, where"False"is a true string, so every point would read as carrying the flag;av_pp_initis a number, zero or more. A balance is never negative in force.ULSG_US_Slets the account value close a month below zero with a loan on an exhausted account, through the loaned part’s lower credited rate; no policy in force can hold that balance, so such a point is restated no later than the last month its account value is still zero or more;sg_pp_initis a number, of either sign: the shadow account is never floored, and a negative balance is the catch-up shortfall;each of
loan_bal_initandcum_prem_initis a number, zero or more;grace_mth_initis a whole number of months, 0 or more;a policy not yet in force,
duration_mth0 or less, has no opening state: each of the five columns is 0, and the issue values come from the formulas;each of
age_at_entry,guarantee_age,duration_mth,grace_mth_initandcoi_rate_dpis below2**53in size, where the int64 vector it is read into holds it exactly: past int64 a float casts to the least int64 without a word. Last, so that every earlier rule keeps its message.ULSG_US_Sprojects a precision of2**53or more, whichroundreads as exact; the rule refuses it, as it does every number read into an int64.
The text columns
sex,rate_class,premium_type,premium_modeandsurr_charge_idare keys and labels, which this Space decodes or joins on at their first read (the Space docstring’s The vectors). The grace counter is not held to the account value:ULSG_US_Scan carry a positive account value in grace, once the loaned part earns more than the unloaned, so no such rule could be right.
- coi_rates()[source]#
Guaranteed maximum annual COI rates, read from coi_rates.csv.
Per $1,000 of net amount at risk, keyed by sex, rate class and attained age. The monthly rate is the annual rate divided by twelve [std] structure; [R3] requires the guaranteed maxima to be stated in the policy, and [REG-R17] names the 2017 CSO family the notes point at.
- corridor_factors()[source]#
The GPT corridor factor table by attained age, read from corridor_factors.csv.
- mort_table()[source]#
The best-estimate annual mortality table by attained age, from mort_table.csv.
- surr_charge_table()[source]#
The surrender charge schedules, read from surr_charge_table.csv.
One row per
surr_charge_id, giving the initial charge per $1,000 of initial face and the number of years over which it runs off linearly.
- rop_table()[source]#
The return-of-premium exercise windows, read from rop_table.csv.
One row per policy anniversary carrying a window: the refund ratio applied to cumulative premiums [S1] and the [std] exercise rate.
- coi_schedules()[source]#
The number of cells coi_rates.csv gives a scale for, the table checked.
One schedule a cell, each
sexandrate_classthe table holds:coi_rate_array()holds each schedule in a row, numbered from 1 in the order of those keys, andcoi_schedule()gives each point its number. The table’s one check, which each of them,coi_rate_first_ages()andcoi_rate_last_ages()ask first. The two text keys may not be blank, and the numeric key,age, is read by value, once: an age that is blank, text or not a whole number is refused, naming the file and the lines it is on. So is a cell whose ages do not run one row an age, without a gap or a repeat: the message names the cell, each age that repeats, with its lines, and each age missing between the cell’s first and its last. And so is acoi_rate_guar_annthat is blank, text, infinite or below 0, naming its lines: a charge per $1,000 of net amount at risk a year, never a credit, which the shipped scale holds above 1 at every age it charges, from 1.48 at 45 to 1,000 at 120, and at 0 at 121, where charges cease; the current monthly rate passes 1 from attained age 69. And so is an age below 0, since each schedule is held from age 0.Projection.coi_rate_last_agetakes a point’s extent fromcoi_rate_last_ages()beforeProjection.coi_rate_guar_atreads its scale. A blank rate is a missing value toULSG_US_S, which its account value’s floor at zero, amax, then reads as an exhausted account.At stage
Ethis check wascoi_rate_last_ages(), which returned the last ages as a Series; a check is an int here, the number of schedules, and the arrays ask it, so every message is the one it was.
- corridor_age_last()[source]#
The last attained age corridor_factors.csv gives a factor for, the table checked.
The
agecolumn is read by value, once, so an age written40.0is 40. A key that is blank, text or not a whole number is refused, naming the file, the column and the lines it is on. So are ages that do not run one row an age, without a gap or a repeat: the message names each age that repeats, with its lines, and each age missing between the first and the last. And so is acorridor_factorthat is blank, text, infinite or below 0, naming its lines: a multiple of the account value, which the statute’s applicable percentages hold to 100% or more. And so is an age below 0, sincecorridor_factor_array()holds the table from age 0.Projection.corridor_factor_at, the table’s one reader, takes both of its extents, this andcorridor_age_first(), before it reads a factor. A blank factor is a missing value toULSG_US_S, whose death benefit, themaxof the face and the corridor’s amount, then reads it as no corridor at all. A factor below 1 only makes the corridor bind later, or never; below 0 it would make the corridor’s amount on an account value below 0 a positive one, which onlyProjection.db_pp’s floor on the account value keeps from the death benefit.
- corridor_age_first()[source]#
The first attained age corridor_factors.csv gives a factor for.
Counted back from
corridor_age_last(), which checks the table’s keys first: the ages run one row an age, so the first is the last less the rows after it.
- mort_age_last()[source]#
The last attained age mort_table.csv gives a rate for, the table checked.
Read and checked as
corridor_age_last()reads and checks its own table, the rate checked beingmort_rate, which must also be from 0 to 1, as a probability; the shipped table reaches 1.0 at attained age 120. An age below 0 is refused, as there.Projection.mort_rate_base_at, the table’s one reader, takes both of its extents, this andmort_age_first(), before it reads a rate. A blank rate is a missing value toULSG_US_S, whose mortality is then not a number, and toProjection.mort_rate, whose cap,min(q, 1.0), keeps it missing; a negative one would project negative deaths.
- mort_age_first()[source]#
The first attained age mort_table.csv gives a rate for.
Counted back from
mort_age_last(), which checks the table’s keys first, ascorridor_age_first()counts its own.
- lapse_last_year()[source]#
The last policy year lapse_table.csv gives a rate for, the table checked.
The
policy_yearcolumn is read by value, once, as the lookup matches it, so a year written5.0is year 5. A key that is blank, text or not a whole number is refused, naming the file, the column and the lines it is on. So are policy years that do not run from 1, one row a year, without a gap or a repeat: the message names each year that repeats or falls below 1, with its lines, and each year missing from 1 to the last. And so is alapse_rate_annthat is blank, text or outside 0 to 1, naming its lines: a probability, which below 0 would grow the count by its lapses, and past 1 would leaveProjection.lapse_rate_mth’s1 - (1 - q)^(1/12)no real value.Projection.lapse_rate_base_py, the table’s one reader, takes its extent from here before it reads a rate. A blank rate is a missing value toULSG_US_S, which its lapse rate’s floor, amax, then reads as the floor.
- class_count()[source]#
The number of classes class_factor_table.csv gives a factor for, the table checked.
A
rate_classthat is blank is refused, naming the file and the lines it is on, and so is one on more than one row, naming each such class with its lines; and so is afactorthat is blank, text, infinite or below 0, naming its lines: a multiple of the base mortality, which below 0 would project negative deaths.Projection.class_factor, the table’s one reader, asks for the count before it reads a factor, so a projection meets the checks first. A blank factor is a missing value toULSG_US_S, whose mortality is then not a number, and toProjection.mort_rate, whose cap,min(q, 1.0), keeps it missing.
- surr_charge_count()[source]#
The number of schedules surr_charge_table.csv gives, the table checked.
A
surr_charge_idthat is blank is refused, naming the file and the lines it is on, and so is one on more than one row, naming each such schedule with its lines. So is asc_per_1000_initthat is blank, text, infinite or below 0, naming its lines, and arunoff_yearsthat is not a whole number of years, 1 or more – blank, text, infinite, a fraction or below 1 alike – naming its lines: the projection divides the charge by the run-off, whereULSG_US_Sdivides by zero at 0.Projection.surr_charge_rate_maxandProjection.surr_charge_runoff_years, the table’s two readers, ask for the count before they read a value, so a projection meets the checks first. A blank charge is a missing value toULSG_US_S, whose surrender charge rate, themaxof 0 and the charge left, then reads it as no charge at all. A charge below 0 leaves a charge below 0 through the schedule’s years, which themaxreads as none, and after them, where the share of the run-off left turns negative, a charge above 0 that rises each month, every check passing.
- rop_count()[source]#
The number of windows rop_table.csv gives, the table checked.
The return-of-premium endorsement’s windows are read by membership of their anniversaries (
Projection.is_rop_anniv), so theanniversarycolumn is read by value, once, as the membership test matches it, so that an anniversary written20.0is 20. One that is blank, text or not a whole number of years, 1 or more, is refused, naming the file and the lines it is on, and so is one on more than one row, naming each such anniversary with its lines: a window at an anniversary before the first, or two rows for one, would be read by no rule. And so is arefund_ratioor anexercise_ratethat is blank, text or outside 0 to 1, naming its lines: a share of the premiums paid, and a probability.Projection.is_rop_anniv,Projection.rop_ratio_annivandProjection.rop_rate_anniv, the table’s three readers, ask for the count before they read the table, so a projection meets the checks first.
- coi_schedule()[source]#
The number of each model point’s guaranteed COI scale, in table order: int64 [point].
The point’s row of
coi_rate_array(): the schedules of coi_rates.csv, one for eachsexandrate_classit holds, numbered from 1 in the order of those keys, ascoi_rate_array()numbers its rows, whatever the order of the file’s lines. The point’s key is itssexand itsrate_class, compared exactly, asULSG_US_Sslices the scale. Every point reads its scale in its first month in cover, soULSG_US_Sfails every projection of a point whose key the table lacks: such a point is refused here, at the first read, naming every such point. Askscoi_schedules()first, which checks the table.
- coi_rate_first_ages()[source]#
The first attained age of each guaranteed COI scale: int64 [schedule].
Element
sis the firstagecoi_rates.csv holds for schedules, numbered ascoi_schedule()numbers it, read by value oncecoi_schedules()has checked the table: 45 on the shipped anchor cell. 0 at element 0, which no point is given.Projection.coi_rate_first_agereads it at the point’s schedule.
- coi_rate_last_ages()[source]#
The last attained age of each guaranteed COI scale: int64 [schedule].
Element
sis the lastagecoi_rates.csv holds for schedules, numbered ascoi_schedule()numbers it, read by value oncecoi_schedules()has checked the table: 121 on the shipped anchor cell. 0 at element 0, which no point is given.Projection.coi_rate_last_agereads it at the point’s schedule beforeProjection.coi_rate_guar_atreads the scale.
- coi_rate_array()[source]#
The guaranteed maximum annual COI rates by schedule and attained age: float64 [schedule, age].
Row
sis schedulesof coi_rates.csv, numbered from 1 in the order of its keys,sexandrate_class, ascoi_schedule()numbers it, and columnais attained agea, so that the age is the index: one more column than the table’s last age, one more row than its schedules. Per $1,000 of net amount at risk a year. NaN in row 0, schedule 0, which no point is given, and outside each schedule’s ages, below its first and past its last, all padding, whichProjection.coi_rate_guar_atnever reads: it refuses an age below the schedule’s first and reads a later age at the schedule’s last. Askscoi_schedules()first, which checks the table.
- corridor_factor_array()[source]#
The GPT corridor factors by attained age: float64 [age].
Element
ais thecorridor_factorof ageain corridor_factors.csv, so that the age is the index, to the last agecorridor_age_last()gives once it has checked the table, which refuses a negative age. NaN from 0 to below the first age, whichProjection.corridor_factor_atnever reads: it reads an age outside the table at the nearest row, asULSG_US_Sdoes.
- mort_table_array()[source]#
The best-estimate annual mortality rates by attained age: float64 [age].
Element
ais themort_rateof ageain mort_table.csv, held ascorridor_factor_array()holds its own table, to the last agemort_age_last()gives. NaN from 0 to below the first age, whichProjection.mort_rate_base_atnever reads.
- lapse_rate_array()[source]#
The base annual lapse rates by policy year: float64 [y].
Element
yis thelapse_rate_annof policy yearyin lapse_table.csv, so that the year is the index, to the last yearlapse_last_year()gives once it has checked the table. NaN at 0, before the first year, whichProjection.lapse_rate_base_pynever reads: it refuses a year below 1.
- rop_last_anniv()[source]#
The last anniversary rop_table.csv gives a window at, the table checked.
Read by value once
rop_count()has checked the anniversaries and the values, so an anniversary written25.0is 25: the extent ofrop_anniv_flags()and the two value arrays. 0 for a table with no window, where every flag array holds one element, 0.Projection.is_rop_annivasks it first, so a projection meets the check before it reads a flag, and answers an anniversary past it without a read.
- rop_anniv_flags()[source]#
Whether a return-of-premium window follows each policy anniversary: int64 [anniversary].
Element
yis 1 where rop_table.csv lists anniversaryyand 0 elsewhere, from 0 torop_last_anniv():ULSG_US_S’s membership of the table’s key column,y in rop_table().index, held as an array padded with zeros, so that the anniversary is the index.
- rop_ratio_array()[source]#
The refund ratio of each return-of-premium window by anniversary: float64 [anniversary].
Element
yis therefund_ratioof anniversaryyin rop_table.csv, and NaN at each anniversary the table does not list, from 0 torop_last_anniv(): padding, whichProjection.rop_ratio_annivnever reads, since it asksProjection.is_rop_annivfirst.
- rop_rate_array()[source]#
The exercise rate of each return-of-premium window by anniversary: float64 [anniversary].
Element
yis theexercise_rateof anniversaryyin rop_table.csv, held asrop_ratio_array()holds the refund ratio, and read only byProjection.rop_rate_anniv, at a window.
- 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, and so is one of2**53or more in size, which numpy would read as the least int64 once past int64. pandas reads a column of whole labels as int64 exactly, so the bound refuses some labels the vector could hold, none of them a label a table needs.
- age_at_entry()[source]#
The issue age (ANB) of every model point: int64 [point].
The
age_at_entrycolumn, whichmodel_point_table()holds to a whole number below2**53in size, 0 or more.
- guarantee_age()[source]#
The elected guarantee age of every model point: int64 [point].
The
guarantee_agecolumn, whichmodel_point_table()holds to a whole number below2**53in size, 0 or more.
- duration_mth()[source]#
The completed policy months at the valuation date of every model point: int64 [point].
The
duration_mthcolumn, whichmodel_point_table()holds to a whole number below2**53in size.
- grace_mth_init()[source]#
The months already spent in grace entering month 0: int64 [point].
The
grace_mth_initcolumn, whichmodel_point_table()holds to a whole number below2**53in size, 0 or more.
- coi_rate_dp()[source]#
The decimal places each model point quotes its COI scales to: int64 [point].
The
coi_rate_dpcolumn, whichmodel_point_table()holds to blank or a whole number, 0 or more, below2**53, read asULSG_US_Sreads it: -1 where it is blank,ULSG_US_S’s own “exact”, so thatProjection.coi_ratetests a number, not a missing value.
- sum_assured()[source]#
The face at issue of every model point: float64 [point].
The
sum_assuredcolumn, whichmodel_point_table()holds to a number above 0.
- policy_count()[source]#
The policies each model point stands for: float64 [point].
The
policy_countcolumn, whichmodel_point_table()holds to a number, zero or more.
The scheduled annual premium per policy of every model point: float64 [point].
The
premium_pp_anncolumn, whichmodel_point_table()holds to a number, zero or more.
- wd_pp()[source]#
The planned monthly withdrawal per policy of every model point: float64 [point].
The
wd_ppcolumn, whichmodel_point_table()holds to a number, zero or more.Projection.wd_pp_mthreads it, sinceProjection.wd_ppis the month’s withdrawal.
- load_prem_rate()[source]#
The base premium load of every model point: float64 [point].
The
load_prem_ratecolumn, whichmodel_point_table()holds to a number from 0 to 1.
- av_pp_init()[source]#
The account value per policy entering month 0: float64 [point].
The
av_pp_initcolumn, whichmodel_point_table()holds to a number, zero or more.
- sg_pp_init()[source]#
The shadow account per policy entering month 0: float64 [point].
The
sg_pp_initcolumn, whichmodel_point_table()holds to a number, of either sign.
- loan_bal_init()[source]#
The loan per policy entering month 0: float64 [point].
The
loan_bal_initcolumn, whichmodel_point_table()holds to a number, zero or more.
- cum_prem_init()[source]#
The premiums paid per policy entering month 0: float64 [point].
The
cum_prem_initcolumn, whichmodel_point_table()holds to a number, zero or more.
- prem_persistency_override()[source]#
The premium persistency pin of every model point: float64 [point].
The
prem_persistency_overridecolumn, whichmodel_point_table()holds to blank or a number from 0 to 1, NaN where it is blank, asULSG_US_Sreads it: a value read only wherehas_prem_persistency_override()says the point pins it.
- has_prem_persistency_override()[source]#
Whether each model point pins its premium persistency: int64 [point].
1 where the
prem_persistency_overridecolumn holds a number, 0 where it is blank,ULSG_US_S’spd.isnadecided once for the table.
- has_surr_charge()[source]#
Whether a surrender charge schedule applies to each model point: int64 [point].
1 where the
has_surr_chargecolumn reads True, in any case, and 0 where it reads False:model_point_table()refuses any other value.
- rop_elected()[source]#
Whether each model point elects the return-of-premium endorsement: int64 [point].
1 where the
rop_electedcolumn reads True, in any case, and 0 where it reads False, ashas_surr_charge()decodes its own.
Whether each model point’s premium pattern is LEVEL: int64 [point].
1 where
premium_typeis"LEVEL", compared element by element asULSG_US_Scompares it, so that"level"or" LEVEL"is not, and 0 elsewhere. A pattern none of the three is not refused here: it is no flag, and the projection cell that branches on the pattern raisesULSG_US_S’s message on it.
Whether each model point’s premium pattern is SINGLE: int64 [point].
1 where
premium_typeis"SINGLE", asis_level_premium()decodes LEVEL.
Whether each model point’s premium pattern is TEN_PAY: int64 [point].
1 where
premium_typeis"TEN_PAY", asis_level_premium()decodes LEVEL.
The scheduled premium payments a year of every model point: int64 [point].
premium_modedecoded element by element, compared exactly asULSG_US_Scompares it:"A"1,"S"2,"Q"4 and"M"12. Any other value, a blank or"a"among them, is 0, and not refused here:ULSG_US_Sreads the mode only on a point paying more than a single premium, soProjection.premium_freqraisesULSG_US_S’s message on a 0 where it is read, and a SINGLE point projects whatever its mode.
- class_factor()[source]#
The underwriting-class factor of each model point: float64 [point].
The
factorclass_factor_table.csv gives the point’srate_class, compared exactly, onceclass_count()has checked the table. A point reads its class factor in its first month in cover, soULSG_US_Sfails every projection of a point whose class the table lacks: such a point is refused here, at the first read, naming every such point.
- surr_charge_rate_max()[source]#
The surrender charge per $1,000 of initial face of each model point, before any of it runs off: float64 [point].
The
sc_per_1000_initof the point’ssurr_charge_idin surr_charge_table.csv, oncesurr_charge_count()has checked the table, on every point whose id the table holds, with a charge or without, asULSG_US_SEC’s accessor read it at stageE: a point without a charge reads its schedule, though no cell reads it there. An id the table lacks, on a point with a charge, whereULSG_US_S’s.locraisedKeyErrorin every month of such a point’s cover, is refused, naming every such point. On a point without a charge it is NaN, andhas_surr_charge_schedule()0: the point projects, andProjection.surr_charge_rate_maxraisesKeyErroron it, as the.locdid at stageE.surr_charge_count()already refuses a run-off that is not a whole number of years, 1 or more, so no further rule is needed for the division by it. The same check runs insurr_charge_runoff_years(), the join’s other vector, so that whichever a projection reads first refuses the point.
- surr_charge_runoff_years()[source]#
The run-off, in policy years, of each model point’s surrender charge: float64 [point].
The
runoff_yearsof the point’ssurr_charge_idin surr_charge_table.csv, on every point whose id the table holds, NaN on a point without a charge whose id it lacks, joined and checked assurr_charge_rate_max()joins and checks the charge, with its refusal.
- has_surr_charge_schedule()[source]#
Whether surr_charge_table.csv holds each model point’s schedule: int64 [point].
1 where the point’s
surr_charge_idis asurr_charge_idof the table, compared exactly, asULSG_US_S’s.loccompares it, and 0 where it is not, blank included, oncesurr_charge_count()has checked the table. 0 only on a point without a charge, sincesurr_charge_rate_max()refuses the table where a point with a charge names an id it lacks: thereProjection.surr_charge_rate_maxandProjection.surr_charge_runoff_yearsraiseKeyError, naming the point.