Package {tidyactuarial}

Internal helper: convert payment counts into annuity factors

Description

Internal helper: convert payment counts into annuity factors

Usage

.annuity_factor_count(n_payments, i_effective, k, timing)

Internal helper: count annuity payments

Description

Internal helper: count annuity payments

Usage

.annuity_payment_count(Kx, died_within_horizon, n, k, timing, Tx = NULL)

Internal helper: collect deprecated Monte Carlo argument names

Description

Internal helper: collect deprecated Monte Carlo argument names

Usage

.life_mc_collect_old_args(dots, allowed)

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

Internal helper: benefit payment information for reserve calculations

Usage

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

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)

Internal helper: simulate future lifetimes from lx

Description

Internal helper: simulate future lifetimes from lx

Usage

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

Arguments

Value

A tibble with simulated curtate and complete future 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)

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)
)

Accumulation factor under conventional or time-varying interest

Description

Computes the accumulation factor from time s to time t using exactly one of three interest specifications:

• a conventional interest rate i;

• an accumulation function a(t);

• a time-varying force of interest delta(t).

Usage

accumulation_factor(
  s = 0,
  t,
  i = NULL,
  i_type = "effective",
  m = 1,
  a = NULL,
  delta = NULL,
  subdivisions = 100L,
  rel.tol = 1e-08,
  tidy = FALSE
)

Arguments

Details

The accumulation factor is

A(s,t) = (1+i)^{t-s}

for a constant annual effective rate,

A(s,t) = \frac{a(t)}{a(s)}

for an accumulation function, and

A(s,t) = \exp\left(\int_s^t \delta(u)\,du\right)

for a time-varying force of interest.

Exactly one of i, a, or delta must be supplied.

Numeric arguments must have length 1 or a common length. Scalars are recycled over the remaining scenarios, making the function suitable for use inside dplyr::mutate() pipelines.

Times must satisfy 0 \le s \le t. Missing times propagate as missing accumulation factors.

Value

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

If tidy = TRUE, a tibble containing the interval, model, relevant intermediate quantities, and accumulation factor.

See Also

standardize_interest, present_value, future_value

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

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

Examples

# Constant annual effective interest
accumulation_factor(t = 5, i = 0.07)

# One rate recycled over several times
accumulation_factor(
  t = c(1, 2, 5),
  i = 0.07
)

# Accumulation function
a_fun <- function(t) {
  exp(0.03 * t + 0.002 * t^2)
}

accumulation_factor(
  s = 2,
  t = 5,
  a = a_fun
)

# Time-varying force of interest
delta_fun <- function(t) {
  0.03 + 0.004 * t
}

accumulation_factor(
  s = 2,
  t = 5,
  delta = delta_fun
)

# Pipe-friendly use with a small tibble
if (requireNamespace("dplyr", quietly = TRUE) &&
    requireNamespace("tibble", quietly = TRUE)) {
  scenarios <- tibble::tibble(
    i = 0.07,
    t = c(1, 2, 3, 5)
  )

  scenarios |>
    dplyr::mutate(
      accumulation = accumulation_factor(
        t = t,
        i = i
      )
    )
}

Add an insurance benefit specification to a life contract

Description

Adds the benefit side of a single-life insurance contract to an existing life_contract() object. This function stores the specification only; it does not calculate an actuarial present value.

Adds the benefit side of a single-life or two-life insurance contract to an existing life_contract() object. This function stores the specification only; it does not calculate an actuarial present value.

Usage

add_insurance(
  contract,
  type = c("whole", "term", "endowment", "pure_endowment", "variable_k"),
  benefit = 1,
  n = Inf,
  h = 0L,
  k = 1L,
  frac = c("UDD", "CF", "CML", "Balducci")
)

add_insurance(
  contract,
  type = c("whole", "term", "endowment", "pure_endowment", "variable_k"),
  benefit = 1,
  n = Inf,
  h = 0L,
  k = 1L,
  frac = c("UDD", "CF", "CML", "Balducci")
)

Arguments

Details

For two-life contracts, the insurance status is inferred from contract$lives: "joint" becomes joint-life status and "last_survivor" becomes last-survivor status.

Value

The original contract with an insurance component.

The original contract with an insurance component.

See Also

Other life-contingencies: add_premium_schedule(), annuity_multi(), 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()

