Package {tidyactuarial}

Internal helper: convert number of payments into annuity factors

Description

Internal helper: convert number of payments into annuity factors

Usage

.annuity_factor_count(n_payments, i_effective, k, timing)

Arguments

Value

Numeric vector of annuity factors.

Internal helper: count annuity payments from simulated curtate lifetimes

Description

Internal helper: count annuity payments from simulated curtate lifetimes

Usage

.annuity_payment_count(Kx, died_within_horizon, n, k, timing)

Arguments

Value

Integer vector with number of payments.

Internal helper: collect old Monte Carlo argument names

Description

Internal helper: collect old Monte Carlo argument names

Usage

.life_mc_collect_old_args(dots, allowed)

Arguments

Value

A list.

Internal helper: annual annuity payment times

Description

Internal helper: annual annuity payment times

Usage

.mc_annuity_payment_times_annual(K, type, n, h, n_guar, timing)

Arguments

Value

Numeric vector with annual payment times.

Internal helper: fractional annuity payment times

Description

Internal helper: fractional annuity payment times

Usage

.mc_annuity_payment_times_fractional(
  T,
  type,
  n,
  h,
  n_guar,
  timing,
  payment_interval
)

Arguments

Value

Numeric vector with fractional payment times.

Internal helper: validate character scalar

Description

Internal helper: validate character scalar

Usage

.mc_assert_character_scalar(x, arg)

Arguments

Value

Invisibly returns TRUE if validation is successful.

Internal helper: validate column existence

Description

Internal helper: validate column existence

Usage

.mc_assert_column(data, col, arg)

Arguments

Value

Invisibly returns TRUE if validation is successful.

Internal helper: validate numeric column

Description

Internal helper: validate numeric column

Usage

.mc_assert_numeric_column(data, col, arg)

Arguments

Value

Invisibly returns TRUE if validation is successful.

Internal helper: validate numeric scalar

Description

Internal helper: validate numeric scalar

Usage

.mc_assert_numeric_scalar(
  x,
  arg,
  min = -Inf,
  max = Inf,
  strict_min = FALSE,
  strict_max = FALSE,
  allow_null = FALSE
)

Arguments

Value

Invisibly returns TRUE if validation is successful.

Internal helper: validate positive integer-like scalar

Description

Internal helper: validate positive integer-like scalar

Usage

.mc_assert_positive_integer(x, arg)

Arguments

Value

Invisibly returns TRUE if validation is successful.

Internal helper: compute annual discount factor

Description

Computes the annual discount factor from an interest-rate convention.

Usage

.mc_discount_factor(
  i,
  i_type = c("effective", "nominal_interest", "nominal_discount", "force"),
  m = 1,
  rate = NULL,
  interest_type = NULL
)

Arguments

Value

Numeric scalar with the annual discount factor.

Internal helper: convert interest rate to annual effective rate

Description

Converts an interest rate supplied under a standard actuarial convention into an equivalent annual effective interest rate.

Usage

.mc_effective_rate(
  i,
  i_type = c("effective", "nominal_interest", "nominal_discount", "force"),
  m = 1,
  rate = NULL,
  interest_type = NULL
)

Arguments

Details

This helper follows the compact actuarial notation used throughout tidyactuarial: i is the interest-rate input, i_type is the interest-rate type, and m is the conversion frequency for nominal rates.

The argument m is used only to convert nominal annual rates into equivalent annual effective rates. It does not represent annuity payment frequency.

Transitional compatibility is intentionally retained for older internal Monte Carlo calls using ⁠rate =⁠ and ⁠interest_type =⁠.

Value

Numeric scalar with the equivalent annual effective interest rate.

Internal helper: normalize Monte Carlo interest-rate type

Description

Converts legacy Monte Carlo labels to the package-wide actuarial labels.

Usage

.mc_normalize_i_type(i_type)

Arguments

Value

Character scalar.

Internal helper: safe payment times

Description

Creates a sequence of payment times. If the upper bound is smaller than the lower bound, it returns numeric(0).

Usage

.mc_payment_times(from, to, by = 1)

Arguments

Value

Numeric vector.

Internal helper: create quantile column names

Description

Internal helper: create quantile column names

Usage

.mc_quantile_names(probs)

Arguments

Value

Character vector with syntactically valid quantile names.

Internal helper: benefit payment information for reserve calculations

Description

Determines whether a benefit is paid and at what time for each simulated scenario.

Usage

.mc_reserve_benefit_info(Kx, Tx, death_time, type, n, h, timing)

Arguments

Value

A list with benefit_indicator and benefit_time.

Internal helper: resolve inputs for single-life Monte Carlo functions

Description

Internal helper: resolve inputs for single-life Monte Carlo functions

Usage

.resolve_life_mc_inputs(lt, x = NULL, i = NULL, i_type = NULL, m = NULL)

Arguments

Value

A list with resolved arguments.

Internal helper: simulate curtate future lifetimes from lx

Description

Internal helper: simulate curtate future lifetimes from lx

Usage

.simulate_lifetime_inverse_lx(lt, x, n, n_sim, seed = NULL)

Arguments

Value

A tibble with simulated curtate lifetimes.

Internal helper: validate common Monte Carlo arguments

Description

Internal helper: validate common Monte Carlo arguments

Usage

.validate_mc_common(x, i, m, n_sim, seed, n)

Arguments

Value

Invisibly returns TRUE.

Level annuity factor a-angle-n

Description

Computes the actuarial present value factor for a level annuity using compact actuarial notation.

Usage

a_angle(
  n = NULL,
  k = 1L,
  i,
  i_type = "effective",
  m = 1L,
  h = 0,
  timing = "immediate",
  perpetuity = FALSE,
  payment = 1,
  tidy = FALSE
)

Arguments

Details

Supported timing conventions:

• "immediate": annuity-immediate with discrete payments.

• "due": annuity-due with discrete payments.

• "continuous": continuous annuity.

For discrete annuities, k is the number of payments per year, so payments are made every 1/k year. The function returns the annuity factor, assuming a unit payment at each payment time.

Deferment is supported through h. For discrete annuities, the deferment must align with the payment grid, that is, hk must be an integer.

If perpetuity = TRUE, the infinite-term annuity factor is returned.

This function follows the compact actuarial notation used throughout tidyactuarial:

• n: annuity term;

• k: payment frequency;

• i: interest rate;

• i_type: interest-rate type;

• m: conversion frequency for nominal rates;

• h: deferment period.

The function first converts the supplied rate to the equivalent annual effective interest rate using standardize_interest.

For finite discrete annuities:

a_{\overline{n|}} = \frac{1 - v^n}{i}

For due annuities:

\ddot{a}_{\overline{n|}} = (1+i)a_{\overline{n|}}

For continuous annuities:

\bar{a}_{\overline{n|}} = \frac{1 - e^{-\delta n}}{\delta}

Input vectors must have length 1 or a common length. Missing values are propagated.

Value

If tidy = FALSE, a numeric vector of annuity factors.

If tidy = TRUE, a tibble with input values, equivalent rates, annuity factors, payment amounts, and present values.

See Also

s_angle, standardize_interest, present_value

Other annuities: annuity_arith(), annuity_geom(), s_angle()

Examples

# Numeric annuity factor
a_angle(n = 10, i = 0.05)

# Nominal interest converted monthly, with monthly payments
a_angle(
  n = 10,
  i = 0.06,
  i_type = "nominal_interest",
  m = 12,
  k = 12
)

# Continuous annuity
a_angle(
  n = 15,
  i = 0.04,
  i_type = "force",
  timing = "continuous"
)

# Tibble output for teaching or auditing
a_angle(
  n = 10,
  i = 0.05,
  payment = 1000,
  tidy = TRUE
)

# Vectorized example
a_angle(
  n = c(5, 10, 20),
  k = c(1, 12, 1),
  i = c(0.05, 0.06, 0.04),
  i_type = c("effective", "nominal_interest", "force"),
  m = c(1, 12, 1),
  h = c(0, 0, 2),
  timing = c("immediate", "immediate", "continuous"),
  perpetuity = c(FALSE, FALSE, FALSE)
)

Amortization schedule with optional prepayment adjustment

Description

Builds an amortization schedule under a fixed annual interest-rate specification, allowing extra principal payments and optional adjustment of either the remaining term or the remaining payment amount.

Usage

amort_schedule(
  principal,
  n,
  i,
  i_type = "effective",
  m = 1L,
  k = 1L,
  timing = c("immediate", "due"),
  payment = NULL,
  extra_principal = NULL,
  adjust = c("none", "term", "payment"),
  tol = 1e-08
)

Arguments

Details

The annual rate is converted internally to an effective rate per schedule period using k.

Adjustment policies after extra principal payments:

• "none": keep the original payment and contractual term, unless the loan is fully repaid early.

• "term": keep the regular payment and shorten the term. No special logic is needed: the loop exits naturally when the outstanding balance reaches zero.

• "payment": keep the remaining contractual term and recalculate the regular payment after each period.

This function follows the compact actuarial notation used throughout tidyactuarial: i is the interest rate, i_type is the interest-rate type, m is the conversion frequency for nominal annual rates, and k is the number of amortization periods per year.

For timing = "immediate" (annuity-immediate), interest accrues on the outstanding balance during the period, and the payment is made at the end. For timing = "due" (annuity-due), the payment is made at the start of the period and interest accrues on the balance after the payment.

If the user supplies a custom payment that is smaller than the periodic interest, principal repayment will be negative (negative amortization). This is permitted but the user should be aware.

Value

A tibble with one row per realized period and columns:

period

Period index.

ob_start

Outstanding balance at the start of the period.

interest

Interest charged during the period.

payment

Regular payment in the period.

extra_principal

Extra principal paid in the period.

principal

Principal repaid through the regular payment.

total_principal

Total principal repaid in the period.

cashflow

Total payment made in the period.

ob_end

Outstanding balance at the end of the period.

i_effective_annual

Equivalent annual effective rate.

i_effective_period

Equivalent effective rate per schedule period.

k

Schedule frequency.

timing

Payment timing convention.

adjust

Adjustment rule used.

See Also

a_angle, present_value, pv_flow, standardize_interest

Other amortization: sinking_fund_schedule()

Examples

amort_schedule(
  principal = 100000,
  n = 12,
  i = 0.12,
  i_type = "nominal_interest",
  m = 12,
  k = 12
)

amort_schedule(
  principal = 100000,
  n = 24,
  i = 0.12,
  i_type = "nominal_interest",
  m = 12,
  k = 12,
  extra_principal = c("6" = 5000, "12" = 3000),
  adjust = "term"
)

amort_schedule(
  principal = 100000,
  n = 24,
  i = 0.12,
  i_type = "nominal_interest",
  m = 12,
  k = 12,
  extra_principal = c("6" = 5000, "12" = 3000),
  adjust = "payment"
)

Arithmetic annuity factor

Description

Computes the actuarial present value or accumulated value factor for an arithmetic annuity, using compact actuarial notation.

Usage

annuity_arith(
  n,
  k = 1L,
  i,
  i_type = "effective",
  m = 1L,
  h = 0,
  timing = "immediate",
  pattern = "increasing",
  P1 = 1,
  g = 1,
  valuation = c("present", "accumulated"),
  tidy = FALSE
)

Arguments

Details

This function covers increasing, decreasing, and custom arithmetic payment patterns. It replaces the more specific increasing and decreasing annuity functions.

Supported payment patterns:

• "increasing": payments 1, 2, \ldots, N.

• "decreasing": payments N, N-1, \ldots, 1.

• "custom": payments following P_r = P_1 + (r - 1)g.

Supported timing conventions:

• "immediate": payments at the end of each period.

• "due": payments at the beginning of each period.

This function follows the compact actuarial notation used throughout tidyactuarial: n is the term, k is the payment frequency, i is the interest-rate input, i_type is the interest-rate type, m is the conversion frequency for nominal rates, and h is the deferment period.

The function first converts the supplied rate to the equivalent annual effective interest rate using standardize_interest.

For each scenario, the total number of payments is

N = n k.

The present value is computed by summing the discounted payment stream. The accumulated value is computed at the end of the annuity term. Under this convention, h affects the present value factor but not the accumulated value factor.

Value

If tidy = FALSE, a numeric vector of arithmetic annuity factors.

If tidy = TRUE, a tibble with input values, equivalent rates, period quantities, and both present and accumulated value factors.

See Also

a_angle, s_angle, standardize_interest

Other annuities: a_angle(), annuity_geom(), s_angle()

Examples

# Increasing arithmetic annuity
annuity_arith(n = 10, i = 0.05, pattern = "increasing")

# Decreasing arithmetic annuity
annuity_arith(n = 10, i = 0.05, pattern = "decreasing")

# Custom arithmetic annuity
annuity_arith(
  n = 10,
  i = 0.05,
  pattern = "custom",
  P1 = 100,
  g = 25
)

# Accumulated value factor
annuity_arith(
  n = 10,
  i = 0.05,
  pattern = "increasing",
  valuation = "accumulated"
)

# Tibble output
annuity_arith(
  n = 10,
  i = 0.05,
  pattern = "decreasing",
  tidy = TRUE
)

Geometric annuity factor

Description

Computes the actuarial present value or accumulated value factor for a geometric annuity, using compact actuarial notation.

Usage

annuity_geom(
  n = NULL,
  k = 1L,
  i,
  i_type = "effective",
  m = 1L,
  g = 0,
  g_type = "effective",
  g_m = 1L,
  h = 0,
  timing = "immediate",
  P1 = 1,
  perpetuity = FALSE,
  valuation = c("present", "accumulated"),
  tidy = FALSE
)

Arguments

Details

This function covers finite geometric annuities and geometric perpetuities.

Supported timing conventions:

• "immediate": payments at the end of each period.

• "due": payments at the beginning of each period.

This function follows the compact actuarial notation used throughout tidyactuarial: n is the term, k is the payment frequency, i is the interest-rate input, i_type is the interest-rate type, m is the conversion frequency for nominal interest rates, g is the growth-rate input, g_type is the growth-rate type, g_m is the conversion frequency for nominal growth rates, h is the deferment period, and P1 is the first payment.

Let i_p be the effective interest rate per payment period, g_p the effective growth rate per payment period, and v_p = (1+i_p)^{-1}.

For a finite geometric annuity-immediate with N payment periods:

ga_N = \sum_{r=1}^{N}\frac{(1+g_p)^{r-1}}{(1+i_p)^r}

If i_p \neq g_p, then

ga_N = \frac{1-\left(\frac{1+g_p}{1+i_p}\right)^N}{i_p-g_p}.

The accumulated value factor is computed at the standard terminal horizon:

gs_N = \sum_{r=1}^{N}(1+g_p)^{r-1}(1+i_p)^{N-r}.

For annuities-due, the corresponding immediate factor is multiplied by 1+i_p.

Value

If tidy = FALSE, a numeric vector.

If tidy = TRUE, a tibble with input values, equivalent rates, period quantities, and both present and accumulated value factors.

See Also

a_angle, s_angle, annuity_arith, standardize_interest

Other annuities: a_angle(), annuity_arith(), s_angle()

Examples

# Present value of a geometric annuity
annuity_geom(
  n = 10,
  i = 0.05,
  g = 0.02,
  valuation = "present"
)

# Accumulated value of a geometric annuity
annuity_geom(
  n = 10,
  i = 0.05,
  g = 0.02,
  valuation = "accumulated"
)

# Nominal interest and nominal growth
annuity_geom(
  n = 10,
  k = 12,
  i = 0.06,
  i_type = "nominal_interest",
  m = 12,
  g = 0.024,
  g_type = "nominal_interest",
  g_m = 12
)

# Tibble output
annuity_geom(
  n = 10,
  i = 0.05,
  g = 0.02,
  tidy = TRUE
)

Actuarial present value of a multi-life annuity (up to 3 independent lives)

Description

Computes the APV of a discrete annuity contingent on multiple independent lives using compact actuarial notation.

Usage

annuity_multi(
  lt,
  ages,
  i,
  i_type = "effective",
  m = 1L,
  n = NULL,
  h = 0L,
  k = 1L,
  annuity = c("cohort", "reversionary"),
  cohort = c("first", "last"),
  alpha = NULL,
  timing = c("immediate", "due"),
  woolhouse = c("none", "first", "second")
)

Arguments

Details

This implementation supports up to three lives, which covers the most common practical multi-life arrangements.

Supports status-based annuities (joint-life / last-survivor) and a joint-and-survivor style annuity ("reversionary") that pays 1 while all lives are alive and then pays a fraction \alpha while at least one life remains alive.

This function follows the compact actuarial notation used throughout tidyactuarial: i is the interest rate, i_type is the interest-rate type, m is the conversion frequency for nominal rates, n is the term, h is the deferment period, and k is the payment frequency.

Under the assumption of independent future lifetimes, the survival probability for the status is calculated as:

