yieldcurves: Yield Curve Fitting, Analysis, and Decomposition

Description

Fits yield curves using Nelson-Siegel (1987) doi:10.1086/296409, Svensson (1994) doi:10.3386/w4871, and cubic spline methods. Extracts forward rates, discount factors, and par rates from fitted curves. Computes duration and convexity risk measures. Computes Z-spread and key rate durations. Provides principal component decomposition following Litterman and Scheinkman (1991) doi:10.3905/jfi.1991.692347, carry and roll-down analysis, and slope measures. All methods are pure computation with no external dependencies beyond base R; works with yield data from any source.

Author(s)

Maintainer: Charles Coverdale charlesfcoverdale@gmail.com

See Also

Useful links:

• https://github.com/charlescoverdale/yieldcurves

• Report bugs at https://github.com/charlescoverdale/yieldcurves/issues

Plot Method for Yield Curve Objects

Description

Plot Method for Yield Curve Objects

Usage

## S3 method for class 'yc_curve'
plot(x, ...)

Arguments

Value

The input object, invisibly.

Plot Method for Yield Curve PCA Objects

Description

Plots the factor loadings for each principal component across tenors.

Usage

## S3 method for class 'yc_pca'
plot(x, ...)

Arguments

Value

The input object, invisibly.

Print Method for Yield Curve Objects

Description

Print Method for Yield Curve Objects

Usage

## S3 method for class 'yc_curve'
print(x, ...)

Arguments

Value

The input object, invisibly.

Print Method for Yield Curve PCA Objects

Description

Print Method for Yield Curve PCA Objects

Usage

## S3 method for class 'yc_pca'
print(x, ...)

Arguments

Value

The input object, invisibly.

Summary Method for Yield Curve Objects

Description

Summary Method for Yield Curve Objects

Usage

## S3 method for class 'yc_curve'
summary(object, ...)

Arguments

Value

The input object, invisibly.

Summary Method for Yield Curve PCA Objects

Description

Summary Method for Yield Curve PCA Objects

Usage

## S3 method for class 'yc_pca'
summary(object, ...)

Arguments

Value

The input object, invisibly.

Coupon Bond Duration and Convexity

Description

Compute Macaulay duration, modified duration, and convexity for a coupon-bearing bond.

Usage

yc_bond_duration(
  face = 100,
  coupon_rate,
  maturity,
  yield,
  frequency = 2,
  compounding = c("semi_annual", "annual", "continuous")
)

Arguments

Value

A list with components macaulay_duration, modified_duration, convexity, and price.

Examples

# 2-year 5% bond at 4% yield, semi-annual coupons
yc_bond_duration(face = 100, coupon_rate = 0.05, maturity = 2,
                 yield = 0.04, frequency = 2)

Carry and Roll-Down Analysis

Description

Decompose expected return from holding a bond into carry (yield income minus financing cost) and roll-down (capital gain from sliding down the curve).

Usage

yc_carry(curve, maturities = NULL, horizon = 1/12, funding_rate = NULL)

Arguments

Value

A data frame with columns maturity, carry, rolldown, and total.

Examples

maturities <- c(0.25, 1, 2, 5, 10, 30)
rates <- c(0.050, 0.048, 0.045, 0.042, 0.040, 0.043)
fit <- yc_nelson_siegel(maturities, rates)
yc_carry(fit)

Fit Cubic Spline Yield Curve

Description

Fit a yield curve using cubic spline interpolation. Provides an exact fit through all observed data points with smooth interpolation between them.

Usage

yc_cubic_spline(
  maturities,
  rates,
  method = c("natural", "fmm"),
  type = c("zero", "par", "forward"),
  date = NULL
)

Arguments

Value

A yc_curve object with method = "cubic_spline".

Examples

maturities <- c(0.25, 0.5, 1, 2, 5, 10, 30)
rates <- c(0.052, 0.050, 0.048, 0.045, 0.042, 0.040, 0.043)
fit <- yc_cubic_spline(maturities, rates)
fit

Create a Yield Curve Object

Description

Construct a yc_curve object from observed maturity-rate pairs. This is the core data structure used throughout the package.

Usage

yc_curve(maturities, rates, type = c("zero", "par", "forward"), date = NULL)

Arguments

Value

