% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/create_problem.R
\name{create_problem}
\alias{create_problem}
\alias{create_problem,data.frame,data.frame,data.frame-method}
\alias{create_problem,ANY,ANY,missing-method}
\alias{create_problem,ANY,ANY,NULL-method}
\alias{create_problem,ANY,data.frame,data.frame-method}
\title{Create a planning problem input object}
\usage{
create_problem(
  pu,
  features,
  dist_features,
  cost = NULL,
  pu_id_col = "id",
  cost_aggregation = c("mean", "sum"),
  ...
)

\S4method{create_problem}{data.frame,data.frame,data.frame}(
  pu,
  features,
  dist_features,
  cost = NULL,
  pu_id_col = "id",
  cost_aggregation = c("mean", "sum"),
  ...
)

\S4method{create_problem}{ANY,ANY,missing}(
  pu,
  features,
  dist_features,
  cost = NULL,
  pu_id_col = "id",
  cost_aggregation = c("mean", "sum"),
  ...
)

\S4method{create_problem}{ANY,ANY,NULL}(
  pu,
  features,
  dist_features,
  cost = NULL,
  pu_id_col = "id",
  cost_aggregation = c("mean", "sum"),
  ...
)

\S4method{create_problem}{ANY,data.frame,data.frame}(
  pu,
  features,
  dist_features,
  cost = NULL,
  pu_id_col = "id",
  cost_aggregation = c("mean", "sum"),
  ...
)
}
\arguments{
\item{pu}{Planning-units input. Depending on the selected method, this may be:
\itemize{
\item a \code{data.frame} with planning-unit information,
\item an \code{sf} object,
\item a \code{terra::SpatVector},
\item a vector file path readable by \pkg{terra},
\item a \code{terra::SpatRaster},
\item or a raster file path.
}}

\item{features}{Feature input. Depending on the selected workflow, this may be:
\itemize{
\item a \code{data.frame} with at least an \code{id} column,
\item a \code{terra::SpatRaster} with one layer per feature,
\item or a raster file path.
}}

\item{dist_features}{Feature-distribution input. In tabular and hybrid
workflows, this must be a \code{data.frame} with columns \code{pu},
\code{feature}, and \code{amount}. In spatial modes it may be omitted or
set to \code{NULL}, in which case it is derived automatically.}

\item{cost}{In spatial modes, planning-unit cost information. Depending on the
input mode, this may be:
\itemize{
\item a column name in the planning-unit attribute table,
\item a raster object,
\item or a raster file path.
}
In raster-cell mode, \code{cost} is required and valid planning units are
defined only where cost is finite and strictly positive.}

\item{pu_id_col}{Character string giving the name of the planning-unit id
column in vector or \code{sf} inputs. Ignored in purely tabular mode and in
raster-cell mode.}

\item{cost_aggregation}{Character string used in vector-PU mode when
\code{cost} is a raster and must be aggregated over polygons. Must be one
of \code{"mean"} or \code{"sum"}.}

\item{...}{Additional arguments forwarded to internal builders.}
}
\value{
A \code{Problem} object for downstream \code{multiscape} workflows.
The returned object always contains a canonical tabular core with planning
units, features, and feature-distribution data, and may additionally
contain aligned spatial metadata depending on the input mode.
}
\description{
Create a \code{Problem} object from tabular or spatial inputs.

\code{create_problem()} is the main entry point to the \code{multiscape}
workflow. Its role is to standardize heterogeneous planning inputs into a
common internal representation that can later be used by actions, effects,
targets, constraints, spatial relations, objectives, and solvers.

In all supported workflows, the result is a \code{Problem} object with a
canonical tabular core, optionally enriched with aligned spatial metadata
such as coordinates, geometry, raster references, or raw planning-unit
attributes.
}
\details{
A \code{Problem} object created by \code{create_problem()} is the basic input
structure used throughout downstream \code{multiscape} workflows.

The returned object always contains a canonical tabular planning core and may
additionally store aligned spatial metadata depending on the input workflow.
This is the internal representation on which later functions such as
\code{add_actions()}, \code{add_effects()},
\code{add_constraint_targets()}, \code{add_spatial_relations()}, and
\code{solve()} operate.

\strong{Conceptual role of \code{create_problem()}}

Regardless of the input workflow, \code{create_problem()} aims to produce a
consistent internal representation containing at least:
\itemize{
\item a planning-unit table,
\item a feature table,
\item a feature-distribution table.
}

Internally, the problem is always reduced to a tabular core of the form:
\itemize{
\item planning units \eqn{i \in \mathcal{I}},
\item features \eqn{f \in \mathcal{F}},
\item non-negative baseline amounts \eqn{a_{if} \ge 0},
\item and, when available, spatial metadata associated with planning units.
}

The feature-distribution table provides the canonical sparse representation of
these baseline amounts. Thus, after \code{create_problem()} has run, the
landscape is internally represented by baseline feature amounts
\eqn{a_{if}}, where \eqn{a_{if}} denotes the amount of feature \eqn{f} in
planning unit \eqn{i}. These baseline amounts are later combined with
actions, effects, targets, objectives, and constraints to build the
optimization model.

\strong{Which input mode should I use?}

\code{create_problem()} supports four main workflows. The best choice depends
on the form of your data and on whether you want to preserve geometry.

\itemize{
\item \strong{Tabular mode.} Use this when \code{pu}, \code{features}, and
\code{dist_features} are already available as \code{data.frame} objects and
no spatial derivation is needed. This is the simplest workflow: all problem
components are already tabular, so \code{create_problem()} only
standardizes them into the canonical internal representation.

\item \strong{Vector-PU spatial mode.} Use this when planning units are
polygons and feature information is stored in one or more raster layers. In
this mode, \code{dist_features} is derived by aggregating raster values
over planning-unit polygons.

\item \strong{Raster-cell fast mode.} Use this when both \code{pu} and
\code{features} are rasters and each valid raster cell should become one
planning unit. This mode avoids raster-to-polygon conversion, treats
\code{NA} feature values as zero before building \code{dist_features},
keeps only strictly positive amounts in the stored distribution table, and
is generally the preferred option for large regular grids.

\item \strong{Hybrid sf + tabular mode.} Use this when you already have a
curated tabular \code{dist_features} table but still want to preserve
planning-unit geometry and attributes for later plotting, spatial
relations, or feasibility specifications. Here, the feature distribution is
already tabular, but geometry and raw attributes are preserved from the
\code{sf} planning-unit object for later spatial operations.
}

\strong{How cost is interpreted across modes}

\code{cost} handling depends on the selected workflow.

\itemize{
\item \strong{Tabular mode.} In purely tabular mode, \code{cost} is not
used by this generic method. Planning-unit costs are expected to already be
present in the \code{pu} table supplied to the internal tabular builder.

\item \strong{Vector-PU spatial mode.} In vector-PU mode, \code{cost} is
required and may be either:
\itemize{
\item the name of a numeric attribute column in the planning-unit layer,
\item or a cost raster to be aggregated over polygons using the
\code{cost_aggregation} argument.
}

\item \strong{Raster-cell fast mode.} In raster-cell mode, \code{cost}
must be a single-layer raster aligned with \code{pu} and \code{features}.
A raster cell becomes a planning unit only if the mask cell is not missing
and the corresponding cost value is finite and strictly positive. In other
words, if \eqn{m_i} denotes the mask value of cell \eqn{i} and \eqn{c_i}
its cost value, then cell \eqn{i} is retained only when the mask is
observed and \eqn{c_i > 0}.

\item \strong{Hybrid sf + tabular mode.} In hybrid mode, \code{cost} must
be either:
\itemize{
\item the name of a numeric attribute column in the \code{sf} layer,
\item or omitted if the \code{sf} attributes already contain a column
literally named \code{cost}.
}
}

\strong{Feature identifiers}

Features are internally standardized to an \code{id}-based representation.
In spatial modes where raster layers are used, one feature is created per
raster layer, with:
\itemize{
\item \code{id = 1, 2, \dots, nlyr(features)},
\item \code{name} equal to the raster layer name, if available,
\item otherwise a generated name of the form \code{"feature.1"},
\code{"feature.2"}, and so on.
}

\strong{Planning-unit identifiers}

In vector and hybrid modes, planning-unit ids are taken from the column named
by \code{pu_id_col}. If that column is missing and \code{pu_id_col = "id"},
sequential ids are created with a warning.

In raster-cell mode, planning-unit ids are always created sequentially from
the valid raster cells retained after masking and cost filtering.

\strong{Ordering and alignment}

In spatial modes, planning units, derived coordinates, raw attributes,
geometry, and extracted feature amounts are aligned to the same planning-unit
id order before the final \code{Problem} object is created.

This alignment is critical because later functions assume that all stored
planning-unit components refer to the same ordered set of planning units.

After \code{create_problem()}, typical next steps include adding actions,
spatial relations, targets or other constraints, objectives, and then solving
the resulting problem.
}
\examples{
# ------------------------------------------------------
# 1) Tabular mode
# ------------------------------------------------------
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)
)

p1 <- create_problem(
  pu = pu_tbl,
  features = feat_tbl,
  dist_features = dist_feat_tbl
)

print(p1)

# ------------------------------------------------------
# 2) Hybrid sf + tabular mode using package data
# ------------------------------------------------------

p2 <- create_problem(
  pu = sim_pu,
  features = sim_features,
  dist_features = sim_dist_features,
  cost = "cost"
)

print(p2)

}
\seealso{
\code{\link{add_actions}},
\code{\link{add_constraint_locked_pu}},
\code{\link{add_spatial_boundary}},
\code{\link{add_spatial_knn}},
\code{\link{solve}}
}
