---
title: "Getting Started with solvency2rfr"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with solvency2rfr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Overview

`solvency2rfr` provides easy access to the risk-free interest rate (RFR) term
structures published monthly by the European Insurance and Occupational Pensions
Authority (EIOPA). These curves are a mandatory input for calculating Solvency II
technical provisions across the European Economic Area.

The package reads the official EIOPA RSS feed, downloads the monthly ZIP files,
and returns the data as a tidy tibble — one row per country and maturity year.

```{r load}
library(solvency2rfr)
```

## Listing available publications

Use `rfr_index()` to see all available datasets. Each row represents one monthly
publication:

```{r index, eval = FALSE}
idx <- rfr_index()
head(idx)
```

```{r index-fake, echo = FALSE}
# Fake output for vignette to avoid network access during package build
tibble::tibble(
  date  = as.Date(c("2026-04-30", "2026-03-31", "2026-02-28",
                    "2026-01-31", "2025-12-31")),
  title = c("April 2026", "March 2026", "February 2026",
            "January 2026", "December 2025"),
  url   = c(
    "https://www.eiopa.europa.eu/system/files/2026-05/EIOPA_RFR_20260430.zip",
    "https://www.eiopa.europa.eu/system/files/2026-04/EIOPA_RFR_20260331.zip",
    "https://www.eiopa.europa.eu/system/files/2026-03/EIOPA_RFR_20260228.zip",
    "https://www.eiopa.europa.eu/system/files/2026-02/EIOPA_RFR_20260131.zip",
    "https://www.eiopa.europa.eu/system/files/2026-01/EIOPA_RFR_20251231.zip"
  )
)
```

## Downloading term structures

`rfr_term_structures()` downloads the most recent publication by default, or a
specific date when supplied:

```{r download, eval = FALSE}
# Most recent publication
rfr <- rfr_term_structures()

# Specific reference date
rfr_april <- rfr_term_structures("2026-04-30")
```

```{r download-fake, echo = FALSE}
# Compact fake output for vignette
rfr <- tibble::tibble(
  date     = as.Date("2026-04-30"),
  country  = rep(c("Euro", "Germany", "France"), each = 5),
  maturity = rep(1:5, 3),
  rate     = c(0.0268, 0.0275, 0.0275, 0.0275, 0.0278,
               0.0268, 0.0275, 0.0275, 0.0275, 0.0278,
               0.0268, 0.0275, 0.0275, 0.0275, 0.0278)
)
rfr
```

The returned tibble contains one row per country–maturity combination:

| Column     | Type        | Description                                  |
|------------|-------------|----------------------------------------------|
| `date`     | `Date`      | Reference date (end of month)                |
| `country`  | `character` | Country or currency area name                |
| `maturity` | `integer`   | Maturity in years (1 to 150)                 |
| `rate`     | `double`    | Annual spot rate as a decimal (not percent)  |

## Selecting a curve type

The `curve` argument selects which rate curve to return. Available options are:

| `curve`            | Description                                       |
|--------------------|---------------------------------------------------|
| `"spot_no_VA"`     | Spot rate without volatility adjustment (default) |
| `"spot_with_VA"`   | Spot rate with volatility adjustment              |
| `"spot_no_VA_up"`  | Upward interest rate shock (no VA)                |
| `"spot_no_VA_down"`| Downward interest rate shock (no VA)              |
| `"spot_with_VA_up"`| Upward interest rate shock (with VA)              |
|`"spot_with_VA_down"`| Downward interest rate shock (with VA)           |

```{r curve-type, eval = FALSE}
rfr_va <- rfr_term_structures("2026-04-30", curve = "spot_with_VA")
```

## Example: plotting the Euro risk-free curve

```{r plot, eval = FALSE}
library(ggplot2)

rfr |>
  subset(country == "Euro" & maturity <= 50) |>
  ggplot(aes(x = maturity, y = rate * 100)) +
  geom_line() +
  labs(
    title = "EIOPA Euro Risk-Free Rate — April 2026",
    x     = "Maturity (years)",
    y     = "Annual spot rate (%)"
  )
```

## Data source and disclaimer

The RFR term structures are published by EIOPA at:
<https://www.eiopa.europa.eu/tools-and-data/risk-free-interest-rate-term-structures_en>

An internet connection is required to download data. EIOPA publishes updated
curves approximately on the 5th of each month for the prior month-end.

> Technical information published is based on sources which EIOPA considers to
> be reasonably reliable. EIOPA accepts no responsibility or liability for any
> losses incurred in connection with any decision made or action or inaction
> in reliance upon EIOPA's technical information.