Other life-contingencies: add_premium_schedule(), annuity_multi(), 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 = 40:90,
  lx = round(100000 * exp(-0.018 * (0:50)^1.35))
)

life_contract(
  lt = lt,
  lives = "single",
  x = 40,
  i = 0.05
) |>
  add_insurance(
    type = "term",
    benefit = 100000,
    n = 20
  )

Add a contingent premium-payment schedule to a life contract

Description

Adds the premium-payment side of a single-life insurance contract. The schedule defines when premiums are payable while the insured is alive. This function stores the specification only; premium_x() later applies the equivalence principle.

Adds the premium-payment side of a single-life or two-life insurance contract. The schedule defines when premiums are payable while the selected life status is in force. This function stores the specification only.

Usage

add_premium_schedule(
  contract,
  k = 1L,
  timing = c("due", "immediate"),
  premium_start = c("issue", "deferred"),
  n_prem = NULL,
  woolhouse = c("none", "first", "second"),
  frac = NULL
)

add_premium_schedule(
  contract,
  k = 1L,
  timing = c("due", "immediate"),
  premium_start = c("issue", "deferred"),
  n_prem = NULL,
  woolhouse = c("none", "first", "second"),
  frac = NULL
)

Arguments

Value

The original contract with a premium_schedule component.

The original contract with a premium_schedule component.

See Also

Other life-contingencies: add_insurance(), annuity_multi(), 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()

Other life-contingencies: add_insurance(), annuity_multi(), 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 = 40:90,
  lx = round(100000 * exp(-0.018 * (0:50)^1.35))
)

life_contract(
  lt = lt,
  lives = "single",
  x = 40,
  i = 0.05
) |>
  add_insurance(
    type = "term",
    benefit = 100000,
    n = 20
  ) |>
  add_premium_schedule(
    k = 12,
    n_prem = 10,
    timing = "due"
  )

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: amort_schedule_general(), 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"
)

General amortization schedule with variable rates and payments

Description

Builds a loan amortization schedule allowing the effective interest-rate pattern, regular-payment pattern, and extra-principal pattern to vary by period.

Usage

amort_schedule_general(
  principal,
  n,
  i,
  i_type = "effective",
  m = 1L,
  k = 1L,
  timing = c("immediate", "due"),
  payment = NULL,
  extra_principal = 0,
  output = c("schedule", "summary"),
  tol = 1e-08
)

Arguments

Details

The function extends the fixed-pattern workflow of amort_schedule without modifying that function. It supports:

• a scalar interest rate recycled over all periods;

• a vector of interest rates, one for each period;

• a level payment computed automatically;

• a scalar or period-specific payment vector;

• a payment function depending on the current loan state.

Each value of i is interpreted as an annual rate under its associated i_type and m. It is first converted to an annual effective rate and then to the effective rate for one amortization period:

i_j^{(p)} = (1 + i_j)^{1/k} - 1.

When payment = NULL, the level payment is determined from the period-specific discount factors. For payments in arrears,

P = \frac{L}{\sum_{j=1}^{n} \prod_{h=1}^{j}(1+i_h^{(p)})^{-1}}.

For payments in advance, the discount factors correspond to payment times 0,1,\ldots,n-1.

A payment smaller than the interest charged may produce negative amortization. The schedule identifies such periods explicitly.

Value

With output = "schedule", a tibble with one row per realized period.

With output = "summary", a one-row tibble containing the initial principal, number of realized periods, total interest, total paid, ending balance, and an indicator of negative amortization.

See Also

amort_schedule, a_angle, standardize_interest

Other amortization: amort_schedule(), sinking_fund_schedule()

Examples

# Level payments and a constant rate
amort_schedule_general(
  principal = 100000,
  n = 12,
  i = 0.12,
  i_type = "nominal_interest",
  m = 12,
  k = 12
)

# Increasing payments
amort_schedule_general(
  principal = 10000,
  n = 5,
  i = 0.06,
  payment = c(1800, 1900, 2000, 2200, 3000)
)

# Period-specific annual effective rates
amort_schedule_general(
  principal = 10000,
  n = 4,
  i = c(0.04, 0.05, 0.06, 0.07),
  payment = NULL
)

# Payment determined from the current balance
payment_rule <- function(
  period,
  ob_start,
  i_effective_period
) {
  1500 + 100 * (period - 1)
}

