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

\item{targets}{Target specification as proportions in \eqn{[0,1]}. 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 relative targets appended to
the stored target table.
}
\description{
Add feature-level relative 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. Relative targets are
supplied as proportions in \eqn{[0,1]} and are converted internally into
absolute thresholds using the current total amount of each
feature in the landscape.

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 as
proportions of current baseline feature totals rather than in original
feature units.

Let \eqn{\mathcal{F}} denote the set of features. For each targeted feature
\eqn{f \in \mathcal{F}}, let \eqn{B_f} denote the current baseline total
amount of that feature in the landscape, as computed by
\code{.pa_feature_totals()}.

If the user supplies a relative target \eqn{r_f \in [0,1]}, then this
function converts it to an absolute threshold:
\deqn{
T_f = r_f \times B_f.
}

The absolute threshold \eqn{T_f} is stored in \code{target_value}, while:
\itemize{
\item the original user-supplied proportion \eqn{r_f} is stored in
\code{target_raw},
\item the baseline total \eqn{B_f} is stored in \code{basis_total}.
}

When the optimization model is built, the resulting target is interpreted as:
\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}.
}

The \code{actions} argument restricts which actions may contribute toward
target achievement, but it does not affect the baseline amount \eqn{B_f} used
to compute the threshold. In other words, relative targets are always scaled
against the current full landscape baseline.

Therefore, \code{actions} changes who may satisfy the target, but not how the
threshold itself is scaled.

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

Relative targets must lie in \eqn{[0,1]}.

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)

# Require 30\% of the baseline total for all features
p1 <- add_constraint_targets_relative(p, 0.3)
p1$data$targets

# Require 20\% for one selected feature
p2 <- add_constraint_targets_relative(
  p,
  0.2,
  features = 1
)
p2$data$targets

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

}
\seealso{
\code{\link{add_constraint_targets_absolute}}
}
