The Projection Space

The by-policy projection of the Annuity_JP_A model.

The Space is parameterized by point_id, so Projection[1] is an ItemSpace projecting model point 1:

>>> Projection[1].result_cf()          # the worked example's anchor cell
>>> Projection.point_id = 4            # or switch the default

t counts completed policy years since issue, 0-based, matching the technical notes and product-spec.md. Premiums fall at t = 0 .. m - 1; the 保険料積立金 accumulates over t = 0 .. n where n = m + d; the annuity is paid at t = n .. n + k - 1; and proj_len() is n + k on the 確定年金 form. pols_if(t) is the in-force count at the start of year t and is the weight on that same result_cf() row.

Input data

Inputs are external files: plain CSVs living in the model folder’s parent directory, products/individual_annuity/, 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.

The consequence worth knowing: the model is not portable on its own. Copying the Annuity_JP_A folder without its parent’s CSVs produces a model that reads and then fails on first evaluation.

Each table has a filename Reference and a reader Cells, both on Data, reached here through the data Reference:

Reference	Cells	File
model_point_file	data.model_point_table()	model_point_table.csv
mort_table_file	data.mort_table()	mort_table.csv
mort_anchor_file	data.mort_anchor_table()	mort_anchor_table.csv
lapse_table_file	data.lapse_table()	lapse_table.csv
pricing_table_file	data.pricing_table()	pricing_table.csv
expense_table_file	data.expense_table()	expense_table.csv
commute_factor_file	data.commute_factor_table()	commute_factor_table.csv

Naming

Cells names follow lifelib wherever it has an analogue — pols_* for policy counts, plural nouns for cash flows, *_rate for rates, *_pp for per-policy amounts, claims(t, kind) with an uppercase kind string, pols_if_at(t, timing) and av_pp_at(t, timing) for the within-year reads. The technical notes use compact actuarial symbols instead. The mapping is:

Notes symbol	Cells	Meaning
(model point row)	model_point()	The selected model point
x	issue_age()	契約年齢 (保険年齢) at issue
x + t	age(t)	Attained age in year t
(none)	sex()	Rating factor, M or F
m	premium_term_y()	保険料払込期間 in years
d	defer_gap_y()	据置期間 in years
n = m + d	annuitisation_t()	Policy year of the 年金支払開始日
(none)	annuity_start_age()	保険年齢 at the 年金支払開始日
k	payout_term_y()	確定年金 payment period in years
g	guar_term_y()	Guarantee period, life form only
t = 0..proj_len-1	proj_len()	Projection horizon in years
P	premium_pp()	Level office annual premium
rho	db_ratio()	Death benefit / cumulative premiums
i_d	int_rate_defer()	予定利率, deferral
i_p	int_rate_payout()	予定利率, payout
beta	expense_loading()	予定事業費率 on premium
theta	annuitisation_charge()	年金支払開始時費用 on the 年金原資
NP(t)	prem_to_av_pp(t)	Net premium credited to the fund
q’(x+t)	mort_rate_pricing(t)	予定死亡率, fund recursion only
q(t)	mort_rate(t)	Best-estimate rate applied in year t
(table)	mort_rate_base(t)	Table rate before the [std] factor
q(x) by age	mort_rate_at_age(table, x)	Table lookup keyed by attained age
(0.85 / 1.10)	mort_be_factor(t)	Best-estimate factor, by phase
w(t)	lapse_rate(t)	解約・失効 rate applied in year t
(table)	lapse_rate_base(t)	Table lapse rate, before dynamics
M(t)	lapse_dyn_factor(t)	Dynamic-lapse multiplier
V(t)	av_pp(t)	保険料積立金 at the start of year t
(within year)	av_pp_at(t, timing)	BEF_PREM / AFT_PREM / AFT_INT
SC(t)	surr_charge_pp(t)	解約控除 at time t
DB(t)	db_pp(t)	死亡給付金 for a death in year t-1
(net of loans)	db_pp_net(t)	死亡給付金 less any loan balance
CV(t)	cv_pp(t)	解約返戻金 at time t
(net of loans)	cv_pp_net(t)	解約返戻金 less any loan balance
F = V(n)	annuity_fund_pp()	年金原資
adue(k, i_p)	annuity_due_factor()	Annuity-due factor, certain form
adue_life(g, i_p)	annuity_due_life_factor()	Guaranteed-plus-life factor
B	annuity_amount_pp()	基本年金額, struck once at t = n
B x 1{n<=t<n+k}	annuity_pp(t)	Instalment payable at the start of t
(factor table)	commute_factor(j)	年金の一括払 factor, j instalments left
(lump sum)	commute_value_pp()	Commuted value per contract
(dividend)	div_credit_pp(t)	契約者配当 declared in year t
(dividend)	div_acc_pp(t)	Accumulated 契約者配当 at time t
l(t)	pols_if(t)	Contracts with an obligation open
l(t)(1-q), l(t+1)	pols_if_at(t, timing)	BEF_DECR / BEF_LAPSE / AFT_DECR
L(t)	lives_if(t)	Probability the annuitant is alive
D(t)	pols_death(t)	Expected deaths in year t
W(t)	pols_lapse(t)	Expected lapses at the end of year t
(none)	pols_commute(t)	Contracts electing 年金の一括払
(none)	pols_maturity(t)	Contracts whose last instalment is paid
(APL)	apl_bal(t)	自動振替貸付 balance per policy
(APL)	apl_engaged(t)	Whether the APL is carrying the premium
(loan)	loan_pp(t)	契約者貸付 balance per policy
P x l(t)	premiums(t)	Premium income
DB, CV, B, lump	claims(t, kind)	Benefit outgo by kind
ec x D(t)	claim_expenses(t)	Claim expense, its own column
E0, e(t)	expenses(t)	Acquisition + maintenance
(none)	inflation_factor(t)	Expense inflation factor
c0, c_r	commissions(t)	Commission outgo
(loan advance)	policy_loans(t)	契約者貸付 advanced, an outflow
CF(t)	net_cf(t)	Net cash flow, income positive

