% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/scenarios_top_n_countries.R
\name{scenario_top_n_iso3}
\alias{scenario_top_n_iso3}
\title{Scenario to reach the top performing rate of change countries}
\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{
\item{df}{Data frame in long format, where 1 row corresponds to a specific
country, year, and indicator.}

\item{n}{(integer) number of countries to picked in the top performing group.}

\item{group_col}{(character) string identifying by which column the top should
be grouped by usinge \code{dplyr::group_by}. Default to NULL.}

\item{use_prop}{(Boolean) identifying if \code{prop} should be used instead of \code{n}
in \code{dplyr::slice_max} or \code{dplyr::slice_min}}

\item{prop}{proportion of countries to be selected. See \code{dplyr::slice_max()}
for details.}

\item{value_col}{Column name of column with indicator values.}

\item{scenario_col}{Column name of column with scenario identifiers. Useful for
calculating contributions on data in long format rather than wide format.}

\item{start_year}{Start year for scenario, defaults to 2018.}

\item{end_year}{End year for scenario, defaults to 2025}

\item{baseline_year}{Year from which the scenario is measured.
Defaults to \code{start_year}}

\item{aroc_end_year}{(integer) year identifying the end of the AROC interval.}

\item{target_year}{Year by which the scenario should eventually be
achieved. Defaults to \code{end_year}}

\item{scenario_name}{Name of the scenario. Defaults to scenario_{percent_change}_{baseline_year}}

\item{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).}

\item{trim}{logical to indicate if the data should be trimmed between
\code{upper_limit} and \code{lower_limit}.}

\item{keep_better_values}{logical to indicate if "better" values should be
kept from \code{value_col} if they are present. Follows the direction set in
\code{small_is_best}.  For instance, if small_is_best is TRUE, then \code{value_col} lower
than \code{col} will be kept.}

\item{upper_limit}{limit at which the indicator should be caped.
Can take any of "guess", or any numeric. \code{guess} (default) will take 100 as
the limit if \code{percent_change} is positive, and 0 if negative.}

\item{lower_limit}{limit at which the indicator should be caped.
Can take any of "guess", or 0 to 100. \code{guess} (default) will take 0 as the
limit if \code{percent_change} is positive, and 100 if negative.}

\item{trim_years}{logical to indicate if years before \code{start_year_trim} and after
\code{end_year_trim} should be removed}

\item{start_year_trim}{(integer) year to start trimming from.}

\item{end_year_trim}{(integer) year to end trimming.}

\item{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
\code{billion_ind_codes()}.}

\item{bau_scenario}{name of scenario to be used for business as usual.
Default is \code{historical}.}

\item{default_scenario}{name of the default scenario to be used.}

\item{no_data_no_scenario}{(Boolean) if TRUE, then no scenario at all is generated
when there is less than 2 reported/estimated values between \code{baseline_year}
and \code{aroc_end_year}}

\item{is_aroc_last_n_years}{(Boolean) identifying if the AROC interval should
be based on the last \code{aroc_last_n_years} since the last \code{reported} or
\code{estimated} value before \code{end_year}.}

\item{aroc_last_n_years}{(integer) number of years after the last \code{reported}
or \code{estimated} value to start the AROC interval.}

\item{min_n_reported_estimated}{(integer) minimum number of \code{value_col}
points \code{reported} or \code{estimated} in the AROC interval.s}

\item{...}{additional parameters to to pass to \code{recycle_data}}
}
\description{
\code{scenario_top_n_iso3} aims to reach the top \code{n} (or \code{prop}) performing countries
Annual Rate of Change (AAROC) in \code{df} \code{default_scenario} (by \code{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 \code{baseline_year}
and \code{aroc_end_year}. Then the values of the top \code{n} or top \code{prop} percent
performing countries (in \code{group_col} if provided) are averaged out to have a
single AROC at which all countries (by \code{group_col} if provided) will aim.
}
\details{
If \code{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 \code{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
\code{indicator_df} \code{small_is_best} column.
}
\concept{basic_benchmarking}
