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}

More generally, let N=nk, let b=0 for immediate payments and b=1 for due payments. The deferred discrete factor is

\sum_{j=1}^{N} \exp\{-\delta[h+(j-b)/k]\}.

Each discrete payment is one unit, whereas a continuous annuity pays one unit per year. The continuous deferred factor is \int_h^{h+n} e^{-\delta t}\,dt.

The original log accumulation rate is retained even if its annual effective equivalent rounds to -1 or overflows. Geometric sums and continuous integrals use stable logarithmic formulas with exact zero-rate limits, rather than replacing a small nonzero rate by zero. Perpetuities require a strictly positive rate, without a numerical lower cutoff. Monetary values combine payments with log factors before declaring range loss; a reported annuity factor or equivalent rate may still be non-finite.

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

Accrued coupon interest and clean/dirty bond prices

Description

Computes the coupon interest accrued between the previous coupon date and settlement, and optionally reconciles a quoted clean or dirty bond price. This is a day-count calculation, not a yield-based bond valuation.

Usage

accrued_interest(
  .data = NULL,
  face = NULL,
  c = NULL,
  settlement = NULL,
  previous_coupon = NULL,
  next_coupon = NULL,
  k = 1L,
  day_count = "act/act",
  clean_price = NULL,
  dirty_price = NULL,
  tol = 1e-10
)

Arguments

Details

Let F be face value, c the nominal annual coupon rate, and k the coupon frequency. The regular coupon is C = F * c / k.

For "act/act", with d actual elapsed calendar days and D actual days in the full coupon period, the year fraction and accrued interest are alpha = d / (k * D) and AI = F * c * alpha = C * d / D.

For "act/360" and "act/365", alpha equals actual elapsed calendar days divided by 360 or 365 respectively; for "30e/360", it equals the number of 30E/360 days divided by 360. These conventions accrue at the annual coupon rate and therefore need not reach exactly one regular coupon at the end of every actual calendar coupon period.

The price identity is dirty_price = clean_price + accrued_interest. A price supplied to this function is not computed from a yield curve. Calculations assume a fixed-rate bond with regular coupon periods, no stubs, no ex-coupon adjustment, no withholding tax, no amortizing principal, and no transaction costs. The caller supplies the correct bracketing coupon dates: a full coupon schedule is not inferred.

All direct-input arguments of length greater than one must have the same length; length-one values are recycled. Calendar dates must have class Date, not bare character strings or numeric date serials. Finite coupon and accrued amounts are recovered from overflowing intermediate products when possible; nonrepresentable final amounts cause an error.

Value

A tibble. For direct input, it contains the bond parameters, settlement/coupon dates, the chosen convention, coupon_per_period, days_elapsed, days_in_period, year_fraction, coupon_fraction, accrued_interest, clean_price, and dirty_price. For data-frame input, original columns are retained and the audit columns added. When neither price is supplied, both price columns contain NA_real_.

See Also

bond_cash_flows(), bond_price(), bond_ytm()

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

Examples

accrued_interest(
  face = 1000, c = 0.06, k = 2,
  previous_coupon = as.Date("2026-01-01"),
  settlement = as.Date("2026-04-01"),
  next_coupon = as.Date("2026-07-01"),
  clean_price = 1005
)

# The same position under two market day-count conventions.
accrued_interest(
  face = 1000, c = 0.06, k = 2,
  previous_coupon = as.Date("2026-01-01"),
  settlement = as.Date("2026-04-01"),
  next_coupon = as.Date("2026-07-01"),
  day_count = "30e/360"
)

# Pipe-friendly portfolio input: each row is one bond position.
bonds <- tibble::tibble(
  bond = c("A", "B"), face = c(1000, 500), c = c(0.06, 0.04),
  k = c(2L, 2L),
  previous_coupon = as.Date(c("2026-01-01", "2026-01-01")),
  settlement = as.Date(c("2026-04-01", "2026-04-01")),
  next_coupon = as.Date(c("2026-07-01", "2026-07-01"))
)
bonds |> accrued_interest()

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. Conventional inputs are valued using their original log accumulation rate. In tidy output, the annual equivalent may round to -1 or overflow to Inf even when the requested interval factor is positive and finite.

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: bootstrap_spot_curve(), discount_factor(), discount_factor_spot(), forward_curve(), forward_rate(), interest_equivalents(), par_rate(), 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)

# The same financial law in three representations
c(
  rate = accumulation_factor(t = 5, i = 0.03, i_type = "force"),
  accumulation = accumulation_factor(t = 5, a = function(t) exp(0.03 * t)),
  varying_force = accumulation_factor(t = 5, delta = function(t) 0.03)
)

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

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.

Components may be added in either order and unrelated contract fields are retained. Standard finite terms must round to at least one year. Large integer-valued terms, deferments and frequencies are stored as doubles when outside R's integer range; feasibility of a valuation horizon is checked by the consumer. Variable-benefit functions are stored without being evaluated.

Value

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

Add a contingent premium-payment schedule to a life contract

Description

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
)

Arguments

Details

The fractional-age assumption is resolved when this component is added: later replacement of the insurance component does not change this stored assumption. 'n_prem = NULL' remains unresolved until valuation. Finite schedules must contain a finite, positive whole number of payments. Large integer-valued frequencies are stored as doubles when needed.

Value

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

Compute the aggregate loss distribution

Description

Evaluates the distribution of the collective aggregate loss

S = \sum_{i=1}^{N} X_i

from a tidyact_collective_risk_spec object.

The function separates the actuarial model from the computational algorithm. It never fits a distribution, never simulates the aggregate loss, and never discretizes a continuous severity implicitly.

Usage

aggregate_distribution(
  x,
  method = c("auto", "analytic", "convolution", "panjer", "fft"),
  tol = 1e-08,
  max_loss = NULL,
  ...
)

Arguments

Details

aggregate_distribution() operates only on an already specified collective model. The probabilistic model is never changed in order to make an algorithm applicable.

In particular, if the severity distribution is continuous and no supported analytic form is available, the function stops and asks the user to apply discretize_severity() explicitly before using Panjer recursion or FFT.

Automatic method selection

With method = "auto", the function uses the following hierarchy:

1. an implemented analytic representation for deterministic aggregate structures;

2. Panjer recursion when the severity is on a lattice and the frequency distribution supplies valid Panjer parameters;

3. exact finite convolution when both frequency and severity have finite discrete support;

4. FFT when the severity is on a lattice and the frequency distribution supplies the probability operations required to truncate its count support.

If none of these conditions is satisfied, an informative error is returned.

Analytic method

The initial analytic engine handles aggregate losses that are degenerate at zero and deterministic severities. If X = c almost surely, then

S = cN

and the aggregate probabilities are obtained directly from the count distribution. Infinite count support is truncated according to tol unless max_loss supplies a tighter explicit cutoff.

Additional analytic compound families may be added later without changing the public interface.

Convolution method

The convolution engine is exact for finite claim-count support and finite discrete severity support. It evaluates

P(S \in A) = \sum_n P(N=n) P(X_1+\cdots+X_n \in A)

by repeated finite convolution. If max_loss is supplied, the full finite distribution is evaluated first and probability above the requested cutoff is reported as tail probability.

Panjer method

For a frequency distribution in the (a,b,0) class,

p_n = \left(a + \frac{b}{n}\right)p_{n-1},

and a lattice severity with probabilities f_j, the aggregate probabilities satisfy

g_0 = G_N(f_0)

and, for k \ge 1,

g_k = \frac{ \sum_{j=1}^{k} \left(a + \frac{bj}{k}\right) f_j g_{k-j} }{ 1-a f_0 }.

Only severity probabilities available on the lattice are used. No discretization is performed by this engine.

FFT method

FFT evaluates a finite polynomial approximation to the compound distribution. For an infinite claim-count distribution, the count support is first truncated at a quantile whose omitted probability is no greater than tol. This omitted count probability is carried explicitly into tail_probability; it is not wrapped into the retained FFT grid.

The FFT engine therefore uses the truncated count polynomial

\sum_{n=0}^{n_{\max}} p_n z^n

rather than the full PGF. This avoids silently treating circular aliasing as aggregate probability.

Returned probabilities

The returned grid contains:

• loss: aggregate loss amount;

• probability: probability mass assigned to that amount;

• cdf: cumulative probability captured on the retained grid.

The grid is intentionally not renormalized when a positive tail remains. Consequently,

\sum p_s + p_{\mathrm{omitted}} = 1

up to numerical tolerance. With loss-grid truncation alone, omitted mass is above the grid. FFT count truncation also omits events with large claim counts but potentially small aggregate losses (especially when zero severities are possible). Thus tail_probability is total unrepresented mass, not necessarily P(S > max(grid$loss)). VaR checks whether omitted count mass could change its selected quantile; TVaR and stop-loss reject unresolved mass.