Three names needed care.

av_pp and cv_pp are not the same quantity and the difference is the product. av_pp is the 保険料積立金, which grows past cumulative premiums on the survivorship release; cv_pp is the 解約返戻金, which is capped at the 死亡給付金 and therefore at cumulative premiums. Clipping av_pp instead of cv_pp destroys the 年金原資, because it is the un-clipped excess of the fund over the death benefit that buys the annuity. The library’s naming ruling puts the surrender quantity under cv_pp, and this model keeps both.

pols_if and lives_if are two different in-force measures, following SPIA_US_S. pols_if counts contracts with an obligation open; lives_if counts annuitants alive. In the deferral phase they separate because lapse removes a contract without removing a life. In the payout phase they separate for the opposite reason: on a 確定年金 the instalments are unconditional, so pols_if is flat through the certain period while lives_if runs down on the payout table. Collapsing the two is the single most likely way to build this product wrongly.

mort_rate_pricing is the 予定死亡率 used only inside the fund recursion, at 100% of the death-cover table. mort_rate is the best-estimate decrement applied to the in-force. They are different numbers in every year, because av_pp is a contractual quantity and not an experience projection — and where actual mortality runs lighter than q' the insurer credits more survivorship than it earns and takes a 死差損, so the mortality sensitivity is signed the opposite way round from a death-cover product.

Two mortality tables, with the margin running opposite ways

The deferral phase reads 生保標準生命表2018（死亡保険用）and the payout phase 生保標準生命表2007（年金開始後用）— expressly not updated in 2018 — and mort_table_name() switches between them at t = n. Both are valuation tables, so neither is a best-estimate basis, and the adjustment to them reverses sign at the same date: the death-cover table carries a prudential margin against death, so a best-estimate basis is 0.85 of it; the payout table carries a prudential margin against longevity, so a best-estimate basis is 1.10 of it. mort_be_factor() is the one place that sign lives. A model applying one factor to both tables has one of the two wrong.

Neither table is shipped. Both are [std] constructions anchored to quoted spot rates: 死亡保険用 is the canonical library-wide file, graduated log-linearly in ln q between its sourced anchors, and 年金開始後用 is a Makeham law fitted to three of them. See the Data docstring, and check_mort_graduation(), which asserts that the shipped rates are still the ones the graduation produces.

Modules that are off in the base run

Six of the notes’ optional constructions are implemented and switched off at the anchor cell, so that the base run reproduces the worked example while the machinery stays visible and testable. Each is a model point column, so a non-anchor point exercises it:

• 保証期間付終身年金, payout_form = "life_guar": instalments unconditional for g years and life-contingent after, priced on annuity_due_life_factor() at 100% of the payout table, with proj_len() running to that table’s terminal age. Held at the issue basis [std] — the election is really priced on the 基礎率 in force at the 年金支払開始日, which no model can know, and that is why base-run take-up is zero. Model points 4 and 9, the second being the anchor cell with nothing changed but the payout form: the life form with g = 10 gives B = ¥281,300 against ¥638,100 on the certain form out of the same 年金原資, because the annuity-due factor is 22.032668 against 9.714338.

• 年金の一括払, commute_rate: the published factor table verbatim over 1-14 remaining instalments and an implied 0.40% p.a. outside it [std]. Model point 5. Base take-up is zero for an arithmetic reason: at t = n the factor for ten remaining instalments returns about 1.10% more than the gross 年金原資, because the factors come from one carrier and the payout 予定利率 from another and the composite does not reconcile them. Switching it on switches on a composite artefact, not a product feature.

• 自動振替貸付, apl_on: while the 解約返戻金 can carry the outstanding balance plus one more premium, the lapse decrement is suppressed and the insurer lends the premium at the contractual cap of 8% p.a.; the balance compounds and is deducted from the 死亡給付金 and from the 年金原資. It is not a no-lapse rule — the moment principal and interest outgrow the surrender value the contract lapses. Model point 7, where it engages at t = 2, carries the contract for six years and then terminates it at t = 8. One carrier’s product has no such facility at all.

• 契約者貸付, loan_on: a loan of half the 解約返戻金 drawn at policy year 20 [std], compounding at 2.40% p.a. and capped at the 解約返戻金, deducted from the 死亡給付金 and from the 年金原資. Model point 8.

• 契約者配当, div_rate: zero declared in the base run, machinery retained. A declared rate credits div_credit_pp() on the fund each year, accumulates it at the 配当積立利率 and applies it at t = n as a single premium increasing the 基本年金額. Under the 税制適格特約 it may never be paid in cash before annuitisation. Model point 8.

• Dynamic lapse, rate_new: M(t) = min(2, max(1, 1 + phi max(0, i_new - i_d))) with phi = 20 [std]. Premiums and the 予定利率 are fixed at issue, so there is no premium-shock lapse on this chassis; the driver runs the other way, a rise in new-business 予定利率 making an in-force contract relatively unattractive. Model point 8.

