In gpw13/billionaiRe: Calculate the WHO Triple Billions

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

The basic scenarios are the building blocks of all other scenarios. They can also be used by themselves on the data.

Each of those scenarios 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() use a general compounded rate of change formula: $$\mathrm{AROC(year_{baseline}, year_{target})} = (Value(year_{target}) / Value(year_{baseline})) ^ (1 / (year_{target} - year_{baseline})) - 1$$

Three options are provided through the aroc_type parameter:

target: aims at a specific target_value by target_year
latest: takes the AROC between baseline_year and the previous year
percent_change: applies percent_change for the AROC from baseline_year.

Fixed targets

scenario_fixed_target() allows to reach a target value from a baseline year by target year. It provides values for scenarios stated as "Reach XX% in INDICATOR by YEAR" or "Eliminate XX by YEAR".

scenario_fixed_target_col() wraps around scenario_fixed_target() to provide targets from a column specified in target_col rather than a single value.

scenario_halt_rise() is a special case of scenario_fixed_target_col() where each country aims at a value of a specific year.

Percentage change from baseline

scenario_percent_baseline() allows to change a value by a fixed percentage to a provided year from a provided baseline year. It provides values for scenarios stated as "Reduce INDICATOR by XX% by YEAR"

The percent_change parameter is understood as a percentage change, and not a percentage point change, as this is usually what intended by those formulations. If it is indeed the percentage change that is required, use scenario_aroc(). For instance, calculating the scenario "reduce the 2018 value (90%) by 30% by 2025", will results to a 2025 value of 63% and not 60%.

Linear change

scenario_linear_change() to add a linear_value percentage point change to baseline_value from a baseline_year. It provides values for scenarios stated as "Increase INDICATOR by XX% points".

scenario_linear_change_col() wraps around scenario_linear_change() to provide linear values from a column specified in linear_value rather than a single value.

It differs from scenario_aroc() percent_change in two ways:

it is not compounded
it adds percentage points and not a percentage of values.

Benchmarking

Those scenarios are compairing countries to find the best performing countries given different parameters.

scenario_quantile() aims to reach the mean quantile average annual change (ARC) in which a country is at quantile_year. The target is based on the ARC between quantile_year and baseline_quantile_year. If ARC is under the mean of the quantile, it will aim at the mean, and at the higher limit of the quantile if above the mean.

scenario_best_in_region aims to reach the mean regional average annual change in which a country is at quantile_year. The target is based on the ARC between quantile_year and quantile_year - 5. If ARC is under the mean of the region, it will aim at the mean, and at the best value of the quantile if above the mean. small_is_best can be used to indicate is lower value is best or not.

scenario_top_n_iso3() aims to reach the top n (or prop) performing countries Annual Rate of Change (AAROC) (by group_col when provided). This is done by calculating the annual rate of change of all countries with at least two reported or estimated values between baseline_year and aroc_end_year. Then the values of the top n or top prop percent performing countries (in group_col if provided) are averaged out to have a single AROC at which all countries (by group_col if provided) will aim.

Compairing scenarios

scenario_best_of() picks the best value between multiple scenarios specified scenario_names.

scenario_bau() filters for values between start_year and end_year for bau_scenario and return those values. If values are missing for years between start_year and end_year, the latest available value will be imputed.

Helper function for scenarios

In order to have clean scenarios, a series of parameters are passed to the functions to run properly:

small_is_best: if TRUE, a lower value is considered as a better public health outcome (e.g. adult obesity)
trim_values(): if TRUE, values will be trimed around:
- keep_better_values: if TRUE, if values before running the scenario are better than after, the original values will be kept.
- upper_limit, lower_limit: if trim is TRUE, values above the upper_limit will have upper_limit and values below lower_limit will hasve lower_limit.
- trim_year: if TRUE values before start_year and after end_year will be removed.