Value

An object with classes "tidyact_aggregate_distribution" and "tidyact_risk_distribution". It contains:

schema_version

Internal schema version.

method

The computational method actually used.

grid

A tibble with loss, probability, and cdf.

support

Support information for the retained grid.

tail_probability

Probability not represented on the retained grid.

model

The source collective risk specification.

label

The model label, if any.

metadata

Audit information about method selection, truncation, exactness, and numerical controls.

References

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

Klugman, S. A., Panjer, H. H., and Willmot, G. E. (2019). Loss Models: From Data to Decisions, 5th ed. Wiley.

See Also

collective_risk_spec(), discretize_severity(), aggregate_moments()

Examples

frequency <- frequency_spec(
  "poisson",
  lambda = 4
)

severity <- severity_spec(
  "gamma",
  shape = 2,
  rate = 0.001
)

model <- collective_risk_spec(
  frequency,
  severity
)

# Continuous severities are never discretized implicitly.
## Not run: 
aggregate_distribution(model)

## End(Not run)

lattice_severity <- discretize_severity(
  severity,
  step = 100
)

lattice_model <- collective_risk_spec(
  frequency,
  lattice_severity
)

aggregate_distribution(
  lattice_model,
  method = "panjer",
  tol = 1e-8
)

aggregate_distribution(
  lattice_model,
  method = "fft",
  tol = 1e-8
)

Calculate moments of a collective aggregate loss

Description

Calculates analytical raw moments, central moments, or cumulants of a collective risk model

S = \sum_{i=1}^{N} X_i,

using the moments of the claim count distribution and the individual severity distribution stored in a tidyact_collective_risk_spec object.

No simulation, numerical integration, discretization, or approximation is performed by this function.

Usage

aggregate_moments(x, order = 1:4, type = "raw")

Arguments

Details

Let

m_j = E[X^j]

denote the raw severity moments and

\nu_k = E[(N)_k]

the factorial moments of the claim count. For positive integer r, the raw aggregate moment is evaluated through the random-sum identity

E[S^r] = \sum_{k=1}^{r} \nu_k B_{r,k}(m_1,\ldots,m_{r-k+1}),

where B_{r,k} is a partial exponential Bell polynomial.

This formulation includes the familiar identities

E[S] = E[N]E[X]

and

\operatorname{Var}(S) = E[N]\operatorname{Var}(X) + \operatorname{Var}(N)(E[X])^2.

Central moments and cumulants are derived algebraically from aggregate raw moments. For a compound Poisson model, cumulants use the direct identity

\kappa_r(S) = \lambda E[X^r]

whenever the corresponding severity moment is finite.

The function respects the status information returned by distribution_moments(). Results are classified as:

• "finite": a finite numerical result;

• "infinite": a mathematically divergent raw or central moment;

• "undefined": the requested quantity cannot be defined from the available moments;

• "overflow": a theoretically finite calculation exceeded floating-point range.

Because both frequency and severity are nonnegative in this module, a finite first moment equal to zero identifies a degenerate-at-zero component. If either N=0 almost surely or X=0 almost surely, then the aggregate loss is degenerate at zero and all positive-order aggregate moments and cumulants are zero.

Value

A tibble::tibble() with one row per requested order and columns: type, order, value, and status.

References

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

Klugman, S. A., Panjer, H. H., and Willmot, G. E. (2019). Loss Models: From Data to Decisions, 5th ed. Wiley.

See Also

collective_risk_spec(), distribution_moments()

Examples

frequency <- frequency_spec(
  "poisson",
  lambda = 4
)

severity <- severity_spec(
  "gamma",
  shape = 2,
  rate = 0.001
)

model <- collective_risk_spec(
  frequency,
  severity
)

aggregate_moments(model)

aggregate_moments(
  model,
  order = 1:4,
  type = "central"
)

aggregate_moments(
  model,
  order = 1:4,
  type = "cumulant"
)

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.

The original log accumulation rate determines the effective period rate and the level payment, avoiding cancellation near zero and saturation of the annual equivalent. The periodic rate must remain finite and greater than -1. The balance tolerance is in monetary units and does not classify nonzero interest rates as zero. Here n counts periods, so the contractual term in years is n / k.

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.

Named extra payments must identify exact integer periods; repeated names are summed. On a payoff row, requested extra principal has priority and the regular payment is reduced to the remaining amount due. Interest still follows the selected timing, and no rows follow full payoff. The general schedule uses a different allocation priority; see amort_schedule_general.

With adjust = "payment", the payment is recalculated after every realized period for the remaining contractual periods, even if no extra payment occurred. A supplied payment is the initial payment. The "none" and "term" policies keep the regular amount; both stop when the debt is repaid and may realize fewer than n rows. A requested loan below tol may produce an empty schedule. Calculated payments for active balances must be representable and positive; non-finite monetary ledger entries cause an explicit error. This does not require a representable displayed annual effective equivalent. The schedule allocates up to n rows; feasible terms are limited by integer indexing and available memory.

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.

Original log accumulation rates are converted directly to period rates. Level-payment discount factors use cumulative log growth, rather than products of rounded accumulation factors. Period rates must remain finite and greater than -1; a displayed annual equivalent may overflow even when the period rate is representable. The term is n / k years.

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.

Negative amortization means that interest exceeds the total payment, including extras, by more than tol. This condition applies to both timings, including interest accrued after an advance payment. Under due timing, the principal columns continue to record payments before interest; the negative-amortization flag refers to the net debt movement.

On a payoff row the regular payment is applied first and extras are capped at the remaining debt; no callback is evaluated after full payoff. This allocation differs from amort_schedule, which preserves the requested extra first. Both cap total cash flow at the amount due. Automatically calculated level payments are determined before extras and are not recast by this function. The discount sum is evaluated in log space before combining it with the principal. Active balances require a positive, representable calculated payment; non-finite monetary ledgers cause errors. A principal below tol may produce an empty schedule, and small residual balances may be treated as zero within that absolute tolerance. Storage grows with n; feasible terms are limited by integer indexing and available memory.

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.

Rate validation uses standardize_interest. Valuation retains the original log accumulation rate, even if the displayed annual effective equivalent rounds to -1 or overflows.

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.

Let b=0 for immediate payments and b=1 for due payments, r=\delta/k, and H=hk. The present value is \sum_{j=1}^N P_j\exp[-r(H+j-b)]; the value at h+n years is \sum_{j=1}^N P_j\exp[r(N-j+b)]. In a custom stream, g is an increment in currency per payment, not an annual growth rate. Signed and zero payments are supported.

Payments are enumerated explicitly, so memory grows with N. Capital-factor products are evaluated stably using the shared cash-flow rules. Those rules do not recover arbitrary extreme signed cancellation across different factors, or payments already outside the numeric range.

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.

Valuation retains the original annual log rates \delta_i and \delta_g. Let r=\delta_i/k, s=\delta_g/k, H=hk, and b=0 for immediate or b=1 for due payments. With G_N(z)=\sum_{j=0}^{N-1}\exp(zj), the finite present value is

P_1\exp[-r(H+1-b)]G_N(s-r).

The accumulated value at h+n years is

P_1\exp[br+(N-1)\max(r,s)]G_N(-|s-r|).

Stable logarithmic sums avoid subtracting nearly equal effective rates or accumulation levels. The spread is computed before period conversion as (\delta_g-\delta_i)/k; no nonzero spread is replaced by zero. For matching effective rates or nominal rates with equal conversion frequencies, log-ratio identities preserve close input differences before taking logarithms. Widely separated ratios that lose range fall back to the original log rates. Different rate families retain the accuracy limits of their separate conversions.

A perpetuity requires \delta_i>\delta_g, without an arbitrary numerical gap. Its value is P_1\exp[-r(H+1-b)]/[1-\exp(s-r)]. Missing finite terms propagate missing values. Signed and zero first payments retain their meaning. Standalone audit rates may saturate, while monetary values combine the first payment with log factors before declaring range loss. No arbitrary precision or universal extreme-range guarantee is implied. Unlike g in annuity_arith, this g is an annual growth-rate specification and not a monetary increment per payment.

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"),
  frac = c("UDD", "CF", "CML", "Balducci")
)

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})].

All values are measured at issue, conditional on the stated lives being alive at issue. Ages identify lives within one policy, not policy scenarios. A k-thly payment is 1/k of an annual unit: exact valuation sums F(h+j/k)/k, with F(t)=e^{-\delta t}w(t) and the expected payment weight w(t) defined above. Due uses j=0,\ldots,nk-1; immediate uses j=1,\ldots,nk. The historical name "reversionary" means joint-and-survivor payments; it does not mean payments only after a death.