• Joint-life (first-death): {}_t p_{x_1 x_2 \dots x_n} = \prod_{j=1}^n {}_t p_{x_j}

• Last-survivor: {}_t p_{\overline{x_1 x_2 \dots x_n}} = 1 - \prod_{j=1}^n (1 - {}_t p_{x_j})

For annuity = "reversionary", the APV is a weighted combination of the two statuses:

APV = APV(\text{joint-life}) + \alpha [APV(\text{last-survivor}) - APV(\text{joint-life})].

Value

A single numeric value representing the APV.

See Also

annuity_x for single-life annuities, t_px for survival probabilities.

Other life-contingencies: annuity_x(), annuity_xy(), insurance_variable_k(), insurance_x(), insurance_xy(), life_contract(), premium_gross(), premium_x(), premium_xy(), reserve_x(), reserve_xy(), simulate_annuity_x(), simulate_insurance_x()

Examples

lt <- data.frame(
  x = 60:90,
  lx = seq(100000, 0, length.out = 31)
)

annuity_multi(
  lt = lt,
  ages = c(60, 62),
  i = 0.05,
  n = 5,
  cohort = "first",
  timing = "due"
)

annuity_multi(
  lt = lt,
  ages = c(60, 62),
  i = 0.05,
  n = 5,
  cohort = "last",
  timing = "due"
)

Actuarial present value of a life annuity

Description

Computes the actuarial present value of a discrete life annuity using compact actuarial notation.

Usage

annuity_x(
  lt,
  x,
  i,
  i_type = "effective",
  m = 1L,
  n = NULL,
  h = 0L,
  k = 1L,
  timing = c("immediate", "due"),
  woolhouse = c("none", "first", "second"),
  frac = NULL,
  tidy = FALSE
)

Arguments

Details

The function supports:

• whole-life annuities,

• temporary annuities,

• integer deferment,

• annual or k-thly payments,

• exact fractional survival for k-thly payments,

• first- and second-order Woolhouse approximations.

This function follows the compact actuarial notation used throughout tidyactuarial:

• lt: life table;

• x: actuarial age;

• i: interest rate;

• i_type: interest-rate type;

• m: interest conversion frequency;

• n: annuity term;

• h: deferment period;

• k: payment frequency.

For annual annuities-due,

\ddot{a}_{x:\overline{n}|} = \sum_{j=0}^{n-1} v^j\,{}_jp_x.

For annual annuities-immediate,

a_{x:\overline{n}|} = \sum_{j=1}^{n} v^j\,{}_jp_x.

Deferment is handled through

v^h\,{}_hp_x,

where h is the deferment period.

For k-thly payments with woolhouse = "none", fractional survival is computed under the selected fractional-age assumption.

Value

If tidy = FALSE, a numeric scalar containing the actuarial present value.

If tidy = TRUE, a one-row tibble with the main input values, equivalent interest rate, deferment factor, pure endowment factor, and APV.

See Also

insurance_x, premium_x, reserve_x, t_px, t_Ex

Other life-contingencies: annuity_multi(), annuity_xy(), insurance_variable_k(), insurance_x(), insurance_xy(), life_contract(), premium_gross(), premium_x(), premium_xy(), reserve_x(), reserve_xy(), simulate_annuity_x(), simulate_insurance_x()

Examples

lt <- data.frame(
  x  = 60:65,
  lx = c(100000, 99000, 97500, 95500, 93000, 90000)
)

# Annual annuity-immediate
annuity_x(
  lt = lt,
  x = 60,
  i = 0.06,
  timing = "immediate"
)

# Annual annuity-due
annuity_x(
  lt = lt,
  x = 60,
  i = 0.06,
  timing = "due"
)

# Temporary annuity
annuity_x(
  lt = lt,
  x = 60,
  i = 0.06,
  n = 3,
  timing = "due"
)

# Deferred annuity
annuity_x(
  lt = lt,
  x = 60,
  i = 0.06,
  h = 2,
  timing = "due"
)

# Tidy output
annuity_x(
  lt = lt,
  x = 60,
  i = 0.06,
  n = 3,
  timing = "due",
  tidy = TRUE
)

# Pipe workflow with a life contract
life_contract(lt = lt, lives = "single", x = 60, i = 0.06) |>
  annuity_x(n = 3, timing = "due")

Actuarial present value of a two-life annuity

Description

Computes the actuarial present value of a discrete annuity contingent on two independent lives, using compact actuarial notation.

Usage

annuity_xy(
  lt,
  x = NULL,
  y = NULL,
  i = NULL,
  i_type = "effective",
  m = 1L,
  status = c("joint", "last"),
  benefit = NULL,
  n = Inf,
  h = 0L,
  k = 1L,
  timing = c("immediate", "due"),
  woolhouse = c("none", "first", "second"),
  frac,
  tidy = FALSE,
  ...
)

Arguments

Details

The function supports joint-life, last-survivor, and state-based reversionary-style payments. The life table input may be either one common table for both lives or a list of two life tables, one for each life.

This function follows the compact actuarial notation used throughout tidyactuarial: lt is the life table input, x and y are the two actuarial ages, i is the interest-rate input, i_type is the interest-rate type, m is the conversion frequency for nominal rates, n is the term, h is the deferment period, and k is the payment frequency.

The function assumes independent future lifetimes. For state-based benefits, the expected payment at time t is

b_{\text{both}}\,{}_tp_x{}_tp_y + b_{x\text{ only}}\,{}_tp_x(1-{}_tp_y) + b_{y\text{ only}}\,{}_tp_y(1-{}_tp_x).

When benefit = NULL, status = "joint" uses benefit = list(both = 1, x_only = 0, y_only = 0), while status = "last" uses benefit = list(both = 1, x_only = 1, y_only = 1).

For k-thly payments, the function values a payment rate of 1 per year, so each payment has size 1/k.

Value

If tidy = FALSE, a numeric scalar.

If tidy = TRUE, a one-row tibble with input values, standardized interest rate, term used, and APV.

See Also

annuity_x, insurance_xy, premium_xy, t_pxy, t_px

Other life-contingencies: annuity_multi(), annuity_x(), insurance_variable_k(), insurance_x(), insurance_xy(), life_contract(), premium_gross(), premium_x(), premium_xy(), reserve_x(), reserve_xy(), simulate_annuity_x(), simulate_insurance_x()

Examples

lt <- data.frame(
  x  = 60:66,
  lx = c(100000, 99000, 97500, 95500, 93000, 90000, 86000)
)

# Joint-life annuity-due
annuity_xy(
  lt = lt,
  x = 60,
  y = 62,
  i = 0.05,
  status = "joint",
  timing = "due"
)

# Last-survivor annuity-due
annuity_xy(
  lt = lt,
  x = 60,
  y = 62,
  i = 0.05,
  status = "last",
  timing = "due"
)

# Different life tables for the two lives
lt_m <- lt
lt_f <- data.frame(
  x  = 60:66,
  lx = c(100000, 99200, 98100, 96500, 94500, 92000, 89000)
)

annuity_xy(
  lt = list(lt_m, lt_f),
  x = 60,
  y = 62,
  i = 0.05,
  status = "joint",
  timing = "due"
)

# State-based reversionary-style payments
annuity_xy(
  lt = list(lt_m, lt_f),
  x = 60,
  y = 62,
  i = 0.05,
  benefit = list(both = 0, x_only = 1, y_only = 0),
  timing = "due"
)

Actuarial present value of a payment stream under mortality

Description

Computes the actuarial present value (APV) of a cash-flow stream contingent on survival. The life table is supplied as the first argument (pipe-friendly). Payments may be specified by numeric times or by calendar dates.

Usage

apv_life_flow(
  lt,
  ages,
  t = NULL,
  date = NULL,
  date0 = NULL,
  cf,
  i,
  i_type = "effective",
  m = 1L,
  status = c("single", "first", "last", "reversionary"),
  alpha = NULL,
  plot = FALSE
)

Arguments

Details

Multiple lives are supported under an independence assumption, through common statuses: single-life, first-death (all alive), last-survivor (any alive), and reversionary (joint-and-survivor) with fraction alpha.

This function follows the compact actuarial notation used throughout tidyactuarial: t denotes payment time, cf denotes cash flows, i denotes the interest rate, i_type denotes the interest-rate type, and m denotes the conversion frequency for nominal rates.

For each payment at time t, the APV contribution is

PV(t) = C(t) v^t P(\text{status alive at } t).

The survival probability depends on the status:

• "single": {}_t p_x for a single life.

• "first": {}_t p_{x_1} \cdot {}_t p_{x_2} \cdots, so all lives must be alive.

• "last": 1 - \prod_j (1 - {}_t p_{x_j}), so at least one life must be alive.

• "reversionary": full benefit while all lives are alive, and fraction \alpha while at least one but not all lives are alive.

Fractional-year survival is computed under UDD within each year.

Value

A tibble with one row per payment and columns: t, cf, surv_prob, discount, expected_cf, pv, and pv_cum. If date was provided, a date column is included. The total APV is stored as attr(result, "apv").

Examples

lt <- data.frame(
  x = 40:100,
  lx = seq(100000, 0, length.out = 61)
)

apv_life_flow(
  lt = lt,
  ages = 40,
  t = c(1, 2, 3),
  cf = c(100, 100, 100),
  i = 0.05
)

apv_life_flow(
  lt = lt,
  ages = c(60, 58),
  t = c(1, 2, 3),
  cf = c(100, 100, 100),
  i = 0.05,
  status = "first"
)

Book value of a level coupon bond at a coupon date

Description

Computes the book value of a level coupon bond at one or more coupon dates, under a specified yield basis, using compact actuarial notation.

Usage

bond_book_value(
  face,
  c,
  n,
  t,
  k = 1L,
  y_effective_per_period = NULL,
  y = NULL,
  y_type = "effective",
  y_m = 1L,
  R = NULL,
  tol = 1e-10,
  check = TRUE,
  tidy = FALSE
)

Arguments

Details

The book value is interpreted prospectively: at a valuation time that lies on the coupon grid, it equals the present value at that time of all remaining future coupons and the final redemption amount, discounted at the bond's yield basis.

This function interprets t as a time immediately after any coupon due at that date has been paid. Therefore:

• at t = 0, the book value equals the bond price,

• at t = n, the book value is 0.

Assumptions:

• Coupons are paid in arrears at regular intervals.

• n * k must be an integer.

• Each t * k must be an integer.

• Stub periods are not supported.

• Valuation is performed at coupon dates; no accrued interest is included.

Yield input conventions:

• If y_effective_per_period is supplied, it takes precedence over y, y_type, and y_m, and is interpreted as the effective yield per coupon period.

• Otherwise, y, y_type, and y_m define an annual yield specification, which is converted first to annual effective yield and then to effective yield per coupon period.

This function follows the compact bond notation used in tidyactuarial: P is price, face is the face value, c is the annual coupon rate, n is maturity, k is coupon frequency, y is the yield, R is redemption value, and t is valuation time.

Let the valuation time correspond to coupon period s, with total maturity period count N. If the remaining future cash flows are C_{s+1}, \dots, C_N, and i_p is the effective yield per coupon period, then the book value at time s is

BV_s = \sum_{r=s+1}^{N} C_r (1+i_p)^{-(r-s)}.

This is the prospective book value on the bond's yield basis.

Value

If tidy = FALSE, a numeric vector of book values, one for each t.

If tidy = TRUE, a tibble with valuation times, valuation periods, book values, yield information, and bond inputs.

See Also

bond_price, bond_cash_flows, bond_duration, bond_convexity

Other bonds: bond_callable_price(), bond_convexity(), bond_duration(), bond_price(), bond_ytm(), portfolio_convexity(), portfolio_duration()

Examples

# Book value at time 0 equals price
bond_book_value(
  face = 100,
  c = 0.08,
  n = 5,
  t = 0,
  k = 2,
  y = 0.06,
  y_type = "effective"
)

# Book value at several coupon dates
bond_book_value(
  face = 100,
  c = 0.08,
  n = 5,
  t = c(0, 1, 2, 3, 4, 5),
  k = 1,
  y = 0.06,
  y_type = "effective"
)

# Tidy output
bond_book_value(
  face = 100,
  c = 0.08,
  n = 5,
  t = c(0, 1, 2, 3, 4, 5),
  k = 1,
  y = 0.06,
  y_type = "effective",
  tidy = TRUE
)

# Yield given directly per coupon period
bond_book_value(
  face = 1000,
  c = 0.05,
  n = 10,
  t = c(0, 2, 4, 6),
  k = 2,
  y_effective_per_period = 0.03
)

Price of a callable bond at a target minimum yield

Description

Computes the maximum price an investor should pay for a callable bond in order to guarantee a specified minimum yield, using compact actuarial notation.

Usage

bond_callable_price(
  face,
  c,
  n,
  k = 1L,
  call_t,
  call_R,
  y_effective_per_period = NULL,
  y = NULL,
  y_type = "effective",
  y_m = 1L,
  R = NULL,
  tol = 1e-10,
  check = TRUE,
  tidy = FALSE
)

Arguments

Details

The bond is evaluated under each possible redemption scenario:

• each callable date with its associated call price, and

• final maturity with its final redemption value.

For each scenario, the bond price is computed using the target yield. The callable-bond price returned by this function is the smallest of those scenario prices, that is, the maximum price consistent with the target yield under the least favorable redemption scenario for the investor.

This follows the standard actuarial/financial interpretation used in introductory fixed-income mathematics: when a bond is callable at the issuer's option, the investor must protect against the redemption scenario that is least favorable to the investor at the required yield.

Assumptions:

• Coupons are paid in arrears at regular intervals.

• n * k must be an integer.

• Each call_t * k must be an integer.

• Stub periods are not supported.

• Pricing is performed at a coupon date; no accrued interest is included.

Yield input conventions:

• If y_effective_per_period is supplied, it takes precedence over y, y_type, and y_m, and is interpreted as the effective yield per coupon period.

• Otherwise, y, y_type, and y_m define an annual yield specification, which is converted first to annual effective yield and then to effective yield per coupon period.

This function follows the compact bond notation used in tidyactuarial: face is the face value, c is the annual coupon rate, n is maturity, k is coupon frequency, y is the target yield, R is the final redemption value, call_t is the vector of call times, and call_R is the vector of call prices.

Let the callable bond have possible redemption scenarios indexed by j = 1, \dots, J, where each scenario corresponds either to a call date or to final maturity. For scenario j, let P_j(y) denote the bond price computed at the target yield y assuming redemption occurs at that scenario time and value.

Then this function returns

\min_j P_j(y)

when tidy = FALSE.

This is the maximum price an investor can pay while still guaranteeing at least the target yield under the least favorable redemption scenario.

Value

If tidy = FALSE, a numeric scalar: the worst-case callable-bond price consistent with the target yield.

If tidy = TRUE, a tibble with one row per redemption scenario, including scenario prices and the worst-case indicator.

See Also

bond_price, bond_cash_flows, bond_book_value, bond_ytm

Other bonds: bond_book_value(), bond_convexity(), bond_duration(), bond_price(), bond_ytm(), portfolio_convexity(), portfolio_duration()

Examples

# Callable bond with two possible call dates
bond_callable_price(
  face = 100,
  c = 0.08,
  n = 10,
  k = 2,
  call_t = c(5, 7),
  call_R = c(105, 102),
  y = 0.06,
  y_type = "effective"
)

# Tidy output with all redemption scenarios
bond_callable_price(
  face = 100,
  c = 0.08,
  n = 10,
  k = 2,
  call_t = c(5, 7),
  call_R = c(105, 102),
  y = 0.06,
  y_type = "effective",
  tidy = TRUE
)

# Target yield given directly per coupon period
bond_callable_price(
  face = 1000,
  c = 0.05,
  n = 12,
  k = 2,
  call_t = c(4, 8),
  call_R = c(1030, 1015),
  y_effective_per_period = 0.028
)

Cash flow structure of a level coupon bond

Description

Builds the cash-flow schedule of a level coupon bond with constant coupon rate and a single redemption payment at maturity, using compact actuarial notation.

Usage

bond_cash_flows(face, c, n, k = 1L, R = NULL, tol = 1e-10, check = TRUE)

Arguments

Details

This function follows the compact bond notation used in tidyactuarial: face is the face value, c is the annual coupon rate, n is the term to maturity, k is the number of coupon payments per year, and R is the redemption value.

Stub periods are not supported; therefore, n * k must be an integer.

Value

A tibble with the bond cash-flow schedule. The main actuarial columns are t for payment time and cf for cash flow.

Examples

bond_cash_flows(
  face = 1000,
  c = 0.05,
  n = 10,
  k = 2,
  R = 1000
)

Discrete convexity of a level coupon bond under a flat yield

Description

Computes discrete convexity measures for a level coupon bond valued under a flat yield-to-maturity assumption, using compact actuarial notation.

Usage