A yc_curve object (S3 class) with components:

maturities

Numeric vector of maturities in years.

rates

Numeric vector of rates as decimals.

type

Character string indicating rate type.

method

Character string indicating fitting method.

params

List of model parameters (empty for observed curves).

fitted

Numeric vector of fitted rates (NULL for observed curves).

residuals

Numeric vector of residuals (NULL for observed curves).

date

Date of the curve observation.

n_obs

Integer count of maturity points.

Examples

# US Treasury yields (2Y, 5Y, 10Y, 30Y)
maturities <- c(2, 5, 10, 30)
rates <- c(0.045, 0.042, 0.040, 0.043)
curve <- yc_curve(maturities, rates)
curve

Compute Discount Factors

Description

Calculate discount factors from a yield curve assuming continuous compounding.

Usage

yc_discount(
  curve,
  maturities = NULL,
  compounding = c("continuous", "annual", "semi_annual")
)

Arguments

Value

A data frame with columns maturity and discount_factor.

Examples

maturities <- c(1, 2, 5, 10)
rates <- c(0.045, 0.043, 0.042, 0.040)
curve <- yc_curve(maturities, rates)
yc_discount(curve)
yc_discount(curve, compounding = "annual")

Duration and Convexity

Description

Compute Macaulay duration, modified duration, and convexity for zero-coupon bonds at each maturity on the curve.

Usage

yc_duration(
  curve,
  maturities = NULL,
  compounding = c("continuous", "annual", "semi_annual")
)

Arguments

Value

A data frame with columns maturity, macaulay_duration, modified_duration, and convexity.

Examples

maturities <- c(0.25, 1, 2, 5, 10, 30)
rates <- c(0.050, 0.048, 0.045, 0.042, 0.040, 0.043)
fit <- yc_nelson_siegel(maturities, rates)
yc_duration(fit)

Fit a Yield Curve

Description

Unified interface for fitting a yield curve using different methods. Dispatches to yc_nelson_siegel(), yc_svensson(), or yc_cubic_spline().

Usage

yc_fit(
  maturities,
  rates,
  method = c("nelson_siegel", "svensson", "cubic_spline"),
  type = c("zero", "par", "forward"),
  date = NULL,
  ...
)

Arguments

Value

A yc_curve object.

Examples

maturities <- c(0.25, 0.5, 1, 2, 5, 10, 30)
rates <- c(0.052, 0.050, 0.048, 0.045, 0.042, 0.040, 0.043)
fit <- yc_fit(maturities, rates, method = "nelson_siegel")
fit

Extract Forward Rates

Description

Compute forward rates from a yield curve. Can compute either instantaneous forward rates or forward-forward rates between two tenors.

Usage

yc_forward(curve, maturities = NULL, horizon = NULL)

Arguments

Details

The instantaneous forward rate is derived as:

f(m) = r(m) + m \cdot r'(m)

Value

A data frame with columns maturity and forward_rate.

Examples

maturities <- c(0.25, 0.5, 1, 2, 5, 10, 30)
rates <- c(0.052, 0.050, 0.048, 0.045, 0.042, 0.040, 0.043)
fit <- yc_nelson_siegel(maturities, rates)
yc_forward(fit)
yc_forward(fit, maturities = c(1, 5, 10), horizon = 1)

Interpolate Yield Curve

Description

Interpolate rates at arbitrary maturities from an observed or fitted yield curve.

Usage

yc_interpolate(curve, maturities, method = c("linear", "log_linear", "cubic"))

Arguments

Value

A data frame with columns maturity and rate.

Examples

maturities <- c(1, 2, 5, 10, 30)
rates <- c(0.045, 0.043, 0.042, 0.040, 0.043)
curve <- yc_curve(maturities, rates)
yc_interpolate(curve, c(3, 7, 15, 20))

Key Rate Durations

Description

Compute key rate durations by bumping the yield curve at specific tenors. Each bump is triangular: the full shift is applied at the key rate tenor and linearly interpolated to zero at adjacent key rate tenors.

Usage

yc_key_rate_duration(
  coupon_rate,
  maturity,
  curve,
  key_rates = c(1, 2, 5, 10, 30),
  shift = 1e-04,
  face = 100,
  frequency = 2
)

Arguments

Value

