treasuryTR (version 0.1.6)

total_return: Calculate bond total returns from constant-maturity yield data

Description

Calculate bond total returns from constant-maturity yield data

Usage

total_return(
  yields,
  maturity,
  mdur = mod_duration(yields, maturity),
  convex = convexity(yields, maturity),
  scale = 261,
  format_out = "xts"
)

Value

Bond total returns

Arguments

yields

xts series or vector or yields

maturity

bond constant-maturity in years

mdur

modified duration, by default calculated using mod_duration()

convex

convexity, by default calculated using convexity()

scale

number of periods in a year (for US treasury data daily scale = 261, weekly scale = 52, monthly scale = 12, quarterly scale = 4)

format_out

xts or tibble

Details

Calculate bond total returns from constant-maturity yield data.

$$R_t = yield income - duration\cdot \Delta y + \frac{1}{2} \cdot convexity \cdot (\Delta y)^2$$

where

$$yield income = (1+y_t)^{\Delta t}-1 \approx y_t {\Delta t}$$

$$duration = \frac{1}{y_t} {z_t}^{2 M}$$

$$convexity = C_1 - C_2$$

and

$$C_1 = \frac{2}{y_t^2} (1-{z_t}^{-2M})$$ $$C_2 = \frac{2M}{y_t}{z_t}^{-2M-1}$$ $$z_t = 1+\frac{y_t}{2}$$

\(M\) is the maturity in years (e.g. 10), \(y_t\) is the yield at time \(t\)

Examples

library(dplyr)
# download US treasury 10Y constant-maturity
#   yield data and compute a total return series
t10_yield <- get_yields("DGS10")
t10_tr <- total_return(yields = t10_yield, maturity = 10)
head(t10_tr)

# step-by-step calculation
t10_yield <- get_yields("DGS10", format_out = "tibble")
t10_tr <- t10_yield %>%
  mutate(convexity = convexity(DGS10, 10),
         mod_duration = mod_duration(DGS10, 10),
         TR = total_return(DGS10, 10, mod_duration, convexity))
head(t10_tr)