amort_schedule_general(
  principal = 8000,
  n = 6,
  i = 0.05,
  payment = payment_rule
)

# Compact summary
amort_schedule_general(
  principal = 100000,
  n = 60,
  i = 0.08,
  k = 12,
  output = "summary"
)

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: add_insurance(), add_premium_schedule(), 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. The payment stream is normalized to an annual payment rate of 1:

\ddot{a}_{x:\overline{n}|}^{(k)} = \frac{1}{k}\sum_{j=0}^{kn-1} v^{j/k}\,{}_{j/k}p_x.

Consequently, each k-thly installment has amount 1/k. This normalization is essential when the function is used as the premium annuity in the equivalence principle: the resulting premium is annualized, and the amount paid at each installment is the annualized premium divided by k.

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: add_insurance(), add_premium_schedule(), 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. For exact valuation, a fractional term is admissible whenever it contains a whole number of payments:

nk \in \mathbb{N}.

Woolhouse approximations are applied only to the standard joint-life and last-survivor statuses. For a deferred annuity, the Woolhouse endpoint corrections are multiplied by the issue-date value of the status at the beginning of the payment period. This preserves the deferment factor v^h\,{}_hp_{xy} or its last-survivor analogue.

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: add_insurance(), add_premium_schedule(), 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
)

Convexity of a general cash-flow stream

Description

Computes the yield convexity of a general cash-flow stream at a specified valuation time.

Usage

convexity_cash_flow(
  cf,
  t,
  rate,
  valuation_time = 0,
  output = c("value", "audit")
)

Arguments

Details

Let \tau be the valuation time. Under an effective yield i, the value of the remaining cash-flow stream is

P_{\tau}(i) = \sum_{j:t_j>\tau} C_j(1+i)^{-(t_j-\tau)}.

The convexity returned by this function is the relative second derivative of value with respect to the effective yield:

\mathcal{C}_{\tau} = \frac{1}{P_{\tau}(i)} \frac{d^2P_{\tau}(i)}{di^2}.

Equivalently,

\mathcal{C}_{\tau} = \frac{ \sum_{j:t_j>\tau} (t_j-\tau)(t_j-\tau+1) C_j(1+i)^{-(t_j-\tau+2)} }{ P_{\tau}(i) }.

Together with modified duration, this convexity gives the second-order approximation

\frac{\Delta P_{\tau}}{P_{\tau}} \approx -D_{\mathrm{mod},\tau}\Delta i + \frac{1}{2}\mathcal{C}_{\tau}(\Delta i)^2.

The function follows an ex-cash-flow convention: cash flows occurring exactly at valuation_time are excluded. Therefore, the result represents convexity immediately after any cash flow paid at that time.

For streams containing both positive and negative cash flows, convexity remains a yield-sensitivity measure, but it may be negative and may not have the usual interpretation associated with conventional bonds.

Value

If output = "value", a numeric scalar.

If output = "audit", a tibble with six columns: time, remaining_time, cash_flow, discount_factor, present_value, and convexity_contribution.

See Also

duration_cash_flow()

Examples

convexity_cash_flow(
  cf = c(100, 100, 1100),
  t = c(1, 2, 3),
  rate = 0.05
)

convexity_cash_flow(
  cf = c(100, 100, 1100),
  t = c(1, 2, 3),
  rate = 0.05,
  valuation_time = 1
)

convexity_cash_flow(
  cf = c(100, 100, 1100),
  t = c(1, 2, 3),
  rate = 0.05,
  output = "audit"
)

Discount factor under conventional or time-varying interest

Description

Computes the discount factor from time t back to time s using exactly one of three interest specifications:

• a conventional interest rate i;

• an accumulation function a(t);

• a time-varying force of interest delta(t).

Usage

discount_factor(
  s = 0,
  t,
  i = NULL,
  i_type = "effective",
  m = 1,
  a = NULL,
  delta = NULL,
  subdivisions = 100L,
  rel.tol = 1e-08,
  tidy = FALSE
)

Arguments

Details

The discount factor is the reciprocal of the corresponding accumulation factor:

v(s,t) = \frac{1}{A(s,t)}.

Therefore,

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

for a constant annual effective rate,

v(s,t) = \frac{a(s)}{a(t)}

for an accumulation function, and

v(s,t) = \exp\left(-\int_s^t \delta(u)\,du\right)

