% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/add_effects.R
\name{add_benefits}
\alias{add_benefits}
\title{Add benefits}
\usage{
add_benefits(
  x,
  benefits = NULL,
  effect_type = c("delta", "after"),
  effect_aggregation = c("sum", "mean")
)
}
\arguments{
\item{x}{A \code{Problem} object created with \code{\link{create_problem}}. It
must already contain feasible actions; run \code{\link{add_actions}} first.}

\item{benefits}{Alias of \code{effects}, kept for backwards compatibility.}

\item{effect_type}{Character string indicating how supplied effect values are
interpreted. Must be one of:
\itemize{
\item \code{"delta"}: values represent signed net changes,
\item \code{"after"}: values represent after-action amounts and are
converted to net changes relative to baseline feature amounts.
}}

\item{effect_aggregation}{Character string giving the aggregation used when
converting raster values to planning-unit level. Must be one of
\code{"sum"} or \code{"mean"}.}
}
\value{
An updated \code{Problem} object containing:
\describe{
\item{\code{dist_effects}}{The canonical filtered effects table, containing
only rows with \code{benefit > 0}.}
\item{\code{dist_benefit}}{A backwards-compatible mirror table containing
only the benefit component.}
}
}
\description{
Convenience wrapper around \code{\link{add_effects}} that keeps only positive
effects, that is, rows with \code{benefit > 0}.

This function is useful when the workflow is focused only on beneficial
consequences of actions and a gain-only wrapper is more convenient than
calling \code{add_effects(..., component = "benefit")} directly.  Internally,
it calls \code{add_effects()} with \code{component = "benefit"}.
The canonical stored result therefore contains only rows whose effect
satisfies \eqn{\mathrm{benefit}_{iaf} > 0}.

For backwards compatibility, a mirror table containing only the benefit
component is also written to \code{x$data$dist_benefit}. The canonical
filtered representation remains the one stored by \code{add_effects()}.
}
\examples{
pu <- data.frame(id = 1:2, cost = c(1, 2))
features <- data.frame(id = 1, name = "sp1")
dist_features <- data.frame(pu = 1:2, feature = 1, amount = c(5, 10))

p <- create_problem(
  pu = pu,
  features = features,
  dist_features = dist_features
)

p <- add_actions(
  p,
  data.frame(id = "restoration")
)

eff <- data.frame(
  pu = c(1, 2),
  action = c("restoration", "restoration"),
  feature = c(1, 1),
  delta = c(2, -1)
)

p <- add_benefits(p, benefits = eff)
p$data$dist_benefit

}
\seealso{
\code{\link{add_effects}},
\code{\link{add_losses}},
\code{\link{add_objective_max_benefit}}
}
