Parameters
Default
Description
age1 *
--
Age of the first annuitant.
lx1 *
--
Mortality table for the first annuitant, usually supplied by LX() or LX_H().
interest *
--
Interest rate, either flat or in VT-style vector form rate1, dur1, rate2, dur2, ... (last rate continues after the final duration).
age2
0
Age of the secondary annuitant, relevant only when reversion is greater than 0.
lx2
empty
Mortality table for the secondary annuitant, relevant only when reversion is greater than 0.
reversion
0
Portion of the pension continuing to the secondary annuitant after death of the first annuitant (e.g., 0.6 for 60%).
guarantee
0
Certain period of the annuity, in years, starting after the deferment period.
deferred
0
Deferment period, in years, before the first payment.
years paid
120
Payment period, in years, starting after deferment. If omitted, the function uses the full lifetime horizon.
indexation
0
Indexation rate, either flat or vector-based.
first age index
age1 + 1 + deferred
Age of the first annuitant at which indexation starts. The effective start is the later of this value and the first payable age.
frequency
12
Number of payments per year.
due
TRUE
TRUE for payments at the beginning of each period, FALSE for payments at the end.
qx-pre
TRUE
TRUE to apply first-life mortality discount during the deferment period, FALSE otherwise.
certain reduced
FALSE
Accepts FALSE, TRUE, or OVERLAP. FALSE keeps guarantee at full level; TRUE applies reduction during guarantee; OVERLAP keeps guarantee and also allows survivor pension during guarantee.
percentage married
1
Probability that the first annuitant has a spouse at retirement.
fraction first indexation
1
Fraction, between 0 and 1, applied to the first indexation.
cash_flow
0
If 0, JS returns a scalar annuity factor. If non-zero, JS returns a spilled yearly expected cash-flow vector multiplied by cash_flow.
JS(65, ...)
Returns the scalar annuity factor for a life aged 65.
JS(65, ..., cash_flow=1)
Returns a spilled yearly vector of unit cash flows.
JS(65, ... cash_flow=1000)
Returns a spilled yearly vector for a pension amount of 1,000.
Two output modes
The function returns a scalar when cash_flow=0 and a spilled yearly vector when cash_flow<>0.
Scaling
In cash-flow mode, the yearly vector is already multiplied by the supplied cash_flow value.
Mortality discount
If qx-pre applies during deferment, that first-life adjustment is reflected in both the scalar result and the yearly cash-flow vector.
Certain reduced modes
certain reduced supports FALSE, TRUE, and OVERLAP to control guarantee/reversion interaction during the guaranteed period.
Indexation
Indexation only applied on and after age1 + deferred; no pre-retirement indexation considered by the function.
Helper functions
The spilled yearly output can be passed directly to CF_Get, CF_SumByYear, CF_SumByRow, CF_SumRange, and PV_CF.