bond_convexity(
  face,
  c,
  n,
  k = 1L,
  y_effective_per_period = NULL,
  y = NULL,
  y_type = "effective",
  y_m = 1L,
  R = NULL,
  tol = 1e-10,
  check = TRUE
)

Arguments

Details

Assumptions:

• Coupons are paid in arrears at regular intervals.

• n * k must be an integer.

• Stub periods are not supported.

• Valuation is at a coupon date with no accrued interest.

• A single flat yield is used to discount all cash flows.

Yield input conventions:

• If y_effective_per_period is supplied, it is interpreted as the effective yield per coupon period.

• Otherwise, y, y_type, and y_m define an annual yield specification, which is converted first to annual effective yield and then to effective yield per coupon period.

This function follows the compact bond notation used in tidyactuarial: face is the face value, c is the annual coupon rate, n is the time to maturity, k is the coupon frequency, y is the annual yield input, and R is the redemption value.

Let j be the effective yield per coupon period, k the number of coupon payments per year, and let cash flows C_r occur at coupon periods r = 1, \dots, N. With v = 1/(1+j) and P = \sum_r C_r v^r, the discrete convexity in coupon periods is

C_p = \frac{1}{P} \frac{\sum_{r=1}^{N} C_r r(r+1) v^r}{(1+j)^2}.

Discrete convexity in years is C_p / k^2.

This is the second-order sensitivity of the bond price to changes in the yield per period. Together with bond_duration, it is used in the second-order Taylor approximation of price changes.

Value

A one-row tibble with:

price

Dirty price at the given yield.

discrete_convexity_periods

Discrete convexity in coupon periods.

discrete_convexity_years

Discrete convexity in years.

yield_per_period

Effective yield per coupon period.

yield_effective_annual

Annual effective yield.

k

Coupon frequency.

n_periods

Total number of coupon periods.

See Also

bond_duration, bond_price, bond_cash_flows, bond_book_value, bond_ytm

Other bonds: bond_book_value(), bond_callable_price(), bond_duration(), bond_price(), bond_ytm(), portfolio_convexity(), portfolio_duration()

Examples

bond_convexity(
  face = 100,
  c = 0.08,
  n = 5,
  k = 2,
  y = 0.06,
  y_type = "effective"
)

bond_convexity(
  face = 1000,
  c = 0.05,
  n = 10,
  k = 2,
  y_effective_per_period = 0.03
)

Macaulay and modified duration of a level coupon bond under a flat yield

Description

Computes Macaulay duration and modified-duration measures for a level coupon bond valued under a flat yield-to-maturity assumption, using compact actuarial notation.

Usage

bond_duration(
  face,
  c,
  n,
  k = 1L,
  y_effective_per_period = NULL,
  y = NULL,
  y_type = "effective",
  y_m = 1L,
  R = NULL,
  tol = 1e-10,
  check = TRUE
)

Arguments

Details

Assumptions:

• Coupons are paid in arrears at regular intervals.

• n * k must be an integer.

• Stub periods are not supported.

• Valuation is at a coupon date with no accrued interest.

• A single flat yield is used to discount all cash flows.

Yield input conventions:

• If y_effective_per_period is supplied, it is interpreted as the effective yield per coupon period.

• Otherwise, y, y_type, and y_m define an annual yield specification, which is converted first to annual effective yield and then to effective yield per coupon period.

This function follows the compact bond notation used in tidyactuarial: face is the face value, c is the annual coupon rate, n is the time to maturity, k is the coupon frequency, y is the annual yield input, and R is the redemption value.

Let j be the effective yield per coupon period, k the number of coupon payments per year, and let cash flows C_r occur at coupon periods r = 1, \dots, N. With v = 1/(1+j) and P = \sum_r C_r v^r:

Macaulay duration in coupon periods:

D_p = \frac{\sum_{r=1}^{N} r C_r v^r}{P}.

Macaulay duration in years is D = D_p / k.

Modified duration with respect to j, in coupon periods, is D^*_j = D_p / (1 + j).

Modified duration with respect to the annual effective rate i, in years, is D^*_i = D / (1 + i), where i = (1+j)^k - 1.

Modified duration measures the first-order sensitivity of the bond price to yield changes. Together with bond_convexity, it forms the second-order Taylor approximation of price changes.

Value

A one-row tibble with:

price

Dirty price at the given yield.

macaulay_duration_periods

Macaulay duration in coupon periods.

macaulay_duration_years

Macaulay duration in years.

modified_duration_periods_j

Modified duration with respect to the effective yield per coupon period, expressed in coupon periods.

modified_duration_years_i

Modified duration with respect to the annual effective yield, expressed in years.

yield_per_period

Effective yield per coupon period.

yield_effective_annual

Annual effective yield.

k

Coupon frequency.

n_periods

Total number of coupon periods.

See Also

bond_convexity, bond_price, bond_cash_flows, bond_book_value, bond_ytm

Other bonds: bond_book_value(), bond_callable_price(), bond_convexity(), bond_price(), bond_ytm(), portfolio_convexity(), portfolio_duration()

Examples

bond_duration(
  face = 100,
  c = 0.08,
  n = 5,
  k = 2,
  y = 0.06,
  y_type = "effective"
)

bond_duration(
  face = 1000,
  c = 0.05,
  n = 10,
  k = 2,
  y_effective_per_period = 0.03
)

Price of a level coupon bond from its yield

Description

Computes the dirty price of a level coupon bond at time 0 from its yield, using compact actuarial notation.

Usage

bond_price(
  face,
  c,
  n,
  k = 1L,
  y_effective_per_period = NULL,
  y = NULL,
  y_type = "effective",
  y_m = 1L,
  R = NULL,
  tol = 1e-10,
  check = TRUE
)

Arguments

Details

Assumptions:

• Coupons are paid in arrears at regular intervals.

• n * k must be an integer.

• Stub periods are not supported.

• No accrued interest is considered; the price is evaluated at a coupon date.

The yield may be supplied in either of two ways:

• directly as an effective yield per coupon period through y_effective_per_period, or

• as an annual rate specification through y, y_type, and y_m.

If an annual rate specification is supplied, it is first converted to the equivalent annual effective yield and then to the effective yield per coupon period.

This function follows the compact bond notation used in tidyactuarial: face is the face value, c is the annual coupon rate, n is the time to maturity, k is the coupon frequency, y is the annual yield input, and R is the redemption value.

Let j be the effective yield per coupon period, k the number of coupon payments per year, and let N = nk be the total number of coupon periods. With coupon per period C = face \cdot c/k and discount factor v = 1/(1+j), the price is:

P = \sum_{r=1}^{N} C_r v^r,

where the sum runs over all coupon and redemption cash flows indexed by coupon period r.

Value

Numeric scalar: dirty price of the bond at time 0.

See Also

bond_ytm, bond_cash_flows, bond_duration, bond_convexity, bond_book_value, bond_callable_price

Other bonds: bond_book_value(), bond_callable_price(), bond_convexity(), bond_duration(), bond_ytm(), portfolio_convexity(), portfolio_duration()

Examples

# 5-year annual coupon bond, yield given as annual effective
bond_price(
  face = 100,
  c = 0.08,
  n = 5,
  k = 1,
  y = 0.06,
  y_type = "effective"
)

# 10-year semiannual bond, yield given directly per coupon period
bond_price(
  face = 1000,
  c = 0.05,
  n = 10,
  k = 2,
  y_effective_per_period = 0.03
)

# Semiannual coupons, nominal annual yield convertible quarterly
bond_price(
  face = 100,
  c = 0.08,
  n = 5,
  k = 2,
  y = 0.06,
  y_type = "nominal_interest",
  y_m = 4
)

Yield to maturity of a level coupon bond

Description

Computes the yield to maturity (YTM) of a level coupon bond given its observed dirty price at time 0, using compact actuarial notation.

Usage

bond_ytm(
  P,
  face,
  c,
  n,
  k = 1L,
  R = NULL,
  interval = NULL,
  tol = 1e-12,
  maxiter = 1000,
  check = TRUE
)

Arguments

Details

The YTM is solved first as the effective yield per coupon period and then reported together with common annual equivalents.

Assumptions:

• Coupons are paid in arrears at regular intervals.

• Price is observed at a coupon date (no accrued interest).

• n * k must be an integer.

• Stub periods are not supported.

This function follows the compact bond notation used in tidyactuarial: P is the observed dirty price, face is the face value, c is the annual coupon rate, n is the time to maturity, k is the coupon frequency, and R is the redemption value.

The effective yield per coupon period j is the solution to

P = \sum_{r=1}^{N} C_r (1+j)^{-r}.

The root is found numerically using uniroot. If no interval is supplied, the function automatically brackets the root starting from (-0.999999, 0.10) and progressively widens the upper bound until a sign change is detected.

From the per-period yield, the annual equivalents are:

j^{(k)} = k j, \qquad i = (1 + j)^k - 1.

Value

A one-row tibble with columns:

price

Input dirty price.

i_period

Effective yield per coupon period.

j_nominal

Nominal annual yield convertible k times per year (= k * i_period). When k = 2, this is the bond-equivalent yield.

i_effective_annual

Annual effective yield.

k

Coupon frequency.

See Also

bond_price, bond_cash_flows, bond_duration, bond_convexity, bond_callable_price

Other bonds: bond_book_value(), bond_callable_price(), bond_convexity(), bond_duration(), bond_price(), portfolio_convexity(), portfolio_duration()

Examples

bond_ytm(
  P = 100,
  face = 100,
  c = 0.06,
  n = 5,
  k = 1
)

bond_ytm(
  P = 950,
  face = 1000,
  c = 0.05,
  n = 10,
  k = 2
)

Sample bond contracts for fixed-income examples

Description

A small pedagogical dataset containing bond contracts for pricing, yield-to-maturity, duration, and convexity examples.

A small pedagogical dataset containing bond contracts for pricing, yield-to-maturity, duration, and convexity examples.

Usage

bonds_sample

bonds_sample

Format

A tibble with 5 rows and 8 variables:

bond_id

Bond identifier.

face

Face value of the bond.

c

Annual coupon rate.

k

Number of coupon payments per year.

n

Maturity in years.

y

Annual nominal yield rate consistent with coupon frequency.

bond_type

Short bond type label.

P

Theoretical bond price computed from the listed yield rate.

A tibble with 5 rows and 8 variables:

bond_id

Bond identifier.

face

Face value of the bond.

c

Annual coupon rate.

k

Number of coupon payments per year.

n

Maturity in years.

y

Annual nominal yield rate consistent with coupon frequency.

bond_type

Short bond type label.

P

Theoretical bond price computed from the listed yield rate.

Details

This dataset uses the compact bond notation adopted in tidyactuarial: face is the face value, c is the annual coupon rate, k is the coupon frequency, n is the maturity, y is the yield input, and P is the bond price.

This dataset uses the compact bond notation adopted in tidyactuarial: face is the face value, c is the annual coupon rate, k is the coupon frequency, n is the maturity, y is the yield input, and P is the bond price.

Source

Synthetic pedagogical data created for tidyactuarial examples.

Synthetic pedagogical data created for tidyactuarial examples.

Examples

data(bonds_sample)

bonds_sample |>
  dplyr::select(bond_id, face, c, k, n, y, P)

data(bonds_sample)

bonds_sample |>
  dplyr::select(bond_id, face, c, k, n, y, P)

Sample cash flows for interest theory examples

Description

A small pedagogical dataset containing cash-flow scenarios for present value, future value, net present value, internal rate of return, equations of value, and cash-flow diagrams.

A small pedagogical dataset containing cash-flow scenarios for present value, future value, net present value, internal rate of return, equations of value, and cash-flow diagrams.

Usage

cash_flows_sample

cash_flows_sample

Format

A tibble with 19 rows and 5 variables:

scenario_id

Scenario identifier.

t

Payment time.

C

Cash-flow amount. Negative values represent outflows and positive values represent inflows.

cashflow_type

Type of cash flow.

description

Short description of the cash flow.

A tibble with 19 rows and 5 variables:

scenario_id

Scenario identifier.

t

Payment time.

C

Cash-flow amount. Negative values represent outflows and positive values represent inflows.

cashflow_type

Type of cash flow.

description

Short description of the cash flow.

Details

This dataset uses the compact financial-actuarial notation used throughout tidyactuarial: t denotes time and C denotes the cash-flow amount at that time.

This dataset uses the compact financial-actuarial notation used throughout tidyactuarial: t denotes time and C denotes the cash-flow amount at that time.

Source

Synthetic pedagogical data created for tidyactuarial examples.

Synthetic pedagogical data created for tidyactuarial examples.

Examples

data(cash_flows_sample)

cash_flows_sample |>
  dplyr::filter(scenario_id == "investment_project") |>
  dplyr::select(scenario_id, t, C, cashflow_type)

data(cash_flows_sample)

cash_flows_sample |>
  dplyr::filter(scenario_id == "investment_project") |>
  dplyr::select(scenario_id, t, C, cashflow_type)

Build an annual commutation table (discrete ages)

Description

The function builds annual commutation columns from x, lx, and an interest-rate specification. The interest rate is converted internally to an annual effective rate before constructing the discount factor.

Usage

commutation_table(lt, i, i_type = "effective", m = 1L, check = TRUE)

Arguments

Details

Constructs classical annual commutation functions D_x, N_x, S_x, C_x, M_x, and R_x from a life table defined at integer ages, using compact actuarial notation.

This function follows the compact actuarial notation used throughout tidyactuarial: lt is the life table, i is the interest-rate input, i_type is the interest-rate type, and m is the conversion frequency for nominal rates.

The annual effective rate is obtained through standardize_interest. If i_e denotes the annual effective rate, then

v = \frac{1}{1+i_e}.

The annual deaths are computed as

d_x = l_x - l_{x+1},

closing the table with l_{\omega+1}=0. The main commutation functions are then computed as

D_x = v^x l_x, \qquad C_x = v^{x+1} d_x,

with reverse cumulative sums used to obtain N_x, S_x, M_x, and R_x.

Value

A tibble with columns x, lx, dx, v, Dx, Nx, Sx, Cx, Mx, and Rx.

Examples

lt <- data.frame(
  x = 60:65,
  lx = c(100000, 99000, 97500, 95500, 93000, 90000)
)

commutation_table(
  lt = lt,
  i = 0.05
)

commutation_table(
  lt = lt,
  i = 0.06,
  i_type = "nominal_interest",
  m = 12
)

Spot discount factor

Description

Computes the discount factor implied by a spot rate for a given time, using compact actuarial notation.

Usage

discount_factor_spot(t, i, i_type = "effective", m = 1L, tidy = FALSE)

Arguments

Details

The spot rate may be supplied in FM-style notation:

• annual effective rate,

• nominal annual interest rate,

• nominal annual discount rate,

• force of interest.

Internally, the supplied spot rate is first converted to the equivalent annual effective rate using standardize_interest. The discount factor is then computed as

v(t) = (1+i)^{-t}.

This function follows the compact actuarial notation used throughout tidyactuarial: t denotes time, i denotes the spot-rate input, i_type denotes the interest-rate type, and m denotes the conversion frequency for nominal rates.

If t = 0, the discount factor is 1.

Input vectors must have length 1 or a common length. Missing values are propagated.

Value

If tidy = FALSE, a numeric vector of discount factors.

If tidy = TRUE, a tibble with input values, standardized rates, and discount factors.

See Also

standardize_interest, present_value, pv_flow

Other interest: forward_rate(), interest_equivalents(), standardize_interest(), yield_curve()

Examples

# Numeric discount factor
discount_factor_spot(
  t = 3,
  i = 0.05
)

# Vectorized example
discount_factor_spot(
  t = c(1, 2, 3),
  i = c(0.05, 0.055, 0.06)
)

# FM-style input with nominal annual interest
discount_factor_spot(
  t = 2,
  i = 0.08,
  i_type = "nominal_interest",
  m = 2
)

# Tibble output for teaching or auditing
discount_factor_spot(
  t = c(1, 2, 3),
  i = c(0.05, 0.055, 0.06),
  tidy = TRUE
)

Expected future lifetime from an annual life table

Description

Computes the curtate or complete expected future lifetime at integer age x, optionally restricted to a temporary horizon of t years.

Usage

e_x(
  lt,
  x,
  t = NULL,
  type = c("curtate", "complete"),
  frac,
  tidy = FALSE,
  check = TRUE,
  tol = 1e-10
)

Arguments

Details

Curtate life expectancy (Finan, Section 23.7):

e_x = \sum_{k=1}^{\omega - x} {}_k p_x = \frac{1}{\ell_x} \sum_{k=1}^{\omega - x} \ell_{x+k}.

The t-year temporary curtate expectancy is (Finan, Sec. 23.7):

e_{x:\overline{t}|} = \sum_{k=1}^{t} {}_k p_x.

Complete life expectancy (Finan, Section 23.3):

