---
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 all types of option's style. The futures price is modeled as a mixture of either two or three lognormal laws. The package 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 additional 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 STIR futures price and the bond futures price. Then, the package extracts in one go from options prices on bond futures two RNDs at options' maturity: the RND of the cheapest-to-deliver bond yield and the RND of the ctd repo rate. Then, the packages provides with the probability attached to each bond in the delivery basket of a government bond futures contract to be the cheapest to deliver at options' maturity, either from the observation of the expected net basis distribution by bond at options' maturity, or from the observation of the implied repo rate distribution by bond at options' maturity. The package also provides with the probability attached to each bond to be the cheapest at futures' maturity. 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. At last, the package provides with functions to extract from Bloomberg interest rate futures contracts characteristics, options prices on interest futures and major characteristics of the bonds in the delivery basket of a government bond futures contract.


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



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


## bond_fut_irr_ytm extracts in one go from options prices on a bond futures, for any bond in the delivery basket, the RND of its implied repo rate and the RND of its yield to maturity. To do so, the bond price at options' maturity and the bond repo price at options' maturity are both modeled with a mixture of two lognormal laws, with a dependency. Then, the "expected cash and carry relationship" at options' maturity between the bond and the futures contract is introduced. The RND of the STIR futures contract of the same currency and approximate same maturity is used to set the initial values of the volatility of the log returns of the repo asset price in the optimization phase.

```{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.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"),
"Germany",
"EUR",
3)
```




## proba_ctd_opt calculates, 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, relying successively on a ranking of the net basis and on a raking of the implied repo rate 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)
```