A data frame with columns tenor and key_rate_duration.

Examples

curve <- yc_curve(c(1, 2, 5, 10, 30), c(0.03, 0.035, 0.04, 0.042, 0.045))
yc_key_rate_duration(coupon_rate = 0.04, maturity = 10,
                     curve = curve, key_rates = c(1, 2, 5, 10, 30))

Extract Level, Slope, and Curvature Factors

Description

For Nelson-Siegel or Svensson curves, extracts the estimated factors directly from the model parameters. For other curves, computes empirical measures.

Usage

yc_level_slope_curvature(curve)

Arguments

Value

A named list with:

level

Long-run level (beta0 for NS/Svensson, or mean rate).

slope

Slope factor (beta1 for NS/Svensson, or short - long rate).

curvature

Curvature factor (beta2 for NS/Svensson, or 2*mid - short - long rate).

Examples

maturities <- c(0.25, 0.5, 1, 2, 5, 10, 30)
rates <- c(0.052, 0.050, 0.048, 0.045, 0.042, 0.040, 0.043)
fit <- yc_nelson_siegel(maturities, rates)
yc_level_slope_curvature(fit)

Fit Nelson-Siegel Yield Curve

Description

Estimate a Nelson-Siegel (1987) yield curve model from observed maturity-rate pairs. The model decomposes the yield curve into three factors: level, slope, and curvature.

Usage

yc_nelson_siegel(
  maturities,
  rates,
  tau_init = 1,
  weights = NULL,
  type = c("zero", "par", "forward"),
  date = NULL
)

Arguments

Details

The Nelson-Siegel model is:

r(m) = \beta_0 + \beta_1 \frac{1 - e^{-m/\tau}}{m/\tau} + \beta_2 \left(\frac{1 - e^{-m/\tau}}{m/\tau} - e^{-m/\tau}\right)

Value

A yc_curve object with method = "nelson_siegel" and params containing beta0, beta1, beta2, and tau.

References

Nelson, C.R. and Siegel, A.F. (1987). Parsimonious Modeling of Yield Curves. The Journal of Business, 60(4), 473–489. doi:10.1086/296409

Examples

maturities <- c(0.25, 0.5, 1, 2, 3, 5, 7, 10, 20, 30)
rates <- c(0.052, 0.050, 0.048, 0.045, 0.043, 0.042, 0.041,
           0.040, 0.042, 0.043)
fit <- yc_nelson_siegel(maturities, rates)
fit

Convert Par Rates to Zero Rates

Description

Bootstrap zero (spot) rates from par (coupon) rates using iterative stripping.

Usage

yc_par_to_zero(maturities, par_rates, frequency = 1)

Arguments

Value

A data frame with columns maturity and zero_rate.

Examples

maturities <- c(1, 2, 3, 5, 10)
par_rates <- c(0.040, 0.042, 0.043, 0.044, 0.045)
yc_par_to_zero(maturities, par_rates)

# Semi-annual coupons
yc_par_to_zero(c(0.5, 1, 2), c(0.04, 0.042, 0.043), frequency = 2)

Principal Component Analysis of Yield Curves

Description

Perform PCA on a time series of yield curves to extract the dominant factors (level, slope, curvature) following Litterman and Scheinkman (1991).

Usage

yc_pca(curves_matrix, n_components = 3, scale = FALSE)

Arguments

Value

A yc_pca object (S3 class) with components:

loadings

Matrix of factor loadings (tenors x components).

scores

Matrix of factor scores (observations x components).

variance_explained

Numeric vector of proportion of variance explained by each component.

cumulative_variance

Numeric vector of cumulative variance explained.

sdev

Standard deviations of each component.

n_components

Number of components retained.

tenors

Column names from the input matrix.

References

Litterman, R. and Scheinkman, J. (1991). Common Factors Affecting Bond Returns. The Journal of Fixed Income, 1(1), 54–61. doi:10.3905/jfi.1991.692347

Examples