For k > 1, woolhouse = "none" uses the actual fractional payment grid. First-order Woolhouse subtracts (1-1/k)[F(h)-F(h+n)]/2 from the annual due value. Second-order also subtracts (1-1/k^2)[(\delta+\eta_h)F(h)- (\delta+\eta_{h+n})F(h+n)]/12. Here \eta_t=-\log(w(t+1)/w(t)) is an annual forward estimate of the logarithmic decay of the payment weight, not an exact instantaneous force. Positive supported weights at both borders and the following year are required for second-order approximation. This is a smoothness approximation, not exact fractional valuation under frac; negative approximations produce a warning. Immediate subtracts [F(h)-F(h+n)]/k from due. Exact valuation requires consecutive annual ages and retains the documented conservative common-age horizon; it does not extrapolate unobserved lives.

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

# Half-yearly payments, each equal to half an annual unit, under UDD
annuity_multi(lt, ages = c(60, 62), i = 0.05, n = 5, k = 2,
              timing = "due", frac = "UDD")

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.

Scenarios and tidy workflows. All arguments except lt and tidy may have a common positive length; only length-one arguments recycle. n = NULL and frac = NULL keep their scalar default meanings. Scenarios are paired by position, not expanded to a Cartesian product, and each describes one life under the shared table. Invalid or missing inputs are rejected with the scenario number; no partial result is returned. Use dplyr::mutate() with tidy = FALSE for portfolios, or tidy = TRUE for an auditable scenario table. Different mortality tables require separate calls, for example in a list-column workflow.

Model and numerical limits. Discounting retains the original log accumulation rate; exact payments are valued from the issue age, avoiding products of separately rounded deferment and conditional values. Intermediate diagnostic values can be zero or infinite while the APV remains finite. Tables must have an annual age grid and nonincreasing finite lx, with a positive count at issue. For compatibility, a count of zero is assumed at one year beyond the last recorded age, even for an open input table. Known extinct tails contribute zero. Woolhouse is an approximation using annual survival estimates of boundary forces, not an exact integral; its second order requires positive survival where a boundary force is needed. Negative approximations generate a warning and are not clamped. Prefer woolhouse = "none" for exact payments under the chosen fractional assumption. At n = 0, APV and the annuity value at start are zero, while the zero-term pure endowment factor is one.

Value

If tidy = FALSE, a numeric vector of actuarial present values, of length one for a single scenario.

If tidy = TRUE, a tibble with one row per scenario, 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")

# Parallel single-life scenarios, suitable for mutate()
policies <- tibble::tibble(age = c(60, 61, 62), rate = c(0.03, 0.04, 0.05))
dplyr::mutate(policies,
  apv = annuity_x(lt, x = age, i = rate, n = 2, k = 12, timing = "due"))
annuity_x(lt, x = c(60, 61), i = 0.04, n = c(2, 3), tidy = TRUE)

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}.

Both lives are alive at issue; both, x_only and y_only refer to occupation at each payment date, without restarting both lives after a death. A designated reversion to y uses both=0, x_only=0, y_only=1; this differs from payments to either sole survivor and from a joint-and-survivor annuity paying while both are alive as well.

Exact valuation sums signed state payments on dates h+j/k, with each payment equal to its state rate divided by k. Cumulative death probabilities use direct survivor-count decrements and fractional interval masses, avoiding cancellation in 1-S. Original log interest, probabilities and monetary weights are combined before exponentiating when necessary.

Woolhouse approximations apply only to standard joint-life/last-survivor statuses. Put F(t)=exp(-g*t)w(t), where w is the status survival from issue and g is the input rate's annual log accumulation. First order subtracts (1-1/k)(F(h)-F(h+n))/2 from the annual due annuity. Second order also subtracts (1-1/k^2)((g+eta(h))F(h)-(g+eta(h+n))F(h+n))/12, with eta(t)=-log(w(t+1)/w(t)), a forward annual estimate, not an exact instantaneous force. Second order requires positive supported weights and the following year at both borders; otherwise use none or first. Immediate subtracts (F(h)-F(h+n))/k from the due approximation. A negative approximation is reported with a warning, without clipping.

Tables must satisfy the annual consistency requirements of t_pxy; issue ages must have positive lx for nonempty valuations. Payment grids must be finite, representable and no larger than R's integer range. One call values one contract; benefit vectors describe states, not scenarios. The existing table-horizon convention is retained: each marginal survival becomes zero beyond its last recorded age. On open tables this is truncation, not evidence of death, and may affect last-survivor or reversionary weights after the shorter horizon. Extend the tables for those interpretations. Infinite n means available horizon, not extrapolated lifetime coverage.

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

Apply an insurance contract to a loss severity specification

Description

Creates a per-loss payment severity specification by combining an existing ground-up severity model with a contract created by coverage_spec(). The original model is retained and not discretized, fitted, or simulated.

Usage

apply_coverage(x, coverage, label = NULL)

Arguments

Details

The payment variable is defined on a per-loss basis, retaining every loss event even when the associated insurer payment is zero. This is not the conditional payment-per-payment severity distribution.

Let X >= 0 be the ground-up severity, f > 0 the inflation factor, d_f the indexed (or fixed) deductible, L_f the indexed (or fixed) layer limit, and c the insurer coinsurance fraction. The exact transformation is

Y_L = c \min\{(fX-d_f)_+, L_f\}

for an ordinary deductible and

Y_L = c \min\{fX,L_f\} 1(fX>d_f)

for a franchise deductible. The limit caps the covered layer before coinsurance; it is not a final insurer-payment limit.

A continuous ground-up distribution can become mixed: probability mass arises at zero and, when the limit is finite and binding, at the maximum payment c * L_f. Pre-existing atoms are preserved under the pushforward and may merge. When coinsurance = 0 or limit = 0, the payment is identically zero. No smoothing or implicit discretization is performed.

The result is an executable per-loss payment distribution specification; its source and coverage fields contain everything necessary to recover the payment law from the underlying severity provider. The internal pure functions .coverage_payment_amount(), .payment_cdf_from_loss(), .payment_boundary_atoms(), and .payment_discrete_pushforward() implement the transformation exactly given loss values or exact source probabilities. Finite discrete sources are transformed exactly into a finite discrete distribution. Continuous or mixed sources use the existing custom-provider contract for CDF, quantiles, random generation and available exact moments. Moment orders without an exact registered formula are reported unavailable; no numerical integration or discretization is introduced silently.

Value

An S3 object with classes tidyact_payment_spec, tidyact_severity_spec, and tidyact_distribution_spec. The list stores source, coverage, basis = "per_loss", label, and a normalized severity specification (dist = "discrete" for finite discrete losses or dist = "custom" for continuous and mixed losses). The support bound is not asserted to be the smallest possible bound under the original distribution.

References

Klugman, S. A., Panjer, H. H., and Willmot, G. E. (2012). Loss Models: From Data to Decisions, 4th ed., Chapter 8.

Frees, E. W., Lee, G., and Yang, L., Loss Data Analytics, chapters on claim severity and coverage modifications.

See Also

coverage_spec()

Examples

# Full, registered severity model.
ground_up <- severity_spec("gamma", shape = 2, rate = 0.001,
                           label = "Ground-up severity")
contract <- coverage_spec(deductible = 500, limit = 10000,
                          coinsurance = 0.8)
payments <- ground_up |> apply_coverage(contract)
inherits(payments, "tidyact_payment_spec")
payments$basis
payments$coverage$deductible

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. Discounting uses the log accumulation rate from the original interest specification. A displayed discount factor may be zero or infinite even when its monetary APV contribution is representable.

Unknown mortality intervals produce missing contributions, unless survival has already reached zero. Missing numeric payment times and cash flows are retained as missing rows. Cumulative APV follows input row order and remains missing after a missing contribution. For compatibility, the apv attribute is the sum of nonmissing contributions (zero if none are known), so it is a subtotal when any contribution is missing, not a complete contract valuation. Calendar times use actual elapsed days divided by 365.25; all dates must be finite and nonmissing. Payments at the same time remain separate rows.

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"). The contingency attribute identifies "survival" or "weighted" (reversionary benefit fraction) for plot_contingent_cash_flow().

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. Valuation retains its original log accumulation rate even if an equivalent reported rate loses numeric range.

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. Valuation times retain their supplied order and duplicates. At maturity the final coupon and redemption have both been paid, so the value is zero; the same convention gives zero for n = t = 0. Integer period counts must fit the cash-flow schedule, with sufficient memory for its rows.

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: accrued_interest(), 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. Scenario prices retain its original log accumulation rate even if a reported equivalent loses numeric range.

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. A scenario pays all coupons through its redemption date, including the coupon on that date, plus its specified redemption value. There is no assumption of reinvestment at the target yield after early redemption and no stochastic model of interest rates or the issuer's exercise decision. Call dates must remain distinct and strictly inside maturity after alignment to integer coupon periods; two dates cannot represent the same coupon date. Rows are sorted by time and retain their original scenario_id.

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. is_worst_case is TRUE exactly when a computed scenario price equals the computed minimum, including all exact computed ties. Near ties are not marked.

