---
title: "Scenarios"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Scenarios}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

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

## Definition

In the Triple Billions and the billionaiRe package context, scenarios are understood as alternative, plausible, description of how the future may develop based on a set of defined assumptions.

Scenarios must:

1.  Be [tidy](https://r4ds.had.co.nz/tidy-data.html): each row is a unique combination of iso3 country-code, year, indicator, and scenario (if relevant).
2.  Contain **all** and **only** the data that is strictly needed for calculations with billionaiRe

Four main sets of scenarios can be identified, from the most basic to the more complex:

1.  [Basic scenarios]: Those scenarios are the building blocks of the other scenarios, but they can also be called on their own. They can reach a fixed target at a specified year (`scenario_fixed_target()`), follow a specific rate of change (`scenario_aroc()`), etc. See [Basic scenario](data-recycling.html) for more details.
2.  [Target scenarios]: Target-based scenarios apply indicator-specific targets or trajectories to be reached by a specific date (e.g. Sustainable Development Goal (SDG) targets (called `sdg` scenarios)).
3.  [Benchmarking scenarios]: Benchmarking scenarios compare performance of countries given various grouping and aim at a specified sub-set of best performing countries.
4.  [Mixed scenarios]: Developped with indicator-level subject matter knowledge to pick realistic improvement scenarios (e.g. `acceleration` scenarios)

If billionaiRe require data that is missing in the scenario, they will be recycled from other scenarios (see [Data recycling](data-recycling.html)).

## Quick start: How to use billionaiRe scenarios

`add_scenario()` is the entry point function to all other scenario functions. It essentially allow to pass a typical billionaiRe data frame (`df`) and apply the selected scenario function.

```{r scenario-example-setup, include = TRUE, eval = FALSE}
library(billionaiRe)

df <- tibble::tibble(
    value = 60:80,
    year = 2010:2030,
    ind = "pm25",
    type = "reported",
    iso3 = "AFG",
    scenario = "default",
    source = NA_character_
  ) %>%
    dplyr::mutate(scenario = dplyr::case_when(
      year > 2021 ~ "historical",
      TRUE ~ scenario
    ),
    type = dplyr::case_when(
      year > 2021 ~ "projected",
      TRUE ~ type
    ))
```

The choice of scenario function to apply to the `df` is done through the `scenario_function` parameter. Additional parameters can be passed through the ellipsis (`...`).

For instance, to halt the rise to the 2010 value by `end_year` (2025 by default), we can apply a simple function to `df`. This will apply the `halt_rise` function to all unique combination of country and indicator. In this case, there is just one combination:

```{r scenario-example-single-function, include = TRUE, eval = FALSE}
df %>%
  add_scenario(
    scenario_function = "halt_rise",
    baseline_year = 2010
  )
```

To apply the SDG targets, we use the `sdg`:

```{r scenario-example-sdg-start-2018, include = TRUE, eval = FALSE}
df %>%
  add_scenario(
    scenario_function = "sdg"
  )
```

By default, the scenarios start from the last reported or estimated value in the default scenario. This can be bypassed by setting `start_scenario_last_default` to FALSE. The scenario will then start at `start_year` (2018 by default):

```{r scenario-example-sdg-start-last, include = TRUE, eval = FALSE}
df %>%
  add_scenario(
    scenario_function = "sdg",
    start_scenario_last_default = FALSE
  )
```

## Basic scenarios

The basic scenarios are the building blocks of all other scenarios. They can also be used by themselves on the data. All basic scenarios functions share  have share parameters, but also have their own. See the individual documentation of each function to see the details.

- Annual Rate of Change (AROC): `scenario_aroc()`
- Fixed targets: `scenario_fixed_target()`, `scenario_fixed_target_col()`, `scenario_halt_rise()`
- Percentage change from baseline: `scenario_percent_baseline()`
- Linear change: `scenario_linear_change()`, `scenario_linear_change_col()`
- Benchmarking: `scenario_quantile()`, `scenario_best_in_region()`, `scenario_top_n_iso3()`
- Compairing scenarios: `scenario_best_of()`, `scenario_bau()`

See [Basic Scenarios documentation](basic-scenarios.html) for a full description of all availabe basic scenarios.

## Target scenarios

Target scenarios apply targets that form a coherent ensemble, but that are specific to each indicator. The prime example of this type of scenario is `sdg` where each indicator is targeting its SDG target by 2030.

All SDG scenarios definitions can be found in the [SDG scenarios](sdg-scenarios.html) documentation.

The other target scenario available in billionaiRe at the moment is `accelerate_target` that removes from acceleration scenarios any scenario that is not a target. The result is similar to SDG scenario in spirit but has different results.

By default, the scenario values are trimmed to 2025. This can be changed with the `end_year` parameter:

```{r scenario-example-sdg, include = TRUE, eval = FALSE}
df %>%
  add_scenario(
    scenario_function = "sdg",
    end_year = 2030
  )
```

## Benchmarking scenarios

Benchmarking scenarios are a curated list of four benchmarking scenarios applied to all indicators, with minor variations:

- Top 20% AROC globally
- Top 20% AROC in WHO regions
- Top 20% AROC in World Bank (WB) Income Groups (IC)

They allow to compare a country trajectories with their peers.

## Mixed scenarios

Acceleration scenarios are version of the future that are ambitious yet achievable by countries. They were created in conjonction with WHO technical units.

Acceleration scenarios are fully indicator specific. The [Acceleration scenarios documentation](acceleration-scenarios.html) provides a full description of each of them.

## Internal use scenarios

There are three *internal use* special case scenario:

-   `routine`: stores the `reported` and `estimated` data
-   `reference_infilling`: stores WHO technical programs projected data (either `projected` or `imputed`).
-   `covid_shock`: stores the data that correspond to the COVID-19 shock.

All together those three scenarios are the *base scenarios*. They are the spine of other scenarios and act then as a filling when scenarios do not contain the required data to build a full time series.

## Scenarios integration into data pipeline

The current Triple Billion data pipeline is composed of four main steps. billionaiRe is dealing only with the calculation step:

1.  Ingestion: Azure DevOps repo
2.  Projection: Azure DevOps repo
3.  Calculation: **billionaiRe**
4.  Export: *rapporteur*

The definition of the [Internal use scenarios] scenarios happen in the `ingestion` and `projection` steps, which are outside of the scope of the billionaiRe package.

Other scenarios are calculated at stage 3 (Calculation), as does the rest of the billionaiRe calculations. Those scenarios can be calculated with the `add_scenario()` function.

Within the Triple Billion calculations pipeline, adding the scenarios values should ideally be the first steps (i.e. before transforming the data). However, some event-based and trajectory-based scenarios, might require some level of data recycling before they run. If this is the case, errors should be produced.

## Scenarios naming convention

-   [Lower Snake case](https://en.wikipedia.org/wiki/Snake_case) is used

-   Short and very descriptive names: use verbs as much as possible

-   Use only commonly understood acronyms and abbreviations

-   `event` scenarios start with them. E.g. covid, pre_covid_bau

    -   Sub-event scenarios should have a descriptive word rather than numbering or other undefined markers. **DO**: covid_never_return. **DON'T**: COVID_1

-   `routine` is reserved for reported/estimated data

-   `reference_infilling` is reserved for imputed/projected data

-   `default` is reserved for the main data present on the dashboard

-   `acceleration` is reserved for acceleration scenarios / trajectories

-   `sdg` is reserved for sustainable development goals
