---
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. The package also provides with the distribution of STIR rates futures and government bond yields themselves at options' maturity, using the RND of respectively the futures price of the STIR futures and the bond futures. It provides with some statistics of the distribution as well as a density and a cumulative density plot. Leveraging on the RND of bond futures, 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. 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 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 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 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 of the yield to maturity of the Cheapest-to-Deliver Bond in a futures contract, using options on the government bond futures

```{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

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