減額, 払済 and 復活 are not implemented [std scope]. On an annual grid a premium unpaid at t terminates the contract at t: there is no partial-year 払込猶予期間 state and no reinstatement re-entry, so this model’s lapse_rate is a net-of-復活 rate by construction and a user substituting a gross experience rate will over-decrement.

Sign convention

The notes’ CF(t) is already income positive, which is the library-wide sign of net_cf(), so there is no liability_cf companion to publish here — that absence is a fact about which orientation the notes chose, not an omission. A reader comparing the payout years with SPIA_US_S, whose notes print outgo-positive, must flip the sign: this model’s payout rows are large negatives.

The absences are product facts

There is no premium income after 払込満了 and none at all once the annuity is in payment; there is no lapse decrement and no surrender value from t = n - 1, because surrender is unavailable from the 年金支払開始日; and there is no maturity benefit, because the contract does not mature — it annuitises. Each of those is stated in a formula rather than left to inference.

Cells Descriptions

model_point()

The selected model point as a Series.

sex()

The annuitant’s sex, M or F; a rating factor on both mortality tables.

issue_age()

x: the 契約年齢 at issue, on 保険年齢 (age nearest birthday) [REG-R20].

The basis 標準生命表2018 is built for. A model ageing its points on 満年齢 must say so and say what it does about the half-year difference; this one does not.

premium_term_y()

m: the 保険料払込期間 in years; at least ten under the 税制適格特約 [R10].

defer_gap_y()

d: the 据置期間 in years, between 払込満了 and the 年金支払開始日 [S6].

Zero is a valid model point and a different product; 払込満了 and 年金支払開始日 are different dates and collapsing them moves the 年金原資 by several per cent.

annuity_start_age()

The 保険年齢 at the 年金支払開始日; at least 60 under the 税制適格特約 [R10].

Derived rather than free: it must equal x + m + d, and the model rejects a model point where it does not, because two spellings of one date is how a projection silently annuitises on the wrong year.

premium_pp()

P: the level office annual premium, guaranteed for the whole 保険料払込期間.

There is no review right [S2] [S4] [S5] [S6], so the insurer has no unilateral repricing lever and all m premiums are inside the contract boundary.

payout_form()

The annuity form: certain (確定年金) or life_guar (保証期間付終身年金).

The base form is 確定年金 chosen at issue, whose 基本年金額 is struck once at t = n from the issue basis [S2] [S3]. The life form is an election priced on the 基礎率 in force at the 年金支払開始日 [S2] [S9]; holding it at the issue basis is a [std] assumption and the reason base-run take-up is zero.

payout_term_y()

k: the 確定年金 payment period in years; 10 or 15 under the 税制適格特約 [R10] [R16].

guar_term_y()

g: the guarantee period of the 保証期間付終身年金 form, in years [S4] [R16].

db_ratio()

rho: the 死亡給付金 as a multiple of cumulative premiums paid.

1.00 on the composite and 0.70 on both retrieved tontine designs [S3] [S10]. It sits on the model point rather than in a code branch because a tontine is the same chassis with a different death-benefit ratio under the same surrender ceiling.

tax_rider()

Whether the 税制適格特約 is attached [S1] [R10].

It constrains the contract rather than the cash flows — ten years of premiums, a start age of 60 or more, a payment period of ten years or more, no cash refund of a 減額 — so it validates the model point and then does nothing else here.

apl_on()

Whether the 自動振替貸付 module is switched on; false in the base run [S4] [REG-R14].

loan_on()

Whether the 契約者貸付 module is switched on; false in the base run [S4] [S11].

commute_rate()

The proportion electing 年金の一括払 at the 年金支払開始日 [std]; 0 in the base run.

Commutation is available from the 年金支払開始日 to the last 年金支払日 [S2] [S4]; the model offers the election at t = n only [std], which is where the published factor table is richest and where the arithmetic against the 年金原資 is checkable.

div_rate()

The declared 契約者配当 rate on the fund [std]; zero in the base run [S4] [S11].

Zero declared is a choice, not a product fact: the machinery is contractual, and under the 税制適格特約 the accumulated dividend may never be withdrawn before annuitisation and must be applied as a single premium increasing the 基本年金額 [S1] [S2] [R10].

rate_new()

i_new: the new-business 予定利率 the dynamic-lapse module compares against [S8].

Flat over the projection on the shipped points. Equal to int_rate_defer() in the base run, which makes lapse_dyn_factor() exactly 1.

annuitisation_t()

n = m + d: the policy year of the 年金支払開始日.

The join between the two contracts this product really is. Everything switches here: the mortality table, the sign of the best-estimate factor, the availability of surrender, and the direction of the cash flow.

Read off annuity_start_age() rather than summed from m and d directly, which is the same number — that cells raises unless the model point’s 年金支払開始日 equals x + m + d — but puts the consistency check on the path every projection takes. Reached only through tax_rider(), it would validate the base form’s model points never, and two spellings of one date is how a projection silently annuitises on the wrong year.

proj_len()

The projection horizon in policy years; result_cf() runs t = 0 .. proj_len - 1.

n + k on the 確定年金 form: there are no tail states, because the 確定年金 pays exactly k instalments and the contract ends [S2] [S4]. On the 保証期間付終身年金 form the horizon is instead the terminal age of the 年金開始後用 table — 122 for a male and 126 for a female [R3] [REG-R19] — because a life annuity has no other natural end.

age(t)

The attained 保険年齢 at the start of policy year t: x + t.

pricing_basis(item)