See Also

bond_price, bond_cash_flows, bond_book_value, bond_ytm

Other bonds: accrued_interest(), 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. The coupon is face \cdot c/k. Coupons and redemption remain separate rows at maturity. At n = 0, only immediate redemption is returned. The schedule requires finite coupons and an integer number of periods below .Machine$integer.max, with sufficient memory for the resulting rows.

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. Calculations retain its original log growth; reported effective equivalents remain subject to numeric range.

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 sensitivity to the nominal annual yield z=kj; it is generally not the relative second derivative with respect to the annual effective yield i=(1+j)^k-1. Before passing convexity to immunize_duration_convexity(), apply the chain rule described there or compute convexity_cash_flow() from annual cash-flow times.

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. Prices use original log yields and moments use relative present values, avoiding monetary numerator overflow. Nonzero-term bonds require a positive finite price and finite risk measures; changing currency alone does not create an undefined sensitivity. Reported equivalent yields may reach -1 or Inf by rounding while the original specification remains usable. At zero term, the existing convention returns immediate redemption and zero risk.

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: accrued_interest(), 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. Calculations retain its original log growth; reported effective equivalents remain subject to numeric range.

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. The two coefficients must use the same yield coordinate: pair modified_duration_periods_j with the period convexity for changes in j. Annual effective duration requires annual effective convexity, obtained using the chain rule or convexity_cash_flow() on year times. Prices use original log yields and moments use relative present values. Nonzero-term bonds require a positive finite price and finite risk measures; calendar tolerance does not define a monetary zero. Reported equivalent yields may reach -1 or Inf by rounding while the specification remains usable. At zero term, immediate redemption and zero risk follow the existing convention.

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: accrued_interest(), 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.

Annual yield specifications are valued using their original log accumulation rate, avoiding loss of precision or range in intermediate annual equivalents.

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: accrued_interest(), 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}.

With nonnegative payments and at least one positive future payment, price is strictly decreasing in j > -1, so the yield is unique. The root is found with uniroot, using the log of the discounted cash-flow sum relative to price to avoid monetary overflow or underflow. If no interval is supplied, the lower bound is the nearest double precision number above -1 and the upper bound starts at 0.10 and is widened until the root is bracketed. A yield outside the representable domain or an exhausted iteration limit causes an error. Tolerance applies to the yield coordinate according to uniroot; it does not guarantee a given price residual, particularly for yields near -1.

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

Bootstrap a spot yield curve from instrument prices

Description

Recovers annual effective spot rates and discount factors sequentially from observed dirty prices and dated cash flows. Each instrument supplies one new maturity; all its earlier positive cash flows must occur at maturities already bootstrapped.

Usage

bootstrap_spot_curve(
  .data,
  col_instrument = "instrument",
  col_price = "price",
  col_t = "t",
  col_cf = "cf"
)

Arguments

Details

For instrument j, with maturity t_j, dirty price P_j, and cash flows CF_{j,k}, the price identity is

P_j = \sum_{k < j} CF_{j,k} v(t_k) + CF_{j,j} v(t_j).

Hence the new discount factor is recovered exactly as

v(t_j) = \frac{P_j - \sum_{k < j} CF_{j,k} v(t_k)}{CF_{j,j}}.

The annual effective spot rate is

i_{t_j} = v(t_j)^{-1/t_j} - 1.

Each input row represents one instrument; t and cf are list-columns. Repeated payment times within an instrument are combined, allowing coupon and redemption flows produced by bond_cash_flows(). Instruments are processed by increasing final positive-payment time, not input row order. Zero cash flows are ignored. Duplicate final maturities, missing earlier discount-factor nodes, zero or negative residual prices, and nonpositive terminal cash flows are rejected.

This is exact triangular bootstrapping: it does not interpolate, extrapolate, fit a curve, or estimate a least-squares solution. An annual effective spot rate can be negative; its discount factor must be positive. Input prices and cash flows must use the same monetary units. Both the positive finite discount factor and its annual effective rate above -1 must be representable. Rounded input prices can make a small terminal residual ill-conditioned; no tolerance silently replaces a nonpositive residual. repricing_error reports the recomputed floating-point discrepancy, not an independent accuracy guarantee or a convergence test.

Value

A tibble ordered by maturity, with columns instrument, t, price, known_pv, terminal_cf, v, i, repriced_price, and repricing_error. The columns v and i contain the new maturity's discount factor and annual effective spot rate. repricing_error is the model price minus the observed dirty price, in monetary units.

See Also

yield_curve(), discount_factor_spot(), forward_rate(), bond_cash_flows()

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

Examples

# Recover a known 1-, 2-, and 3-year annual effective spot curve.
t <- 1:3
i <- c(0.04, 0.045, 0.05)
v <- (1 + i)^(-t)
instruments <- tibble::tibble(
  instrument = c("Zero 1Y", "Coupon 2Y", "Coupon 3Y"),
  price = c(100 * v[1],
            5 * v[1] + 105 * v[2],
            6 * v[1] + 6 * v[2] + 106 * v[3]),
  t = list(1, c(1, 2), c(1, 2, 3)),
  cf = list(100, c(5, 105), c(6, 6, 106))
)
curve <- instruments |> bootstrap_spot_curve()
curve
yield_curve(t = curve$t, i = curve$i)

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)

Specify a collective risk model

Description

Creates a lightweight specification of the classical collective risk model

S = \sum_{i=1}^{N} X_i,

where N is a claim count random variable and X_1, X_2, \ldots are identically distributed individual claim severities. Independence between the frequency variable and the severities, and mutual independence of the severities, are intrinsic assumptions of this specification.

The constructor records the probabilistic model only. It does not calculate aggregate moments, construct the distribution of S, discretize a severity distribution, simulate losses, or apply an approximation.

Usage

collective_risk_spec(frequency, severity, count_basis = NULL, label = NULL)

Arguments

Details

The collective model is represented by the random sum

S = X_1 + \cdots + X_N,

with the convention S = 0 when N = 0.

collective_risk_spec() deliberately keeps the model specification separate from computational methods. In particular, no Panjer recursion, convolution, FFT calculation, Monte Carlo simulation, numerical discretization, or normal approximation is performed by this function.

The count_basis field is part of the model because frequency and severity must refer to the same event basis. A loss-basis specification counts underlying losses, including losses that may later produce a zero payment after coverage is applied. A payment-basis specification counts positive payments. Conversion between these bases is a separate actuarial operation and is not performed silently by this constructor.

The constructor does not expose an independence argument. Independence is part of the definition of this version of the collective risk model rather than an optional computational setting.

Value

An object with classes "tidyact_collective_risk_spec" and "tidyact_risk_spec". It contains the following fields:

• schema_version: internal schema version.

• frequency: the frequency specification.

• severity: the severity specification.

• count_basis: either "loss" or "payment".

• label: optional user label.

• metadata: reserved metadata list.

References

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

See Also

frequency_spec(), severity_spec(), empirical_frequency(), empirical_severity(), distribution_moments()

Examples

frequency <- frequency_spec(
  "poisson",
  lambda = 4
)

severity <- severity_spec(
  "gamma",
  shape = 2,
  rate = 0.001
)

model <- collective_risk_spec(
  frequency,
  severity
)

model

# An explicit payment-basis model.
collective_risk_spec(
  frequency,
  severity,
  count_basis = "payment",
  label = "Illustrative payment model"
)

# Empirical components can be used without fitting a parametric model.
empirical_n <- empirical_frequency(c(0, 0, 1, 1, 2, 3))
empirical_x <- empirical_severity(c(500, 750, 1000, 1500, 3000))

collective_risk_spec(
  empirical_n,
  empirical_x
)

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 original log accumulation rate before forming discounted products.

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 rate specification is validated 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,