# Simulate 100 days of yield curves at 5 tenors
set.seed(42)
n_days <- 100
tenors <- c(1, 2, 5, 10, 30)
base_rates <- c(0.045, 0.043, 0.042, 0.040, 0.043)
curves <- matrix(NA, n_days, length(tenors))
colnames(curves) <- paste0(tenors, "Y")
level <- cumsum(rnorm(n_days, 0, 0.001))
slope <- cumsum(rnorm(n_days, 0, 0.0005))
for (i in seq_len(n_days)) {
  curves[i, ] <- base_rates + level[i] + slope[i] * (tenors - mean(tenors)) / 30
}
pca_result <- yc_pca(curves)
pca_result

Predict Rates from a Fitted Yield Curve

Description

Evaluate a fitted yield curve at new maturities.

Usage

yc_predict(curve, maturities)

Arguments

Value

A data frame with columns maturity and rate.

Examples

maturities <- c(0.25, 0.5, 1, 2, 5, 10, 30)
rates <- c(0.052, 0.050, 0.048, 0.045, 0.042, 0.040, 0.043)
fit <- yc_nelson_siegel(maturities, rates)
yc_predict(fit, c(3, 7, 15, 20))

Yield Curve Slope Measures

Description

Compute common slope and curvature measures from a yield curve.

Usage

yc_slope(curve)

Arguments

Value

A named list with slope measures:

spread_2s10s

10-year minus 2-year rate (the most common slope measure).

spread_2s30s

30-year minus 2-year rate.

spread_5s30s

30-year minus 5-year rate.

spread_3m10y

10-year minus 3-month rate (term premium proxy).

butterfly_2s5s10s

2 * 5-year minus 2-year minus 10-year (curvature measure).

Returns NA for any measure whose required tenors fall outside the curve range.

Examples

maturities <- c(0.25, 0.5, 1, 2, 5, 10, 30)
rates <- c(0.052, 0.050, 0.048, 0.045, 0.042, 0.040, 0.043)
fit <- yc_nelson_siegel(maturities, rates)
yc_slope(fit)

Fit Svensson Yield Curve

Description

Estimate a Svensson (1994) yield curve model from observed maturity-rate pairs. Extends Nelson-Siegel by adding a second curvature term with its own decay parameter, providing greater flexibility for curves with two humps.

Usage

yc_svensson(
  maturities,
  rates,
  tau1_init = 1,
  tau2_init = 5,
  weights = NULL,
  type = c("zero", "par", "forward"),
  date = NULL
)

Arguments

Value

A yc_curve object with method = "svensson" and params containing beta0, beta1, beta2, beta3, tau1, and tau2.

References

Svensson, L.E.O. (1994). Estimating and Interpreting Forward Interest Rates: Sweden 1992–1994. NBER Working Paper, 4871. doi:10.3386/w4871

Examples

maturities <- c(0.25, 0.5, 1, 2, 3, 5, 7, 10, 20, 30)
rates <- c(0.052, 0.050, 0.048, 0.045, 0.043, 0.042, 0.041,
           0.040, 0.042, 0.043)
fit <- yc_svensson(maturities, rates)
fit

Convert Zero Rates to Par Rates

Description

Compute par (coupon) rates from zero (spot) rates. The par rate for maturity T is the coupon rate that makes a bond price equal to par.

Usage

yc_zero_to_par(maturities, zero_rates, frequency = 1)

Arguments

Value

A data frame with columns maturity and par_rate.

Examples

maturities <- c(1, 2, 3, 5, 10)
zero_rates <- c(0.040, 0.042, 0.043, 0.044, 0.045)
yc_zero_to_par(maturities, zero_rates)

# Semi-annual coupons
yc_zero_to_par(c(0.5, 1, 2), c(0.04, 0.042, 0.043), frequency = 2)

Z-Spread

Description

Compute the Z-spread (zero-volatility spread) for a bond. The Z-spread is the constant spread added to each zero rate on the benchmark curve that makes the discounted cash flows equal the market price.

Usage

yc_zspread(price, coupon_rate, maturity, curve, face = 100, frequency = 2)

Arguments

Value

A list with components zspread (the Z-spread as a decimal), price (the input price), and model_price (the price implied by the curve with the Z-spread applied).

Examples

# Create a benchmark curve
curve <- yc_curve(c(0.5, 1, 2, 5, 10), c(0.03, 0.035, 0.04, 0.042, 0.045))

# A bond priced below par (positive Z-spread)
yc_zspread(price = 95, coupon_rate = 0.04, maturity = 5,
           curve = curve, frequency = 2)