One row of the pricing and module basis table, as a float.

A single lookup helper so that every basis item is read the same way and every one of them carries a provenance tag in the CSV rather than sitting as an untagged constant in a formula.

expense_basis(item)

One row of the best-estimate cash expense and commission table, as a float.

int_rate_defer()

i_d: the deferral-phase 予定利率, 1.00% p.a., fixed at issue [S8].

int_rate_payout()

i_p: the payout-phase 予定利率, 0.65% p.a., set separately from i_d [S5].

Since i_p < i_d, each yen of 年金原資 buys less annuity than a single-rate model would say. Using the deferral rate to buy the annuity overstates the 基本年金額 by about 1.55% at k = 10.

expense_loading()

beta: the 予定事業費率 on each office premium, 6.5% [std].

One loading, not a three-way 新契約費 / 維持費 / 集金費 split: no retrieved document discloses one, the 算出方法書 is a 基礎書類 filed with the FSA and not published [REG-R2], and inventing a split no source can confirm is worth less than one round number calibrated against a published specimen [S6].

annuitisation_charge()

theta: the 年金支払開始時費用, 1.0% of the 年金原資, charged once [std, new here].

mort_table_name(t)

Which mortality table applies in policy year t.

death_cover_2018 in the deferral phase and annuity_payout_2007 from t = n. For contracts concluded from 2018-04-01 the standard valuation basis is 生保標準生命表2018（死亡保険用）for death cover and 生保標準生命表2007（年金開始後用）for annuities in payment [REG-R10] [REG-R11] [R4]. An annuity computed off the death-cover table is wrong by construction and wrong in the expensive direction.

mort_be_factor(t)

The best-estimate adjustment to the valuation table in policy year t.

0.85 in the deferral phase and 1.10 from t = n [std, new here]. Both tables are valuation bases carrying a prudential margin, and the margin runs opposite ways: against death before annuitisation, against longevity after it. 0.85 sits inside the range the death-cover margin implies, from 1/1.30 where the 130% cap binds to 1.00 where no margin does [REG-R20]; the 作成概要 for the 2007 table was not retrieved, so the size of 1.10 is [unverified] and only its direction is structural.

omega_age(table)

The terminal age of a shipped mortality table: 109 / 113 and 122 / 126.

Read from data.mort_anchor_table(), where it is a published fact about the real table rather than a property of the construction [REG-R18] [R3] [REG-R19]. q is truncated to 1 there.

mort_rate_at_age(table, x)

The shipped [std] rate of table at attained age x, truncated to 1 at omega.

The single point at which the model touches its mortality input, so a licensed table drops in by replacing mort_table.csv with a same-schema file.

mort_rate_base(t)

The table rate applying in policy year t, before the best-estimate factor.

mort_rate_pricing(t)

q’(x+t): the 予定死亡率, 100% of the 死亡保険用 table, used only in the fund.

av_pp is a contractual quantity and not an experience projection, so its survivorship release is credited at the pricing rate whatever the best-estimate basis says. Where actual mortality runs lighter than q', the insurer credits more survivorship than it earns and takes a 死差損.

mort_rate(t)

q(t): the best-estimate mortality rate applied to the in-force in policy year t.

The table rate of the phase times mort_be_factor(), capped at 1. Two tables, two factors, and the factors point opposite ways; see the Space docstring.

lapse_rate_base(t)

The [std] table 解約・失効 rate in policy year t, before any dynamic multiplier.

6.0 / 5.0 / 4.5 / 4.0 percent over the first ten policy years, 3.0% for the rest of the 保険料払込期間, 1.0% through the 据置期間 — no premium is due there, so the commonest lapse trigger is absent — and zero from t = n - 1, because that year ends on the 年金支払開始日 where surrender is no longer available [S2] [S4]. The only public calibration point is a market-wide 3.4% for FY2024 whose denominator is 契約高, not policy count [R15] [REG-R31]; the duration shape is a standardization.

lapse_dyn_factor(t)

M(t): the dynamic-lapse multiplier [std]; 1 in the base run.

min(cap, max(1, 1 + phi max(0, i_new(t) - i_d))) with phi = 20 and a cap of 2. Premiums and the 予定利率 are both fixed at issue, so there is no premium-shock lapse and no rate-driven surrender on this chassis. The economic driver runs the other way: when new-business 予定利率 rise above the rate at issue — as they did in 2025, for the first time in about forty years [S8] — an in-force contract becomes relatively unattractive and lapse should rise.

lapse_rate(t)

w(t): the annual 解約・失効 rate applied at the end of policy year t.

The table rate times the dynamic multiplier, capped at 1 — except where the 自動振替貸付 module is carrying the contract, which suppresses the decrement entirely, and except in the year that module can no longer carry it, where the whole in-force lapses [S4] [REG-R14]. Zero from t = n - 1 in every case.

prem_to_av_pp(t)

NP(t): the office premium net of the 予定事業費率, credited to the fund.

P (1 - beta) while t < m and zero after. Credited whether or not the premium arrives in cash: under the 自動振替貸付 module the insurer lends it, so the fund is fed and the loan balance grows instead.

av_pp(t)

V(t): the 保険料積立金 per policy at the start of year t, before that year’s premium.

A net-level-premium accumulation carrying a survivorship release:

V(0)   = 0
V(t+1) = [ (V(t) + NP(t)) (1 + i_d) - q'(x+t) DB(t+1) ] / (1 - q'(x+t))