\breve{e}_x = \int_0^{\omega - x} {}_t p_x \, dt = \frac{T_x}{\ell_x}.

The integral is decomposed year-by-year. Within each year, the within-year survival integral \int_0^s {}_u p_y \, du is evaluated in closed form under the selected fractional-age assumption (Finan, Section 24):

• UDD (Sec. 24.1): \int_0^s {}_u p_y \, du = s - \frac{1}{2} s^2 q_y

• CF (Sec. 24.2): \int_0^s {}_u p_y \, du = (1 - p_y^s) / (-\ln p_y)

• Balducci (Sec. 24.3): \int_0^s {}_u p_y \, du = \frac{p_y}{q_y} \ln \left( \frac{p_y + q_y s}{p_y} \right)

Under UDD, the complete expectancy satisfies the well-known approximation (Finan, Example 20.24):

\breve{e}_x \approx e_x + \frac{1}{2}.

Value

A numeric vector of expected future lifetimes, or a tibble if tidy = TRUE with columns x, t, type, frac, ex.

Expected future lifetime for two independent lives

Description

Computes the expected future lifetime for two independent lives aged x and y, for either joint-life (first death) or last-survivor (second death).

Usage

e_xy(
  lt,
  x,
  y,
  t = NULL,
  type = c("curtate", "complete"),
  frac,
  cohort = c("first", "last"),
  tidy = FALSE,
  check = TRUE,
  tol = 1e-10
)

Arguments

Details

Curtate expectation (Finan, Section 56.4 / Section 57):

e_{xy} = \sum_{k=1}^{\infty} {}_kp_{xy}, \quad e_{\overline{xy}} = \sum_{k=1}^{\infty} {}_kp_{\overline{xy}}.

Complete expectation (Finan, Section 56.4):

\mathring{e}_{xy} = \int_0^{\infty} {}_tp_{xy} \, dt.

The integral is decomposed year-by-year. Within each year, the survival integral for the two-life status is computed numerically via composite trapezoid (80-point grid), since closed-form expressions for joint/last survivor under fractional-age assumptions are complex.

Key identity (Finan, Example 57.4):

\mathring{e}_{\overline{xy}} = \mathring{e}_x + \mathring{e}_y - \mathring{e}_{xy}.

This can be used to cross-validate results.

Value

Numeric vector, or tibble if tidy = TRUE.

See Also

e_x for single-life expectancy, t_pxy for two-life survival probabilities, annuity_xy for two-life annuity APVs.

Examples

lt <- data.frame(
  x  = 60:66,
  lx = c(100000, 99000, 97500, 95500, 93000, 90000, 86000)
)

# Curtate joint-life expectancy (Finan, Sec. 56.4)
e_xy(lt, x = 60, y = 62, type = "curtate", cohort = "first")

# Curtate last-survivor expectancy (Finan, Sec. 57)
e_xy(lt, x = 60, y = 62, type = "curtate", cohort = "last")

# Verify identity (Finan, Example 57.4):
# e_{xy-bar} = e_x + e_y - e_xy
e_joint <- e_xy(lt, x = 60, y = 62, type = "curtate", cohort = "first")
e_last  <- e_xy(lt, x = 60, y = 62, type = "curtate", cohort = "last")
e_x_val <- e_x(lt, x = 60, type = "curtate")
e_y_val <- e_x(lt, x = 62, type = "curtate")
c(last_surv = e_last, sum_minus_joint = e_x_val + e_y_val - e_joint)

# Complete joint-life expectancy under UDD
e_xy(lt, x = 60, y = 62, type = "complete", frac = "UDD", cohort = "first")

# Temporary: 3-year curtate joint-life
e_xy(lt, x = 60, y = 62, t = 3, type = "curtate", cohort = "first")

# Tidy output
e_xy(lt, x = 60, y = 62, type = "curtate", cohort = "first", tidy = TRUE)

Compute an implied forward rate from a discrete spot curve

Description

Returns the annual effective forward rate implied between two maturities from a discrete yield curve stored in tibble-first format, using compact actuarial notation.

Usage

forward_rate(
  .data = NULL,
  t = NULL,
  i = NULL,
  t_start = NULL,
  t_end = NULL,
  col_t = "t",
  col_i = "i",
  col_t_start = "t_start",
  col_t_end = "t_end",
  i_type = "effective",
  m = 1L,
  method = c("exact", "linear"),
  plot = FALSE,
  .out = "f",
  .out_plot = "forward_rate_plot",
  .keep = c("all", "used", "none"),
  .na = c("propagate", "error", "drop")
)

Arguments

Details

Each row is treated as one curve. For tibble input, col_t and col_i must be list-columns of equal-length numeric vectors, and col_t_start and col_t_end must be numeric columns giving the forward interval for each row.

The implied forward rate is computed from the standardized annual effective spot curve through:

(1+i_1)^{t_1}(1+f)^{t_2-t_1}=(1+i_2)^{t_2}

so that

f_{t_1,t_2} = \left(\frac{(1+i_2)^{t_2}}{(1+i_1)^{t_1}}\right)^{1/(t_2-t_1)} - 1.

Two extraction methods are supported for the spot rates:

• "exact": requires that t_start and t_end match curve nodes.

• "linear": uses linear interpolation between adjacent nodes.

No extrapolation is performed outside the observed maturity range.

This function follows the compact actuarial notation used throughout tidyactuarial: t denotes maturity, i denotes the spot rate, i_type denotes the interest-rate type, and m denotes the conversion frequency for nominal spot rates. The output column f denotes the implied annual effective forward rate.

Spot-rate inputs are converted to annual effective form using standardize_interest before interpolation and forward-rate calculation.

Value

A tibble. By default it returns the original columns plus a new numeric column named by .out. If plot = TRUE, it also adds a list-column named by .out_plot containing ggplot2 objects.

References

Marcel B. Finan, A Basic Course in the Theory of Interest and Derivatives Markets: A Preparation for the Actuarial Exam FM/2, Section 53: The Term Structure of Interest Rates and Yield Curves.

Kellison, S. G. The Theory of Interest, Chapter 10: The Term Structure of Interest Rates.

See Also

yield_curve, discount_factor_spot, standardize_interest

Other interest: discount_factor_spot(), interest_equivalents(), standardize_interest(), yield_curve()

Examples

# Simple example: exact forward rate
forward_rate(
  t = c(1, 2, 3, 4, 5),
  i = c(0.040, 0.045, 0.048, 0.050, 0.051),
  t_start = 2,
  t_end = 5
)

# Interpolated forward rates for multiple curves
curves <- tibble::tibble(
  curve_id = c("A", "B"),
  t = list(c(1, 2, 3, 5), c(1, 3, 5, 7)),
  i = list(c(0.04, 0.05, 0.055, 0.06),
           c(0.03, 0.035, 0.04, 0.045)),
  t_start = c(2, 2),
  t_end = c(4, 6)
)

forward_rate(
  curves,
  method = "linear",
  plot = TRUE
)

# Nominal annual spot rates convertible semiannually
forward_rate(
  t = c(1, 2, 3),
  i = c(0.05, 0.055, 0.06),
  i_type = "nominal_interest",
  m = 2,
  t_start = 1,
  t_end = 3
)

Future value of a single payment

Description

Computes the future value of a payment invested at time 0 and accumulated to a given time, using the annual effective interest rate implied by the supplied interest-rate specification and compact actuarial notation.

Usage

future_value(C, i, i_type = "effective", m = 1, t, tidy = FALSE)

Arguments

Details

The future value is computed as

FV = C(1+i)^t

where i is the annual effective interest rate.

The input interest rate may be supplied as:

• annual effective interest rate,

• nominal annual interest rate,

• nominal annual discount rate,

• force of interest.

Internally, all rate specifications are first converted to the equivalent annual effective interest rate using standardize_interest.

This function follows the compact actuarial notation used throughout tidyactuarial: C denotes the initial payment amount or capital, t denotes time, i denotes the interest-rate input, i_type denotes the interest-rate type, and m denotes the conversion frequency for nominal rates.

Input vectors must have length 1 or a common length. Missing values are propagated. This function does not accept dates; use fv_flow for dated cash flows.

Value

If tidy = FALSE, a numeric vector of future values.

If tidy = TRUE, a tibble with input values, equivalent rates, accumulation factors, and future values.

See Also

standardize_interest, present_value, fv_flow

Other time-value: fv_flow(), irr_flow(), irr_flow_multi(), plot_cash_flow(), present_value(), pv_flow()

Examples

# Numeric future value
future_value(C = 1000, i = 0.08, t = 3)

# Nominal interest converted monthly
future_value(
  C = 1000,
  i = 0.12,
  i_type = "nominal_interest",
  m = 12,
  t = 5
)

# Tibble output for teaching or auditing
future_value(
  C = 1000,
  i = 0.08,
  t = 3,
  tidy = TRUE
)

# Vectorized example
future_value(
  C = c(1000, 2500, 4000),
  i = c(0.08, 0.10, 0.12),
  i_type = c("effective", "nominal_interest", "force"),
  m = c(1, 12, 1),
  t = c(3, 5, 2)
)

Future value of a general cash flow

Description

Computes the future value of a cash-flow vector under either:

• a constant interest-rate specification, or

• a term structure of spot rates, one rate per cash flow.

Usage

fv_flow(
  cf,
  i,
  i_type = "effective",
  m = 1L,
  t = NULL,
  date = NULL,
  day_count = c("act/365", "act/360"),
  tol = 1e-10
)

Arguments

Details

The cash flow is supplied explicitly through cf. Its timing is supplied either through t (in years) or date (calendar dates). If date is supplied, the earliest date is taken as time 0.

The future value is accumulated to the latest payment time or latest date.

Interest-rate input:

• If i has length 1, the same rate is used for all cash flows.

• If i has the same length as cf, each rate is interpreted as the annual effective spot rate associated with the corresponding cash-flow time.

Rate types may be supplied in FM-style notation:

• annual effective rate i,

• nominal annual interest rate j^{(m)},

• nominal annual discount rate d^{(m)},

• force of interest \delta.

Internally, all supplied rates are converted to annual effective rates using standardize_interest. When i is a vector, the accumulation uses the implied discount-factor ratio under the spot-rate interpretation.

This function follows the compact actuarial notation used throughout tidyactuarial: cf denotes cash flows, t denotes time, i denotes the interest rate, i_type denotes the interest-rate type, and m denotes the conversion frequency for nominal rates.

Let T be the latest cash-flow time, the accumulation horizon. For each cash flow C_k at time t_k with annual effective spot rate i_k, the future value contribution is

FV_k = C_k \cdot \frac{(1+i_T)^T}{(1+i_k)^{t_k}}.

The total future value is FV = \sum_k FV_k. When a single constant rate is supplied, i_k = i_T = i for all k, and the formula simplifies to

FV = \sum_k C_k (1+i)^{T-t_k}.

Value

Numeric scalar: the future value of the cash flow accumulated to the latest cash-flow time.

See Also

pv_flow, future_value, standardize_interest

Other time-value: future_value(), irr_flow(), irr_flow_multi(), plot_cash_flow(), present_value(), pv_flow()

Examples

# Constant annual effective rate
fv_flow(
  cf = c(100, 150, 200),
  i = 0.08,
  i_type = "effective",
  t = c(0, 1, 2)
)

# Spot rates, one per cash flow
fv_flow(
  cf = c(100, 150, 200),
  i = c(0.05, 0.055, 0.06),
  i_type = "effective",
  t = c(1, 2, 3)
)

# Using dates; earliest date is taken as t = 0
fv_flow(
  cf = c(100, 150, 200),
  i = c(0.05, 0.055, 0.06),
  i_type = "effective",
  date = as.Date(c("2026-01-10", "2027-01-10", "2028-01-10"))
)

# Nominal rates by cash flow
fv_flow(
  cf = c(100, 100, 100),
  i = c(0.12, 0.12, 0.12),
  i_type = "nominal_interest",
  m = c(12, 12, 12),
  t = c(1, 2, 3)
)

Duration-based immunization with multiple assets

Description

Computes asset weights that duration-immunize a stream of liabilities using two or more assets, using compact actuarial notation.

Usage

immunize_duration(L, t, P, D, i, i_type = "effective", m = 1L)

Arguments

Details

The method enforces:

1. present value of assets = present value of liabilities;

2. Macaulay duration of assets = Macaulay duration of liabilities.

For exactly two assets, a closed-form solution is used. For three or more assets, a minimum-norm solution is computed by linear algebra.

This function follows the compact actuarial notation used throughout tidyactuarial: L denotes liabilities, t denotes payment times, P denotes asset prices or present values, D denotes asset durations, i denotes the interest rate, i_type denotes the interest-rate type, and m denotes the conversion frequency for nominal rates.

Let PV_L and D_L be the present value and Macaulay duration of the liability stream at yield i. Let P_j and D_j be the price and duration of asset j. The weights w_j are chosen so that:

\sum_j w_j P_j = PV_L

and

\frac{\sum_j w_j P_j D_j}{\sum_j w_j P_j} = D_L.

For two assets, the closed-form solution is:

w_1 = \frac{PV_L(D_L - D_2)}{P_1(D_1 - D_2)}, \qquad w_2 = \frac{PV_L - w_1 P_1}{P_2}.

For three or more assets, the minimum-norm solution of the linear system Aw = b is computed, where A is a 2 \times r matrix with rows

(P_1,\ldots,P_r)

and

(P_1D_1,\ldots,P_rD_r),

and

b = (PV_L, PV_LD_L)^T.

Value

A tibble with:

w

Numeric vector of asset weights or units.

PV_L

Present value of the liabilities.

D_L

Macaulay duration of the liabilities.

PV_A

Present value of the immunized asset portfolio.

D_A

Macaulay duration of the asset portfolio.

n_assets

Number of assets used.

See Also

immunize_duration_convexity, bond_duration, bond_convexity

Other immunization: immunize_duration_convexity(), plot_immunization_gap()

Examples

# Two-asset immunization
immunize_duration(
  L = c(5000, 8000),
  t = c(3, 7),
  P = c(100, 200),
  D = c(3, 7),
  i = 0.05
)

# Three-asset immunization: minimum-norm solution
immunize_duration(
  L = c(5000, 8000),
  t = c(3, 7),
  P = c(100, 150, 200),
  D = c(2, 5, 8),
  i = 0.05
)

# Nominal annual interest rate convertible monthly
immunize_duration(
  L = c(5000, 8000),
  t = c(3, 7),
  P = c(100, 200),
  D = c(3, 7),
  i = 0.06,
  i_type = "nominal_interest",
  m = 12
)

Duration and convexity immunization with multiple assets

Description

Computes asset weights that immunize a stream of liabilities using three or more assets, enforcing:

1. present value of assets = present value of liabilities;

2. Macaulay duration of assets = Macaulay duration of liabilities;

3. convexity of assets = convexity of liabilities.

Usage

immunize_duration_convexity(L, t, P, D, C, i, i_type = "effective", m = 1L)

Arguments

Details

For exactly three assets, the system is solved directly. For four or more assets, a minimum-norm solution is computed by linear algebra.

This function follows the compact actuarial notation used throughout tidyactuarial: L denotes liabilities, t denotes payment times, P denotes asset prices or present values, D denotes asset durations, C denotes asset convexities, i denotes the interest rate, i_type denotes the interest-rate type, and m denotes the conversion frequency for nominal rates.

Let PV_L, D_L, and C_L be the present value, Macaulay duration, and discrete convexity of the liability stream at yield i. The discrete convexity of the liabilities is computed as:

C_L = \frac{\sum_t L_t\,t(t+1)\,v^{t+2}}{PV_L},

where v = 1/(1+i) after converting i to the equivalent effective rate.

The weights w_j satisfy the 3 \times r system Aw = b, where the rows of A are

(P_1,\ldots,P_r),

(P_1D_1,\ldots,P_rD_r),

and

(P_1C_1,\ldots,P_rC_r),

and

b = (PV_L,\; PV_LD_L,\; PV_LC_L)^T.

For three assets, the system is square and solved directly. For four or more assets, the minimum-norm solution

w = A^T(AA^T)^{-1}b

is computed.

Value

A tibble with:

w

Numeric vector of asset weights or units.

PV_L

Present value of the liabilities.

D_L

Macaulay duration of the liabilities.

C_L

Discrete convexity of the liabilities.

PV_A

Present value of the asset portfolio.

D_A

Macaulay duration of the asset portfolio.

C_A

Discrete convexity of the asset portfolio.

n_assets

Number of assets used.

See Also

immunize_duration, bond_duration, bond_convexity

Other immunization: immunize_duration(), plot_immunization_gap()

Examples

# Three-asset immunization
immunize_duration_convexity(
  L = c(5000, 8000, 10000),
  t = c(3, 5, 7),
  P = c(100, 150, 200),
  D = c(2, 5, 8),
  C = c(6, 30, 72),
  i = 0.05
)