Discounted products retain the original log accumulation rate to avoid intermediate factor overflow or underflow. This constructor always closes the terminal count, including when the input carries open-table metadata. The horizon is therefore different from the truncated integral in e_x. Reverse cumulative sums are 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. Relative contributions retain log weights rather than first forming a monetary convexity numerator. Representable products can be recovered when a standalone discount factor underflows; its audit column can then be zero while present value is positive. Discount factors, present values, their total/absolute sum, and the contributions/result must remain finite. Signed streams with absolute total value at most 'sqrt(.Machine$double.eps)' times the sum of absolute present values are rejected as numerically cancelled.

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

Specify an insurance coverage contract

Description

Creates a lightweight S3 specification for per-loss insurance coverage, including an ordinary or franchise deductible, a coverage limit, coinsurance, inflation, and optional indexation of contract terms.

Usage

coverage_spec(
  deductible = 0,
  limit = Inf,
  coinsurance = 1,
  inflation_factor = 1,
  deductible_type = c("ordinary", "franchise"),
  index_deductible = FALSE,
  index_limit = FALSE,
  label = NULL
)

Arguments

Details

This function only records contractual terms. It does not accept a severity distribution, evaluate payments, simulate losses, or change a frequency model.

Let X >= 0 denote the original loss, f the inflation factor, d the deductible, L the limit, and c the coinsurance fraction. Write Z = f * X, d_f = d * f if the deductible is indexed (otherwise d), and L_f = L * f if the limit is indexed (otherwise L). The specified processing order is inflation, deductible, limit, and coinsurance.

For an ordinary deductible, the intended payment per loss is

Y_L = c \min\{\max(Z-d_f,0),L_f\}.

For a franchise deductible, the intended payment per loss is

Y_L = c \min\{Z,L_f\} \mathbf{1}_{\{Z>d_f\}}.

Thus a franchise loss exactly equal to its deductible produces no payment. With a finite limit, the maximum insurer payment is c * L_f (or a smaller achievable maximum if the loss distribution is bounded).

In standard actuarial notation, the maximum covered loss for an ordinary deductible with finite d_f and L_f is u = d_f + L_f; it is distinct from this function's limit argument.

All monetary amounts must use the same currency and reference monetary basis. Inputs are deliberately scalar: one object represents one contract.

Value

An object of class tidyact_coverage_spec, implemented as a named list containing deductible, limit, coinsurance, inflation_factor, deductible_type, index_deductible, index_limit, and label. No derived payments or distributional quantities are stored.

References

Klugman, S. A., Panjer, H. H., and Willmot, G. E. (2012). Loss Models: From Data to Decisions, 4th edition, Chapter 8.

Examples

# Default: full insurance of each loss, without inflation.
coverage_spec()

# Ordinary deductible with a capped covered layer and 80% coinsurance.
contract <- coverage_spec(
  deductible = 500,
  limit = 10000,
  coinsurance = 0.80,
  label = "Standard contract"
)
contract$limit

# A qualifying loss is covered from its first unit under a franchise.
coverage_spec(deductible = 1000, deductible_type = "franchise")

# Inflation with indexed deductible, but a fixed nominal limit.
coverage_spec(
  deductible = 500,
  limit = 10000,
  inflation_factor = 1.12,
  index_deductible = TRUE,
  index_limit = FALSE
)

# Completely indexed contract, including an unbounded limit.
coverage_spec(
  deductible = 500,
  limit = Inf,
  inflation_factor = 1.05,
  index_deductible = TRUE,
  index_limit = TRUE
)

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. The requested discount factor is evaluated from the log accumulation, without requiring its reciprocal to be representable. It must be positive and finite. In tidy output, an unrepresentable intermediate accumulation factor may be Inf or zero; the discount factor is computed independently.

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(), bootstrap_spot_curve(), discount_factor_spot(), forward_curve(), forward_rate(), interest_equivalents(), par_rate(), 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. Valuation retains the original log accumulation rate. In tidy output, an extreme annual equivalent can round to -1 or overflow to Inf without invalidating a representable discount factor.

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(), bootstrap_spot_curve(), discount_factor(), forward_curve(), forward_rate(), interest_equivalents(), par_rate(), 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
)

Discretize a continuous claim severity distribution

Description

Converts a continuous nonnegative severity specification into an explicit lattice distribution. The transformation is intended for actuarial algorithms that require discrete severities, such as Panjer recursion or FFT-based aggregate-loss methods.

Discretization is always explicit: this function is never called silently by aggregate-loss functions.

Usage

discretize_severity(
  x,
  step,
  to = NULL,
  method = c("unbiased", "upper", "lower", "rounding"),
  tail_prob = 1e-08,
  label = NULL
)

Arguments

Details

Let F be the severity CDF, h the lattice step, and b = \mathrm{to}. The lattice is

0, h, 2h, \ldots, b.

The four methods follow standard actuarial discretization conventions.

Upper method

For lattice points below to,

p_x = F(x+h)-F(x).

This assigns each interval to its lower lattice endpoint. Probability above to is assigned explicitly to the upper grid point.

Lower method

p_0 = F(0), \qquad p_x = F(x)-F(x-h).

This assigns each interval to its upper lattice endpoint. Probability above to is added to the upper grid point.

Rounding method

Probability is allocated according to the midpoint intervals around each lattice point. Thus the first cell extends from zero to step / 2, interior cells have width step, and the last cell contains everything above to - step / 2.

Unbiased method

The unbiased method performs local first-moment matching. If L(d) = E[\min(X,d)], the finite-grid probabilities before the final tail adjustment are

p_0 = 1 - F(0) - \frac{L(h)-L(0)}{h},

p_x = \frac{2L(x)-L(x-h)-L(x+h)}{h}, \qquad 0 < x < b,

and

p_b = \frac{L(b)-L(b-h)}{h} - 1 + F(b).

The residual tail probability above to is then assigned to to. Consequently, the resulting distribution is a proper probability distribution and its first moment matches E[\min(X,b)], rather than silently discarding probability above the truncation point.

For the exponential, gamma, lognormal, Weibull, and Pareto II families, the first limited moment used by the unbiased method is evaluated analytically. For other continuous specifications with a CDF, including Burr XII, log-logistic, and eligible custom models, the limited mean is obtained by numerical integration of the survival function. The source used is recorded in metadata$discretization$limited_mean_source.

Only continuous severity specifications are accepted in this initial implementation. Finite discrete and empirical severities already have probability masses and should not be silently re-discretized. Support for mixed severities can be added later without changing this public interface.

The returned object uses the existing "discrete" severity operations but has support$type = "lattice". Zero-probability grid points need not be stored explicitly in params$values; the lattice information is retained in support.

Value

A tidyact_severity_spec and tidyact_distribution_spec object with dist = "discrete", lattice support, and discretization information in metadata$discretization.

The metadata records:

• method;

• step;

• to;

• whether to was supplied or selected from tail_prob;

• the requested tail_prob when applicable;

• the actual probability above to;

• the explicit tail treatment;

• the original distribution identifier; and

• the source of the limited mean for the unbiased method.

References

Klugman, S. A., Panjer, H. H., and Willmot, G. E. (2019). Loss Models: From Data to Decisions, 5th ed. Wiley.

See Also

severity_spec(), distribution_convolution()

Examples

x <- severity_spec(
  "gamma",
  shape = 2,
  rate = 0.001
)

# Automatic upper grid point from a small tail probability.
dx <- discretize_severity(
  x,
  step = 100
)
dx

# Inspect the resulting lattice probabilities.
tibble::tibble(
  amount = dx$params$values,
  probability = dx$params$probs
)

# Use a fixed truncation point and another discretization rule.
discretize_severity(
  x,
  step = 250,
  to = 10000,
  method = "rounding"
)

# The discretization choices remain auditable.
dx$metadata$discretization

Specify a convolution of probability distributions

Description

Creates a lazy specification of the convolution of two independent distributions or of an iid sum of a single distribution.

If X and Y are independent, the pairwise form represents

Z = X + Y.

The iid form represents

Z_n = X_1 + \cdots + X_n,

where X_1,\ldots,X_n are independent copies of the distribution specified by x.

The function records the convolution model but does not evaluate a density, mass function, distribution function, or numerical convolution.

Usage

distribution_convolution(x, y = NULL, n = NULL, label = NULL)

Arguments

Details

Exactly one of y and n must be supplied.

The pairwise form

distribution_convolution(x, y)

represents the distribution of the sum of two independent random variables.

The iid form

distribution_convolution(x, n = 5)

represents the five-fold convolution of x.

The cases n = 0 and n = 1 follow the usual convolution conventions:

• n = 0 represents the degenerate distribution at zero;

• n = 1 returns the original distribution specification. If label is supplied, only the label of the returned copy is changed.

The operation is deliberately lazy. It does not choose a computational algorithm, discretize a continuous distribution, truncate an infinite support, or apply FFT or Panjer recursion. Those decisions belong to later computational functions.