for a time-varying force of interest.

Exactly one of i, a, or delta must be supplied.

Numeric arguments may have length 1 or a common length. Scalars are recycled over the remaining scenarios, making the function suitable for use inside dplyr::mutate() pipelines.

This function handles general discounting over an interval [s,t]. For discount factors obtained specifically from a spot-rate curve, see discount_factor_spot.

Value

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

If tidy = TRUE, a tibble containing the interval, interest model, relevant intermediate quantities, accumulation factor, and discount factor.

See Also

accumulation_factor, discount_factor_spot, present_value, pv_flow

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

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

Examples

# Constant annual effective interest
discount_factor(
  t = 5,
  i = 0.07
)

# One rate recycled over several times
discount_factor(
  t = c(1, 2, 5),
  i = 0.07
)

# Accumulation function
a_fun <- function(t) {
  exp(0.03 * t + 0.002 * t^2)
}

discount_factor(
  s = 2,
  t = 5,
  a = a_fun
)

# Time-varying force of interest
delta_fun <- function(t) {
  0.03 + 0.004 * t
}

discount_factor(
  s = 2,
  t = 5,
  delta = delta_fun
)

# Pipe-friendly use
if (requireNamespace("dplyr", quietly = TRUE) &&
    requireNamespace("tibble", quietly = TRUE)) {
  scenarios <- tibble::tibble(
    i = 0.07,
    t = c(1, 2, 3, 5)
  )

  scenarios |>
    dplyr::mutate(
      discount = discount_factor(
        t = t,
        i = i
      )
    )
}

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: accumulation_factor(), discount_factor(), 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
)

Duration of a general cash-flow stream

Description

Computes the Macaulay or modified duration of a general cash-flow stream at a specified valuation time.

Usage

duration_cash_flow(
  cf,
  t,
  rate,
  valuation_time = 0,
  duration = c("macaulay", "modified"),
  output = c("value", "audit")
)

Arguments

Details

Let \tau be the valuation time. Under an effective yield i, the value of the remaining cash-flow stream is

P_{\tau} = \sum_{j:t_j>\tau} C_j(1+i)^{-(t_j-\tau)}.

The Macaulay duration measured from \tau is

D_{\mathrm{Mac},\tau} = \frac{ \sum_{j:t_j>\tau} (t_j-\tau)C_j(1+i)^{-(t_j-\tau)} }{ P_{\tau} }.

The modified duration with respect to the effective yield is

D_{\mathrm{mod},\tau} = \frac{D_{\mathrm{Mac},\tau}}{1+i}.

The function follows an ex-cash-flow convention: cash flows occurring exactly at valuation_time are excluded. Therefore, the result represents duration immediately after any cash flow paid at that time.

For streams containing both positive and negative cash flows, duration remains a yield-sensitivity measure, but it may not have the usual interpretation as a weighted-average payment time.

Value

If output = "value", a numeric scalar.

If output = "audit", a tibble with six columns: time, remaining_time, cash_flow, discount_factor, present_value, and duration_contribution.

Examples

duration_cash_flow(
  cf = c(100, 100, 1100),
  t = c(1, 2, 3),
  rate = 0.05
)

duration_cash_flow(
  cf = c(100, 100, 1100),
  t = c(1, 2, 3),
  rate = 0.05,
  duration = "modified"
)

duration_cash_flow(
  cf = c(100, 100, 1100),
  t = c(1, 2, 3),
  rate = 0.05,
  valuation_time = 1,
  output = "audit"
)

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: accumulation_factor(), discount_factor(), 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: accumulation_factor(), discount_factor(), fv_flow(), irr_flow(), irr_flow_multi(), plot_cash_flow(), present_value(), pv_flow(), solve_value()

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: accumulation_factor(), discount_factor(), future_value(), irr_flow(), irr_flow_multi(), plot_cash_flow(), present_value(), pv_flow(), solve_value()

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: add_insurance(), add_premium_schedule(), 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: add_insurance(), add_premium_schedule(), 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: add_insurance(), add_premium_schedule(), 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: accumulation_factor(), discount_factor(), 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: accumulation_factor(), discount_factor(), future_value(), fv_flow(), irr_flow_multi(), plot_cash_flow(), present_value(), pv_flow(), solve_value()

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: accumulation_factor(), discount_factor(), future_value(), fv_flow(), irr_flow(), plot_cash_flow(), present_value(), pv_flow(), solve_value()

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: add_insurance(), add_premium_schedule(), 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. The output makes the units explicit through payment_per_payment = payment and payment_annualized = k * payment.

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