# Four-asset immunization: minimum-norm solution
immunize_duration_convexity(
  L = c(5000, 8000, 10000),
  t = c(3, 5, 7),
  P = c(100, 120, 150, 200),
  D = c(2, 4, 6, 8),
  C = c(6, 20, 42, 72),
  i = 0.05
)

# Nominal annual interest rate convertible monthly
immunize_duration_convexity(
  L = c(5000, 8000, 10000),
  t = c(3, 5, 7),
  P = c(100, 150, 200),
  D = c(2, 5, 8),
  C = c(6, 30, 72),
  i = 0.06,
  i_type = "nominal_interest",
  m = 12
)

Actuarial present value of a life insurance with variable k-thly benefits

Description

Computes the actuarial present value of a life insurance where the death benefit may vary by subperiod and is payable at the end of the subperiod of death, using compact actuarial notation.

Usage

insurance_variable_k(
  lt,
  x,
  i,
  benefit,
  n = NULL,
  h = 0,
  k = 12,
  i_type = "effective",
  m = 1L,
  frac,
  tidy = FALSE,
  check = TRUE,
  tol = 1e-10
)

Arguments

Details

This function is useful for level, increasing, decreasing, and credit-style life insurance benefits when benefits are specified at a subannual frequency.

This function follows the compact actuarial notation used throughout tidyactuarial: lt is the life table, x is the age at issue, i is the interest-rate input, i_type is the interest-rate type, m is the conversion frequency for nominal rates, n is the term, h is the deferment period, and k is the number of subperiods per year.

Let k be the number of subperiods per year and N = nk the total number of subperiods in the insurance term. With deferment h, the actuarial present value at age x is:

APV = \sum_{j=1}^{N} v^{h + j/k} b_j \left({}_{h + (j-1)/k}p_x - {}_{h + j/k}p_x\right).

Here b_j is the benefit payable if death occurs in subperiod j, and v = (1+i_e)^{-1}, where i_e is the annual effective interest rate equivalent to the input i, i_type, and m.

If benefit is numeric of length 1, it is recycled to all subperiods. If it is numeric with length greater than 1, its length must equal n k. If benefit is a function, it is evaluated at the end of each subperiod, at times 1/k, 2/k, \ldots, n.

Fractional survival probabilities are computed via t_px under the selected fractional-age assumption.

Value

A numeric actuarial present value, or a one-row tibble if tidy = TRUE.

See Also

insurance_x for level-benefit life insurance, annuity_x for life annuity APVs, t_px for survival probabilities.

Other life-contingencies: annuity_multi(), annuity_x(), annuity_xy(), insurance_x(), insurance_xy(), life_contract(), premium_gross(), premium_x(), premium_xy(), reserve_x(), reserve_xy(), simulate_annuity_x(), simulate_insurance_x()

Examples

lt <- data.frame(
  x  = 60:66,
  lx = c(100000, 99000, 97500, 95500, 93000, 90000, 86000)
)

# Monthly insurance with increasing benefits
insurance_variable_k(
  lt = lt,
  x = 60,
  i = 0.05,
  benefit = seq(100, 1200, length.out = 12),
  n = 1,
  k = 12
)

# Credit-style insurance with declining outstanding balance
balance <- function(t) 2000 * exp(-0.3 * t)

insurance_variable_k(
  lt = lt,
  x = 60,
  i = 0.05,
  benefit = balance,
  n = 1,
  k = 12
)

# Level benefit with annual payments
insurance_variable_k(
  lt = lt,
  x = 60,
  i = 0.05,
  benefit = 1,
  n = 5,
  k = 1
)

# 2-year deferred, 3-year term with monthly varying benefits
insurance_variable_k(
  lt = lt,
  x = 60,
  i = 0.05,
  benefit = rep(1000, 36),
  n = 3,
  h = 2,
  k = 12
)

# Nominal annual interest convertible monthly
insurance_variable_k(
  lt = lt,
  x = 60,
  i = 0.06,
  i_type = "nominal_interest",
  m = 12,
  benefit = rep(1000, 12),
  n = 1,
  k = 12
)

# Tidy output
insurance_variable_k(
  lt = lt,
  x = 60,
  i = 0.05,
  benefit = rep(1000, 12),
  n = 1,
  k = 12,
  tidy = TRUE
)

Actuarial present value of a life insurance

Description

Computes the actuarial present value of a discrete single-life insurance using a life table and compact actuarial notation.

Usage

insurance_x(
  lt,
  x,
  i,
  i_type = "effective",
  m = 1L,
  n = Inf,
  h = 0L,
  type = c("whole", "term", "endowment"),
  benefit = 1,
  tidy = FALSE,
  ...
)

Arguments

Details

The benefit is paid at the end of the year of death for whole-life and term insurance. For endowment insurance, the same benefit is paid either at death within the term or at the end of the term if the life survives.

Supported contracts:

• "whole": whole-life insurance.

• "term": n-year term insurance.

• "endowment": n-year endowment insurance.

This function follows the compact actuarial notation used throughout tidyactuarial: lt is the life table, x is the age at issue, i is the interest-rate input, i_type is the interest-rate type, m is the conversion frequency for nominal rates, n is the insurance term, and h is the deferment period.

The function computes APVs directly from lx. For a deferred insurance, the value at age x + h is multiplied by

v^h\,{}_hp_x.

For whole-life insurance, the death benefit APV at the deferred starting age is computed over the available life-table horizon. For term and endowment insurance, the death benefit is computed over the first n years. Endowment insurance additionally includes the pure endowment component

v^n\,{}_np_x.

Value

If tidy = FALSE, a numeric scalar containing the actuarial present value.

If tidy = TRUE, a one-row tibble with the main input values, equivalent interest rate, deferral factor, pure endowment factor, annuity-due value used in the standard identities, and APV.

See Also

annuity_x, premium_x, reserve_x, t_Ex, insurance_xy

Other life-contingencies: annuity_multi(), annuity_x(), annuity_xy(), insurance_variable_k(), insurance_xy(), life_contract(), premium_gross(), premium_x(), premium_xy(), reserve_x(), reserve_xy(), simulate_annuity_x(), simulate_insurance_x()

Examples

lt <- data.frame(
  x  = 60:65,
  lx = c(100000, 99000, 97500, 95500, 93000, 90000)
)

# Whole-life insurance
insurance_x(
  lt = lt,
  x = 60,
  i = 0.06,
  type = "whole"
)

# 5-year term insurance
insurance_x(
  lt = lt,
  x = 60,
  i = 0.06,
  n = 5,
  type = "term"
)

# 5-year endowment insurance
insurance_x(
  lt = lt,
  x = 60,
  i = 0.06,
  n = 5,
  type = "endowment"
)

# Deferred whole-life insurance
insurance_x(
  lt = lt,
  x = 60,
  i = 0.06,
  h = 2,
  type = "whole"
)

# Tidy output
insurance_x(
  lt = lt,
  x = 60,
  i = 0.06,
  n = 5,
  type = "term",
  tidy = TRUE
)

Cause-specific term/whole-life insurance APV under multiple decrements

Description

This function evaluates cause-specific insurance benefits under a multiple decrement model. It supports whole-life and term insurance, integer deferment, vectorized issue ages and interest-rate assumptions, and compact actuarial notation.

Usage

insurance_xj(
  md,
  x,
  i,
  cause,
  type = c("whole", "term"),
  benefit = 1,
  n = NULL,
  h = 0L,
  i_type = "effective",
  m = 1L,
  tidy = FALSE,
  check = TRUE,
  tol = 1e-10
)

A_xj(
  md,
  x,
  i,
  cause,
  type = c("whole", "term"),
  benefit = 1,
  n = NULL,
  h = 0L,
  i_type = "effective",
  m = 1L,
  tidy = FALSE,
  check = TRUE,
  tol = 1e-10
)

Arguments

Details

Computes the actuarial present value (APV) of an annual discrete insurance that pays benefit at the end of the year of decrement by a specified cause j, using a multiple decrement table produced by md_table.

Let q_{x+k}^{(j)} be the one-year decrement probability for cause j at age x+k, and let p_{x+r}^{(\tau)} be the one-year total survival probability against all decrements at age x+r.

For a product with deferment h and term n, with benefit payable at the end of the year of decrement by cause j, the APV is:

\sum_{k=h}^{h+n-1} v^{k+1} \left(\prod_{r=0}^{k-1} p_{x+r}^{(\tau)}\right) q_{x+k}^{(j)}.

Here v = (1+i_e)^{-1}, where i_e is the annual effective interest rate obtained from i, i_type, and m.

If type = "whole", the function sets n to the remaining length of the table after deferment, that is, whole life over the available ages.

This function follows the compact actuarial notation used throughout tidyactuarial: md is a multiple decrement table, x is age at issue, i is the interest rate, i_type is the interest-rate type, m is the conversion frequency for nominal rates, n is the term, and h is the deferment period.

Value

Numeric vector of APVs, or a tibble if tidy = TRUE.

See Also

t_qxj for cause-specific decrement probabilities, lt_tau to build a single-decrement life table for the total decrement.

Examples

qx_df <- tibble::tibble(
  x = 30:35,
  q_death = c(0.001, 0.0012, 0.0014, 0.0017, 0.0020, 1.0000),
  q_disability = c(0.002, 0.0021, 0.0022, 0.0023, 0.0024, 0.0000)
)
md <- md_table(qx_df, radix = 1e5, close = TRUE)

# 5-year term cause-specific insurance for death, i = 5%
insurance_xj(
  md = md,
  x = 30,
  i = 0.05,
  cause = "q_death",
  type = "term",
  n = 5
)

# Whole-life over available ages, 2-year deferred
insurance_xj(
  md = md,
  x = 30,
  i = 0.05,
  cause = "q_death",
  type = "whole",
  h = 2,
  tidy = TRUE
)

Actuarial present value of a two-life insurance

Description

Computes the actuarial present value of a discrete two-life insurance with benefit payable at the end of the year of the triggering death, assuming independent future lifetimes and using compact actuarial notation.

Usage

insurance_xy(
  lt,
  x = NULL,
  y = NULL,
  i = NULL,
  i_type = "effective",
  m = 1L,
  type = c("whole", "term", "endowment"),
  status = c("joint", "last"),
  n = Inf,
  h = 0L,
  benefit = 1,
  frac,
  tidy = FALSE,
  ...
)

Arguments

Details

Supported contracts:

• "whole": whole-life two-life insurance.

• "term": n-year two-life term insurance.

• "endowment": n-year two-life endowment insurance.

The status argument determines the two-life status:

• status = "joint": first-death insurance, based on the joint-life status.

• status = "last": second-death insurance, based on the last-survivor status.

This function follows the compact actuarial notation used throughout tidyactuarial: lt is the life table input, x and y are the two actuarial ages, i is the interest-rate input, i_type is the interest-rate type, m is the conversion frequency for nominal rates, n is the insurance term, and h is the deferment period.

The function uses the standard fully discrete identities that express insurance values through two-life annuity-due values.

For a whole-life contract:

A = 1 - d \ddot{a}.

For an n-year term insurance:

A^1_{:\overline{n}|} = 1 - d\ddot{a}_{:\overline{n}|} - v^n\,{}_np.

For an n-year endowment insurance:

A_{:\overline{n}|} = 1 - d\ddot{a}_{:\overline{n}|}.

A deferred insurance is valued by multiplying the value at deferred ages x + h and y + h by the deferment factor

v^h\,{}_hp_{xy}

for the selected two-life status.

Value

If tidy = FALSE, a numeric scalar.

If tidy = TRUE, a one-row tibble with input values, standardized interest rate, deferment factor, unit APV, and APV.

See Also

annuity_xy, premium_xy, insurance_x, t_pxy

Other life-contingencies: annuity_multi(), annuity_x(), annuity_xy(), insurance_variable_k(), insurance_x(), life_contract(), premium_gross(), premium_x(), premium_xy(), reserve_x(), reserve_xy(), simulate_annuity_x(), simulate_insurance_x()

Examples

lt <- data.frame(
  x = 60:110,
  lx = seq(100000, 0, length.out = 51)
)

insurance_xy(
  lt = lt,
  x = 60,
  y = 62,
  i = 0.06,
  type = "whole",
  status = "joint"
)

insurance_xy(
  lt = lt,
  x = 60,
  y = 62,
  i = 0.06,
  type = "term",
  status = "last",
  n = 10,
  tidy = TRUE
)

lt |>
  life_contract(lives = "joint", x = 60, y = 62, i = 0.06) |>
  insurance_xy(
    type = "term",
    n = 4,
    status = "joint"
  )

Equivalent interest rates in FM actuarial notation

Description

Converts a single interest-rate specification into equivalent actuarial rates for the same conversion frequency m.

Usage

interest_equivalents(
  i_type = c("effective", "nominal_interest", "nominal_discount", "force"),
  i,
  m = 1L
)

Arguments

Details

Internally, the supplied rate is first converted to the annual effective interest rate i using standardize_interest.

This function follows the compact actuarial notation used throughout tidyactuarial: i denotes the interest-rate value, i_type denotes the type of interest rate, and m denotes the conversion frequency for nominal rates.

Given the annual effective interest rate i, the equivalents are:

Effective discount rate:

d = i/(1+i)

Discount factor:

v = 1/(1+i)

Force of interest:

\delta = \ln(1+i)

Nominal interest:

j^{(m)} = m[(1+i)^{1/m} - 1]

Nominal discount:

d^{(m)} = m[1 - (1+i)^{-1/m}]

Value

A tibble with columns:

family

Rate family: "effective", "discount", "force", "nominal_interest", or "nominal_discount".

notation

Actuarial notation for the equivalent rate.

m

Conversion frequency used for nominal rates.

description

Human-readable description.

value

Equivalent rate value.

See Also

standardize_interest, discount_factor_spot

Other interest: discount_factor_spot(), forward_rate(), standardize_interest(), yield_curve()

Examples

interest_equivalents(i_type = "nominal_interest", i = 0.18, m = 4)
interest_equivalents(i_type = "nominal_discount", i = 0.10, m = 12)
interest_equivalents(i_type = "force", i = 0.12)
interest_equivalents(i_type = "effective", i = 0.08)

# Batch use with purrr
if (requireNamespace("purrr", quietly = TRUE) &&
    requireNamespace("tibble", quietly = TRUE)) {
  cases <- tibble::tibble(
    i_type = c("effective", "force"),
    i = c(0.08, 0.12),
    m = c(1, 1)
  )

  purrr::pmap(cases, interest_equivalents)
}

Internal rate of return for a cash flow

Description

Computes the internal rate of return (IRR) of a cash flow by finding the annual effective rate that makes its present value equal to zero, using compact actuarial notation.

Usage

irr_flow(
  cf,
  t = NULL,
  date = NULL,
  m = 1L,
  interval = c(-0.99, 10),
  tol = 1e-10,
  maxiter = 1000,
  day_count = c("act/365", "act/360")
)

Arguments

Details

The cash flow is supplied explicitly through cf. Its timing is given either through t (in years) or date (calendar dates). If date is supplied, the earliest date is treated as time 0.

The IRR returned is interpreted as an annual effective rate.

This function follows the compact actuarial notation used throughout tidyactuarial: cf denotes cash flows, t denotes time, and m denotes the conversion frequency used to report the equivalent nominal annual interest rate.

The IRR is defined as the rate r satisfying

\sum_{k} C_k (1+r)^{-t_k} = 0

where C_k are the cash flows and t_k the corresponding times in years.

The root is found using uniroot over the specified interval. If the NPV does not change sign over the interval, no root can be bracketed and the function returns gracefully with converged = FALSE.

The number of sign changes in the nonzero cash-flow sequence is reported as a diagnostic. If there is exactly one sign change, the IRR is usually unique under the usual ordered cash-flow setting.

Value

A one-row tibble with:

irr

Estimated IRR as an annual effective rate.

i_effective_annual

Same as irr, reported explicitly.

j_nominal_interest

Equivalent nominal annual interest rate convertible m times.

delta

Equivalent force of interest.

npv

Present value at the estimated IRR, close to zero.

interval_left

Left endpoint of the search interval.

interval_right

Right endpoint of the search interval.

converged

Logical flag indicating whether a root was found.

n_iter

Number of iterations used by uniroot.

n_cashflows

Length of cf.

has_both_signs

Whether the cash flow has at least one positive and one negative value.

n_sign_changes

Number of sign changes in the nonzero cash-flow sequence.

If no sign change is present in the cash flow, or if the NPV does not change sign over interval, the function returns converged = FALSE and irr = NA_real_.

See Also

pv_flow, irr_flow_multi, bond_ytm

Other time-value: future_value(), fv_flow(), irr_flow_multi(), plot_cash_flow(), present_value(), pv_flow()

Examples

irr_flow(
  cf = c(-1000, 300, 400, 500),
  t = c(0, 1, 2, 3)
)