Support bounds are propagated algebraically. For example, if x has support bounded below by a and y by b, the convolution is bounded below by a+b. Infinite upper bounds are preserved.

Support type is inferred conservatively:

• count + count remains count;

• iid lattice sums remain lattice;

• a continuous component convolved with a discrete component is continuous;

• any convolution involving a mixed distribution is classified as mixed;

• otherwise discrete supports are retained as discrete.

Independence is part of the meaning of a convolution specification and is therefore not stored as a separate flag.

Value

For a genuine convolution, an object with classes "tidyact_convolution_spec" and "tidyact_distribution_spec".

The object follows the common distribution specification schema:

schema_version

Internal schema version.

dist

The identifier "convolution".

params

The lazy convolution definition.

support

Inferred support information.

data

Always NULL.

custom

Always NULL.

label

Optional user label.

metadata

Reserved metadata list.

When n = 1, the original distribution specification is returned instead of wrapping it in a convolution object.

References

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

Klugman, S. A., Panjer, H. H., and Willmot, G. E. (2019). Loss Models: From Data to Decisions, 5th ed. Wiley.

See Also

frequency_spec(), severity_spec(), collective_risk_spec()

Examples

x <- severity_spec(
  "gamma",
  shape = 2,
  rate = 0.001
)

y <- severity_spec(
  "lognormal",
  meanlog = 7,
  sdlog = 0.6
)

# Pairwise convolution: X + Y
distribution_convolution(x, y)

# Four iid claim amounts: X1 + ... + X4
distribution_convolution(
  x,
  n = 4
)

# The zero-fold convolution is degenerate at zero.
distribution_convolution(
  x,
  n = 0
)

# The one-fold convolution is the original specification.
identical(
  distribution_convolution(x, n = 1),
  x
)

# Count distributions can also be convolved.
n_claims <- frequency_spec(
  "poisson",
  lambda = 3
)

distribution_convolution(
  n_claims,
  n = 2
)

Calculate moments of a frequency or severity distribution

Description

Calculates raw, central, factorial, or cumulant moments from an existing frequency or severity specification. The calculation is deterministic: it does not fit a model, generate observations, or approximate moments using simulation or numerical integration.

Usage

distribution_moments(x, order = 1:4, type = "raw")

Arguments

Details

For a random variable Z, the raw and central moments are

m_r = E[Z^r], \qquad \mu_r = E[(Z-E[Z])^r].

For a nonnegative integer-valued frequency N, the factorial moment is

E[(N)_r], \qquad (N)_r=N(N-1)\cdots(N-r+1).

Cumulants are calculated algebraically from raw moments. In particular, \kappa_1=E[Z], \kappa_2=\mathrm{Var}(Z), and \kappa_3=E[(Z-E[Z])^3] when the relevant moments are finite.

Moment order zero is one for raw, central, and factorial moments. Cumulants start at order one.

All built-in distributions use their registered analytical raw or factorial moment functions. A custom specification must explicitly supply raw_moment or (for a frequency) factorial_moment to provide a moment calculation; supplying only a PMF or PDF does not trigger numerical integration or summation. Raw and factorial frequency moments can be converted into one another using Stirling numbers when the necessary source moments are available.

The status column distinguishes:

• "finite": a finite numerical result;

• "infinite": a mathematically divergent moment;

• "undefined": the moment is not defined or the specification does not provide sufficient information to evaluate it;

• "overflow": a theoretically finite moment or an intermediate algebraic expression exceeds the available floating-point range.

For built-in Pareto II, Burr XII, and log-logistic severities, divergence is determined from the distribution's analytical moment-existence condition. For custom distributions, an explicitly returned positive Inf is interpreted as mathematical divergence; custom moment functions are responsible for this distinction.

A central moment of positive order requires a finite mean. When the mean exists but a higher-order moment diverges, the corresponding central moment is infinite. Higher-order cumulants are reported as undefined if the moments needed for their definition are infinite. The first cumulant follows the first raw moment.

Central moments and cumulants derived from raw moments may suffer from cancellation for extremely large parameter values. Such arithmetic is not silently replaced by a simulated or approximated answer.

Value

A tibble::tibble() with one row per requested order and columns: type (character), order (integer), value (double), and status (character). Input order and repeated orders are preserved. Undefined values are returned as NA_real_.

References

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

See Also

frequency_spec(), severity_spec()

Examples

# Raw and central moments of a claim count distribution.
counts <- frequency_spec("poisson", lambda = 4)
distribution_moments(counts)
distribution_moments(counts, order = 1:4, type = "central")
distribution_moments(counts, order = 0:4, type = "factorial")
distribution_moments(counts, order = 1:4, type = "cumulant")

# Raw moments of a nonnegative claim amount.
loss <- severity_spec("gamma", shape = 2.5, rate = 0.001)
distribution_moments(loss, order = 1:4)

# The mean exists but the variance does not.
heavy_tail <- severity_spec("pareto", shape = 1.5, scale = 2000)
distribution_moments(heavy_tail, order = 1:4)
distribution_moments(heavy_tail, order = 1:4, type = "central")

# A nonrandom payment has zero central moments of positive order.
fixed <- severity_spec("degenerate", value = 1000)
distribution_moments(fixed, order = 1:4, type = "central")

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. Relative contributions are computed without first forming a monetary duration numerator. Representable products can be recovered when a standalone discount factor underflows; its audit column can then be zero while present value is positive. Discount factors, present values, their total/absolute sum, and the selected contributions/result must remain finite. A signed stream is rejected when absolute total value is at most 'sqrt(.Machine$double.eps)' times the sum of absolute present values.

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)

Integrals use stable exponential/logarithmic increments for small durations. Extinct cohorts contribute zero to later intervals, even if their conditional probabilities are undefined. The CF/Balducci zero-survival interval has integral zero; UDD retains its linear decline. Unknown survivor counts propagate as missing expectations. When annual probabilities must be derived from survivor counts, survival uses the direct count ratio rather than 1-q_y. Its logarithm retains the CF integral even when the annual ratio is below floating-point range.

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 and evaluated analytically under UDD, constant force, or Balducci, retaining small survival in log form. Observed annual lx ratios determine the fractional survival. Survival is always measured from the initial ages, conditional on both lives being alive at time zero. In particular, last-survivor survival at later times does not imply that both lives remain alive.

Horizons end at the last recorded age: the older life limits joint-life expectation and the younger life limits last-survivor expectation. Survival beyond that age is taken as zero, as in t_px; an open table therefore gives a truncated expectation. Missing initial ages or zero initial survivors give NA, including when t = 0. Tables must have unique consecutive annual integer ages and finite, nonnegative, nonincreasing lx. Observed px/qx must be probabilities consistent with annual lx ratios within 1e-10; unknown probabilities may be NA. The age tolerance tol does not relax this mortality consistency threshold.

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

Specify an empirical claim frequency distribution

Description

Constructs the exact discrete distribution implied by observed claim counts or a weighted count table. No parametric distribution is fitted, no smoothing is applied, and unobserved counts receive probability zero.

Usage

empirical_frequency(data, count = NULL, weight = NULL, label = NULL)

Arguments

Details

If the observed counts are n_1,\ldots,n_m and their nonnegative weights are w_1,\ldots,w_m, the empirical probability mass function is

\widehat p_k = \frac{\sum_{i=1}^m w_i\,I(n_i=k)}{\sum_{i=1}^m w_i}.

At least one weight must be positive. Rows with zero weight do not contribute to the empirical support. Missing, negative, fractional, or nonfinite claim counts are rejected rather than silently discarded. Counts must not exceed 2^{53}, the largest consecutive integer representable exactly by an IEEE-754 double. Weights must be finite, nonnegative, and have a strictly positive finite total. Counts are kept in increasing order; no gaps in the observed set are filled with artificial positive probabilities.

This is the empirical distribution of the claim count per observational unit (such as a policy-year), not a table of individual claims. A vector of all ones describes a degenerate count distribution at one, not the total number of claims in a portfolio.

The result has the same lightweight S3 contract as frequency_spec(). Its dist field is "empirical"; params holds the finite count values and their exact empirical probabilities, and data contains the aggregated observed weights and probabilities. Only this compact frequency table is retained, not the original individual records.

The internal frequency registry provides the PMF, CDF, quantile function, RNG, raw and factorial moments, and probability generating function for this model. A general finite empirical frequency distribution is not assumed to belong to the Panjer (a,b,0) class; its panjer operation is therefore unavailable. Other methods can use the same specification without silently fitting or approximating its probabilities.

Value

An object of classes "tidyact_frequency_spec" and "tidyact_distribution_spec", with the ordered fields schema_version, dist, params, support, data, custom, label, and metadata. The data field is a tibble::tibble() with columns count, weight, and probability, one row per count with positive empirical mass.

