create_problem: Create a planning problem input object
In multiscape: Multi-Action, Multi-Objective Spatial Planning

create_problem

R Documentation

Create a planning problem input object

Description

Create a Problem object from tabular or spatial inputs.

create_problem() is the main entry point to the 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 Problem object with a canonical tabular core, optionally enriched with aligned spatial metadata such as coordinates, geometry, raster references, or raw planning-unit attributes.

Usage

create_problem(
  pu,
  features,
  dist_features,
  cost = NULL,
  pu_id_col = "id",
  cost_aggregation = c("mean", "sum"),
  ...
)

## S4 method for signature 'data.frame,data.frame,data.frame'
create_problem(
  pu,
  features,
  dist_features,
  cost = NULL,
  pu_id_col = "id",
  cost_aggregation = c("mean", "sum"),
  ...
)

## S4 method for signature 'ANY,ANY,missing'
create_problem(
  pu,
  features,
  dist_features,
  cost = NULL,
  pu_id_col = "id",
  cost_aggregation = c("mean", "sum"),
  ...
)

## S4 method for signature 'ANY,ANY,NULL'
create_problem(
  pu,
  features,
  dist_features,
  cost = NULL,
  pu_id_col = "id",
  cost_aggregation = c("mean", "sum"),
  ...
)

## S4 method for signature 'ANY,data.frame,data.frame'
create_problem(
  pu,
  features,
  dist_features,
  cost = NULL,
  pu_id_col = "id",
  cost_aggregation = c("mean", "sum"),
  ...
)

Arguments

`pu`	Planning-units input. Depending on the selected method, this may be: a `data.frame` with planning-unit information, an `sf` object, a `terra::SpatVector`, a vector file path readable by terra, a `terra::SpatRaster`, or a raster file path.
`features`	Feature input. Depending on the selected workflow, this may be: a `data.frame` with at least an `id` column, a `terra::SpatRaster` with one layer per feature, or a raster file path.
`dist_features`	Feature-distribution input. In tabular and hybrid workflows, this must be a `data.frame` with columns `pu`, `feature`, and `amount`. In spatial modes it may be omitted or set to `NULL`, in which case it is derived automatically.
`cost`	In spatial modes, planning-unit cost information. Depending on the input mode, this may be: a column name in the planning-unit attribute table, a raster object, or a raster file path. In raster-cell mode, `cost` is required and valid planning units are defined only where cost is finite and strictly positive.
`pu_id_col`	Character string giving the name of the planning-unit id column in vector or `sf` inputs. Ignored in purely tabular mode and in raster-cell mode.
`cost_aggregation`	Character string used in vector-PU mode when `cost` is a raster and must be aggregated over polygons. Must be one of `"mean"` or `"sum"`.
`...`	Additional arguments forwarded to internal builders.

Details

Feature amounts describe a user-defined reference scenario, which can be current conditions, a future business-as-usual scenario, or existing management. The term baseline in older interfaces refers to these reference amounts. Action outcomes and reference amounts must share units and, for future scenarios, the same time horizon. The package optimizes supplied effects; it does not estimate causal effects or simulate reference scenarios.

A Problem object created by create_problem() is the basic input structure used throughout downstream 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 add_actions(), add_effects(), add_constraint_targets(), add_spatial_relations(), and solve() operate.

Conceptual role of create_problem()

Regardless of the input workflow, create_problem() aims to produce a consistent internal representation containing at least:

a planning-unit table,
a feature table,
a feature-distribution table.

Internally, the problem is always reduced to a tabular core of the form:

planning units i \in \mathcal{I},
features f \in \mathcal{F},
non-negative baseline amounts a_{if} \ge 0,
and, when available, spatial metadata associated with planning units.

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

Which input mode should I use?

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

Tabular mode. Use this when pu, features, and dist_features are already available as data.frame objects and no spatial derivation is needed. This is the simplest workflow: all problem components are already tabular, so create_problem() only standardizes them into the canonical internal representation.
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, dist_features is derived by aggregating raster values over planning-unit polygons.
Raster-cell fast mode. Use this when both pu and features are rasters and each valid raster cell should become one planning unit. This mode avoids raster-to-polygon conversion, treats NA feature values as zero before building dist_features, keeps only strictly positive amounts in the stored distribution table, and is generally the preferred option for large regular grids.
Hybrid sf + tabular mode. Use this when you already have a curated tabular 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 sf planning-unit object for later spatial operations.

How cost is interpreted across modes

cost handling depends on the selected workflow.

Tabular mode. In purely tabular mode, cost is not used by this generic method. Planning-unit costs are expected to already be present in the pu table supplied to the internal tabular builder.
Vector-PU spatial mode. In vector-PU mode, cost is required and may be either:
- the name of a numeric attribute column in the planning-unit layer,
- or a cost raster to be aggregated over polygons using the cost_aggregation argument.
Raster-cell fast mode. In raster-cell mode, cost must be a single-layer raster aligned with pu and 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 m_i denotes the mask value of cell i and c_i its cost value, then cell i is retained only when the mask is observed and c_i > 0.
Hybrid sf + tabular mode. In hybrid mode, cost must be either:
- the name of a numeric attribute column in the sf layer,
- or omitted if the sf attributes already contain a column literally named cost.

Feature identifiers

Features are internally standardized to an id-based representation. In spatial modes where raster layers are used, one feature is created per raster layer, with:

id = 1, 2, ..., nlyr(features),
name equal to the raster layer name, if available,
otherwise a generated name of the form "feature.1", "feature.2", and so on.

Planning-unit identifiers

In vector and hybrid modes, planning-unit ids are taken from the column named by pu_id_col. If that column is missing and 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.

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 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 create_problem(), typical next steps include adding actions, spatial relations, targets or other constraints, objectives, and then solving the resulting problem.

Value

A Problem object for downstream 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.

Examples

# Load a complete simulated planning problem.
example_data <- load_sim_multiaction()

# Spatial mode: keep planning-unit geometries.
p1 <- create_problem(
  pu = example_data$planning_units,
  features = example_data$features,
  dist_features = example_data$dist_features,
  cost = "cost"
)
print(p1)

# Tabular mode: use the same data without geometry.
p2 <- create_problem(
  pu = sf::st_drop_geometry(example_data$planning_units),
  features = example_data$features,
  dist_features = example_data$dist_features,
  cost = "cost"
)
print(p2)

multiscape documentation built on Oct. 12, 2026, 5:08 p.m.