% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/add_constraint_targets.R
\name{add_constraint_targets_absolute}
\alias{add_constraint_targets_absolute}
\title{Add absolute targets}
\usage{
add_constraint_targets_absolute(
  x,
  targets,
  features = NULL,
  actions = NULL,
  label = NULL
)
}
\arguments{
\item{x}{A \code{Problem} object.}

\item{targets}{Target specification. This is interpreted as an absolute target
value in the same units as the modelled feature contributions. It may be a
scalar, vector, named vector, or \code{data.frame}. See Details.}

\item{features}{Optional feature specification indicating which features the
supplied target values refer to when \code{targets} does not identify
features explicitly. If \code{NULL}, all features are targeted.}

\item{actions}{Optional character vector indicating which actions count toward
target achievement. Entries may match action ids, \code{action_set} labels,
or both. If \code{NULL}, all actions count.}

\item{label}{Optional character string stored with the targets for reporting
and bookkeeping.}
}
\value{
An updated \code{Problem} object with absolute targets appended to
the stored target table.
}
\description{
Add feature-level absolute targets to a planning problem.

These targets are stored in the problem object and later translated into
linear constraints when the optimization model is built. Absolute targets
are interpreted directly in the same units as the feature
contributions used by the model. Each call appends one or more target definitions to the problem. This makes
it possible to combine multiple target rules, including targets associated
with different action subsets.
}
\details{
Use this function when target requirements are naturally expressed in the
original units of the modelled feature contributions, rather than as
proportions of current baseline totals.

Let \eqn{\mathcal{F}} denote the set of features. For each targeted feature
\eqn{f \in \mathcal{F}}, this function stores an absolute target threshold
\eqn{T_f \ge 0}.

When the optimization model is built, each such target is interpreted as a
lower-bound constraint of the form:
\deqn{
\sum_{(i,a) \in \mathcal{D}_f^{\star}} c_{iaf} x_{ia} \ge T_f,
}
where:
\itemize{
\item \eqn{i \in \mathcal{I}} indexes planning units,
\item \eqn{a \in \mathcal{A}} indexes actions,
\item \eqn{x_{ia}} indicates whether action \eqn{a} is selected in planning
unit \eqn{i},
\item \eqn{c_{iaf}} is the contribution of that action to feature
\eqn{f},
\item \eqn{\mathcal{D}_f^{\star}} is the subset of planning unit--action
pairs allowed to count toward the target for feature \eqn{f}.
}

In the absolute case, the stored target threshold is simply:
\deqn{
T_f = t_f,
}
where \eqn{t_f} is the user-supplied target value for feature \eqn{f}.

The \code{actions} argument restricts which actions may contribute toward
achievement of the target, but it does not modify the value of \eqn{T_f}
itself.

The \code{targets} argument is parsed by \code{.pa_parse_targets()} and may be
supplied in several equivalent forms, including:
\itemize{
\item a single numeric value recycled to all selected features,
\item a numeric vector aligned to \code{features},
\item a named numeric vector where names identify features,
\item a \code{data.frame} with \code{feature} and \code{target} columns.
}

If \code{targets} does not explicitly identify features:
\itemize{
\item if \code{features = NULL}, the target is applied to all features,
\item if \code{features} is supplied, the target values are interpreted with
respect to that feature set.
}

Repeated calls append new target rules rather than replacing previous ones.
This allows cumulative target modelling, including multiple rules on the same
feature with different contributing action subsets.
}
\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)
)

p <- create_problem(
  pu = pu_tbl,
  features = feat_tbl,
  dist_features = dist_feat_tbl,
  cost = "cost"
) |>
  add_actions(data.frame(id = "conservation", name = "conservation"), cost = 0)

# Same absolute target for all features
p1 <- add_constraint_targets_absolute(p, 3)
p1$data$targets

# Different targets by feature
p2 <- add_constraint_targets_absolute(
  p,
  c("1" = 4, "2" = 2)
)
p2$data$targets

# Restrict which actions count toward target achievement
p3 <- add_constraint_targets_absolute(
  p,
  2,
  actions = "conservation"
)
p3$data$targets

}
\seealso{
\code{\link{add_constraint_targets_relative}}
}
