---
title: "yrnd-functions"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{yrnd-functions}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(yrnd)
```

```{r setup}
library(yrnd)
```

## yrnd

The package '"yrnd"' estimates a parametric form of the Risk Neutral Density (RND) of the price of fixed-income futures such as Short Term Interest Rates futures and government bond futures, using options written on those futures. The RND is estimated at options' maturity for any type of option's style. The futures price is modeled either as a mixture of two or three lognormal laws. It provides with the options prices predicted with the fitted parameters, some statistics of the distribution as well as a density and a cumulative density plot. Leveraging on this, the package provides with several functions. First, it provides with the distribution of the STIR rate and the government bond yield themselves at options' maturity, using the RND of respectively the futures price of the STIR futures and the bond futures. Then, using the RND of the bond futures price, it provides with the probability attached to each bond in the delivery basket of a government bond futures contract to be the cheapest at maturity of the futures and at maturity of the options, using the forward net basis. Then, the package extracts from the RND of the bond futures price two RNDs simultaneously: for each bond in the delivery basket of the futures contract, it provides with the RND of its forward yield and the RND of its forward repo rate. At last, it also provides with the non parametric RND of the bond yield spread between two issuers or two maturities, using RNDs on two bond futures with the same maturity date and a Gaussian copula.


## stir_future_price provides with the risk neutral density at options' maturity of the STIR futures price, using options on the STIR futures

```{r}
stir_future_price( c(1.44500, 1.32000, 1.19750, 1.07500, 0.95750,
0.84250, 0.78750, 0.73250, 0.68000, 0.62750, 0.57750, 0.53000, 0.48500,
0.44000, 0.39750, 0.35750, 0.32000, 0.28500, 0.25250, 0.22250, 0.19500,
0.17000, 0.14750, 0.12750, 0.10750, 0.09250, 0.07750, 0.06500, 0.05500,
0.04500, 0.03750, 0.03000, 0.02500, 0.02000, 0.01500, 0.01250, 0.01000,
0.00750, 0.00500, 0.00500, 0.00250, 0.00250, 0.00250, 0.00250,
rep(0.00024, 47)),
c(seq(93.25, 93.875, 0.125),  seq(93.9375, 98.8125, 0.0625),
seq(98.875, 99.5, 0.125)),
c(0.0025, 0.0050, 0.0075, 0.0125, 0.0175, 0.0300, 0.0350, 0.0425, 0.0525,
0.0625, 0.0750, 0.0900, 0.1050, 0.1225, 0.1425, 0.1650, 0.1900, 0.2175,
0.2450, 0.2775, 0.3125, 0.3500, 0.3875, 0.4300, 0.4725, 0.5175, 0.5675,
0.6150, 0.6675, 0.7200, 0.7750, 0.8300, 0.8850, 0.9425, 1.0025, 1.0625,
1.1225, 1.1825, 1.2425, 1.3050, 1.3675, 1.4300, 1.4925, 1.5550, 1.6175,
1.6800, 1.7425, 1.8050, 1.8675, 1.9300, 1.9925, 2.0550, 2.1175, 2.1800,
2.2425, 2.3050, 2.3675, 2.4300, 2.4925, 2.5550, 2.6175, 2.6800, 2.7425,
2.8050, 2.8675, 2.9300, 2.9925, 3.0550, 3.1175, 3.1800, 3.2425, 3.3050,
3.3675, 3.4300, 3.4925, 3.5550, 3.6175, 3.6800, 3.7425, 3.8050, 3.8675,
3.9300, 3.9925, 4.0550, 4.1175, 4.1800, 4.3050, 4.4300, 4.5550, 4.6800,
4.8050),
c(seq(93.25, 93.875, 0.125),  seq(93.9375, 98.8125, 0.0625),
seq(98.875, 99.5, 0.125)),
2,
0.0537,
1,
3,
94.7,
as.Date("2024-02-29"),
as.Date("2024-02-25"),
as.Date("2023-12-18"),
"fed_fund_rate",
"USD")
```

## stir_rate provides with the risk neutral density at options' maturity of the STIR rate implicit in the STIR futures price, using options on the STIR futures

```{r}
stir_rate( c(1.44500, 1.32000, 1.19750, 1.07500, 0.95750,
0.84250, 0.78750, 0.73250, 0.68000, 0.62750, 0.57750, 0.53000, 0.48500,
0.44000, 0.39750, 0.35750, 0.32000, 0.28500, 0.25250, 0.22250, 0.19500,
0.17000, 0.14750, 0.12750, 0.10750, 0.09250, 0.07750, 0.06500, 0.05500,
0.04500, 0.03750, 0.03000, 0.02500, 0.02000, 0.01500, 0.01250, 0.01000,
0.00750, 0.00500, 0.00500, 0.00250, 0.00250, 0.00250, 0.00250,
rep(0.00024, 47)),
c(seq(93.25, 93.875, 0.125),  seq(93.9375, 98.8125, 0.0625),
seq(98.875, 99.5, 0.125)),
c(0.0025, 0.0050, 0.0075, 0.0125, 0.0175, 0.0300, 0.0350, 0.0425,
0.0525, 0.0625, 0.0750, 0.0900, 0.1050, 0.1225, 0.1425, 0.1650, 0.1900,
0.2175, 0.2450, 0.2775, 0.3125, 0.3500, 0.3875, 0.4300, 0.4725, 0.5175,
0.5675, 0.6150, 0.6675, 0.7200, 0.7750, 0.8300, 0.8850, 0.9425, 1.0025,
1.0625, 1.1225, 1.1825, 1.2425, 1.3050, 1.3675, 1.4300, 1.4925, 1.5550,
1.6175, 1.6800, 1.7425, 1.8050, 1.8675, 1.9300, 1.9925, 2.0550, 2.1175,
2.1800, 2.2425, 2.3050, 2.3675, 2.4300, 2.4925, 2.5550, 2.6175, 2.6800,
2.7425, 2.8050, 2.8675, 2.9300, 2.9925, 3.0550, 3.1175, 3.1800, 3.2425,
3.3050, 3.3675, 3.4300, 3.4925, 3.5550, 3.6175, 3.6800, 3.7425, 3.8050,
3.8675, 3.9300, 3.9925, 4.0550, 4.1175, 4.1800, 4.3050, 4.4300, 4.5550,
4.6800, 4.8050),
c(seq(93.25, 93.875, 0.125),  seq(93.9375, 98.8125, 0.0625),
seq(98.875, 99.5, 0.125)),
2,
0.0537,
1,
3,
94.7,
as.Date("2024-02-29"),
as.Date("2024-02-25"),
as.Date("2023-12-18"),
"fed_fund_rate",
"USD")
```


## bond_future_price provides with the risk neutral density at options' maturity of the government bond futures price, using options on the government bond futures

```{r}
bond_future_price(c(10.39,9.92,9.46,9.00,8.55,8.10,7.66,7.23,
6.81,6.39,5.98,5.58,5.20,4.82,4.46,4.10,3.76,3.44,3.13,2.83,2.56,
2.29,2.05,1.82,1.61,1.42,1.25,1.09,0.95,0.82,0.71,0.61,0.53,0.45,
0.38,0.33,0.28,0.23,0.20,0.17,0.14,0.12,0.10,0.08),
seq(106, 127.5, 0.5),
c(0.22,0.25,0.29,0.33,0.38,0.43,0.49,0.56,0.64,0.72,0.81,0.91,
1.03,1.15,1.29, 1.43,1.59,1.77,1.96,2.16,2.39,2.62,2.88,3.15,
3.44,3.75,4.08, 4.42,4.78,5.15,5.54,5.94,6.36,6.78,7.21,7.66,
8.11,8.56,9.03, 9.50,9.97,10.45,10.93,11.41),
seq(106, 127.5, 0.5),
2,
0.0344,
1,
3,
as.Date("2033-11-01"),
116.17,
as.Date("2024-12-10"),
as.Date("2024-11-22"),
as.Date("2024-06-14"),
"Italian",
"EUR")
```

## ctd_bond_yield provides with the risk neutral density at options' maturity of the yield to maturity of the Cheapest-to-Deliver Bond in a futures contract, using options on the government bond futures. The current CtD is assumed to be the CtD at futures' maturity. This is achieved by considering a "term cash and carry relationship" between the Cheapest-to-Deliver Bond and the futures contract, holding constant the CtD repo rate at options' maturity.

```{r}
ctd_bond_yield(c(10.39,9.92,9.46,9.00,8.55,8.10,7.66,7.23,
6.81,6.39,5.98,5.58,5.20,4.82,4.46,4.10,3.76,3.44,3.13,2.83,2.56,
2.29,2.05,1.82,1.61,1.42,1.25,1.09,0.95,0.82,0.71,0.61,0.53,0.45,
0.38,0.33,0.28,0.23,0.20,0.17,0.14,0.12,0.10,0.08),
seq(106, 127.5, 0.5),
c(0.22,0.25,0.29,0.33,0.38,0.43,0.49,0.56,0.64,0.72,0.81,0.91,
1.03,1.15,1.29, 1.43,1.59,1.77,1.96,2.16,2.39,2.62,2.88,3.15,
3.44,3.75,4.08, 4.42,4.78,5.15,5.54,5.94,6.36,6.78,7.21,7.66,
8.11,8.56,9.03, 9.50,9.97,10.45,10.93,11.41),
seq(106, 127.5, 0.5),
2,
0.0344,
0.035,
1,
3,
0.893,
0.0435, 
as.Date("2033-11-01"),
2,
100,
2,
116.17,
as.Date("2024-12-10"),
as.Date("2024-11-22"),
as.Date("2024-06-14"),
"Italian",
"EUR")
```


## proba_ctd provides, for each bond in the delivery basket of a government bond futures contact, its probability to be the cheapest to deliver bond at futures' maturity, based on a ranking of the net basis of each bond in the delivery basket at futures' maturity. Here it is assumed that the RND of the bond futures price at futures maturity is the same as its RND at options' maturity.

```{r}
proba_ctd( c(24.10, 23.10, 22.12, 21.12, 20.12, 19.14, 18.14, 17.16, 16.18, 15.20,
14.22, 13.24, 12.28, 11.32, 10.36, 9.44, 8.50, 7.60, 6.72, 5.86, 5.04, 4.28,
3.56, 2.88, 2.30, 1.78,  1.36, 1.02, 0.76, 0.56, 0.42, 0.30, 0.22, 0.18, 0.14,
0.10,  0.08, 0.06, 0.06, 0.04, 0.04, 0.02, 0.02, 0.02, 0.02, 0.02, 0.02),
seq(85, 131),
c(0.02,  0.02, 0.02, 0.02, 0.02, 0.04, 0.04, 0.06, 0.08, 0.10, 0.12, 0.14, 0.18, 0.22,
0.26, 0.34,  0.40, 0.50, 0.62, 0.76, 0.94, 1.18, 1.46, 1.78, 2.20, 2.68, 3.26, 3.92,
4.66,  5.46, 6.32, 7.20, 8.12, 9.08, 10.04, 11.00, 11.98, 12.96, 13.96, 14.94, 15.94,
16.92, 17.92, 18.92, 19.92, 20.92, 21.92),
seq(85, 131),
2,
0.0187,
1,
3,
as.Date("2054-08-15"),
109.1,
as.Date("2026-09-08"),
as.Date("2026-08-21"),
as.Date("2026-05-28"),
c("DE0001102572", "DE0001102614", "DE0001030757", "DE000BU2D004", "DE000BU2D012"),
c(0.000, 0.018, 0.018, 0.025, 0.029),
rep(1, 5),
as.Date(c("2052-08-15", "2053-08-15", "2053-08-15", "2054-08-15", "2056-08-15")),
100,
c(0.361698, 0.641260, 0.641260, 0.750372, 0.809987),
c(0.03500, 0.03507, 0.03492, 0.03510, 0.03514),
2)
```


## proba_ctd_opt provides, for each bond in the delivery basket of a government bond futures contact, its probability to be the cheapest to deliver bond at options' maturity, based on a ranking of the net basis of each bond in the delivery basket at options' maturity

```{r}
proba_ctd_opt( c(24.10, 23.10, 22.12, 21.12, 20.12, 19.14, 18.14, 17.16, 16.18, 15.20,
14.22, 13.24, 12.28, 11.32, 10.36, 9.44, 8.50, 7.60, 6.72, 5.86, 5.04, 4.28,
3.56, 2.88, 2.30, 1.78,  1.36, 1.02, 0.76, 0.56, 0.42, 0.30, 0.22, 0.18, 0.14,
0.10,  0.08, 0.06, 0.06, 0.04, 0.04, 0.02, 0.02, 0.02, 0.02, 0.02, 0.02),
seq(85, 131),
c(0.02,  0.02, 0.02, 0.02, 0.02, 0.04, 0.04, 0.06, 0.08, 0.10, 0.12, 0.14, 0.18, 0.22,
0.26, 0.34,  0.40, 0.50, 0.62, 0.76, 0.94, 1.18, 1.46, 1.78, 2.20, 2.68, 3.26, 3.92,
4.66,  5.46, 6.32, 7.20, 8.12, 9.08, 10.04, 11.00, 11.98, 12.96, 13.96, 14.94, 15.94,
16.92, 17.92, 18.92, 19.92, 20.92, 21.92),
seq(85, 131),
2,
0.0187,
0.019,
1,
3,
as.Date("2054-08-15"),
109.1,
as.Date("2026-09-08"),
as.Date("2026-08-21"),
as.Date("2026-05-28"),
c("DE0001102572", "DE0001102614", "DE0001030757", "DE000BU2D004", "DE000BU2D012"),
c(0.000, 0.018, 0.018, 0.025, 0.029),
rep(1, 5),
as.Date(c("2052-08-15", "2053-08-15", "2053-08-15", "2054-08-15", "2056-08-15")),
100,
c(0.361698, 0.641260, 0.641260, 0.750372, 0.809987),
c(0.03500, 0.03507, 0.03492, 0.03510, 0.03514),
2)
```


## bond_yield_spread provides, at a given maturity, 10,000 realizations of the bond yield spread between two different issuers' yield or two yields of the same issuer at different maturities, using options on two bond futures with the same maturity and using the correlation coefficient between returns of the corresponding bond futures' prices. The realizations are generated with the joint distribution of the two bond futures prices which are converted into bond yields, using the bonds in the delivery basket of each futures contract. The joint distribution is modeled with a gaussian copula and the marginal RNDs of bond futures price at option's maturity. The bond futures prices are modeled as a mixture of two lognormal laws. The function also returns a density plot of the spread, in bps

```{r}
bond_yield_spread(
c(12.64, 12.14, 11.65, 11.15, 10.65, 10.15,  9.65,  9.16, 8.66,
8.16, 7.67,  7.17, 6.68, 6.19, 5.70, 5.21, 4.73, 4.25, 3.78, 3.32,
2.87,  2.45, 2.05, 1.67, 1.33, 1.03, 0.77, 0.57, 0.41, 0.29,
0.21,  0.15, 0.10, 0.07, 0.06, 0.04, 0.04, 0.03, 0.02, 0.02, 0.02,
0.02,  0.01, 0.01, 0.01, 0.01, 0.01),
c(seq(114, 136.5, 0.5), 137.5),
c(0.01, 0.01, 0.02, 0.02, 0.02, 0.02, 0.02, 0.03, 0.03, 0.03, 0.04, 0.04,
0.05, 0.06, 0.07, 0.08, 0.10, 0.12, 0.15, 0.19, 0.24, 0.32, 0.42, 0.54,
0.70, 0.90, 1.14, 1.44, 1.78, 2.16, 2.58, 3.02, 3.47, 3.94, 4.43, 4.91,
5.41, 5.90, 6.39, 6.89, 7.39, 7.89, 8.38, 8.88, 9.38, 9.88, 10.88),
c(seq(114, 136.5, 0.5), 137.5),
c(13.46, 12.96, 12.46, 11.96, 11.47, 10.97, 10.47, 9.98, 9.48, 8.99, 8.49,
8.00,  7.51, 7.02, 6.53, 6.04, 5.56, 5.08, 4.61, 4.15, 3.69, 3.25, 2.82,
2.41,  2.02, 1.67, 1.34, 1.05, 0.80, 0.59, 0.43, 0.30, 0.21, 0.14, 0.09,
0.06, 0.04,  0.02, 0.01, 0.01, 0.01, 0.01, 0.01, 0.01, 0.01, 0.01, 0.01, 0.01),
seq(105.5, 129, 0.5),
c(0.02, 0.02, 0.02, 0.02, 0.03, 0.03, 0.03, 0.04, 0.04, 0.05, 0.05, 0.06,
0.07, 0.08, 0.09, 0.10, 0.12, 0.14, 0.17, 0.21, 0.25, 0.31, 0.38, 0.47,
0.58, 0.73, 0.90, 1.11, 1.36, 1.65, 1.99, 2.36, 2.77, 3.20, 3.65, 4.12,
4.60, 5.08, 5.57, 6.07, 6.57, 7.06, 7.56, 8.06, 8.56, 9.06, 9.56, 10.06),
seq(105.5, 129, 0.5),
0.0187,
0.019,
1,
1,
3,
3,
as.Date("2035-08-15"),
as.Date("2035-08-01"),
126.66,
119.04,
as.Date("2026-09-08"),
as.Date("2026-08-21"),
as.Date("2026-06-17"),
c("DE000BU2Z056", "DE000BU2Z064"),
c(0.026, 0.029),
rep(1, 2),
as.Date(c("2035-08-15", "2036-02-15")),
c(0.770088, 0.781249),
c(0.02898, 0.02926),
2,
c("IT0005631590", "IT0005648149", "IT0005676504", "IT0005402117",
"IT0005706285", "IT0005433195"),
c(0.0365, 0.0360, 0.0345, 0.0145, 0.0380, 0.0095),
rep(2, 6),
as.Date(c("2035-08-01", "2035-10-01", "2036-02-01", "2036-03-01",
"2036-07-01", "2037-03-01")),
c(0.845212, 0.839556, 0.824415, 0.679587, 0.844354, 0.616457),
c(0.03567, 0.03587, 0.03620, 0.03614, 0.03665, 0.03712),
2,
100,
0.4,
"Germany",
"Italy")
```


## bond_fut_irr_ytm fits to options on a bond futures the RND of the bond futures price with a mixture of two lognormal laws. Then it extracts from this RND, for the current Cheapest-to-Deliver bond in the delivery basket of the futures contract, the RND of its forward yield and the RND of its forward repo rate which are again decribed by a mixture of two lognormal laws each. The current CtD is assumed to be the CtD at futures' maturity. This is achieved again by considering a "term cash and carry relationship" between the current Cheapest-to-Deliver bond and the futures contract, allowing here the repo rate of the bond at options' maturity to have a distribution. The RND of the STIR futures contract of the same currency and approximate same maturity is used to fix the bounds of the volatility of the forward repo rate density.

```{r}
bond_fut_irr_ytm(c(12.64, 12.14, 11.65, 11.15, 10.65, 10.15, 9.65,
9.16, 8.66, 8.16, 7.67,  7.17, 6.68, 6.19, 5.70, 5.21, 4.73, 4.25,
3.78, 3.32, 2.87, 2.45, 2.05, 1.67, 1.33, 1.03, 0.77, 0.57, 0.41,
0.29, 0.21, 0.15, 0.10, 0.07, 0.06, 0.04, 0.04, 0.03, 0.02, 0.02,
0.02, 0.02, 0.01, 0.01, 0.01, 0.01, 0.01),
c(seq(114, 136.5, 0.5), 137.5),
c(0.01, 0.01, 0.02, 0.02, 0.02, 0.02, 0.02, 0.03, 0.03, 0.03, 0.04,
0.04, 0.05, 0.06, 0.07, 0.08, 0.10, 0.12, 0.15, 0.19, 0.24, 0.32,
0.42, 0.54, 0.70, 0.90, 1.14, 1.44, 1.78, 2.16, 2.58, 3.02, 3.47,
3.94, 4.43, 4.91, 5.41, 5.90, 6.39, 6.89, 7.39, 7.89, 8.38, 8.88,
9.38, 9.88, 10.88),
c(seq(114, 136.5, 0.5), 137.5),
c(1.704999924, 1.579999924, 1.454999924, 1.329999924, 1.204999924,
1.079999924, 0.954999983, 0.892499983, 0.829999983, 0.767499983,
0.704999983, 0.642499983, 0.582499981, 0.519999981, 0.457499981,
0.397499979, 0.334999979, 0.275000006, 0.217500001, 0.162499994,
0.112499997, 0.072499998, 0.039999999, 0.02, 0.0075, 0.0025, 0.0025,
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0),
c(seq(95.75, 96.5, 0.125), seq(96.5625, 98.75, 0.0625),
seq(98.875, 99.5, 0.125)),
c(0, 0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0.0025,  0.0025,
0.0025,  0.005, 0.005,  0.0075,  0.012499999,  0.02, 0.029999999,
0.055, 0.085000001, 0.127499998, 0.177499995, 0.234999999,
0.297499985, 0.357499987, 0.419999987, 0.482499987, 0.544999957,
0.607499957, 0.669999957, 0.732499957, 0.794999957, 0.857499957,
0.919999957, 0.982499957, 1.044999957, 1.107499957, 1.169999957,
1.232499957, 1.294999957, 1.419999957, 1.544999957, 1.669999957,
1.794999957, 1.919999957, 2.044999838),
c(seq(95.75, 96.5, 0.125), seq(96.5625, 98.75, 0.0625),
seq(98.875, 99.5, 0.125)),
0.0224,
0.02232,
1,
3,
126.66,
0.026,
1,
0.770088,
2,
bond_N = 100,
as.Date("2035-08-15"),
as.Date("2026-09-08"),
as.Date("2026-08-21"),
3,
97.45,
as.Date("2026-09-14"),
as.Date("2026-08-14"),
as.Date("2026-06-17"),
ref_rate = "3-mth Euribor",
country = "Germany",
currency = "EUR")
```