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

In treasuryTR: Generate Treasury Total Returns from 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"
)

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 = yieldincome - duration * delta(y) + 1/2 * convexity * delta(y)^2

where

yieldincome = (1+y_t)^(delta(t))-1 ~ y_t * delta(t)

duration = 1/(y_t) * z_t^(2M)

convexity = C_1 - C_2

and

C_1 = 2/(y_t^2) * (1-z_t^(-2M))

C_2 = 2M/y_t * z_t^(-2M-1)

z_t = 1 + y_t/2

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

Value

Bond total returns

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)

treasuryTR documentation built on July 22, 2021, 9:06 a.m.