The Projection Space#
The by-policy projection of the Term_US_SEC model; holds all formulas.
The Space is parameterized by idx, the position of a model point in the table and in
every Data vector, as basiclife.BasicTerm_SC is: Projection[3]
is an ItemSpace projecting the table’s fourth row, model point 4, the anchor cell in force
126 months at the valuation date, and point_id() is its label:
>>> Projection[3].result_cf() # one row per month from the valuation date
>>> Projection[3].result_pols() # the counts behind it
>>> Projection[3].point_id() # 4, the row's point_id
>>> Projection.idx = 1 # or switch the default, before it computes
Compiled, no cache is ever cleared: set idx, like every Reference, on a model just
imported, before anything is computed, or project through Projection[i]. modelx
recomputes what a Reference reaches when it is set; a compiled ItemSpace takes the
References when it is made and keeps every value it has computed until it is deleted,
and the base Projection and Data keep theirs for good.
Any idx makes an ItemSpace, and none is refused here. Projection[-1] reads every
vector at its last element, as numpy and a compiled memoryview both do, so it is the
table’s last point, under that point’s own point_id(); an idx past the last
row raises IndexError at its first read of a vector, which modelx reports inside its
FormulaError.
This is Term_US_S taught to run in force at a valuation date, as lifelib’s
basiclife.BasicTerm_SE extends basiclife.BasicTerm_S, and then made to compile, as
basiclife.BasicTerm_SC is made from basiclife.BasicTerm_S. A formula of
Term_US_S is rewritten where it depends on where the projection starts, where it
must answer for a month outside cover, or where it read a month far ahead of its own. The
min of the notes’ M(1) rule and the max of the PLT grading,
plt_mort_factor_init_formula() and plt_mort_factor(), are rewritten with their
bounds second, as mort_rate() writes its cap, min(q, 1.0), in both models, so
that a NaN stays NaN; wherever its argument is a number, each is the float it would be
with its bound first. Every other formula is Term_US_S’s own, mort_rate()
among them. products/term_life/model-sec.md lists the rewritten cells with the reason
for each. Making it compile changed how each cell reads its inputs and spells its codes, and
no number: every model point attribute a projection cell uses is read as a number from a
Data vector, every table as an array indexed by integers, and every timing and phase is
an int code (Codes, below).
Input data
Inputs are external files: plain CSVs living in the model folder’s parent
directory, products/term_life/, read at run time rather than 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, and an
input can be edited or swapped without rewriting the model. 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. A test asserts this by round-tripping the model together
with its inputs.
input_dir() resolves the directory from
_model.path.parent at run time, so the model works wherever the repository is
checked out. The four assumption tables are the files Term_US_S reads, read in
place; the model point table is this model’s own. Each table has a filename Reference
and a reader Cells:
Reference |
Cells |
File |
|---|---|---|
model_point_file |
data.model_point_table() |
model_point_table_sec.csv |
premium_rates_file |
data.premium_rates() |
premium_rates.csv |
mort_table_file |
data.mort_table() |
mort_table.csv |
class_factor_file |
data.class_factor_table() |
class_factor_table.csv |
shock_lapse_file |
data.shock_lapse_table() |
shock_lapse_table.csv |
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. No formula changes. Replacing
the file changes Term_US_S too, which reads the same one.
No cell here but model_point(), a reporting cell, reads the readers’ DataFrames,
and the label accessors read through it. Every other reads Data’s
vectors and arrays, one element at a time: a model point’s attribute at its position,
data.age_at_entry()[idx], decoded already into the number the formula needs; the
premium schedule at data.premium_rates_array()[premium_schedule(), y]; the mortality
table at the attained age, data.mort_table_array()[age(t)]. Data’s docstring
lists them.
Naming
Cells names follow lifelib’s basiclife.BasicTerm_S wherever that model has an
analogue — pols_* for policy counts, plural nouns for cash flows, *_rate for
rates, *_pp for per-policy amounts — and, for the monthly grid, the
duration_mth / duration / policy_year triple that savings.CashValue_SE
and the UL family in this library use. What running in force adds is named as
basiclife.BasicTerm_SE names it: duration_mth read from the model point,
policy_count, pols_new_biz, pols_if_at with its BEF_NB and BEF_DECR
timings, is_active and result_pols. duration_mth_init, the policy months
completed at the valuation date, takes UL_US_S’s name; t_entry and
expiry_mth are this model’s own. What compiling adds is named as
basiclife.BasicTerm_SC names it: idx, point_id and the Data vectors under
their columns’ names. A cell keyed by policy year rather than by month carries _py.
The technical notes use compact actuarial symbols instead.
Two clocks
t counts months from the valuation date, 0-based, the clock
basiclife.BasicTerm_SE runs on: t = 0 is the valuation month for every model
point, however old the policy, period t runs from time t to time t + 1, and
the frame is t = 0 .. proj_len() - 1, where proj_len() counts the months from
the valuation date to the end of cover. Row t is the same month for every point, so
the frames of a block line up and sum row by row.
duration_mth(t) counts policy months, the months the policy has been in force at
time t: duration_mth(t) = duration_mth_init() + t, where
duration_mth_init() is read from the model point — positive for a policy in force
at the valuation date, 0 for one issued at it, -k for one issued k months later,
at most ten years later. It is the technical notes’ month index. Everything contractual
reads it: the completed policy years duration(t) = duration_mth(t) // 12, the
contractual 1-based label policy_year(t) = duration(t) + 1, the attained age
age(t) = age_at_entry() + duration(t), and through them the premium schedule, the
ART renewals, the shock lapse, the conversion window and the commission scale. The
anchor cell in force 126 months is in policy year 11 at attained age 45 at t = 0,
and pays its next premium at t = 6, its eleventh anniversary.
One input reads the valuation clock instead: expense inflation,
inflation_factor(t) = (1 + inflation_rate) ** (t / 12), so that the maintenance
charge is in valuation-date dollars for every point alike. Acquisition is a flat
expense_acq per policy issued, charged in the issue month and not inflated, as in
basiclife.BasicTerm_SE.
On a point issued at t = 0 the two clocks coincide and this model computes what
Term_US_S computes, but for one difference by design: acquisition is charged
per policy issued, where Term_US_S charges it once per model point, whatever
the count. The two agree on Term_US_S’s own model points, which count one
policy each: there every cell the two share agrees at every argument
Term_US_S evaluates in its sweep, but for two whose meaning changed,
pols_if_init, now the count already in force at the valuation date, and
model_point, a row of another table. That is how the S worked example carries over,
and tests/test_model_conventions.py asserts it cell by cell.
Counts
pols_if(t) is the count that weights row t: pols_if_at(t, BEF_DECR), the
count carried in from t - 1 (BEF_NB) plus the month’s new business,
pols_new_biz(), before the month’s decrements. A point in force at the valuation
date opens with pols_if_init(), its policy_count; one issued at or after the
valuation date opens with none, and takes its policy_count as new business in its
issue month. The recursion’s base is t_entry(), the first month on the books, and
nothing is counted outside cover (is_active()): before issue every count, and so
every cash flow, is zero.
Codes
What Term_US_S spells as text, a timing or a phase, is here an int Reference
named as the text it replaces, so that every cell takes and returns C numbers. A call
site reads as it did, less the quotes: pols_if_at(t, BEF_DECR).
Reference |
Value |
Meaning |
|---|---|---|
BEF_NB |
0 |
|
BEF_DECR |
1 |
|
PRE_ISSUE |
0 |
|
LEVEL |
1 |
|
PLT |
2 |
|
EXPIRED |
3 |
|
A code a cell takes indexes that cell’s cache, a C array of two timings a month for
pols_if_at, so codes are numbered densely from 0. Timings are numbered in the order of
their instants within the month, BEF_NB before BEF_DECR, as in every SEC model,
and phases in their natural order. They are References, not cells, so the symbol map
below does not list them.
Reporting cells
model_point(), the label accessors sex(), rate_class(), plan()
and premium_mode(), and the reports result_cf(), result_cf_annual() and
result_pols() return Python values, a table row, text and DataFrames, for a reader
and for the comparison with Term_US_S, which has every one of them but
result_pols(). No cell but these calls them: every other reads the number Data
decoded from the same column instead, the plan’s level period, the mode’s cycle, the
class’s factor, the schedule the four keys select. So they stay Python when the model
compiles, and every other cell returns a C bint, long long or double.
Symbols
The two-speed structure is the library’s convention, asserted by
tests/test_model_conventions.py: mort_rate(t) and lapse_rate(t) are the
annual rates of the policy year containing month t — the vectors the technical
notes tabulate — and mort_rate_mth(t) and lapse_rate_mth(t) are the monthly
rates actually applied, 1 - (1 - q)^(1/12). The notes’ month index is this model’s
duration_mth(t). The mapping is:
Notes symbol |
Cells |
Meaning |
|---|---|---|
x |
age_at_entry |
Issue age (ANB) |
x + dur |
age(t) |
Attained age in month t |
n |
policy_term |
Level period in years |
F |
sum_assured |
Face amount |
(none) |
point_id |
The model point’s label in the table |
(none) |
policy_count |
Policies the model point stands for |
(none) |
duration_mth_init |
Completed policy months at the valuation date; -k if issued k months later |
t |
duration_mth(t) |
The notes’ month index: completed policy months at month t |
dur(t) |
duration(t) |
Completed policy years at month t |
dur(t) + 1 |
policy_year(t) |
Policy year, the 1-based contractual label |
12(95 - x) |
expiry_mth |
Policy month at which cover ends |
(frame) |
proj_len |
Months from the valuation date to the end of cover; frame ends at proj_len - 1 |
(none) |
t_entry |
First month on the books |
(none) |
is_active(t) |
Whether month t is inside cover |
l(t) |
pols_if(t) |
In-force weighting month t: after new business, before decrements |
(none) |
pols_if_at(t, timing) |
In-force at time t, BEF_NB or BEF_DECR |
(l(0)) |
pols_if_init |
In-force at the valuation date |
(none) |
pols_new_biz(t) |
Policies issued in month t |
d(t) |
pols_death(t) |
Deaths in month t |
s(t) |
pols_surv(t) |
Survivors to end of month t |
x(t) |
pols_lapse(t) |
Lapses at end of month t |
c(t) |
pols_conv(t) |
Conversions at end of month t |
(none) |
pols_maturity(t) |
Expiries at attained age 95 |
q(t) |
mort_rate(t) |
Annual mortality, all factors applied, capped at 1 |
q_m(t) |
mort_rate_mth(t) |
The monthly rate actually applied |
(q_base) |
mort_rate_base(t) |
Base table rate before factors |
w(t) |
lapse_rate(t) |
Annual lapse rate, incl. the shock |
w_m(t) |
lapse_rate_mth(t) |
The monthly rate actually applied |
w(n-1) |
shock_lapse_rate |
Shock lapse, in full at policy month 12n - 1 |
cv(t) |
conv_rate(t) |
Annual conversion rate |
cv_m(t) |
conv_rate_mth(t) |
The monthly rate actually applied |
conv_elig(t) |
conv_elig(t) |
Conversion eligibility |
(window) |
conv_elig_py(y) |
Whether policy year y is in the window |
M(d) |
plt_mort_factor(d) |
PLT mortality deterioration, d = policy_year - n |
M(1) |
plt_mort_factor_init |
M(1) actually used |
(M(1) rule) |
plt_mort_factor_init_formula |
The notes’ formula for M(1) |
J |
jump_ratio |
AP of policy year n + 1 over year n, fee included |
AP(t) |
premium_pp_ann(t) |
Guaranteed annualized premium, policy year of t |
(AP by year) |
premium_pp_ann_py(y) |
The same, for policy year y |
(schedule) |
premium_schedule |
The point’s guaranteed premium schedule |
(modal) |
premium_pp(t) |
Premium per policy actually due in month t |
(modal factor) |
modal_factor |
Modal factor of the premium mode |
(modal cycle) |
prem_cycle |
Months between instalments |
(due month) |
prem_due(t) |
Whether a modal premium falls due in month t |
G(t) |
premiums(t) |
Premium income |
K(t) |
commissions(t) |
Commission |
k(t) |
comm_rate(t) |
Commission rate |
X(t) |
premium_taxes(t) |
Premium tax |
E(t) |
expenses(t) |
Acquisition + maintenance |
1.02^(t/12) |
inflation_factor(t) |
Expense inflation, valuation clock |
DC(t) |
claims(t) |
Death claims |
CV(t) |
conv_credits(t) |
Conversion credit outflow |
NetCF(t) |
net_cf(t) |
Net cash flow |
phase(t) |
phase(t) |
PRE_ISSUE / LEVEL / PLT / EXPIRED, as codes |
(none) |
result_cf_annual() |
result_cf() summed into policy years |
(none) |
result_pols() |
The counts, one row per month |
Three notes on the mapping. The notes write deaths as d(t) while also using d
as the post-level-term duration index in M(d); the pols_death / plt_mort_factor
split removes that collision. The notes’ x(t) (lapses) and X(t) (premium tax)
differ only by case, which pols_lapse and premium_taxes separate. And
pols_maturity has no symbol in the notes at all — see below.
The shock lapse is not spread
Every ordinary decrement is converted to a monthly rate at 1 - (1 - q)^(1/12), so
twelve months of it compound back to exactly the annual rate the notes tabulate. The
shock lapse is the one exception the notes make explicitly: it is not spread, but
applied in full at the end of the final level-period month, the month whose
duration_mth(t) is 12n - 1, immediately before the first ART premium falls due
at 12n. Its policy year’s annual rate w(n-1) is the shock, so
lapse_rate_mth() returns zero in the other eleven months of that year and the
shock itself in the last one.
That is what makes the two grids reconcile: because the ordinary monthly rates
compound to the annual ones and the shock falls at a year boundary, the in-force
at every policy anniversary is identical to the annual-step model’s, to
floating-point. The cash flows are not identical and are not meant to be: claims now
fall at the end of the month of death rather than the end of the policy year,
maintenance expense accrues monthly, and a modal premium is collected when it is
contractually due. Those timing differences are the reason for the monthly grid.
result_cf_annual() sums the frame into policy years so the two can be laid side
by side.
Premium mode
premium_pp(t) is the premium actually collected in month t: the model point’s
premium_mode picks the modal factor (modal_factor()) and the payment months
(prem_cycle()) — annual in month 0 of each policy year, semi-annual every sixth
month, quarterly every third, monthly every month — and the annualized guaranteed
premium AP(t) the notes tabulate is premium_pp_ann(). Modal loading is
inside the factor (twelve monthly payments come to 0.99996 of the annual premium, two
semi-annual instalments to 1.04 of it) exactly as the specimen prints it [S6]. The
jump ratio and the conversion credit are both on AP, which is what keeps them
mode-independent; commission is a rate keyed by policy year applied to the premium
actually collected, so a modal payer earns it in instalments too.
pols_maturity
The notes give the roll-forward as l(t+1) = l(t)(1-q_m)(1-cv_m)(1-w_m) and,
separately, the rule l(t) = 0 for x + duration(t) >= 95. Those do not reconcile in
the last covered month, duration_mth(t) = expiry_mth() - 1: its survivors neither
die, lapse nor convert — their coverage simply runs out. Without a term for that, the
roll-forward appears to lose lives with no cause. pols_maturity(t) names it, zero
in every month but that one, so that:
pols_if(t) - pols_if_at(t + 1, BEF_NB)
= pols_death(t) + pols_lapse(t) + pols_conv(t) + pols_maturity(t)
holds for every t in the frame, and pols_if(t + 1) adds pols_new_biz(t + 1)
to the count on the left. It is bookkeeping determined by the notes’ own rules, not an
added assumption. The name follows BasicTerm_S.pols_maturity.
Cells Descriptions#
- model_point()[source]#
The selected model point, its row of
model_point_table_sec.csv, as a Series.Row
idxof the table, for a reader who wants every column at once: a reporting cell (the Space docstring), which no projection cell reads. Each reads its ownDatavector instead.
- point_id()[source]#
The label of the selected model point, its
point_id, fromData.point_id.Projectionis indexed by position,idx, asbasiclife.BasicTerm_SCis; the label is what a reader finds in the table, so every refusal names it.
- age_at_entry()[source]#
The issue age (ANB) of the selected model point, from
Data.age_at_entry.The age at issue, not at the valuation date:
age(0)is the attained age then.
- sex()[source]#
The sex of the selected model point, as the table spells it.
A reporting cell (the Space docstring):
Data.premium_schedulejoins the premium schedule by the column, and no projection cell reads it here.
- rate_class()[source]#
The underwriting class of the selected model point, as the table spells it.
A reporting cell:
Data.class_factorandData.premium_schedulejoin the class factor and the premium schedule by the column, and no projection cell reads it here.
- plan()[source]#
The plan code of the selected model point (T10 / T20 / T30).
A reporting cell:
Data.policy_termdecodes the level period from the column, and no projection cell reads it here.
- policy_count()[source]#
The number of policies the model point stands for, its
policy_countcolumn.A point in force at the valuation date counts the policies in force then, before any month-0 event; any other point counts the policies it issues. Either way the count enters the projection once: as
pols_if_init()for the first, aspols_new_biz()in the issue month for the second. Read fromData.policy_count.
- pols_if_init()[source]#
Policies in force at the valuation date, before any month-0 event.
policy_count()for a point already in force att = 0(duration_mth_init() > 0), and 0 for one issued at or after it, whose policies enter throughpols_new_biz()in the issue month instead, as inbasiclife.BasicTerm_SE. So on a point issued att = 0this is 0, andpols_if(0)is the issued count.
The premium mode of the selected model point: A, SA, Q or M [S6].
A reporting cell:
Data.prem_cycledecodes the months between instalments from the column, andmodal_factor()selects the factor by them.
- band()[source]#
Face-amount band 1-4, from
Data.band: boundaries at $250,000 / $500,000 / $1,000,000 [S5], the four-band choice [std]; the anchor cell is band 1.Datajoins the premium schedule by the band, so no projection cell reads this; it is kept for a reader, and for the comparison withTerm_US_S, which has it.
- policy_term()[source]#
The level premium period in years, from
Data.policy_term:T10is 10.Datadecodes it from the plan code, asTerm_US_Sreads it,int(plan[1:]).
- expiry_mth()[source]#
The policy month at which cover ends:
12 * (expiry_age - age_at_entry()).Coverage expires at attained age 95, so this is the
duration_mthof the first month not covered, and the last covered month isexpiry_mth() - 1. It isTerm_US_S’s frame length, counted from issue on the policy clock;proj_len()counts from the valuation date instead.
- proj_len()[source]#
The number of months from the valuation date to the end of cover.
expiry_mth() - duration_mth_init(): 720 for the anchor cell issued att = 0, 594 for it in force 126 months, and 723 for it issued 3 months after the valuation date. The frame ist = 0, 1, ..., proj_len() - 1;proj_len()is its exclusive end and the row count ofresult_cf().Three kinds of point raise here, naming the point, rather than project nothing or a frame the contract does not have:
one whose cover ended at or before the valuation date, which an in-force extract should not carry;
one whose plan’s level period is below
policy_term_min, 10 years, the shortest plan’s (product-spec.md), such asT5orT0;one issued below
issue_age_min, 18, the youngest issue age of every plan.
Datareads the last two asTerm_US_Sreads its columns. They are refused here becausespec_sec.pysizes the compiled model’s caches from the contract, cover from 18 toexpiry_age, 95, the PLT years after the shortest level period, and the shipped future horizon, and on such a point the compiled model would run past them, where modelx reads on. Every report reads this cell first, so modelx and the compiled model refuse such a point alike. The three References are the contract the caches hold: loweringissue_age_minorpolicy_term_min, or raisingexpiry_age, needs the spec’s sizes raised and the model rebuilt, as a longerData.future_horizon_mthdoes.
- duration_mth_init()[source]#
Completed policy months at the valuation date, the
duration_mthcolumn.The policy’s age in months at
t = 0: 126 for a policy issued 126 months before the valuation date, 0 for one issued at it, and -3 for one to be issued 3 months after it, whichDataadmits up tofuture_horizon_mthmonths ahead. It is read asbasiclife.BasicTerm_SEreads it, and is the one fact the policy clock takes from the model point, its element ofData.duration_mth.
- duration_mth(t)[source]#
Completed policy months at the start of month t, the policy clock.
duration_mth_init() + t:tcounts months from the valuation date andduration_mth(t)months from issue, and the two move together. A closed form, wherebasiclife.BasicTerm_SEadds one a month by recursion: the same numbers, without a call chain as long as the frame. Negative before issue. Everything contractual reads this clock, throughduration(),policy_year()andage().
- t_entry()[source]#
The first month the policy is on the books:
max(0, -duration_mth_init()).0 for a point in force at the valuation date or issued at it,
kfor one issuedkmonths later. It is the base of the count recursion:pols_if_at()opens there, frompols_if_init(), and reads no month before it.
- is_active(t)[source]#
Whether month t is inside cover: issued, and not yet expired.
0 <= duration_mth(t) < expiry_mth(). False before issue and from the month cover has ended. Outside cover every count is zero, and so every cash flow; no count cell evaluates a rate there, and no table is read at a policy year or an attained age the policy does not have.
- duration(t)[source]#
Completed policy years at the start of month t,
duration_mth(t) // 12.0 throughout the first policy year, and negative before issue. Every contractual schedule in this product is annual, so this is what the attained age and the premium schedule are read at.
- policy_year(t)[source]#
The contractual policy year containing month t,
duration(t) + 1.A 1-based label on the policy clock, never indexed by: the guaranteed premium schedule in
premium_rates.csvis keyed by it, and so are the annual decrement vectors. It is 0 or less before issue, where nothing reads a table by it.
- age(t)[source]#
The attained age (ANB) in month t:
age_at_entry() + duration(t).Age changes on the policy anniversary rather than on the birthday, which is the ANB convention the whole model is built on [std].
- modal_factor()[source]#
The model point’s modal factor: the fraction of AP collected per instalment [S6].
Annual 1.0, semi-annual 0.52, quarterly 0.27, monthly 0.08333 — the specimen’s own scale, so the modal loading is inside the factor. Each is its own Reference, so a carrier’s own scale drops in without a formula change. The factor is selected by
prem_cycle(), which is one to one with the mode, 12, 6, 3 and 1 months for A, SA, Q and M;Data.prem_cyclerefuses any other mode, naming the point, so the last branch is the monthly factor.
- prem_cycle()[source]#
Months between premium instalments: A 12, SA 6, Q 3, M 1, from
Data.prem_cycle.Arithmetic of the mode rather than an assumption, so
Datadecodes it from the mode rather than a Reference holding it.
- prem_due(t)[source]#
Whether a modal premium falls due at the beginning of month t.
Payments start at issue and repeat on the mode’s own cycle on the policy clock,
duration_mth(t) % prem_cycle() == 0: annual in month 0 of each policy year, semi-annual every sixth month, quarterly every third, monthly every month. None falls due outside cover. A point in force mid-year pays its next instalment on that cycle, so the anchor cell in force 126 months pays nothing untilt = 6.
AP(t): the guaranteed annualized gross premium per policy, fee included.
The notes’
APfor the policy year containing month t,premium_pp_ann_py(policy_year(t)), and zero outside cover, where the policy has no policy year to look up. It is the base for the conversion credit, which should not move with the premium mode;premium_pp()is what is actually collected in month t, and it is that instalment — notAP— thatcommissions()andpremium_taxes()are charged on.
The selected model point’s guaranteed premium schedule, from
Data.premium_schedule: its row ofData.premium_rates_array.Datajoins it by the point’s plan, sex, rate class and band, the keyTerm_US_Slooks the premium up by. It is 0 where premium_rates.csv has no schedule for that key, a schedule whose extent holds no policy year.
AP of policy year y, read from the point’s schedule of
premium_rates.csv.The schedule is keyed by the contractual, 1-based policy year, so this is the cell that reads it, for any year the contract has:
premium_pp_ann()atpolicy_year(t), andjump_ratio()at policy yearsnandn + 1, which need not fall in the frame: the point in force 126 months is in yearn + 1at the valuation date, with yearnbehind it.It is the one cell that reads
Data.premium_rates_array, at[premium_schedule(), y], and it checks the year against both ends of the schedule first,Data.premium_first_yearandData.premium_last_year. A year outside them raisesValueError, naming the point and the year, whereTerm_US_S’s lookup raisedKeyError, rather than reading the array’s padding.
The premium per policy actually due at the beginning of month t.
modal_factor() * AP(t)in a payment month, zero otherwise.
- jump_ratio()[source]#
Initial premium jump ratio, fee included: the first ART annualized premium over the last level one,
premium_pp_ann_py(n + 1) / premium_pp_ann_py(n).Policy years n + 1 and n, read by policy year.
Term_US_Sreads them at months12nand12n - 1, which are those years only on a policy issued att = 0.
- plt_mort_factor_init_formula()[source]#
The notes’ rule for M(1): min(8.0, 1 + 0.55*(J-1)) [std].
Returns 3.4514 for the anchor cell, where the worked example uses 3.50. Not used unless the model point leaves plt_mort_factor_override blank. Written with the bound second,
min(1.0 + 0.55 * (J - 1.0), 8.0), asmort_rate()writes its cap, so that a NaN jump ratio gives NaN rather than 8.0; whereverJis a number it is the notes’ value.
- plt_mort_factor_init()[source]#
M(1) actually used: the model point’s override if given, else the formula.
Data.has_plt_mort_factor_overridesays whether the point gives one, andData.plt_mort_factor_overrideholds it. A blank is the flag’s 0, beside a 0.0, so no NaN reaches this formula and none is tested for here.
- plt_mort_factor(d)[source]#
Post-level-term mortality deterioration at PLT duration d; grades to 2.00 [std].
dis the notes’ PLT duration in years,d = policy_year(t) - n:d = 1in the first post-level-term policy year (duration_mth(t) = 12n .. 12n + 11). It is neither the frame indextnor a policy month.The floor is written second,
max(M(1) - 0.15 * (d - 1), 2.0), asmort_rate()writes its cap, so that a NaN M(1) gives NaN rather than 2.0; wherever M(1) is a number it is the notes’ value.
- class_factor()[source]#
Underwriting-class multiplier on the base mortality table [std].
From
Data.class_factor, which joins the point’s class to class_factor_table.csv.
- mort_rate_base(t)[source]#
Base-table annual mortality rate at the attained age in month t,
age(t).Zero outside cover, where
age(t)is not an age the policy reaches in force. Inside it, this is the one cell that readsData.mort_table_array, which is indexed by the age itself. An age outside the table’s,Data.mort_age_firsttoData.mort_age_last, raisesValueError, naming the point and the age, whereTerm_US_S’s lookup raisedKeyError, rather than reading the array’s padding.
- mort_rate(t)[source]#
The annual mortality rate of the policy year containing month t, at most 1.
Base x class factor x PLT deterioration, capped at 1, as
Term_US_Scaps it,min(q, 1.0): the product first, the float bound second.minkeeps its first argument unless a later one compares smaller, in Python and in the compiled cell alike, and no comparison with NaN holds, somin(1.0, q)would be 1.0 whereqis NaN, a blank input read as certain death, silently.min(q, 1.0)is NaN there, and whereverqis a number it is the floatmin(1.0, q)is, 1.0 included.Datarefuses a blank, text or infinite value wherever the product reads one, so that none reaches it. The PLT duration isd = policy_year(t) - n, so the multiplier applies fromduration_mth(t) = 12n(d = 1) on.mort_rate_mth()is the rate actually applied in the month.Past 1 the monthly rate,
1 - (1 - q)^(1/12), has no real value. At 1 it is 1, and every policy in force at the start of the month dies in it. On the shipped mortality and class tables the product passes 1 only after the level period. At the issue agesproduct-spec.mdadmits, it first does so, at the lowest M(1), in the tobacco class on the twenty-year plan issued at 65, its oldest tobacco issue age: at attained age 94, once M(1) passes 5.9152, which the notes’ rule gives at a jump ratio past 9.9367. There a non-tobacco class needs an M(1) above 8, the most the rule gives, so an override. The model does not refuse an older issue age. Where the first PLT year falls at attained age 94, as on the ten-year plan issued at 84, the product passes 1 there once M(1) passes 4.5652 in the tobacco class and 7.9891 in the standard non-tobacco class, the least M(1) that does so on any point the model projects.
- mort_rate_mth(t)[source]#
q_m(t): the monthly mortality rate applied in month t [std].
1 - (1 - q)^(1/12)on the policy year’s annual rate, so twelve months of it compound back to exactly that rate — the notes’ own conversion.
- shock_lapse_rate()[source]#
Shock lapse at the end of the level period, by jump-ratio bucket [std].
The rate of the first bucket of shock_lapse_table.csv, in the table’s order, whose range
jump_lo < J <= jump_hiholds the jump ratio, and the last bucket’s where none does, asTerm_US_Sreads the table: a loop overData’s three bucket vectors, which runs once for a point.
- lapse_rate(t)[source]#
The annual lapse rate of the policy year containing month t [std].
The notes’
wvector, keyed byduration(t). Level period (duration = 0 .. n-1): 6% in policy year 1, 5% in year 2, 4% in years 3..n-2, 6% anticipatory in year n-1, and the shock in year n. Post-level term: 30%, 15%, then 10% by PLT durationd = policy_year(t) - n.lapse_rate_mth()is the rate actually applied in the month, and it treats the shock year specially — see there.
- lapse_rate_mth(t)[source]#
w_m(t): the lapse rate applied at the end of month t [std].
1 - (1 - w)^(1/12)on the policy year’s annual rate in every month except those of the final level-period year. The notes are explicit that the shock is not spread: that year’s annual rate is the shock, so it falls in full at the end of the final level-period month, the month withduration_mth(t) = 12n - 1— immediately before the first ART premium is due at12n— and the other eleven months of the year carry no ordinary lapse at all.
- conv_elig(t)[source]#
True while convertible: inside cover, within the level period, attained age below 70.
conv_elig_py(policy_year(t))for a month inside cover, False outside it.
- conv_elig_py(y)[source]#
Whether policy year y lies in the conversion window.
Within the level period,
y <= n, and at an attained age below 70,age_at_entry() + y - 1 < 70: the window ends atmin(end of level period, attained age 70). Keyed by policy year, so thatconv_rate()can ask about the year after month t’s without reading a month of the frame twelve months ahead.
- conv_rate(t)[source]#
The annual conversion rate of the policy year containing month t [std].
Zero outside the eligibility window;
conv_rate_finalin the last eligible policy year, the one whose successor is outside the window, andconv_rate_basebefore it. Both ship at 0, as the worked example requires.
- conv_rate_mth(t)[source]#
cv_m(t): the monthly conversion rate applied at the end of month t [std].
1 - (1 - cv)^(1/12)on the policy year’s annual rate, the same conversion the other voluntary decrement takes.
- phase(t)[source]#
The phase of month t, as a code: PRE_ISSUE, LEVEL (
duration < n), PLT (to expiry) or EXPIRED, the int References of the Space docstring’s Codes.On the policy clock:
PRE_ISSUEwhileduration_mth(t) < 0, the months before a future point is issued, andEXPIREDfromduration_mth(t) = expiry_mth()on, which ist = proj_len().
- pols_if(t)[source]#
Number of policies in force at time t, the count that weights row t.
pols_if_at(t, BEF_DECR): the count carried in from month t - 1, plus month t’s new business, before month t’s decrements. On a point issued att = 0that is exactlyTerm_US_S’spols_if, the count at the start of the month. It isbasiclife.BasicTerm_SE’sBEF_DECRcount, not itspols_if, which is the count before maturity. Zero outside cover: before issue, and fromt = proj_len()on, when coverage has expired at attained age 95.
- pols_if_at(t, timing)[source]#
Number of policies in force at time t, at the instant
timingnames.BEF_NBThe count carried in from month t - 1, before month t’s new business: the survivors of month t - 1’s deaths, conversions and lapses, out of month t - 1’s
BEF_DECRcount. Att_entry(), the first month on the books, it ispols_if_init(), the count in force at the valuation date (0 for a point issued at or after it), and the recursion reads no earlier month. Zero outside cover, so the survivors of the last covered month leave aspols_maturity().BEF_DECRBEF_NBpluspols_new_biz(): the count that weights month t, whichpols_if()returns.
These are
basiclife.BasicTerm_SE’s names, as int References, 0 and 1 (the Space docstring’s Codes). Its"BEF_MAT"is not adopted: here the policies expire at the end of the last covered month, asTerm_US_Shas it, and any timing but these two raises.BEF_NBforms month t - 1’sBEF_DECRcount itself, asBEF_NBpluspols_new_biz()at t - 1, the same sum in the same order, rather than calling for it. So the chain of calls from month t back tot_entry()is one cell a month, as deep asTerm_US_S’spols_ifchain and no deeper: a compiled model runs that chain on the C stack.
- pols_new_biz(t)[source]#
Number of policies issued in month t:
policy_count()in the issue month.The issue month is the one with
duration_mth(t) == 0:t = 0for a point issued at the valuation date,t = kfor one issuedkmonths later. A point already in force at the valuation date has none.
- pols_surv(t)[source]#
Number of policies surviving to the end of month t, before voluntary decrements.
Zero outside cover.
- pols_lapse(t)[source]#
Number of lapses at the end of month t, including the shock in the month with
duration_mth(t) = 12n - 1; zero outside cover.
- pols_maturity(t)[source]#
Number of policies whose coverage ends at attained age 95.
Non-zero only in the last covered month,
duration_mth(t) = expiry_mth() - 1, which is the frame’s last row,t = proj_len() - 1. Not a decrement - the contract runs out - but needed for the in-force roll-forward to close; see the Space docstring.
- comm_rate(t)[source]#
Commission rate [std]: 80% in policy year 1 (
duration(t) == 0), 5% to the end of the level period, 2% after. It is a rate on the premium collected, so a modal payer pays it in instalments too.Zero outside cover, where the month has no policy year: before issue
duration(t)is negative, which the scale would otherwise read as a level-period year.
- inflation_factor(t)[source]#
The expense inflation factor in month t,
(1 + inflation_rate) ** (t / 12).On the valuation clock:
tcounts months from the valuation date, so the maintenance charge it inflates is in valuation-date dollars, whatever the policy’s age, and every point of a block inflates alike.Term_US_Sinflates from issue; on a point issued att = 0the two are the same. Acquisition is not inflated (seeexpenses()). Compounded on the monthly grid rather than stepped at anniversaries: on an annual model the factor can only move once a year, and the monthly refinement is one of the things the finer grid buys.
Premium income in month t, at the beginning of the month.
Premium tax in month t [std].
- expenses(t)[source]#
Acquisition on new business and inflating maintenance expenses in month t [std].
Acquisition is
expense_acqper policy issued,expense_acq * pols_new_biz(t): in the issue month, never for a point already in force at the valuation date, and not inflated, as inbasiclife.BasicTerm_SE, so a policy written after the valuation date costsexpense_acqin the dollars of its issue month.Term_US_Scharges it once, att = 0, whatever the count. One twelfth of the annual maintenance charge accrues each month, inflated on the valuation clock, so a policy that runs a full year carries the same charge as it did on the annual grid — but it is now borne by the in-force of each month rather than of the anniversary, which is what makes a decrementing block cost less.
- claims(t)[source]#
Death claims incurred in month t, paid at the end of the month.
Face amount only: the notes’ simplification (i) — the pro-rata unearned-premium refund and the due-unpaid-premium deduction on death [S6] are not modelled. On the monthly grid the item is bounded by one modal premium, so it is immaterial by construction for a monthly payer and at most one annual premium on the deceased cohort for an annual one.
- conv_credits(t)[source]#
Conversion credit outflow: one annualized premium per conversion, after the first policy year (
duration(t) >= 1). The credit is contractual and stated on the annual premium [S6], so it does not move with the premium mode.
- result_cf()[source]#
Result table of cashflows, one row per month
t = 0 .. proj_len() - 1.Row 0 is the valuation month for every model point, so the frames of a block line up and sum row by row. A point issued after the valuation date has zeros until its issue month. The columns are
Term_US_S’s.
- result_cf_annual()[source]#
result_cf()summed into policy years, indexed bypolicy_year.Every cash flow column is the total of the year’s months in the frame, and
pols_ifis the count in its first month in the frame. The months before issue belong to no policy year and are left out. On a point issued att = 0every year is whole,pols_ifis the count entering it, and the table isTerm_US_S’s. A point in force at the valuation date may open part-way through a policy year, as the point in force 126 months does; its first row then holds the rest of that year only, and itspols_ifis the count at the valuation date. On an anniversary, as at 12 months, the first row is a whole year.On the shipped annual-mode points, in every policy year the frame holds whole, the two grids agree exactly on five columns —
pols_if,premiums,commissions,premium_taxesandconv_credits— because an annual premium is collected on the anniversary and weighted by the anniversary in force under either grid, and the other three are rates on it. They do not agree onclaimsorexpenses, which now fall where they happen rather than at the anniversary, and so not onnet_cf. That gap is the point of the finer grid — see the Space docstring.
- result_pols()[source]#
The policy counts, one row per month
t = 0 .. proj_len() - 1.The counts
result_cf()weights its rows by, and how they move, asbasiclife.BasicTerm_SE’sresult_polssets them out:pols_if, the count of month t;pols_new_biz, the part of it issued in month t; then month t’s deaths, conversions and lapses in processing order, and the expiries of the last covered month. Row by row,pols_ifatt + 1ispols_ifless the four outflows of month t, plus the new business of montht + 1.