The division by (1 - q') is the release: the premiums of those who die go to the survivors net of the death benefit paid. Because DB is capped at cumulative premiums while V is not, that release turns positive from the duration at which V first exceeds DB, and that excess is precisely the survival benefit a 生存保障重視型 design buys. Lapse does not appear: the surrender release is the 解約控除, which accrues to the insurer and not to the surviving fund. Zero after annuitisation, where the fund has been converted into the annuity and the liability is the instalment stream instead.

av_pp_at(t, timing)

The 保険料積立金 per policy at a point inside policy year t.

"BEF_PREM"

V(t), the start of the year before the premium is credited; the same number as av_pp().

"AFT_PREM"

after the year’s net premium is credited, before interest.

"AFT_INT"

after the 予定利率 is credited, before the survivorship release and the death benefit are settled.

db_pp(t)

DB(t): the 死亡給付金 payable for a death in year t - 1, paid at t.

rho P min(t, m) — the annual-grid form of the contractual 月払保険料 x 経過月数 [S2] [S4], which 所令211①ロ requires to increase with duration or with cumulative premiums [R10]. It stops growing at 払込満了, because no further premium is paid: a model that keeps accruing it to n overstates deferral-phase claims by d years’ worth of premium.

db_pp_net(t)

The 死亡給付金 actually paid: db_pp() less any loan principal and interest.

Unpaid premiums, 契約者貸付 and 自動振替貸付 balances are deducted from the benefit [S2] [S4]. Equal to db_pp() in the base run, where both loan modules are off.

surr_charge_pp(t)

SC(t): the 解約控除 at time t [std].

One annual premium running off linearly over ten policy years. Both 約款 state the shape and not the parameters — 「ご契約後短期間で解約されたときには、解約返還金がない場合があります」 [S2] and 「まったくないか、あってもごくわずか」 [S4] — and the formula sits in the unpublished 算出方法書 [REG-R2]. The base amount of one annual premium is what makes the sourced invariant hold: the first-year 解約返戻金 is nil-or-negligible against a full year’s premium.

cv_pp(t)

CV(t): the 解約返戻金 per policy at time t.

min(max(0, V(t) - SC(t)), DB(t)) before annuitisation and zero from t = n, because surrender is not available from the 年金支払開始日 [S2] [S4] [R16]. The upper cap is the sourced ceiling 「解約返還金は…死亡給付金の額を限度とします」 [S2], and it is what the other carrier means by 「一定期間経過後は死亡給付金と同額になります」 [S4]: beyond the crossover the surrender value and the death benefit are literally the same number.

That cap also reverses the sign of the late-duration lapse sensitivity. From the crossover a surrender returns exactly what was paid in and no interest, while the fund behind it is worth more, so late-duration lapse is profitable to the insurer and a prudent reserving basis loads it down, not up.

cv_pp_net(t)

The 解約返戻金 actually paid on surrender: cv_pp() less any loan balance.

Equal to cv_pp() in the base run, where both loan modules are off.

apl_engaged(t)

Whether the 自動振替貸付 is carrying the premium in policy year t; false in the base run.

True while the module is on, a premium is still due, the 解約返戻金 is at least one premium, and the outstanding balance has not yet outgrown the 解約返戻金 [S4]. That last condition is the whole point: 自動振替貸付 is a policyholder election, not a no-lapse rule [REG-R14], and one carrier’s product does not offer it at all [S2].

apl_bal(t)

The 自動振替貸付 principal and interest per policy at time t; zero in the base run.

Each premium the module lends is added to the balance and the whole compounds at the contractual cap of 8% p.a. [S4], adopted at the cap [std]. 8% against a surrender value that is itself capped at cumulative premiums is why the facility carries a contract for a few years and not for a term: the moment principal and interest outgrow the 解約返戻金 the contract lapses [S4], which is what lapse_rate() does with it.

loan_pp(t)

The 契約者貸付 principal and interest per policy at time t; zero in the base run.

A loan of half the 解約返戻金 drawn at policy year 20 [std], compounding at 2.40% p.a. on the current issue cohort [S11] [S8] and capped at the 解約返戻金 [S4] [REG-R14]. Deducted from the 死亡給付金 and from the 年金原資, so it does not touch av_pp(): the fund is a contractual accumulation and the loan is a separate account against it.

policy_loans(t)

The 契約者貸付 advanced in policy year t, an outflow; zero in the base run.

Only the drawdown is a cash flow. The balance is recovered by deduction from the 死亡給付金, the 解約返戻金 or the 年金原資, which is where db_pp_net(), cv_pp_net() and annuity_fund_pp() take it.

div_credit_pp(t)

The 契約者配当 declared in policy year t per policy [std]; zero in the base run.

div_rate on the fund at the start of the year. The composite is a 5年ごと利差配当 design [S4]; declaring annually on the fund is a [std] simplification of it, and the declared rate rather than the frequency is what moves the answer.

div_acc_pp(t)

The accumulated 契約者配当 per policy at time t; zero in the base run.

Accumulated at the 配当積立利率 of 0.60% p.a. [S11]. Under the 税制適格特約 it cannot be withdrawn before annuitisation and must be applied as a single premium increasing the 基本年金額, never paid in cash [S1] [S2] [R10] — so it appears in annuity_amount_pp() and nowhere in the cash flow before t = n.

annuity_fund_pp()

F = V(n): the 年金原資, the fund out of which the annuity is bought.

Struck once, at t = n, net of any outstanding loan balance [S2] [S4]. One carrier pins the definition down by publishing both 一括受取率 (F / Pm) and 年金受取率 (kB / Pm) at one model point [S6], which is what makes the loading calibration checkable rather than merely plausible.

annuity_due_factor()

adue(k, i_p): the k-year annuity-due factor at the payout 予定利率.

(1 - (1 + i)^-k) / i x (1 + i). The rate is i_p = 0.65%, not the deferral rate: the payout phase is priced on its own 予定利率, published separately and left unchanged when that carrier’s deferral rates moved [S5].

annuity_due_life_factor()

adue_life(g, i_p): the guaranteed-plus-life annuity-due factor at annuitisation.

sum over j >= 0 of max(1{j < g}, jp_(x+n)) / (1 + i_p)**j on the 年金開始後用 table at 100% — a pricing basis, not the best-estimate factor. At the anchor cell’s fund and g = 10 this is about 22.03 against 9.71 on the certain form, which is why the same 年金原資 buys ¥281,300 a year as a life annuity and ¥638,100 a year as a ten-year certain one. That ratio is the product fact the module exists to show.

annuity_amount_pp()

B: the 基本年金額, the annual instalment, struck once at t = n and never recomputed.

floor( (F (1 - theta) + accumulated dividend) / adue / 100 ) x 100. The rounding down to the nearest ¥100 is contractual rather than a display convention [std, new here] — Japanese specimens are published at that granularity [S3] [S5] [S6] [S10] — so it happens inside the model.

annuity_pp(t)

B x 1{in payment}: the annuity instalment per contract payable at the start of t.

Paid in advance, once a year, from the 年金支払開始日. On the 確定年金 form there are exactly k of them and then the contract ends; on the 保証期間付終身年金 form the instalment is the same amount for as long as the contract is in force, and it is pols_if() rather than the amount that carries the life contingency.

commute_factor(j)

The 年金の一括払 factor for j remaining instalments [S2]; [std] outside 1-14.

The published table verbatim where it reaches, and an annuity-due at the 0.40% p.a. it implies outside it. That rate is not the model’s payout 予定利率 of 0.65%, and the composite does not reconcile the two: the factors come from one carrier [S2] and the payout rate from another [S5]. A production model must re-derive the factors on its own payout basis.

commute_value_pp()

The lump sum per contract electing 年金の一括払 at the 年金支払開始日 [S2] [S4].

B times the factor for the whole certain or guaranteed period. At the anchor cell’s numbers this returns about 1.10% more than the gross 年金原資, which is why base-run take-up is zero: switching commutation on switches on a composite artefact rather than a product feature.

pols_if(t)

l(t): contracts with an obligation open at the start of policy year t.

1.0 at t = 0. Through the deferral phase the notes’ recursion l(t+1) = l(t)(1 - q(t))(1 - w(t)). From t = n the rules change with the payout form: on the 確定年金 the instalments are unconditional, so l is flat through the certain period and drops to zero once the last one is paid; on the 保証期間付終身年金 it is flat through the guarantee period and then runs off on the best-estimate payout basis.

This is the weight on every cash flow of the same result_cf() row. Do not decrement it by mortality during a certain or guaranteed period: deaths there pay the PV of the unpaid instalments, or the recipient elects continuation, and the base run assumes continuation at 100% [std] so that the stream is unchanged [S2] [R16].

pols_if_at(t, timing)

The number of contracts in force at a point inside policy year t.

"BEF_DECR"

l(t), the start of the year before any decrement; the same number as pols_if() and the weight on that year’s cash flows.

"BEF_LAPSE"

after deaths, before lapses — the notes’ processing order is death before lapse [std order], so this is the population lapses are taken from.

"AFT_DECR"

l(t+1), the end-of-year state.

lives_if(t)

L(t): the probability the annuitant is alive at the start of policy year t.

L(t+1) = L(t)(1 - q(t)) throughout, on whichever table the phase reads. It is carried separately from pols_if() because the two measure different things: in the deferral phase lapse removes a contract without removing a life, and in the payout phase the 確定年金 obligation survives the annuitant. At the anchor cell lives_if falls from 0.91268274 to 0.77848987 over the ten payout years without moving a single yen of projected cash flow, which is the clearest statement of why the two are not one cells.

pols_death(t)

D(t): expected deaths in policy year t, taken at the end of the year.

l(t) q(t) in the deferral phase. Zero inside a certain or guaranteed period, where the obligation does not depend on survival; on the 保証期間付終身年金 form after the guarantee it is the run-off of pols_if() itself.

pols_lapse(t)

W(t): expected lapses at the end of policy year t, from the survivors of mortality.

l(t)(1 - q(t)) w(t), and zero from t = n - 1: that year ends on the 年金支払開始日, where surrender is no longer available [S2] [S4]. A lapse applied there would remove contracts at t = n, where cv_pp is zero — in-force would disappear with no payment and the annuity outgo would be understated.

pols_commute(t)

Contracts electing 年金の一括払 at the 年金支払開始日; zero in the base run.

A decrement at t = n only [std]: the elector takes the lump sum in place of the instalments and the contract terminates [S2] [S4].

pols_maturity(t)

The count whose cover ends at the scheduled end of the contract, paid for or not.

The library-wide meaning of the name, as in BasicTerm_S and Term_UK_A: the contracts reaching the scheduled end, whether or not anything is paid for reaching it. Here that end is the last 確定年金 instalment, so this is non-zero only at t = n + k - 1, and zero on the 保証期間付終身年金 form, which has no fixed end.

There is no claims(t, "MATURITY") on this product, and the absence is a product fact rather than a gap: the 確定年金 pays exactly k instalments and then the contract simply ends [S2] [S4], so the money attaching to this year is the ordinary instalment in claims(t, "ANNUITY") and nothing further falls due. The count is still needed for the in-force roll-forward to close, because the survivors of that year neither die nor lapse; see check_pols_roll_fwd().

premiums(t)

P l(t): premium income at the start of policy year t, an inflow.

Level and guaranteed for the whole 保険料払込期間, and nothing after 払込満了 — the 据置期間 and the payout phase carry no premium at all. Zero as well once the 自動振替貸付 module has started carrying the contract, because there the insurer lends the premium rather than receiving it, and a policyholder who has stopped paying does not resume in the year the facility fails.

claims(t, kind=None)

Benefit outgo in policy year t, by kind; the total when kind is omitted.

"ANNUITY" — published as claims_annuity — is a living benefit here: it is paid on the annuitant surviving to a payment date, never on death. The same column name carries a death benefit in IncomeTerm_JP_S, where the survivor income runs to the end of the term after the life assured dies, and a living benefit again in LTC_JP_S. The name is the benefit’s form — a stream rather than a lump sum — so the contingency has to be read off the product, and this is where it is stated.

"ANNUITY"

the instalments paid in advance at the start of year t, to every contract with an obligation open that has not commuted. Past the guarantee period of the 保証期間付終身年金 form the instalment is payable only while the annuitant is alive; over the 確定年金’s certain period it is unconditional, which is prepaid survival-contingent cover and still not a benefit death can trigger.

"DEATH"

the 死亡給付金 for deaths at the end of the year, DB(t+1) D(t), net of any loan balance. Zero inside a certain or guaranteed period.

"LAPSE"

surrender payments at the end of the year, CV(t+1) W(t), net of any loan balance. Zero from t = n - 1.

"COMMUTATION"

the 年金の一括払 lump sums at the 年金支払開始日; zero in the base run.

inflation_factor(t)

The expense inflation factor in policy year t: (1 + pi)^t [std], pi = 1%.

claim_expenses(t)

ec D(t): the claim handling expense on the year’s death claims [std].

¥5,000 per death claim and none on surrender. A cells of its own, a claim_expenses column of its own in result_cf(), and a term of its own in net_cf() — the library-wide meaning: expenses() is acquisition and maintenance, and the expense that scales with claims rather than with in-force is never folded into it.

expenses(t)

E0 and e(t): acquisition and maintenance expense in year t [std].

¥30,000 per policy at t = 0, then ¥4,000 per policy per year in the deferral phase and ¥2,000 once the annuity is in payment, both inflating at 1% p.a. Acquisition and maintenance only: the claim handling expense is claim_expenses(), deducted explicitly in net_cf() and published as its own claim_expenses column, which is the library-wide meaning of the two names. These are best-estimate cash expenses and are entirely separate from the 予定事業費率, which is a pricing loading living inside av_pp(). Charging the loading against the cash flow, or projecting these into the fund, double-counts expense in one direction and destroys the calibration in the other.

commissions(t)

Commission outgo in policy year t [std].

40% of the annual premium at t = 0, then 2% of premium income for t = 1 .. m - 1, and nothing after 払込満了. Against a ¥180,000 annual premium this is a small acquisition cost, which is why the year-0 net cash flow of this product is a large positive — the mirror image of UK term assurance, where 150% of an annualized premium in upfront commission produces a deep new business strain.

net_cf(t)

CF(t): the net cash flow of policy year t, income positive.

Premiums less annuity instalments, death and surrender benefits, commutation lump sums, acquisition and maintenance expense, claim expense, commission and any loan advanced. claim_expenses() is deducted as its own term rather than through expenses(). The notes print the stream this way round, so this model publishes no liability_cf companion — that absence is a fact about which orientation the notes chose, not an omission.

The shape to expect is a large positive at t = 0, then thirty years of declining positive margin as surrender outgo grows against a shrinking premium base, then a decade of pure outgo once the annuity is in payment.

check_pols_roll_fwd_resid(t)

The in-force roll-forward residual in policy year t; zero everywhere.

l(t) - l(t+1) - deaths - lapses - commutations - expiries. Expiries are non-zero only in the year the last 確定年金 instalment is paid, where the survivors neither die nor lapse — the contract simply ends — so without that term the final payout year appears to lose contracts with no cause.

check_pols_roll_fwd()

True when the in-force roll-forward closes in every projected policy year.

The library-wide form of a roll-forward check: no argument, one bool over all t. check_pols_roll_fwd_resid() gives the signed residual of the year that failed.

check_lives_roll_fwd_resid(t)

The survivorship roll-forward residual in policy year t; zero everywhere.

L(t) - L(t+1) - L(t) q(t). Carried separately from the in-force check because the two measures decrement differently, and a model that has quietly collapsed them would still close one of the two.

check_lives_roll_fwd()

True when the survivorship roll-forward closes in every projected policy year.

check_fund_resid(t)

The 保険料積立金 recursion residual in policy year t; zero over the deferral phase.

(V(t) + NP(t))(1 + i_d) - q' DB(t+1) - (1 - q') V(t+1). Scaled by the fund, so the tolerance means the same thing at every duration. Zero by definition from t = n, where there is no fund left to roll forward.

