% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/scenarios_aroc.R
\name{scenario_aroc}
\alias{scenario_aroc}
\title{Scenario to use the average annual rate of change}
\usage{
scenario_aroc(
  df,
  value_col = "value",
  start_year = 2018,
  end_year = 2025,
  baseline_year = 2018,
  target_year = end_year,
  target_value = NULL,
  percent_change = NULL,
  aroc_type = c("target", "latest", "percent_change"),
  scenario_name = glue::glue("aroc_{aroc_type}"),
  scenario_col = "scenario",
  limit_aroc_direction = NULL,
  limit_aroc_value = 0,
  trim = TRUE,
  small_is_best = FALSE,
  keep_better_values = TRUE,
  start_year_trim = start_year,
  end_year_trim = end_year,
  upper_limit = 100,
  lower_limit = 0,
  trim_years = TRUE,
  ind_ids = billion_ind_codes("all"),
  default_scenario = "default"
)
}
\arguments{
\item{df}{Data frame in long format, where 1 row corresponds to a specific
country, year, and indicator.}

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

\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{target_year}{Year by which the scenario should eventually be
achieved. Defaults to \code{end_year}}

\item{target_value}{value to be reached. Used when \code{aroc_type} is \code{target}.
Should be expressed as a percentage point and not a fraction of 100 (e.g. 6\%
increase = 6, and not 0.06).}

\item{percent_change}{Numeric with the percent_change. Should be
expressed a as percentage point and not a fraction of 100 (e.g. 6\% increase = 6,
and not 0.06).}

\item{aroc_type}{String identifying type of AROC. Can be \code{target},\code{latest} or
\code{percent_change}. See details. Defaults to \code{target}.}

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

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

\item{limit_aroc_direction}{string is identify if positive or negative AROC
should be limited by \code{limit_aroc_value}. If NULL (default), no limitation will be
applied}

\item{limit_aroc_value}{numeric with values at which the AROC should be limited to.
If \code{limit_aroc_direction} is \code{positive}, will take the maximum between
\code{limit_aroc_value} and AROC. If \code{negative}, it will take the minimum between 0 and
AROC. Defaults to 0. Ignored if \code{limit_aroc_direction} is NULL (default).}

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

\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{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{start_year_trim}{(integer) year to start trimming from.}

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

\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{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{default_scenario}{name of the default scenario to be used.}
}
\description{
\code{scenario_aroc()} uses the annual rate of change (AROC) in different cases to
calculate the values of the scenario:
}
\details{
\itemize{
\item \code{target}: aims at a specific \code{target_value} by \code{target_year}
\item \code{latest}: takes the AROC between \code{baseline_year} and the previous year
\item \code{percent_change}: applies \code{percent_change}  for the AROC from
\code{baseline_year}.
}

This function is different than \code{scenario_percent_baseline()} or
\code{scenario_linear_change()} as it uses percentage difference and not
percentage points difference.

AROC use a general \href{https://en.wikipedia.org/wiki/Compound_annual_growth_rate}{compounded rate of change}
formula:
(Value(year_n) / Value(year_0)) ^ (1 / (year_n -  year_0)) - 1

\code{direction_limit_aroc} in combination with \code{limit_aroc} allows to limit the
AROC to a value given a direction. This can be helpful to avoid extreme
values if AROC is unknown before being passed to the function.If
\code{direction_limit_aroc} is \code{positive}, the AROC will be the minimum between
the calculated AROC and \code{limit_aroc}. If \code{negative}, it will be the maximum
between AROC and
}
\seealso{
Basic scenarios
\code{\link{scenario_bau}()},
\code{\link{scenario_best_of}()},
\code{\link{scenario_linear_change}()},
\code{\link{scenario_percent_baseline}()}
}
\concept{aroc}
\concept{basic_scenarios}