irr_flow(
  cf = c(-1000, 300, 400, 500),
  date = as.Date(c("2026-01-01", "2027-01-01", "2028-01-01", "2029-01-01"))
)

Multiple internal rates of return for a cash flow

Description

Searches for multiple internal rates of return (IRRs) of a cash flow by scanning a search interval and solving for all detectable roots of the net present value (NPV) function, using compact actuarial notation.

Usage

irr_flow_multi(
  cf,
  t = NULL,
  date = NULL,
  m = 1L,
  search_interval = c(-0.99, 10),
  grid_points = 2000L,
  tol = 1e-10,
  maxiter = 1000L,
  day_count = c("act/365", "act/360")
)

Arguments

Details

This function is intended for cash flows with multiple sign changes, where more than one IRR may exist. It evaluates the NPV on a fine grid over the search interval, identifies subintervals with sign changes (and grid points where the NPV is approximately zero), and applies uniroot to each candidate interval.

The IRRs returned are interpreted as annual effective rates.

Timing can be supplied either through t (in years) or date (calendar dates). If date is supplied, the earliest date is treated as time 0.

This function follows the compact actuarial notation used throughout tidyactuarial: cf denotes cash flows, t denotes time, and m denotes the conversion frequency used to report the equivalent nominal annual interest rate.

This function detects roots numerically over a finite search interval. It may miss roots if:

• the grid is too coarse,

• two roots are extremely close,

• the NPV touches zero without changing sign,

• or the root lies outside the search interval.

For a single-IRR workflow, use irr_flow.

Value

A tibble with one row per detected IRR and columns:

root_id

Root index.

irr

Detected IRR as an annual effective rate.

i_effective_annual

Same as irr, reported explicitly.

j_nominal_interest

Equivalent nominal annual interest rate convertible m times.

delta

Equivalent force of interest.

npv

NPV evaluated at the detected root, approximately zero.

interval_left

Left endpoint of the local search bracket.

interval_right

Right endpoint of the local search bracket.

n_cashflows

Length of cf.

has_both_signs

Whether the cash flow has at least one positive and one negative value.

n_sign_changes_cashflow

Number of sign changes in the nonzero cash-flow sequence.

If no roots are detected, the function returns a tibble with zero rows.

See Also

irr_flow, pv_flow

Other time-value: future_value(), fv_flow(), irr_flow(), plot_cash_flow(), present_value(), pv_flow()

Examples

# A standard single-IRR cash flow
irr_flow_multi(
  cf = c(-1000, 300, 400, 500),
  t = c(0, 1, 2, 3)
)

# A cash flow with multiple sign changes
irr_flow_multi(
  cf = c(-1000, 5000, -4500, 200),
  t = c(0, 1, 2, 3),
  search_interval = c(-0.99, 5),
  grid_points = 5000
)

# Date-based version
irr_flow_multi(
  cf = c(-1000, 300, 400, 500),
  date = as.Date(c("2026-01-01", "2027-01-01", "2028-01-01", "2029-01-01"))
)

Kaplan–Meier survival curve and a lifetable-style life table

Description

Fits the nonparametric Kaplan–Meier estimator \hat S(t) for right-censored time-to-event data, computes Greenwood's variance estimator for \hat S(t), and constructs a discrete life table by evaluating \hat S(t) at user-provided cut points (breaks).

Usage

km_lifetable(
  time,
  status,
  entry = NULL,
  breaks = NULL,
  radix = 1e+05,
  conf_level = 0.95,
  assumption = c("UDD", "CF", "Balducci")
)

Arguments

Details

The resulting life table is intended for experience-based (empirical) life tables in actuarial/demographic contexts (e.g., cohort studies, population indicators). It is not a replacement for graduated/regulatory tables when smoothing, extrapolation, or product-specific selection effects are required.

Kaplan–Meier estimator. At each observed event time t_j:

\hat S(t) = \prod_{t_j \le t} \left(1 - \frac{d_j}{n_j}\right)

where n_j is the risk set size and d_j is the number of events. Greenwood's variance:

\widehat{\mathrm{Var}}(\hat S(t)) = \hat S(t)^2 \sum_{t_j \le t} \frac{d_j}{n_j(n_j - d_j)}.

Pointwise confidence intervals use the log(-log) transformation.

Life table mapping. For each interval [x, x + \Delta):

\ell_x = \text{radix} \cdot \hat S(x), \quad d_x = \ell_x - \ell_{x+\Delta}, \quad q_x = d_x / \ell_x.

Exposure L_x = \int_x^{x+\Delta} \ell(t)\,dt is computed using the selected fractional-age assumption (Finan, Section 24):

• UDD (Finan, Sec. 24.1): L_x \approx \tfrac{\ell_x + \ell_{x+\Delta}}{2} \Delta

• CF (constant force, Finan, Sec. 24.2): L_x = \Delta \cdot (\ell_x - \ell_{x+\Delta}) / \ln(\ell_x / \ell_{x+\Delta})

• Balducci (Finan, Sec. 24.3): L_x = \Delta \cdot \ell_x \ell_{x+\Delta} / (\ell_x - \ell_{x+\Delta}) \cdot \ln(\ell_x / \ell_{x+\Delta})

Additional columns follow Finan, Sections 23.3, 23.8–23.9:

• T_x = \sum_{k \ge x} L_k: total expected years lived after age x (Finan, Sec. 23.3).

• \mathring{e}_x = T_x / \ell_x: complete life expectancy (Finan, Sec. 23.3).

• m_x = d_x / L_x: central death rate (Finan, Sec. 23.9).

• a_x = (\ell_x \Delta - L_x) / d_x: average fraction of the interval lived by those who die.

Value

A list with two tibbles:

• km: tibble with columns time, n_risk, d, censored, S, varS, seS, ci_low, ci_high.

• lifetable: tibble with columns x, x_next, width, lx, dx, qx, px, mx, ax, Lx, Tx, ex. Carries class "lifetable" and standard attributes for compatibility with downstream functions.

See Also

lifetable for building tables from known mortality inputs, plot_km for plotting the KM curve.

Examples

set.seed(1)
n <- 200
trueT <- rexp(n, rate = 0.08)
censT <- rexp(n, rate = 0.04)
time <- pmin(trueT, censT)
status <- as.integer(trueT <= censT)

out <- km_lifetable(time, status, breaks = 0:25, radix = 100000)
head(out$km)
head(out$lifetable)

# Tidy pipeline: filter high-mortality intervals
out$lifetable |> dplyr::filter(qx > 0.05)

# Compare UDD vs CF assumptions
udd <- km_lifetable(time, status, breaks = 0:20, assumption = "UDD")
cfm <- km_lifetable(time, status, breaks = 0:20, assumption = "CF")
c(ex_udd = udd$lifetable$ex[1], ex_cf = cfm$lifetable$ex[1])

# Plot the KM curve with plot_km
plot_km(out$km, time_col = "time", surv_col = "S",
        lower_col = "ci_low", upper_col = "ci_high")

Create a life-contingency contract specification

Description

Creates a lightweight actuarial contract object that stores common life-contingency inputs for use in pipe workflows.

Usage

life_contract(
  lt,
  lives = c("single", "joint", "last_survivor"),
  x = NULL,
  y = NULL,
  i,
  i_type = "effective",
  m = 1L,
  ...
)

Arguments

Details

This function does not compute actuarial values. It validates and stores common actuarial inputs such as the life table, life status, ages, and interest-rate specification. Calculation functions such as annuity_x(), insurance_x(), premium_x(), reserve_x(), annuity_xy(), insurance_xy(), premium_xy(), reserve_xy(), and simulation functions can then consume this object.

life_contract() follows the compact actuarial notation used throughout tidyactuarial:

• lt: life table;

• x: age of the first or single life;

• y: age of the second life;

• i: interest rate;

• i_type: type of interest rate;

• m: conversion frequency for nominal rates.

The object stores actuarial fields using the compact names above. During the 0.1.4 API transition, it also stores internal compatibility fields so that functions not yet migrated can continue to read the contract. These internal fields are not part of the preferred user-facing notation.

Value

An object of class "tidyact_life_contract".

See Also

Other life-contingencies: annuity_multi(), annuity_x(), annuity_xy(), insurance_variable_k(), insurance_x(), insurance_xy(), premium_gross(), premium_x(), premium_xy(), reserve_x(), reserve_xy(), simulate_annuity_x(), simulate_insurance_x()

Examples

lt <- data.frame(
  x = 40:90,
  lx = round(100000 * exp(-0.018 * (0:50)^1.35))
)
lt$lx[nrow(lt)] <- 0

life_contract(
  lt = lt,
  lives = "single",
  x = 40,
  i = 0.05
)

life_contract(
  lt = lt,
  lives = "joint",
  x = 60,
  y = 58,
  i = 0.05
)

Build an annual life table (tidy tibble) from lx, qx, px, or mx

Description

Creates an annual life table with integer, consecutive ages and returns a tibble (tidyverse-friendly) with class "lifetable".

Usage

lifetable(
  x,
  lx = NULL,
  qx = NULL,
  px = NULL,
  mx = NULL,
  radix = NULL,
  omega = NULL,
  close = TRUE,
  ax = 0.5,
  type = c("ultimate", "select"),
  frac = c("UDD", "CF", "Balducci"),
  check = TRUE,
  tol = 1e-10
)

Arguments

Details

The table can be built from exactly one of:

• lx (survivors), or

• qx (one-year death probabilities), or

• px (one-year survival probabilities), or

• mx (central death rates),

and the function will compute the remaining columns consistently: dx, qx, px, and mx.

When multiple inputs are provided, priority is: lx > qx > px > mx. If lx is provided together with qx, cross-consistency is validated (both must agree via q_x = (\ell_x - \ell_{x+1}) / \ell_x).

By default, the table is actuarially closed at omega:

\ell_{\omega+1} = 0 \Rightarrow d_{\omega} = \ell_{\omega} \Rightarrow q_{\omega} = 1 \Rightarrow p_{\omega} = 0.

The life table follows the standard actuarial construction described in Finan, Sections 22–24 (Exam MLC preparation).

The basic identities are (Finan, Section 22):

\ell_x = \ell_0 \cdot s(x), \quad d_x = \ell_x - \ell_{x+1}, \quad q_x = d_x / \ell_x, \quad p_x = \ell_{x+1} / \ell_x.

The central death rate mx is computed via the discrete approximation (Finan, Section 23.9):

m_x = \frac{q_x}{1 - a_x \cdot q_x}

which under UDD (ax = 0.5) reduces to the classical formula m_x = q_x / (1 - 0.5 \, q_x) (Finan, Section 24.1). This arises because under UDD, L_x = \ell_x - \tfrac{1}{2} d_x, and therefore m_x = d_x / L_x.

At the terminal age \omega with close = TRUE, closure forces q_\omega = 1, p_\omega = 0, and d_\omega = \ell_\omega. The corresponding m_\omega equals 1/(1 - a_x), which is 2 under UDD (ax = 0.5). If ax = 1, m_\omega = \infty.

Value

A tibble with class c("lifetable","tbl_df","tbl","data.frame") and columns:

• x: integer ages

• lx: survivors at exact age x

• dx: deaths in [x, x+1)

• qx: probability of death in [x, x+1)

• px: probability of survival to x+1

• mx: central death rate (derived using ax). At the terminal age with close = TRUE, mx equals 1/(1 - a_x) and may be Inf if ax = 1.

Attributes include: radix, omega, type, frac, closed, ax.

See Also

km_lifetable for Kaplan–Meier construction, t_px and t_qx for survival and death probabilities (including fractional ages), e_x for curtate and complete life expectancy, annuity_x and insurance_x for life contingency valuations that consume a life table.

Examples

# Example 1: build from lx (Finan, Section 22 style)
x  <- 0:5
lx <- c(100000, 99500, 99000, 98200, 97000, 95000)
lt1 <- lifetable(x = x, lx = lx, omega = 5, close = TRUE)
lt1

# Example 2: build from qx (radix required)
qx <- c(0.005, 0.005, 0.008, 0.012, 0.020, 1)
lt2 <- lifetable(x = x, qx = qx, radix = 100000, omega = 5, close = TRUE)
lt2

# Example 3: build from px
px <- 1 - c(0.005, 0.005, 0.008, 0.012, 0.020, 1)
lt3 <- lifetable(x = x, px = px, radix = 100000, omega = 5, close = TRUE)
lt3

# Example 4: build from mx
mx <- c(0.005, 0.006, 0.008, 0.012, 0.020, 0.030)
lt4 <- lifetable(x = x, mx = mx, radix = 100000, omega = 5, close = TRUE, ax = 0.5)
lt4

# Example 5: truncate to a smaller omega
lt5 <- lifetable(x = 0:10, lx = 100000 * exp(-0.01 * (0:10)), omega = 7, close = TRUE)
lt5

# Example 6: Finan Example 22.1 - exponential survival s(x) = exp(-0.005x)
lt_exp <- lifetable(
  x  = 0:7,
  lx = 1000 * exp(-0.005 * (0:7)),
  close = TRUE
)
lt_exp

# Example 7: verify survival identity (Finan, Section 22)
# 2_p_2 = l_4 / l_2 = 97000 / 99000
lt1$lx[lt1$x == 4] / lt1$lx[lt1$x == 2]

# Example 8: without closure - qx at omega is not forced to 1
lt_open <- lifetable(x = 0:3, lx = c(1000, 900, 750, 500), close = FALSE)
lt_open$qx  # last element is NA

# Example 9: access table metadata
attr(lt1, "omega")   # 5
attr(lt1, "closed")  # TRUE
attr(lt1, "frac")    # "UDD"
attr(lt1, "ax")      # 0.5

Sample loan contracts for amortization examples

Description

A small pedagogical dataset containing level-payment loan contracts for amortization schedule and outstanding balance examples.

A small pedagogical dataset containing level-payment loan contracts for amortization schedule and outstanding balance examples.

Usage

loans_sample

loans_sample

Format

A tibble with 4 rows and 7 variables:

loan_id

Loan identifier.

L

Initial loan principal.

i

Annual effective interest rate.

n_months

Loan term in months.

k

Number of payments per year.

loan_type

Short loan type label.

R

Level payment amount per payment period.

A tibble with 4 rows and 7 variables:

loan_id

Loan identifier.

L

Initial loan principal.

i

Annual effective interest rate.

n_months

Loan term in months.

k

Number of payments per year.

loan_type

Short loan type label.

R

Level payment amount per payment period.

Details

This dataset uses compact loan notation: L is the initial loan principal, i is the annual effective interest rate, n_months is the loan term in months, k is the payment frequency, and R is the level payment.

This dataset uses compact loan notation: L is the initial loan principal, i is the annual effective interest rate, n_months is the loan term in months, k is the payment frequency, and R is the level payment.

Source

Synthetic pedagogical data created for tidyactuarial examples.

Synthetic pedagogical data created for tidyactuarial examples.

Examples

data(loans_sample)

loans_sample |>
  dplyr::select(loan_id, L, i, n_months, k, R)

data(loans_sample)

loans_sample |>
  dplyr::select(loan_id, L, i, n_months, k, R)

Total-decrement lifetable from a multiple decrement table: lt_tau

Description

Builds a single-decrement lifetable for the total decrement (any cause), using q_x^{(\tau)} from a multiple decrement table produced by md_table. This enables direct re-use of single-life functions (e.g., t_px, t_qx, t_Ex, annuities, insurances) under the total decrement model.

Usage

lt_tau(md, ...)

Arguments

Details

Given cause-specific decrement probabilities q_x^{(j)}, the total decrement is q_x^{(\tau)} = \sum_j q_x^{(j)}. This function simply passes x = md$x and qx = md$q_total to lifetable.

Value

A lifetable object as produced by lifetable.

Examples

qx_df <- tibble::tibble(
  x = 30:35,
  q_death = c(0.001, 0.0012, 0.0014, 0.0017, 0.0020, 1.0000),
  q_disability = c(0.002, 0.0021, 0.0022, 0.0023, 0.0024, 0.0000)
)
md <- md_table(qx_df, radix = 1e5, close = TRUE)
lt <- lt_tau(md, radix = 1e5, close = TRUE, frac = "UDD")
t_px(lt, x = 30, t = 5)

Compute simulated present values for life annuities

Description

Computes Monte Carlo simulated present values of life annuity payments from simulated future lifetimes, using compact actuarial notation.

Usage

mc_annuity(
  .data = NULL,
  i,
  payment = 1,
  k = 1L,
  type = c("whole", "temporary", "deferred", "deferred_temporary", "certain",
    "guaranteed", "whole_life"),
  n = NULL,
  h = 0,
  n_guar = NULL,
  timing = c("immediate", "due"),
  i_type = c("effective", "nominal_interest", "nominal_discount", "force", "nominal"),
  m = 1,
  col_K = "Kx",
  col_T = "Tx",
  col_pv = "pv_annuity",
  ...
)