See Also

frequency_spec(), distribution_moments()

Examples

# One observation per policy-year: 0, 1, or 2 claims.
counts <- c(0, 0, 0, 1, 1, 2)
n <- empirical_frequency(counts)
n
n$data
distribution_moments(n, order = 1:3)
distribution_moments(n, order = 1:3, type = "factorial")

# The same empirical distribution as a summarized portfolio table.
portfolio <- tibble::tibble(
  claims = c(0, 1, 2),
  policies = c(3, 2, 1)
)
portfolio |>
  empirical_frequency(count = claims, weight = policies)

# Unweighted data-frame input and a descriptive label.
observations <- tibble::tibble(claim_count = c(0, 1, 0, 2, 1))
observations |>
  empirical_frequency(count = claim_count, label = "Observed policy counts")

Specify an empirical claim severity distribution

Description

Constructs the discrete severity distribution implied by observed individual claim amounts or a weighted table of claim amounts. No parametric family is fitted, observations are not rounded, and no smoothing or discretization is performed.

Usage

empirical_severity(data, amount = NULL, weight = NULL, label = NULL)

Arguments

Details

Given observed amounts x_1,\ldots,x_n and nonnegative weights w_1,\ldots,w_n, the exact empirical probability assigned to amount x is

\widehat{p}(x) = \frac{\sum_{i=1}^n w_i I(x_i=x)}{\sum_{i=1}^n w_i}.

Only strictly positive-weight observations contribute to the distribution; at least one positive weight is required. Repeated amounts are combined and stored in increasing order. Every unobserved amount has probability zero. Amounts must be finite, nonnegative numeric values. An observed amount of zero is valid and produces a genuine probability mass at zero; it is not removed or converted into a positive-payment severity.

The result is a finite discrete severity specification, even when the observed amounts are decimal or come from an underlying continuous loss process. It is not a continuous density estimate and has no PDF. Values are compared exactly as represented numerically: close but unequal amounts are not merged. The function also does not infer a loss/payment basis, deductibles, limits, or monetary rounding rules.

The S3 contract matches severity_spec(): dist = "empirical", with params = list(values = ..., probs = ...) and a compact data table. The original individual observations are not retained. The internal severity registry makes the PMF, CDF, quantile, RNG, raw moments, limited moments, MGF, and Laplace transform available. No simulation occurs during construction.

For these finite observations all positive integer-order raw moments exist mathematically, although large powers can exceed floating-point range.

Value

An object with classes "tidyact_severity_spec" and "tidyact_distribution_spec", containing schema_version, dist, params, support, data, custom, label, and metadata. The data field is a tibble::tibble() with amount, weight, and probability columns, sorted by amount. Only observed amounts with positive empirical probability are retained.

See Also

severity_spec(), empirical_frequency(), distribution_moments()

Examples

# One claim amount per observation, including a zero payment.
losses <- c(0, 500, 500, 1250.50, 3000)
x <- empirical_severity(losses)
x
x$data
distribution_moments(x, order = 1:4)

# Exactly the same empirical distribution from a summarized claim table.
claims <- tibble::tibble(
  payment = c(0, 500, 1250.50, 3000),
  claims = c(1, 2, 1, 1)
)
claims |>
  empirical_severity(amount = payment, weight = claims)

# A tidyverse pipeline with individual claim observations.
tibble::tibble(claim_amount = c(150, 150, 375, 900)) |>
  empirical_severity(amount = claim_amount, label = "Reported severities")

Construct a forward-rate curve from spot rates

Description

Computes the annual effective forward rates for every consecutive interval implied by an observed spot yield curve. Unlike forward_rate(), which evaluates a selected interval, forward_curve() returns the complete adjacent-interval schedule in a tidy, long-format tibble.

Usage

forward_curve(
  .data = NULL,
  t = NULL,
  i = NULL,
  col_t = "t",
  col_i = "i",
  col_curve = NULL,
  i_type = "effective",
  m = 1L,
  include_origin = TRUE
)

Arguments

Details

Let 0=t_0<t_1<\cdots<t_n denote maturities, and let v(t_j) be their spot discount factors. For each consecutive interval,

(1+f_{t_{j-1},t_j})^{t_j-t_{j-1}}= \frac{v(t_{j-1})}{v(t_j)},

so the annual effective forward rate is

f_{t_{j-1},t_j}=\left( \frac{v(t_{j-1})}{v(t_j)}\right)^{1/(t_j-t_{j-1})}-1.

The function evaluates log discount-factor ratios from original log spot growth rates, retaining small rates even when reported discounts round to 1. Equal spot log rates are preserved across intervals with a large common origin. Discount factors are obtained from the existing discount_factor_spot() function, which standardizes the chosen interest-rate convention. Negative spot and forward rates are supported when the discount factors are positive and finite.

With include_origin = TRUE, the first interval starts at time zero and uses the exact identity v(0)=1. A supplied zero-maturity node is retained without duplication. With include_origin = FALSE, only intervals between supplied nodes are returned.

Maturities are sorted within each curve. Repeated, nonfinite or negative maturities, missing or nonfinite rates, and invalid discount factors are rejected. No interpolation, extrapolation, curve fitting or forward-rate forecast is performed. Intervals may have unequal lengths. Spot-to-forward relationships represent no-arbitrage implications of the supplied discount factors, not predictions of realized future rates.

Accepted input shapes are: direct numeric t and i vectors; a data frame with numeric t and i columns (one node per row, optionally partitioned using col_curve); or a data frame with t and i list-columns (one complete curve per row), such as yield_curve() output. Each curve produces one or more rows. curve is a character identifier: an ID from col_curve, or the input curve's sequential number if no ID is supplied. If more than one curve is supplied, i_type and m must be scalars; for a single curve they can instead have one value per node.

Value

A tibble, with one row per forward interval and columns curve, t_start, t_end, duration, v_start, v_end, and f. f is an annual effective forward rate and duration is measured in years.

See Also

forward_rate(), yield_curve(), discount_factor_spot(), bootstrap_spot_curve()

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

Examples

# A forward curve for consecutive annual spot maturities.
forward_curve(t = 1:3, i = c(0.04, 0.045, 0.05))

# The output of yield_curve() can be used directly in a pipe.
yield_curve(t = c(1, 2, 3), i = c(0.04, 0.045, 0.05)) |>
  forward_curve()

# Multiple curves, using tidyverse-friendly list-columns.
tibble::tibble(
  scenario = c("base", "stress"),
  t = list(c(1, 2, 3), c(1, 3, 5)),
  i = list(c(0.04, 0.045, 0.05), c(0.05, 0.055, 0.06))
) |>
  forward_curve(col_curve = "scenario")

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.

Exact extraction retains the original log accumulation rates and evaluates the spot-forward identity without forming powers or their ratio. Reported annual equivalents and the final forward rate can reach double precision limits. Linear extraction interpolates annual effective spot rates, not log discounts, and requires finite annual equivalents greater than -1. With .na = "propagate", an incomplete row keeps its position and has a NULL plot entry when plotting is requested.

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(), bootstrap_spot_curve(), discount_factor(), discount_factor_spot(), forward_curve(), interest_equivalents(), par_rate(), 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
)

Specify a claim frequency distribution

Description

Creates a lightweight specification of a claim count distribution for use in actuarial risk models.

Usage

frequency_spec(dist, ..., custom = NULL, label = NULL)

Arguments

Details

A frequency specification represents a nonnegative integer-valued random variable. The constructor stores the probabilistic model only; it does not simulate observations, estimate parameters, or calculate aggregate losses.

Built-in parameterizations follow 'stats': Poisson uses 'lambda', binomial uses 'size' and 'prob', negative binomial uses 'size' and 'prob', and geometric uses 'prob' with support beginning at zero.

Value

An object with classes '"tidyact_frequency_spec"' and '"tidyact_distribution_spec"'.

Examples

frequency_spec("poisson", lambda = 4)
frequency_spec("binomial", size = 20, prob = 0.15)
frequency_spec("negative_binomial", size = 2.5, prob = 0.4)
frequency_spec("geometric", prob = 0.25)

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.

Valuation retains the log accumulation rate of the original specification. In tidy output, an extreme annual equivalent can round to -1 or overflow to Inf while the requested accumulation factor remains representable. Capital-factor products use log space when a separate factor loses range or precision. The product can be representable even when the factor is not.

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. The ratio is evaluated from log accumulation rates, avoiding overflow of its separate numerator and denominator. If a horizon annual equivalent rounds to -1 or overflows to Inf, tied horizon flows must have exactly equal log accumulation rates; otherwise the existing annual-rate tolerance applies.

