Scenario to reach the top performing rate of change countries

scenario_top_n_iso3 aims to reach the top n (or prop) performing countries Annual Rate of Change (AAROC) in df default_scenario (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.

Usage

scenario_top_n_iso3(
  df,
  n = 10,
  group_col = NULL,
  use_prop = FALSE,
  prop = NULL,
  value_col = "value",
  scenario_col = "scenario",
  start_year = 2018,
  end_year = 2025,
  baseline_year = 2013,
  aroc_end_year = 2018,
  target_year = end_year,
  scenario_name = glue::glue("top_{n}_{group_col}_aroc"),
  small_is_best = FALSE,
  trim = TRUE,
  keep_better_values = TRUE,
  upper_limit = 100,
  lower_limit = 0,
  trim_years = TRUE,
  start_year_trim = start_year,
  end_year_trim = end_year,
  ind_ids = billion_ind_codes("all"),
  bau_scenario = "historical",
  default_scenario = "default",
  no_data_no_scenario = FALSE,
  is_aroc_last_n_years = FALSE,
  aroc_last_n_years = 5,
  min_n_reported_estimated = 2,
  ...
)

Arguments

df: Data frame in long format, where 1 row corresponds to a specific country, year, and indicator.
n: (integer) number of countries to picked in the top performing group.
group_col: (character) string identifying by which column the top should be grouped by usinge dplyr::group_by. Default to NULL.
use_prop: (Boolean) identifying if prop should be used instead of n in dplyr::slice_max or dplyr::slice_min
prop: proportion of countries to be selected. See dplyr::slice_max() for details.
value_col: Column name of column with indicator values.
scenario_col: Column name of column with scenario identifiers. Useful for calculating contributions on data in long format rather than wide format.
start_year: Start year for scenario, defaults to 2018.
end_year: End year for scenario, defaults to 2025
baseline_year: Year from which the scenario is measured. Defaults to start_year
aroc_end_year: (integer) year identifying the end of the AROC interval.
target_year: Year by which the scenario should eventually be achieved. Defaults to end_year
scenario_name: Name of the scenario. Defaults to scenario_percent_change_baseline_year
small_is_best: Logical to identify if a lower value is better than a higher one (e.g. lower obesity in a positive public health outcome, so obesity rate should have small_is_best = TRUE).
trim: logical to indicate if the data should be trimmed between upper_limit and lower_limit.
keep_better_values: logical to indicate if "better" values should be kept from value_col if they are present. Follows the direction set in small_is_best. For instance, if small_is_best is TRUE, then value_col lower than col will be kept.
upper_limit: limit at which the indicator should be caped. Can take any of "guess", or any numeric. guess (default) will take 100 as the limit if percent_change is positive, and 0 if negative.
lower_limit: limit at which the indicator should be caped. Can take any of "guess", or 0 to 100. guess (default) will take 0 as the limit if percent_change is positive, and 100 if negative.
trim_years: logical to indicate if years before start_year_trim and after end_year_trim should be removed
start_year_trim: (integer) year to start trimming from.
end_year_trim: (integer) year to end trimming.
ind_ids: Named vector of indicator codes for input indicators to the Billion. Although separate indicator codes can be used than the standard, they must be supplied as a named vector where the names correspond to the output of billion_ind_codes().
bau_scenario: name of scenario to be used for business as usual. Default is historical.
default_scenario: name of the default scenario to be used.
no_data_no_scenario: (Boolean) if TRUE, then no scenario at all is generated when there is less than 2 reported/estimated values between baseline_year and aroc_end_year
is_aroc_last_n_years: (Boolean) identifying if the AROC interval should be based on the last aroc_last_n_years since the last reported or estimated value before end_year.
aroc_last_n_years: (integer) number of years after the last reported or estimated value to start the AROC interval.
min_n_reported_estimated: (integer) minimum number of value_col points reported or estimated in the AROC interval.s
...: additional parameters to to pass to recycle_data

Details

If prop is used and there is an insufficient number of countries to select at least one, then the best perfoming is kept. For instance, if there are two countries with data and prop is 0.1, then it is not possible to select 10% of 2 countries. So only the best performing will be kept.

In this case, best performing is defined by the direction identified in indicator_df small_is_best column.