% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/add_spatial_relations.R
\name{add_spatial_relations}
\alias{add_spatial_relations}
\title{Add spatial relations}
\usage{
add_spatial_relations(x, relations, name, directed = FALSE, allow_self = FALSE)
}
\arguments{
\item{x}{A \code{Problem} object created with \code{\link{create_problem}}.}

\item{relations}{A \code{data.frame} describing relation edges. It must
contain either:
\itemize{
\item \code{pu1}, \code{pu2}, and \code{weight}, using external
planning-unit ids, or
\item \code{internal_pu1}, \code{internal_pu2}, and \code{weight}, using
internal planning-unit indices.
}
Extra columns such as \code{distance} or \code{source} are allowed and are
preserved when possible.}

\item{name}{Character string giving the key under which the relation is
stored.}

\item{directed}{Logical. If \code{FALSE}, treat edges as undirected and
collapse duplicate unordered pairs. If \code{TRUE}, keep edges as directed
ordered pairs.}

\item{allow_self}{Logical. If \code{TRUE}, allow self-edges
\eqn{(i,i)}. Default is \code{FALSE}.}
}
\value{
An updated \code{Problem} object with the relation stored in
\code{x$data$spatial_relations[[name]]}.
}
\description{
Register an externally computed spatial relation inside a \code{Problem}
object using the unified internal representation adopted by \code{multiscape}.

Most users will typically prefer one of the convenience constructors such as
\code{\link{add_spatial_boundary}}, \code{\link{add_spatial_rook}},
\code{\link{add_spatial_queen}}, \code{\link{add_spatial_knn}}, or
\code{\link{add_spatial_distance}}. This function is the advanced low-level
entry point for adding an already computed relation.
}
\details{
Use this function when the spatial relation has already been computed
externally and should be registered directly in the \code{Problem} object.

The input relation may be provided either in terms of external planning-unit
identifiers or in terms of internal planning-unit indices.

Specifically, the input \code{relations} table must contain either:
\itemize{
\item \code{pu1}, \code{pu2}, and \code{weight}, or
\item \code{internal_pu1}, \code{internal_pu2}, and \code{weight}.
}

If external ids are supplied, they are mapped to internal indices using the
planning-unit identifiers stored in the problem.

Let \eqn{G = (\mathcal{I}, E, \omega)} denote the supplied relation, where
\eqn{E} corresponds to the rows of \code{relations}. If
\code{directed = FALSE}, each edge is treated as undirected, so pairs
\eqn{(i,j)} and \eqn{(j,i)} are interpreted as the same edge. In that case,
duplicated undirected edges are collapsed automatically using the maximum
weight observed for each unordered pair.

If \code{directed = TRUE}, edges are preserved as ordered pairs, so
\eqn{(i,j)} and \eqn{(j,i)} are distinct unless the user provides both.

Self-edges \eqn{(i,i)} are permitted only if \code{allow_self = TRUE}.

The final relation is stored in \code{x$data$spatial_relations[[name]]}.

If a relation with the same \code{name} already exists, it is replaced.
}
\examples{
pu <- data.frame(id = 1:3, cost = c(1, 2, 3))

features <- data.frame(
  id = 1,
  name = "sp1"
)

dist_features <- data.frame(
  pu = 1:3,
  feature = 1,
  amount = c(1, 1, 1)
)

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

rel <- data.frame(
  pu1 = c(1, 1, 2),
  pu2 = c(2, 3, 3),
  weight = c(1, 1, 2)
)

p <- add_spatial_relations(
  x = p,
  relations = rel,
  name = "my_relation"
)

p$data$spatial_relations$my_relation

}
\seealso{
\code{\link{add_spatial_boundary}},
\code{\link{add_spatial_rook}},
\code{\link{add_spatial_queen}},
\code{\link{add_spatial_knn}},
\code{\link{add_spatial_distance}}
}
