Package 'tidyactuarial'

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

Description

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

Usage

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

Arguments

Details

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

Adjustment policies after extra principal payments:

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

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

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

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

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

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

Value

A tibble with one row per realized period and columns:

period

Period index.

ob_start

Outstanding balance at the start of the period.

interest

Interest charged during the period.

payment

Regular payment in the period.

extra_principal

Extra principal paid in the period.

principal

Principal repaid through the regular payment.

total_principal

Total principal repaid in the period.

cashflow

Total payment made in the period.

ob_end

Outstanding balance at the end of the period.

i_effective_annual

Equivalent annual effective rate.

i_effective_period

Equivalent effective rate per schedule period.

k

Schedule frequency.

timing

Payment timing convention.

adjust

Adjustment rule used.

See Also

a_angle, present_value, pv_flow, standardize_interest

Other amortization: sinking_fund_schedule()

Examples

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

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

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

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
)

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
)

Description

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

Usage

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

Arguments

Details

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

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

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

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

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

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

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

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

Value

A single numeric value representing the APV.

See Also

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

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

Examples

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

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

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

Description

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

Usage

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

Arguments

Details

The function supports:

• whole-life annuities,

• temporary annuities,

• integer deferment,

• annual or k-thly payments,

• exact fractional survival for k-thly payments,

• first- and second-order Woolhouse approximations.

This function follows the compact actuarial notation used throughout tidyactuarial:

• lt: life table;

• x: actuarial age;

• i: interest rate;

• i_type: interest-rate type;

• m: interest conversion frequency;

• n: annuity term;

• h: deferment period;

• k: payment frequency.

For annual annuities-due,

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

For annual annuities-immediate,

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

Deferment is handled through

$v^h\,{}_hp_x,$

where $h$ is the deferment period.

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

Value

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

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

See Also

insurance_x, premium_x, reserve_x, t_px, t_Ex

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

Examples

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

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

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

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

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

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

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

Description

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

Usage

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

Arguments

Details

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

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

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

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

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

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

Value

If tidy = FALSE, a numeric scalar.

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

See Also

annuity_x, insurance_xy, premium_xy, t_pxy, t_px

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

Examples

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

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

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

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

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

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

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

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
)

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
)

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
)

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
)

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
)

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
)

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
)

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)

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)

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
)

Description

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

Usage

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

Arguments

Details

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

• annual effective rate,

• nominal annual interest rate,

• nominal annual discount rate,

• force of interest.

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

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

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

If $t = 0$, the discount factor is 1.

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

Value

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

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

See Also

standardize_interest, present_value, pv_flow

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

Examples

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

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

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

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

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.

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)

Description

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

Usage

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

Arguments

Details

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

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

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

so that

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

Two extraction methods are supported for the spot rates:

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

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

No extrapolation is performed outside the observed maturity range.

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

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

Value

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

References

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

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

See Also

yield_curve, discount_factor_spot, standardize_interest

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

Examples

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

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

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

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

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: