% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/scenarios_dip_recover.R
\name{scenario_dip_recover}
\alias{scenario_dip_recover}
\alias{scenario_dip_recover_iso3}
\alias{scenario_dip_recover_iso3_ind}
\title{Scenario dip and recover}
\usage{
scenario_dip_recover(
  df,
  start_year = 2018,
  dip_year = 2020,
  recovery_year = 2021,
  progressive_recovery = FALSE,
  aroc_type = c("lastest_year", "average_years_in_range"),
  aroc_start_year = start_year,
  end_year = 2025,
  value_col = "value",
  scenario_col = "scenario",
  scenario_name = "dip_recover",
  ind_ids = billion_ind_codes("all"),
  default_scenario = "default",
  source = sprintf("WHO DDI, \%s", format(Sys.Date(), "\%B \%Y")),
  ...
)

scenario_dip_recover_iso3(
  df,
  iso3,
  start_year = 2018,
  dip_year = 2020,
  recovery_year = 2021,
  progressive_recovery = FALSE,
  aroc_type = c("lastest_year", "average_years_in_range"),
  aroc_start_year = start_year,
  end_year = 2025,
  value_col = "value",
  scenario_col = "scenario",
  scenario_name = "dip_recover",
  trim = TRUE,
  small_is_best = FALSE,
  keep_better_values = FALSE,
  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"),
  source = sprintf("WHO DDI, \%s", format(Sys.Date(), "\%B \%Y")),
  default_scenario = "default"
)

scenario_dip_recover_iso3_ind(
  df,
  iso3,
  ind,
  dip_year = 2020,
  recovery_year = 2021,
  progressive_recovery = FALSE,
  aroc_type = c("lastest_year", "average_years_in_range"),
  aroc_start_year = start_year,
  baseline_year = 2018,
  last_year = NULL,
  start_year = 2018,
  end_year = 2025,
  value_col = "value",
  scenario_col = "scenario",
  scenario_name = "dip_recover",
  ind_ids = billion_ind_codes("all"),
  default_scenario = "default",
  trim = TRUE,
  small_is_best = FALSE,
  keep_better_values = FALSE,
  upper_limit = 100,
  lower_limit = 0,
  trim_years = TRUE,
  start_year_trim = start_year,
  end_year_trim = end_year,
  source = sprintf("WHO DDI, \%s", format(Sys.Date(), "\%B \%Y"))
)
}
\arguments{
\item{df}{Data frame in long format, where 1 row corresponds to a specific
country, year, and indicator.}

\item{start_year}{Base year for contribution calculation, defaults to 2018.}

\item{dip_year}{(integer) year where the dip appends}

\item{recovery_year}{(integer) year from which the AROC will be applied}

\item{progressive_recovery}{(logical) TRUE if the recovery after dip
should be progressive.}

\item{aroc_type}{(character) name of the type of AROC to be used. Can be either:
\itemize{
\item \code{lastest_year}: only the latest \code{reported}/\code{estimated} year between \code{start_year}
and \code{dip_year} is used to calculate
\item \code{average_years_in_range}:
}}

\item{aroc_start_year}{(integer) year}

\item{end_year}{End year(s) for contribution calculation, defaults to 2019 to 2025.}

\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{scenario_name}{name of scenario}

\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.}

\item{source}{Source to provide for calculated average service coverage and
single measure.}

\item{...}{additional parameters to be passed to
\code{scenario_dip_recover_iso3()}}

\item{iso3}{(character) ISO3 code of country to scenario}

\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{upper_limit}{upper limit at which the indicator should be caped.}

\item{lower_limit}{lower_limit limit at which the indicator should be caped.}

\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}{(character) name of the indicator on which to calculate the
scenario}

\item{baseline_year}{(integer) identify baseline year on which the AROC
should be calculated.}

\item{last_year}{(integer) identify last year where values were \code{reported}
or \code{estimated} between \code{start_year} and \code{end_year}.}

\item{scenario}{name of scenario column to be created}
}
\value{
a data frame with scenario values in \code{value_col} with a \code{scenario} column.
}
\description{
\code{scenario_dip_recover()} creates a scenario where there is a rapid
return to the previous situation after a dip. The same annual rate of change (AROC) as
before dip is applied from the \code{recovery_year}.
}
\details{
\code{scenario_dip_recover_iso3()} applies \code{scenario_dip_recover()} to a specific iso3.

\code{scenario_dip_recover_iso3_ind()} applies \code{scenario_dip_recover()} to a specific \code{ind} and \code{iso3} combination.

Two types of AROC are supported:
\itemize{
\item \code{lastest_year}: the AROC is calculated the values between the \code{start_year} and the last \code{reported} or
\code{estimated} value before \code{dip_year} is applied to the last reported value to
\code{recovery_year} onward.
\item \code{average_years_in_range}: all AROC between the \code{aroc_start_year} and the last \code{reported} or
\code{estimated} value before \code{dip_year} are calculated. The average AROC for that period is then
applied to the last reported value to \code{recovery_year} onward.
}

If there are missing values between \code{dip_year} and
\code{recovery_year}, the last value from \code{dip_year} is carried forward. This
applies only to countries where the indicator value for \code{dip_year} is
\code{reported} or \code{estimated}. Otherwise, the value is carried with
\code{scenario_bau}.

If \code{progressive_recovery} is TRUE, then the recovery is
spread between the years between \code{recovery_year} and \code{end_year}. For
instance, if \code{recovery_year} is 2021 and \code{end_year} 2025, then 2021 will have 0\%
of AROC, 2022 25\%, 2023 50\%, 2024 75\%, and 2025 100\%.
}
\seealso{
COVID scenarios
\code{\link{scenario_covid_delayed_return}()},
\code{\link{scenario_covid_never_return}()},
\code{\link{scenario_covid_rapid_return}()},
\code{\link{scenario_covid_sustained_disruption}()},
\code{\link{scenario_return_previous_trajectory}()}
}
\concept{scenario_covid}
\keyword{internal}