check_fund()

True when the 保険料積立金 recursion closes in every deferral year.

The identity that the survivorship release is exactly what is left after the death benefit is paid out of the accumulated fund. A model that had put lapse into this recursion, or that had used the best-estimate rate instead of the 予定死亡率, would fail here rather than silently misstate the 年金原資.

check_cv_cap_resid(t)

The 解約返戻金 ceiling residual at duration t; zero or negative is the breach.

DB(t) - CV(t), which is non-negative at every deferral duration by the sourced ceiling [S2] [S4]. The residual is published unsigned rather than clipped so that the crossover — where it reaches exactly zero and stays there — is readable off it.

check_cv_cap()

True when the 解約返戻金 never exceeds the 死亡給付金 at any deferral duration.

The product’s sourced invariant [S2] [S4]. It is the fund, not the surrender value, that is allowed past the ceiling: clipping av_pp() instead of cv_pp() would pass this check and destroy the 年金原資.

check_annuity_total_resid(t)

The guaranteed-instalment residual in policy year t; zero everywhere.

The instalment actually payable per contract less B, over the certain period of the 確定年金 or the guarantee period of the 保証期間付終身年金. Zero outside that window.

check_annuity_total()

True when the undiscounted guaranteed instalments sum to k B (or g B).

The 確定年金 pays exactly k instalments of the same amount, regardless of survival [S2] [R16], and the 保証期間付終身年金 pays at least g of them [S4] [R16]. A model that had decremented the payout phase by mortality, or that had recomputed B after annuitisation, would fail here.