Arguments

Details

This function is designed to be used after simulate_lifetime, simulate_lifetimes, or mc_multilife_status. It takes simulated values of the curtate future lifetime K_x, and when needed the complete future lifetime T_x, and evaluates the present value random variable associated with classical annuity benefits.

This function follows the compact actuarial notation used throughout tidyactuarial: i is the interest-rate input, i_type is the interest-rate convention, m is the nominal conversion frequency, k is the annuity payment frequency, n is the annuity term, and h is the deferral period.

The arguments m and k have different meanings:

• m is used only for nominal interest-rate conversion.

• k controls how frequently annuity payments are made.

The argument payment represents the amount of each annuity payment. Thus, for a monthly annuity with total annual payment equal to 1, use payment = 1 / 12 and k = 12.

For annual payments, k = 1, the function works directly with K_x. For fractional payments, such as monthly, quarterly, or semiannual payments, the function uses T_x to determine whether the life is alive at each fractional payment time.

For annual whole-life annuity-immediate, the simulated present value is

Y = \sum_{j=1}^{K_x} c v^j,

where c is the amount of each payment.

For annual whole-life annuity-due, the simulated present value is

\ddot{Y} = \sum_{j=0}^{K_x} c v^j.

The function returns simulated present values, not only their expected value. Therefore the resulting column can be summarized with summary_mc, plotted with ggplot2, or used to construct premiums, losses, and reserves.

Value

A tibble with the original simulation columns and additional columns:

i

Original interest-rate input.

i_type

Interest-rate convention.

m

Interest conversion frequency.

i_effective

Equivalent annual effective interest rate.

v

Annual discount factor.

type

Canonical annuity type.

payment

Amount of each annuity payment.

k

Annuity payment frequency.

n

Annuity term, if applicable.

h

Deferral period.

n_guar

Guaranteed period, if applicable.

timing

Annuity payment timing.

n_payments

Number of payments made in the simulated scenario.

first_payment_time

First payment time in the simulated scenario.

last_payment_time

Last payment time in the simulated scenario.

pv_annuity

Simulated present value of annuity payments, or another name supplied through col_pv.

For transition, the output also includes legacy columns such as rate, interest_type, effective_rate, discount_factor, annuity, payments_per_year, term, deferral_years, and guarantee_years.

References

Bowers, N. L., Gerber, H. U., Hickman, J. C., Jones, D. A., and Nesbitt, C. J. (1997). Actuarial Mathematics. Second Edition. Society of Actuaries.

See Also

simulate_lifetime, simulate_lifetimes, mc_multilife_status, mc_insurance, mc_premium, mc_loss, mc_reserve, summary_mc

Other monte-carlo: mc_insurance(), mc_loss(), mc_premium(), mc_reserve(), simulate_lifetime(), summary_mc()

Examples

lt <- tibble::tibble(
  x = 40:100,
  qx = seq(0.002, 1, length.out = 61)
)

# Annual whole-life annuity-due
lt |>
  simulate_lifetime(
    x = 40,
    n_sim = 25,
    seed = 123
  ) |>
  mc_annuity(
    i = 0.05,
    type = "whole",
    payment = 1,
    k = 1,
    timing = "due"
  )

# Monthly whole-life annuity-due with total annual payment equal to 1
lt |>
  simulate_lifetime(
    x = 40,
    n_sim = 25,
    frac = "udd",
    seed = 123
  ) |>
  mc_annuity(
    i = 0.05,
    type = "whole",
    payment = 1 / 12,
    k = 12,
    timing = "due"
  )

# Quarterly temporary life annuity-immediate
lt |>
  simulate_lifetime(
    x = 40,
    n_sim = 25,
    frac = "udd",
    seed = 123
  ) |>
  mc_annuity(
    i = 0.05,
    type = "temporary",
    n = 20,
    payment = 1 / 4,
    k = 4,
    timing = "immediate"
  )

# Nominal interest convertible monthly, with quarterly payments
lt |>
  simulate_lifetime(
    x = 40,
    n_sim = 25,
    frac = "udd",
    seed = 123
  ) |>
  mc_annuity(
    i = 0.06,
    i_type = "nominal_interest",
    m = 12,
    type = "whole",
    payment = 1 / 4,
    k = 4,
    timing = "due"
  )

# Multiple-life status workflow
lt |>
  simulate_lifetimes(
    x = c(60, 58),
    n_sim = 25,
    frac = "udd",
    seed = 123
  ) |>
  mc_multilife_status(status = "joint") |>
  mc_annuity(
    i = 0.04,
    type = "whole",
    payment = 1,
    k = 1,
    timing = "due",
    col_K = "K_status",
    col_T = "T_status"
  )

Compute simulated present values for life insurance benefits

Description

Computes Monte Carlo simulated present values of life insurance benefits from simulated future lifetimes, using compact actuarial notation.

Usage

mc_insurance(
  .data = NULL,
  i = NULL,
  benefit = 1,
  type = c("whole", "term", "deferred", "deferred_term", "pure_endowment", "endowment",
    "whole_life", "deferred_temporary"),
  n = NULL,
  h = 0,
  timing = c("end_of_year", "moment_of_death"),
  i_type = c("effective", "nominal_interest", "nominal_discount", "force", "nominal"),
  m = 1,
  col_K = "Kx",
  col_T = "Tx",
  col_pv = "pv_benefit",
  ...
)

Arguments

Details

This function is designed to be used after simulate_lifetime, simulate_lifetimes, or mc_multilife_status. It takes simulated values of the curtate future lifetime K_x, and when needed the complete future lifetime T_x, and evaluates the present value random variable associated with classical life insurance benefits.

This function follows the compact actuarial notation used throughout tidyactuarial: i is the interest-rate input, i_type is the interest-rate convention, m is the nominal conversion frequency, n is the insurance term, and h is the deferral period.

The arguments m and col_K have deliberately different roles:

• m is used only for nominal interest-rate conversion.

• col_K identifies the simulated curtate future lifetime column.

If timing = "end_of_year", death benefits are discounted using K_x + 1. If timing = "moment_of_death", death benefits are discounted using T_x.

The following insurance types are supported:

• "whole": benefit is paid whenever death occurs.

• "term": benefit is paid if death occurs within n years.

• "deferred": benefit is paid if death occurs after the deferral period h.

• "deferred_term": benefit is paid if death occurs after h and within the following n years.

• "pure_endowment": benefit is paid at time n if the life survives to that time.

• "endowment": death benefit is paid if death occurs within n years; otherwise, a survival benefit is paid at time n.

The function returns simulated present values, not only their expected value. Therefore the resulting column can be summarized with summary_mc, plotted with ggplot2, or used to construct premiums, losses, and reserves.

Value

A tibble with the original simulation columns and additional columns:

i

Original interest-rate input.

i_type

Interest-rate convention.

m

Interest conversion frequency.

i_effective

Equivalent annual effective interest rate.

v

Annual discount factor.

type

Canonical insurance type.

benefit

Benefit amount.

n

Insurance term, if applicable.

h

Deferral period.

timing

Timing used for death benefits.

benefit_time

Simulated payment time of the benefit.

benefit_indicator

Indicator that the benefit is paid.

pv_benefit

Simulated present value of the benefit, or another name supplied through col_pv.

For transition, the output also includes legacy columns such as rate, interest_type, effective_rate, discount_factor, insurance, term, deferral_years, and payment_timing.

References

Bowers, N. L., Gerber, H. U., Hickman, J. C., Jones, D. A., and Nesbitt, C. J. (1997). Actuarial Mathematics. Second Edition. Society of Actuaries.

See Also

simulate_lifetime, simulate_lifetimes, mc_multilife_status, mc_annuity, mc_premium, mc_loss, mc_reserve, summary_mc

Other monte-carlo: mc_annuity(), mc_loss(), mc_premium(), mc_reserve(), simulate_lifetime(), summary_mc()

Examples

lt <- tibble::tibble(
  x = 40:100,
  qx = seq(0.002, 1, length.out = 61)
)

# Whole-life insurance payable at the end of the year of death
lt |>
  simulate_lifetime(
    x = 40,
    n_sim = 25,
    seed = 123
  ) |>
  mc_insurance(
    i = 0.05,
    type = "whole",
    benefit = 1
  )

# 20-year term insurance
lt |>
  simulate_lifetime(
    x = 40,
    n_sim = 25,
    seed = 123
  ) |>
  mc_insurance(
    i = 0.05,
    type = "term",
    n = 20,
    benefit = 100000
  )

# 10-year deferred whole-life insurance
lt |>
  simulate_lifetime(
    x = 40,
    n_sim = 25,
    seed = 123
  ) |>
  mc_insurance(
    i = 0.05,
    type = "deferred",
    h = 10,
    benefit = 1
  )

# Endowment insurance payable at the moment of death if death occurs
lt |>
  simulate_lifetime(
    x = 40,
    n_sim = 25,
    frac = "udd",
    seed = 123
  ) |>
  mc_insurance(
    i = 0.05,
    type = "endowment",
    n = 20,
    timing = "moment_of_death",
    benefit = 1
  )

# Nominal interest rate convertible monthly
lt |>
  simulate_lifetime(
    x = 40,
    n_sim = 25,
    seed = 123
  ) |>
  mc_insurance(
    i = 0.06,
    i_type = "nominal_interest",
    m = 12,
    type = "whole",
    benefit = 1
  )

# First-death insurance using a multiple-life status
lt |>
  simulate_lifetimes(
    x = c(60, 58),
    n_sim = 25,
    frac = "udd",
    seed = 123
  ) |>
  mc_multilife_status(status = "joint") |>
  mc_insurance(
    i = 0.04,
    type = "whole",
    benefit = 100000,
    col_K = "K_status",
    col_T = "T_status"
  )

Compute Monte Carlo loss random variables for life contingencies

Description

Computes simulated actuarial loss random variables from Monte Carlo present values of benefits, premium annuities, and premiums, using compact actuarial notation.

Usage

mc_loss(
  .data = NULL,
  col_Z = "pv_benefit",
  col_Y = "pv_annuity",
  col_P = "P",
  col_L = "L",
  P = NULL,
  ...
)

Arguments

Details

This function constructs the simulated loss random variable

L = Z - P Y,

where Z is the present value random variable of insurance benefits, Y is the present value random variable of the premium annuity, and P is the premium per payment.

This function follows the compact actuarial notation used throughout tidyactuarial: Z denotes the present value random variable of benefits, Y denotes the present value random variable of the premium annuity, P denotes the premium per payment, and L denotes the actuarial loss random variable at issue.

The function does not estimate the premium. It only constructs the simulated loss random variable. The premium may come from a column previously created by mc_premium, or it may be supplied directly through the P argument.

The interpretation of P depends on how the premium annuity present value was constructed. If pv_annuity was generated with annual payments, then P corresponds to that annual premium structure. If pv_annuity was generated using fractional payments in mc_annuity, such as payment = 1 / 12 and k = 12, then P is applied to that same fractional payment pattern.

Thus, mc_loss() can be used without modification for annual premiums, monthly premiums, quarterly premiums, semiannual premiums, and multiple-life premium structures, provided that col_Y contains the appropriate simulated premium annuity present value.

The resulting loss column can be used to estimate quantities such as expected loss, variance, standard deviation, probability of positive loss, loss quantiles, empirical value-at-risk measures, and sensitivities across actuarial assumptions.

Value

A tibble with the original columns and one additional column containing the simulated loss random variable. The name of this column is controlled by col_L. For transition, if col_L != "loss" and the input does not already contain a column named loss, a legacy column loss is also added with the same value.

References

Bowers, N. L., Gerber, H. U., Hickman, J. C., Jones, D. A., and Nesbitt, C. J. (1997). Actuarial Mathematics. Second Edition. Society of Actuaries.

See Also

simulate_lifetime, simulate_lifetimes, mc_multilife_status, mc_insurance, mc_annuity, mc_premium, mc_reserve, summary_mc

Other monte-carlo: mc_annuity(), mc_insurance(), mc_premium(), mc_reserve(), simulate_lifetime(), summary_mc()

Examples

# Example 1: direct use with simulated present values
sim_values <- tibble::tibble(
  sim_id = 1:5,
  pv_benefit = c(0.80, 0.75, 0.95, 0.60, 0.70),
  pv_annuity = c(8.0, 7.5, 9.0, 6.0, 7.0),
  P = 0.10
)

sim_values |>
  mc_loss()

# Example 2: using a premium supplied directly
sim_values |>
  mc_loss(P = 0.12)

# Example 3: annual whole life loss
lt <- tibble::tibble(
  x = 40:100,
  qx = seq(0.002, 1, length.out = 61)
)

lt |>
  simulate_lifetime(
    x = 40,
    n_sim = 25,
    seed = 123
  ) |>
  mc_insurance(
    i = 0.05,
    type = "whole",
    benefit = 1
  ) |>
  mc_annuity(
    i = 0.05,
    type = "whole",
    payment = 1,
    k = 1,
    timing = "due"
  ) |>
  mc_premium() |>
  mc_loss()

# Example 4: monthly whole life loss
lt |>
  simulate_lifetime(
    x = 40,
    n_sim = 25,
    frac = "udd",
    seed = 123
  ) |>
  mc_insurance(
    i = 0.05,
    type = "whole",
    benefit = 1
  ) |>
  mc_annuity(
    i = 0.05,
    type = "whole",
    payment = 1 / 12,
    k = 12,
    timing = "due"
  ) |>
  mc_premium() |>
  mc_loss()

# Example 5: summarising simulated losses
lt |>
  simulate_lifetime(
    x = 45,
    n_sim = 25,
    frac = "udd",
    seed = 123
  ) |>
  mc_insurance(
    i = 0.04,
    type = "term",
    n = 20,
    benefit = 100000
  ) |>
  mc_annuity(
    i = 0.04,
    type = "temporary",
    n = 20,
    payment = 1 / 12,
    k = 12,
    timing = "due"
  ) |>
  mc_premium() |>
  mc_loss() |>
  summary_mc(value_col = "L")

# Example 6: joint-life annual loss
lt |>
  simulate_lifetimes(
    x = c(60, 58),
    n_sim = 25,
    seed = 123
  ) |>
  mc_multilife_status(status = "joint") |>
  mc_insurance(
    i = 0.04,
    type = "whole",
    benefit = 100000,
    col_K = "K_status",
    col_T = "T_status"
  ) |>
  mc_annuity(
    i = 0.04,
    type = "whole",
    payment = 1,
    k = 1,
    timing = "due",
    col_K = "K_status",
    col_T = "T_status"
  ) |>
  mc_premium() |>
  mc_loss()

# Transitional compatibility with old column arguments
sim_values |>
  mc_loss(
    benefit_col = "pv_benefit",
    annuity_col = "pv_annuity",
    premium_col = "P",
    loss_col = "loss"
  )

Compute multiple-life simulated status variables

Description

Combines simulated future lifetimes from multiple lives into a single multiple-life status. For a joint-life status, the status fails at the first death. For a last-survivor status, the status fails at the last death.

Usage

mc_multilife_status(
  data,
  status = c("joint", "last_survivor"),
  col_sim = "sim_id",
  col_life = "life_id",
  col_K = "Kx",
  col_T = "Tx"
)

Arguments

Value

A tibble with one row per simulation and the columns K_status and T_status.

Examples

lt <- tibble::tibble(
  x = 40:100,
  qx = seq(0.002, 1, length.out = 61)
)

lt |>
  simulate_lifetimes(
    x = c(60, 58),
    n_sim = 25,
    frac = "udd",
    seed = 123
  ) |>
  mc_multilife_status(status = "joint")

Compute Monte Carlo net premiums for life contingencies

Description

Computes Monte Carlo net premiums from simulated present values of insurance benefits and premium annuities, using compact actuarial notation.

Usage

mc_premium(
  .data = NULL,
  col_Z = "pv_benefit",
  col_Y = "pv_annuity",
  col_P = "P",
  by = NULL,
  na_rm = TRUE,
  ...
)

Arguments

Details

This function applies the actuarial equivalence principle to simulated present value random variables. If Z denotes the simulated present value of benefits and Y denotes the simulated present value of the premium annuity, the Monte Carlo net premium is estimated as

\hat{P} = \frac{\bar{Z}}{\bar{Y}}.

Equivalently, this estimates

P = \frac{E[Z]}{E[Y]}.

This function follows the compact actuarial notation used throughout tidyactuarial: Z denotes the present value random variable of benefits, Y denotes the present value random variable of the premium annuity, and P denotes the net premium per payment.

The function does not simulate lifetimes and does not calculate present values directly. It only computes the Monte Carlo net premium from columns that already contain simulated present values.

In a typical workflow, simulate_lifetime generates simulated values of K_x and possibly T_x; mc_insurance creates the simulated benefit present value Z; mc_annuity creates the simulated premium annuity present value Y; and mc_premium() estimates the net level premium.

