% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/add_objectives.R
\name{add_objective_min_loss}
\alias{add_objective_min_loss}
\title{Add objective: minimize loss}
\usage{
add_objective_min_loss(x, actions = NULL, features = NULL, alias = NULL)
}
\arguments{
\item{x}{A \code{Problem} object.}

\item{actions}{Optional subset of actions to include in the objective. Values
may match \code{x$data$actions$id} and, if present,
\code{x$data$actions$action_set}. If \code{NULL}, all actions are included.}

\item{features}{Optional subset of features to include in the objective.
Values may match \code{x$data$features$id} and, if present,
\code{x$data$features$name}. If \code{NULL}, all features are included.}

\item{alias}{Optional identifier used to register this objective for
multi-objective workflows.}
}
\value{
An updated \code{Problem} object.
}
\description{
Define an objective that minimizes the total negative effects generated by
selected actions on selected features.

This objective is based on the canonical effects table and uses only the
non-negative \code{loss} component.
}
\details{
Use this function when harmful ecological effects should be minimized
explicitly, without offsetting them against beneficial effects.

Let \eqn{\ell_{iaf} \ge 0} denote the stored loss associated with planning
unit \eqn{i}, action \eqn{a}, and feature \eqn{f}.

If no subsets are supplied, the objective can be written as:

\deqn{
\min \sum_{(i,a,f) \in \mathcal{R}} \ell_{iaf} \, x_{ia}.
}

where \eqn{\mathcal{R}} denotes the set of stored loss rows and
\eqn{x_{ia} \in \{0,1\}} indicates whether action \eqn{a} is selected in
planning unit \eqn{i}.

If \code{actions} is provided, only rows whose action belongs to the selected
subset contribute to the objective.

If \code{features} is provided, only rows whose feature belongs to the
selected subset contribute to the objective.

More generally, letting \eqn{\mathcal{R}^{\star}} be the subset induced by
the selected actions and features, the objective is:

\deqn{
\min \sum_{(i,a,f) \in \mathcal{R}^{\star}} \ell_{iaf} \, x_{ia}.
}

This objective minimizes harmful effects only. It does not offset losses
against benefits unless benefits are handled elsewhere through additional
objectives or constraints.
}
\examples{
pu_tbl <- data.frame(
  id = 1:4,
  cost = c(1, 2, 3, 4)
)
feat_tbl <- data.frame(
  id = 1:2,
  name = c("feature_1", "feature_2")
)
dist_feat_tbl <- data.frame(
  pu = c(1, 1, 2, 3, 4),
  feature = c(1, 2, 2, 1, 2),
  amount = c(5, 2, 3, 4, 1)
)
actions_df <- data.frame(
  id = c("conservation", "restoration"),
  name = c("conservation", "restoration")
)
effects_df <- data.frame(
  pu = c(1, 2, 3, 4, 1, 2, 3, 4),
  action = c("conservation", "conservation", "conservation", "conservation",
             "restoration", "restoration", "restoration", "restoration"),
  feature = c(1, 1, 1, 1, 2, 2, 2, 2),
  benefit = c(2, 1, 0, 1, 3, 0, 1, 2),
  loss = c(0, 0, 1, 0, 0, 1, 0, 0)
)

p <- create_problem(
  pu = pu_tbl,
  features = feat_tbl,
  dist_features = dist_feat_tbl,
  cost = "cost"
) |>
  add_actions(actions_df, cost = c(conservation = 1, restoration = 2)) |>
  add_effects(effects_df)

p1 <- add_objective_min_loss(p)
p1$data$model_args

p2 <- add_objective_min_loss(
  p,
  actions = "restoration"
)
p2$data$model_args

p3 <- add_objective_min_loss(
  p,
  features = 1
)
p3$data$model_args

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