check_net_cf_resid(t)

The cash flow ledger residual in policy year t; zero everywhere.

net_cf() less the sum of the columns result_cf() publishes. It is the check that the published statement and the projected total are the same object, which is the one identity a reader of the output cannot verify for themselves.

check_net_cf()

True when the published cash flow columns add up to net_cf() in every year.

mort_anchor_ages(table)

The ages at which table is anchored to a quoted rate, ascending.

Read from data.mort_anchor_table(). On 死亡保険用 these are the sourced ages of the canonical library-wide table; on 年金開始後用 they are the three spot rates the Makeham construction is fitted to.

makeham_coeff(table)

(A, B, c) of the [std] Makeham law fitted to the three anchors of table.

Solved in closed form from equally spaced anchors: with mu = -ln(1 - q) and a spacing of h years, c**h is the ratio of the two successive differences. The anchors are therefore reproduced exactly by construction. Used for 年金開始後用 only — 死亡保険用 is graduated log-linearly instead; see mort_rate_graduated().

mort_rate_graduated(table, x)

The rate the shipped table’s own stated graduation produces at age x.

On death_cover_2018 the graduation is log-linear in age between the two neighbouring anchors — linear in ln q, evaluated in full double precision and rounded to five decimal places — which is the graduation the canonical library-wide 死亡保険用 file states in its provenance column. There is no extrapolation: every age the model can reach lies between two sourced anchors.