Legacy-compatible amount of each annuity payment.

payment_per_payment

Amount paid at each payment date.

payment_annualized

Payment amount multiplied by the number of payments per year.

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_multilife_status(), mc_premium(), mc_reserve(), simulate_lifetime(), simulate_lifetimes(), 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. Under this discrete convention, finite terms and deferral periods must be whole numbers of years because eligibility is determined from the curtate lifetime K_x. If timing = "moment_of_death", death benefits are discounted using T_x, and fractional terms or deferral periods are allowed.

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_multilife_status(), mc_premium(), mc_reserve(), simulate_lifetime(), simulate_lifetimes(), 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

Constructs simulated actuarial losses from present values of benefits and premium-payment annuities while keeping annualized premiums distinct from amounts paid at each premium date.

Usage

mc_loss(
  .data = NULL,
  col_Z = "pv_benefit",
  col_Y = "pv_annuity",
  col_P = "P",
  col_L = "L",
  P = NULL,
  premium_unit = c("auto", "annualized", "per_payment", "annuity_scale"),
  k = NULL,
  annuity_payment = NULL,
  tol = 1e-10,
  ...
)

Arguments

Details

Let Z be the present value random variable of benefits. Suppose col_Y contains

Y_c = c\sum_j v^{t_j},

where c is the amount used in mc_annuity at each of the k premium dates per year.

If P^{(k)} is the annualized premium, the actual installment is P^{(k)}/k, and the simulated present value of premiums is

\Pi = \frac{P^{(k)}}{k c}Y_c.

Hence the loss at issue is

L = Z - \Pi.

The recommended normalized premium annuity uses payment = 1 / k in mc_annuity. Then c=1/k, Y_c=Y^{(k)}, and the expression simplifies to

L = Z - P^{(k)}Y^{(k)}.

This convention agrees with premium_x, premium_xy, reserve_x, and reserve_xy: the premium is annualized, while the amount collected at each date is the annualized premium divided by k.

For backward compatibility, legacy columns P and premium are interpreted as coefficients that multiply the supplied annuity present value directly. If such a coefficient is q, then

P_{\mathrm{per\ payment}} = q c, \qquad P^{(k)} = k q c.

Value

A tibble containing the original simulation and standardized columns:

premium_annualized

Annualized premium P^{(k)}.

premium_per_payment

Amount collected at each premium date.

payments_per_year

Premium payment frequency k.

premium_annuity_scale

Coefficient multiplying col_Y.

pv_premiums

Simulated present value of premium income.

L

Simulated loss, or the name supplied through col_L.

A compatibility column loss is synchronized with col_L.

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

mc_annuity, mc_insurance, mc_premium, mc_reserve, premium_x, premium_xy

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

Examples

simulated <- tibble::tibble(
  pv_benefit = c(900, 700, 1100),
  pv_annuity = c(8, 7, 9),
  payment_per_payment = 1 / 12,
  payment_annualized = 1,
  payments_per_year = 12,
  premium_annualized = 120
)

simulated |>
  mc_loss()

# A premium supplied directly as an annualized amount
simulated |>
  mc_loss(
    P = 120,
    premium_unit = "annualized"
  )

# Historical coefficient multiplying the annuity PV directly
tibble::tibble(
  pv_benefit = c(900, 700),
  pv_annuity = c(8, 7),
  P = 100
) |>
  mc_loss()

Compute multiple-life simulated status variables

Description

Combines simulated future lifetimes for several lives into one simulated multiple-life status. A joint-life status terminates at the first death, whereas a last-survivor status terminates 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",
  tol = 1e-10
)

Arguments

Details

For simulated complete future lifetimes T_1,\ldots,T_r, the multiple-life complete future lifetime is

T_{\mathrm{joint}}=\min(T_1,\ldots,T_r)

for the joint-life status and

T_{\mathrm{last}}=\max(T_1,\ldots,T_r)

for the last-survivor status.

The corresponding curtate future lifetime is obtained with the same minimum or maximum operation on K_1,\ldots,K_r. Because the function validates K_j \le T_j < K_j+1, the returned values satisfy the same curtate-complete relationship.