The estimated premium is attached to every row of the input data. This is intentional: it makes it easy to construct the simulated loss random variable with mc_loss, for example

L = Z - \hat{P}Y.

The function is also valid for premiums payable more than once per year. In that case, the payment frequency is not specified in mc_premium(); it is already embedded in the simulated premium annuity present value supplied through col_Y.

For example, if mc_annuity was called with payment = 1 / 12 and k = 12, then pv_annuity represents the present value of a monthly premium stream whose total annual amount is

1. The premium estimated by mc_premium() is then consistent with that monthly payment structure.

If mc_annuity was called with payment = 1 and k = 12, then pv_annuity represents a stream of payments of 1 each month, and the resulting premium should be interpreted relative to that payment pattern.

This function computes net premiums only. It does not include expenses, safety loadings, profit margins, taxes, surrender charges, commissions, or other practical pricing adjustments.

Value

A tibble with the original columns and one additional column containing the simulated net premium. The name of this column is controlled by col_P. For transition, if col_P != "premium" and the input does not already contain a column named premium, a legacy column premium is also added with the same value.

References

Bowers, N. L., Gerber, H. U., Hickman, J. C., Jones, D. A., and Nesbitt, C. J. (1997). Actuarial Mathematics. Second Edition. Society of Actuaries.

See Also

simulate_lifetime, simulate_lifetimes, mc_insurance, mc_annuity, mc_loss, mc_reserve, summary_mc

Other monte-carlo: mc_annuity(), mc_insurance(), mc_loss(), mc_reserve(), simulate_lifetime(), summary_mc()

Examples

# Example 1: direct use with simulated present values
sim_values <- tibble::tibble(
  sim_id = 1:6,
  pv_benefit = c(0.82, 0.74, 0.61, 0.95, 0.70, 0.88),
  pv_annuity = c(8.2, 7.5, 6.1, 9.0, 7.2, 8.8)
)

sim_values |>
  mc_premium()

# Example 2: grouped premiums by age
sim_by_age <- tibble::tibble(
  sim_id = rep(1:6, times = 2),
  x = rep(c(40, 50), each = 6),
  pv_benefit = c(
    0.82, 0.74, 0.61, 0.95, 0.70, 0.88,
    0.91, 0.86, 0.79, 0.98, 0.83, 0.94
  ),
  pv_annuity = c(
    8.2, 7.5, 6.1, 9.0, 7.2, 8.8,
    6.8, 6.4, 5.9, 7.1, 6.2, 6.7
  )
)

sim_by_age |>
  mc_premium(by = "x")

# Example 3: using dplyr grouping
sim_by_age |>
  dplyr::group_by(x) |>
  mc_premium()

# Example 4: annual whole life net premium
lt <- tibble::tibble(
  x = 40:100,
  qx = seq(0.002, 1, length.out = 61)
)

lt |>
  simulate_lifetime(
    x = 40,
    n_sim = 25,
    seed = 123
  ) |>
  mc_insurance(
    i = 0.05,
    type = "whole",
    benefit = 1
  ) |>
  mc_annuity(
    i = 0.05,
    type = "whole",
    payment = 1,
    k = 1,
    timing = "due"
  ) |>
  mc_premium()

# Example 5: monthly whole life net premium
lt |>
  simulate_lifetime(
    x = 40,
    n_sim = 25,
    frac = "udd",
    seed = 123
  ) |>
  mc_insurance(
    i = 0.05,
    type = "whole",
    benefit = 1
  ) |>
  mc_annuity(
    i = 0.05,
    type = "whole",
    payment = 1 / 12,
    k = 12,
    timing = "due"
  ) |>
  mc_premium()

# Example 6: term insurance with monthly premium annuity
lt |>
  simulate_lifetime(
    x = 45,
    n_sim = 25,
    frac = "udd",
    seed = 123
  ) |>
  mc_insurance(
    i = 0.04,
    type = "term",
    n = 20,
    benefit = 100000
  ) |>
  mc_annuity(
    i = 0.04,
    type = "temporary",
    n = 20,
    payment = 1 / 12,
    k = 12,
    timing = "due"
  ) |>
  mc_premium()

# Example 7: joint-life annual net premium
lt |>
  simulate_lifetimes(
    x = c(60, 58),
    n_sim = 25,
    seed = 123
  ) |>
  mc_multilife_status(status = "joint") |>
  mc_insurance(
    i = 0.04,
    type = "whole",
    benefit = 100000,
    col_K = "K_status",
    col_T = "T_status"
  ) |>
  mc_annuity(
    i = 0.04,
    type = "whole",
    payment = 1,
    k = 1,
    timing = "due",
    col_K = "K_status",
    col_T = "T_status"
  ) |>
  mc_premium()

# Transitional compatibility with old column arguments
sim_values |>
  mc_premium(
    benefit_col = "pv_benefit",
    annuity_col = "pv_annuity",
    premium_col = "premium"
  )

Compute Monte Carlo prospective reserves for life contingencies

Description

Computes simulated prospective reserve losses at one or more policy durations from simulated future lifetimes, using compact actuarial notation.

Usage

mc_reserve(
  .data = NULL,
  t = 0,
  i = NULL,
  P = NULL,
  col_P = "P",
  benefit = 1,
  payment = 1,
  k = 1L,
  type = c("whole", "term", "deferred", "deferred_term", "pure_endowment", "endowment",
    "whole_life", "deferred_temporary"),
  annuity_type = c("whole", "temporary", "deferred", "deferred_temporary", "certain",
    "guaranteed", "whole_life"),
  n = NULL,
  h = 0,
  n_guar = NULL,
  timing = c("end_of_year", "moment_of_death"),
  premium_timing = c("due", "immediate"),
  reserve_timing = c("before_payment", "after_payment"),
  i_type = c("effective", "nominal_interest", "nominal_discount", "force", "nominal"),
  m = 1,
  col_K = "Kx",
  col_T = "Tx",
  in_force_basis = c("auto", "complete", "curtate"),
  not_in_force = c("na", "zero"),
  col_L = "L_t",
  ...
)

Arguments

Details

This function recalculates future benefit and future premium present values from each valuation duration. It is not a wrapper around mc_loss, because reserves require valuing only the cash flows that remain after the valuation time.

For a policy in force at duration t, the simulated prospective loss is

L_t = Z_t - P Y_t,

where Z_t is the present value at duration t of future benefits, Y_t is the present value at duration t of future premium payments, and P is the premium per payment.

This function follows the compact actuarial notation used throughout tidyactuarial: t is the valuation duration, i is the interest-rate input, i_type is the interest-rate convention, m is the nominal conversion frequency, k is the premium payment frequency, n is the contract term, h is the deferral period, P is the premium per payment, and L_t is the simulated prospective loss at duration t.

The arguments m and k have deliberately different meanings:

• m is used only for nominal interest-rate conversion.

• k controls how frequently future premium payments are made.

The argument payment represents the amount of each premium annuity payment used to construct Y_t. Thus, for monthly premiums with total annual premium equal to 1, use payment = 1 / 12 and k = 12.

If k = 1, future premiums are annual. If k > 1, future premiums are made at fractional times, and a valid complete future lifetime column supplied through col_T is required for life-contingent premium annuities.

Durations may be integer or fractional. Fractional reserve durations require complete future lifetimes. For example, monthly reserve calculations may use t = seq(0, 20, by = 1 / 12).

If reserve_timing = "before_payment", cash flows occurring exactly at the valuation duration are included. If reserve_timing = "after_payment", cash flows occurring exactly at the valuation duration are excluded.

If not_in_force = "na", scenarios that are not in force at a given duration receive NA values for future present values and reserve losses. This is useful for estimating reserves conditional on the policy still being in force. If not_in_force = "zero", those scenarios receive zero values, which may be useful for portfolio run-off summaries.

This function computes prospective reserves under the simulated model. It does not include expenses, surrender values, taxes, profit loadings, or statutory reserving adjustments.

Value

A tibble with one row per original simulation and per requested duration. It contains the original simulation columns and additional columns including t, in_force, i, i_type, m, i_effective, v, type, annuity_type, benefit, payment, k, Z_t, Y_t, P, and L_t or another name supplied through col_L.

For transition, the output also includes legacy columns such as duration, rate, interest_type, effective_rate, discount_factor, insurance, annuity, payments_per_year, term, deferral_years, guarantee_years, future_pv_benefit, future_pv_premiums, premium, and reserve_loss.

References

Bowers, N. L., Gerber, H. U., Hickman, J. C., Jones, D. A., and Nesbitt, C. J. (1997). Actuarial Mathematics. Second Edition. Society of Actuaries.

See Also

simulate_lifetime, simulate_lifetimes, mc_multilife_status, mc_insurance, mc_annuity, mc_premium, mc_loss, summary_mc

Other monte-carlo: mc_annuity(), mc_insurance(), mc_loss(), mc_premium(), simulate_lifetime(), summary_mc()

Examples

lt <- tibble::tibble(
  x = 40:100,
  qx = seq(0.002, 1, length.out = 61)
)

# Annual prospective reserves for whole-life insurance
lt |>
  simulate_lifetime(
    x = 40,
    n_sim = 25,
    seed = 123
  ) |>
  mc_reserve(
    t = c(0, 5, 10),
    i = 0.05,
    type = "whole",
    annuity_type = "whole",
    benefit = 1,
    payment = 1,
    k = 1,
    premium_timing = "due"
  )

# Monthly premium reserve curve at annual valuation durations
lt |>
  simulate_lifetime(
    x = 40,
    n_sim = 25,
    frac = "udd",
    seed = 123
  ) |>
  mc_reserve(
    t = c(0, 1, 2, 3),
    i = 0.05,
    type = "whole",
    annuity_type = "whole",
    benefit = 1,
    payment = 1 / 12,
    k = 12,
    premium_timing = "due"
  )

# Fractional reserve durations
lt |>
  simulate_lifetime(
    x = 40,
    n_sim = 25,
    frac = "udd",
    seed = 123
  ) |>
  mc_reserve(
    t = seq(0, 1, by = 1 / 4),
    i = 0.05,
    type = "whole",
    annuity_type = "whole",
    benefit = 1,
    payment = 1 / 12,
    k = 12,
    premium_timing = "due"
  ) |>
  summary_mc(value_col = "L_t", by = "t")

# Joint-life reserve using a multiple-life status
lt |>
  simulate_lifetimes(
    x = c(60, 58),
    n_sim = 25,
    seed = 123
  ) |>
  mc_multilife_status(status = "joint") |>
  mc_reserve(
    t = c(0, 5),
    i = 0.04,
    type = "whole",
    annuity_type = "whole",
    benefit = 1,
    payment = 1,
    k = 1,
    col_K = "K_status",
    col_T = "T_status"
  )

Multiple decrement table (annual, discrete ages)

Description

Builds a multiple decrement table from cause-specific annual decrement probabilities q_x^{(j)}. This function is annual/discrete: ages must be integer-valued and the input probabilities are interpreted as one-year decrement probabilities for each cause.

Usage

md_table(
  qx_df,
  age_col = "x",
  cause_cols = NULL,
  radix = 1e+05,
  close = TRUE,
  check = TRUE,
  tol = 1e-10
)

Arguments

Details

Let the cause columns be q_x^{(1)}, \dots, q_x^{(J)}. The total decrement probability is q_x^{(\tau)} = \sum_j q_x^{(j)} and the total survival probability is p_x^{(\tau)} = 1 - q_x^{(\tau)}. The cohort is generated recursively by \ell_{x+1} = \ell_x \, p_x^{(\tau)} with starting radix \ell_{x_0} = \text{radix}.

If close = TRUE, the last age (omega) must satisfy q_{\omega}^{(\tau)} = 1 (within tolerance), so that the table closes naturally.

Value

A tibble with columns:

• x: integer ages.

• lx: cohort \ell_x.

• q_total: total decrement probability q_x^{(\tau)}.

• p_total: total survival probability p_x^{(\tau)}.

• d_total: total decrements d_x^{(\tau)} = \ell_x q_x^{(\tau)}.

• cause columns (as provided).

• cause-specific decrements d_* with d_x^{(j)} = \ell_x q_x^{(j)}.

Examples

qx_df <- tibble::tibble(
  x = 30:35,
  q_death = c(0.001, 0.0012, 0.0014, 0.0017, 0.0020, 1.0000),
  q_disability = c(0.002, 0.0021, 0.0022, 0.0023, 0.0024, 0.0000)
)
md <- md_table(qx_df, radix = 1e5, close = TRUE)
md

Colombian mortality tables

Description

A tidy collection of Colombian mortality tables for life-contingency examples. The dataset includes regulatory and pedagogical mortality tables used in Colombian actuarial applications.

Usage

mortality_colombia_tables

Format

A tibble with 12 variables:

table_id

Mortality table identifier.

sex

Sex category, typically "male" or "female".

x

Integer actuarial age.

lx

Number of survivors at exact age x.

dx

Expected number of deaths between ages x and x + 1.

qx

One-year death probability between ages x and x + 1.

px

One-year survival probability between ages x and x + 1.

mu_x

Force of mortality at age x, when available.

ex

Complete life expectancy at age x, when available.

source

Source identifier or reference.

qx_calc

Death probability recalculated from lx and dx, when available.

qx_diff

Difference between reported qx and recalculated qx, when available.

Details

The dataset is intended for actuarial examples involving Colombian mortality tables, survival probabilities, life annuities, life insurance present values, and validation of life-table calculations.

The variable names follow the compact actuarial notation used throughout tidyactuarial: x denotes age, lx the number of lives, dx the number of deaths, qx the one-year death probability, px the one-year survival probability, mu_x the force of mortality, and ex the life expectancy at age x.

The variables qx_calc and qx_diff are included as validation aids. They allow users to compare reported death probabilities against probabilities reconstructed from lx and dx.

Some tables may start at different initial ages, use different terminal ages, or use different radix values. Users should filter the desired table and sex before passing the data to life-contingency functions.

Source

Colombian mortality tables cleaned for tidyactuarial examples. Source identifiers are provided in the source column.

Examples

data(mortality_colombia_tables)

head(mortality_colombia_tables)

mortality_colombia_tables |>
  dplyr::count(table_id, sex)

rv08_male <- mortality_colombia_tables |>
  dplyr::filter(table_id == "RV08_Rentistas_2005_2008", sex == "male") |>
  dplyr::select(x, lx, dx, qx, px, mu_x, ex)

head(rv08_male)

Generate a tidy life table from a theoretical mortality law

Description

Creates a tidy life table with one row per integer age from a parametric mortality law, using compact actuarial notation.

Usage

mortality_law_table(
  law = c("Exponential", "Gompertz", "Makeham", "Weibull", "Logistic", "DeMoivre",
    "Beta", "HeligmanPollard"),
  x_min,
  x_max,
  ...,
  params = NULL,
  frac = c("CF", "UDD", "Balducci", "CML"),
  l0 = 1e+05,
  close = TRUE,
  a_x = 0.5,
  check = TRUE,
  tol = 1e-10,
  radix = NULL,
  ax = NULL
)

Arguments

Details

The output follows tidyactuarial conventions and includes columns such as x, qx, px, lx, dx, Lx, Tx, ex, and mx.

This function follows the compact actuarial notation used throughout tidyactuarial: x denotes age, l0 denotes the starting radix, a_x denotes the average fraction of the year lived by those dying during the age interval, qx denotes the one-year death probability, and px = 1 - qx.

The parameter F_hp is used for the Heligman-Pollard law instead of F, because F is historically associated with FALSE in R and should not be promoted in a CRAN-facing API. The old name F is still accepted as a transitional alias.

Value

A tibble with columns x, law, frac, mu_x, qx, px, lx, dx, Lx, Tx, ex, and mx.

Supported laws

• Exponential: \mu_x = \lambda.

• Gompertz: \mu_x = Bc^x.

• Makeham: \mu_x = A + Bc^x.

• Weibull: \mu_x = (shape/scale)(x/scale)^{shape-1}.

• Logistic: \mu_x = (A + Bc^x)/(1 + Cc^x).

• DeMoivre: finite lifetime law with q_x = 1/(\omega - x) for x < \omega.

• Beta: scaled lifetime model X/\omega \sim Beta(\alpha,\beta).

• HeligmanPollard: odds model returning q_x directly.

Law parameters

Parameters for the selected law are supplied either through ... or through the named list params. Direct parameters supplied through ... override values in params.

Required parameters:

• "Exponential": lambda.

• "Gompertz": B, c.

• "Makeham": A, B, c.

• "Weibull": shape, scale. Transitional aliases k and lambda are accepted.

• "Logistic": A, B, c, C.

• "DeMoivre": omega.

• "Beta": alpha, beta, omega.

• "HeligmanPollard": A, B, C, D, E, F_hp, and G. Transitional alias F is accepted and mapped to F_hp.