On annuity_payout_2007 it is the Makeham law of makeham_coeff(). Two tables, two graduations, because the two anchor sets are different: the death-cover table is anchored at every published age the library uses, the payout table at three spot rates.

check_mort_graduation_resid(t)

The shipped-rate residual at the attained age of policy year t; zero everywhere.

mort_table.csv rate less the graduation mort_rate_graduated() rebuilds from the anchors in mort_anchor_table.csv. Non-zero is not a defect once a licensed or company table has been dropped in — it is the correct answer, and the reason this check reports a residual rather than raising.

check_mort_graduation()

True when the shipped rates are still the [std] graduation of the quoted anchors.

The library ships no copy of 標準生命表2018 or of the 2007 年金開始後用 table: what it ships is a construction anchored to quoted rates, and this is the assertion that mort_table.csv and mort_anchor_table.csv still agree with each other — the 死亡保険用 rates log-linear between their anchors, the 年金開始後用 rates on the Makeham law.

result_cf()

Result table of cash flows, indexed by policy year t.

pols_if is the start-of-year count, which is the weight applied to every cash flow on the same row. net_cf carries the notes’ own income-positive sign, so the deferral rows are positive and the payout rows are large negatives. claims_commutation and policy_loans are columns of zeros in the base run and are published rather than dropped, because a zero states the module is off where a missing column would only hide it.

claims_annuity is a living benefit on this product — the instalments are paid on the annuitant surviving to a payment date, never on death. The library uses the same column name for the form of the benefit, a stream rather than a lump sum, so it names a death benefit in IncomeTerm_JP_S and a living benefit in LTC_JP_S; the contingency is a product fact and is stated rather than inferred. The death contingency has its own column here, claims_death, carrying the 死亡給付金.

result_pols()

Result table of in-force, decrements and per-policy amounts, indexed by t.

The companion to result_cf(): the two in-force measures side by side, the decrements that move them, and the fund, death benefit and surrender value that price them. Reading av_pp, db_pp and cv_pp in one table is the quickest way to see the crossover, where the fund passes the death benefit and the surrender value stops rising.

lapse_rate_mean(weighting='count')

The mean 解約・失効 rate over the deferral phase, on a stated weighting.

"count"

weighted by pols_if(), sum l(t) w(t) / sum l(t) over t = 0 .. n - 1.

"fund"

weighted by av_pp() over the same range.

Published as a cells because the two are not interchangeable and a calibration must say which one it used. Lapse is front-loaded and the fund is back-loaded, so the fund weighting comes out materially lower — and the one public figure this curve is anchored to, a market-wide 3.4% for FY2024, is itself measured on 契約高 rather than on policy count [R15] [REG-R31]. Calibrating a count model directly against the published number without saying which weighting is meant mis-states the deferral decrement.