Products are evaluated in log space when separate factors lose range or precision; original cash-flow signs and known zero amounts are preserved. If individual values overflow, amounts with exactly equal finite log factors are netted before valuation. Cancellation between unequal factors is not recovered by this rule and may still produce non-finite results.

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.

The minimum Euclidean norm is taken over asset units w, not portfolio market-value fractions. It is evaluated by singular value decomposition of the row-scaled constraint matrix, without forming normal equations. Short positions are allowed. Matching present value and duration gives a zero value and first derivative of the surplus at the base yield, but does not ensure nonnegative surplus after rate shifts; the Redington convexity condition must be checked separately. Liability values retain the original log accumulation rate, and relative moments avoid monetary numerator overflow. Payment times include zero: a liability at time zero contributes value but no duration. Constraints are scaled by a common monetary magnitude and by moment magnitudes before products are formed. These are row transformations, preserving the norm over units; asset columns are not rescaled independently. Final values, weights and sensitivities must be finite, and nearly cancelled liability value is rejected. Rank and cancellation tests remain subject to double precision; reported portfolio moments should be inspected for ill-conditioned systems.

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. It is evaluated by singular value decomposition of the row-scaled constraint matrix, without forming normal equations. The norm is over asset units w, not market-value fractions; short positions are allowed.

All asset sensitivities must use the same annual effective yield as the liabilities, even when i_type specifies a nominal rate or a force. For coupon frequency k, let j=(1+i_e)^{1/k}-1. If C_j=P''(j)/P and D_j^*=-P'(j)/P, the required convexity is

C_{i_e}=C_j[j'(i_e)]^2-D_j^*j''(i_e).

The outputs discrete_convexity_periods from bond_convexity() and modified_duration_periods_j from bond_duration() give C_j and D_j^*. Alternatively, use convexity_cash_flow() on the asset cash flows at the annual effective yield.

Matching convexity makes the surplus's second derivative zero at the base yield. This differs from Redington's strict positive-curvature condition and does not guarantee a nonnegative surplus after rate shifts. Liability values retain the original log accumulation rate; convexity is still with respect to the annual effective yield. Relative moments and row scaling before monetary products prevent avoidable overflow. Scaling uses common monetary and moment magnitudes, preserving the minimum norm over asset units, without rescaling asset columns independently. Time-zero liabilities contribute value but zero duration and convexity. Final values, weights and sensitivities must be finite; nearly cancelled liability values are rejected. Rank and cancellation tests remain subject to double precision; reported portfolio moments should be inspected for ill-conditioned systems.

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) / (1.05)^2,
  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) / (1.05)^2,
  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) / (1 + 0.06 / 12)^(2 * 12),
  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 mortality is interpolated under the selected assumption. Death masses are evaluated directly from annual survivor decrements and stable fractional formulas, avoiding subtraction of rounded survival probabilities. The table must have consecutive annual ages and nonincreasing finite 'lx', with positive exposure at issue and support through 'x + h + n'. No extra terminal death year is invented. A zero annual survival under CF or Balducci uses the limiting mass at the beginning of that annual interval, consistently with the package's fractional survival convention.

This values one policy per call. A benefit vector is a sequence of payments, not a vector of policy scenarios; signed benefits are supported. Functional benefits are evaluated at times relative to the start of coverage, excluding 'h'; discounting and death probabilities use absolute times including 'h'. The payment is at the end of the subperiod of death, not at the exact death time. Full contractual amounts are used, without division by 'k'. 'i_effective' is diagnostic and may round to -1 or Inf for an extreme valid original rate; valuation retains the original log accumulation rate.

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.

Scenarios. x, i, i_type, m, n, h, type, and benefit may have a common positive length; only length-one arguments recycle. The table and tidy control are shared. Scenarios are paired by position, not expanded to a Cartesian product. Missing or invalid cases are rejected with the scenario number. Use the numeric result in dplyr::mutate(), or request a tibble for intermediate values. Explicit interest arguments override contract defaults.

Valuation and scope. For annual deaths in interval [r,r+1), the unconditional payment probability is (l_{x+r}-l_{x+r+1})/l_x. The benefit is discounted at r+1, not at the exact moment of death. Decrements are formed before division, and log ratios and original interest rates retain representable APVs when intermediate conditional values or discount factors overflow or underflow. Intermediate diagnostics may therefore be zero or infinite while APV is finite. Tables require an annual age grid, nonincreasing finite lx, and a positive count at issue. For compatibility the terminal count one year beyond the table is zero, even for an open input table. Extinct tails contribute zero. A zero-term endowment pays the benefit at time h on survival; zero-term death insurance pays nothing.

Use insurance_variable_k for benefits varying by subperiod, including level benefits paid at the end of the subperiod of death, and t_Ex for pure endowments. Continuous death-time insurance, fractional issue ages and time-varying interest curves require additional model specifications and are not implied by this annual contract.

Value

If tidy = FALSE, a numeric vector of actuarial present values, of length one for a single scenario.

If tidy = TRUE, a tibble with one row per scenario, 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
)

# Parallel single-life scenarios with a shared mortality table
insurance_x(lt, x = c(60, 61), i = 0.04, n = c(2, 3),
            type = "term", benefit = c(10000, 20000), 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. With an open table this is a truncated value, not a complete whole-life APV; completeness requires that no active survivors remain beyond the last row. Cause probabilities are dependent probabilities of exit from the active state in a competing-decrement model, not independent/net decrement rates. Survival to each year's start uses all decrements. The payment is at year end, not the moment of exit; the cause-specific probability is not multiplied by survival to year end. Values are conditional on active status at issue.

The selected probabilities must be finite, in [0,1], with cause probability no greater than total decrement. Ages must be consecutive annual ages. Optional 'q_total' is checked against 'p_total'; redundant cohort counts are not the valuation basis. 'q_total' itself can be selected to value all exits. Original log accumulation and cumulative log survival retain representable values despite overflowing annual equivalent rates or underflowing intermediate survival. Scalar inputs recycle to a common positive scenario length; 'cause' and 'type' select one model per call.

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.

Both lives are alive at issue (state 11). Internal states 10 and 01 mean only x or only y is alive; 00 is absorbing. The API does not take an observed single-survivor initial state. In a joint-life contract, leaving 11 triggers the first-death benefit once. A last-survivor contract continues through 10 or 01 and pays on entering 00. Both deaths within one annual interval trigger one benefit, payable at the end of that year.

Valuation sums discounted annual transition masses from the issue ages; it does not subtract rounded annuity values. With marginal survival Sx, Sy, cumulative death Qx, Qy, and interval death masses Dx, Dy, the first-death mass in (t,t+1] is Dx(t) Sy(t) + Sx(t+1) Dy(t); the second-death mass is Dx(t) Qy(t) + Qx(t) Dy(t) + Dx(t) Dy(t). Counts supply the decrements directly. Original log interest and monetary amounts are combined before exponentiating when necessary. The annual payment model is independent of fractional interpolation; frac is retained as an audit assumption.

The following fully discrete identities remain checks on the result:

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}|}.

Whole-life valuation requires observed mortality through extinction of the selected status: at least one marginal must reach zero within the joint horizon, and both must reach zero for last-survivor insurance. An open table cannot imply a terminal death or maturity benefit. Use an explicit term or endowment for the observed horizon, or extend the table. No missing annual interval of an open marginal table is extrapolated. A zero-term endowment pays benefit at h if the status survives; a zero-term term insurance has no death coverage and pays zero. Annual tables must satisfy the consistency requirements of t_pxy, and issue ages must have positive lx. One call values one contract, not scenarios.

A deferred insurance retains survival probabilities from the issue ages. Its continuation value conditional on the selected status surviving to h is multiplied by the deferment factor

v^h\,{}_hp_{xy}

for the selected two-life status. For last-survivor insurance, this conditioning includes paths with only one survivor at h; it does not restart both lives at deferred ages. In tidy output, annuity_due_value is the annuity at time h conditional on that status surviving to h, and survival_to_maturity, when reported, uses the same conditioning.

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.

Calculations retain the log accumulation rate of the original input. An extreme annual effective equivalent may round to -1 or overflow to Inf while other equivalent quantities remain representable.

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 or factor family: "effective", "discount", "discount_factor", "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(), bootstrap_spot_curve(), discount_factor(), discount_factor_spot(), forward_curve(), forward_rate(), par_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.

Root finding scales the cash flows by their largest absolute amount; this preserves roots across monetary units. The reported NPV remains in the original currency. Scaling that would erase a nonzero amount through underflow is rejected. The tolerance controls the rate-coordinate solve.

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