In gpw13/billionaiRe: Calculate the WHO Triple Billions

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:

Be tidy: each row is a unique combination of iso3 country-code, year, indicator, and scenario (if relevant).
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:

[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 for more details.
[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)).
[Benchmarking scenarios]: Benchmarking scenarios compare performance of countries given various grouping and aim at a specified sub-set of best performing countries.
[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).

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.

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:

df %>%
  add_scenario(
    scenario_function = "halt_rise",
    baseline_year = 2010
  )

To apply the SDG targets, we use the sdg:

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):

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 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 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:

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 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:

Ingestion: Azure DevOps repo
Projection: Azure DevOps repo
Calculation: billionaiRe
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 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