% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot.R
\name{plot_spatial_features}
\alias{plot_spatial_features}
\title{Plot spatial feature values from a solution}
\usage{
plot_spatial_features(
  x,
  runs = NULL,
  features = NULL,
  value = c("final", "baseline", "benefit"),
  layout = NULL,
  max_facets = 4L,
  ...,
  base_alpha = 0.1,
  selected_alpha = 0.9,
  base_fill = "grey92",
  base_color = NA,
  selected_color = NA,
  draw_borders = FALSE,
  show_base = TRUE,
  fill_na = "grey80",
  use_viridis = TRUE
)
}
\arguments{
\item{x}{A \code{Solution} or \code{SolutionSet} object.}

\item{runs}{Optional integer vector of run ids. If \code{NULL}, a
\code{Solution} is used directly and a \code{SolutionSet} defaults to the
first run.}

\item{features}{Optional feature subset to display. Matching is attempted
against both feature ids and feature names.}

\item{value}{Character string indicating which feature quantity to plot. Must
be one of \code{"final"}, \code{"baseline"}, or \code{"benefit"}.}

\item{layout}{Character string controlling the layout. Must be one of
\code{"single"} or \code{"facet"}. If \code{NULL}, the default is
\code{"facet"}.}

\item{max_facets}{Maximum number of feature facets shown when
\code{features = NULL} and faceting would otherwise create many panels.}

\item{...}{Reserved for future extensions.}

\item{base_alpha}{Unused in the current feature view, kept for interface
consistency.}

\item{selected_alpha}{Unused in the current feature view, kept for interface
consistency.}

\item{base_fill}{Unused in the current feature view, kept for interface
consistency.}

\item{base_color}{Unused in the current feature view, kept for interface
consistency.}

\item{selected_color}{Border colour for filled feature polygons.}

\item{draw_borders}{Logical. If \code{FALSE}, borders are not drawn.}

\item{show_base}{Unused in the current feature view, kept for interface
consistency.}

\item{fill_na}{Fill colour for missing values.}

\item{use_viridis}{Logical. If \code{TRUE} and the \pkg{viridis} package is
available, use a continuous viridis scale.}
}
\value{
Invisibly returns a \code{ggplot} object.
}
\description{
Plot feature values in space from a \code{Solution} or \code{SolutionSet}.

This function combines baseline feature amounts from
\code{x$problem$data$dist_features} with positive effects induced by selected
actions to produce planning-unit-level feature maps.
}
\details{
For each planning unit \eqn{i} and feature \eqn{f}, the plotted quantities
are:
\deqn{
\mathrm{baseline}_{if},
}
\deqn{
\mathrm{benefit}_{if},
}
\deqn{
\mathrm{final}_{if} = \mathrm{baseline}_{if} + \mathrm{benefit}_{if}.
}

In the current implementation:
\itemize{
\item \code{baseline} is the summed baseline amount from
\code{x$problem$data$dist_features},
\item \code{benefit} is the summed positive effect from selected actions,
\item \code{final} is \code{baseline + benefit}.
}

Negative effects are not subtracted in this plotting method. Therefore,
\code{value = "final"} should be interpreted as baseline plus selected
positive effects under the current plotting logic.

If \code{layout = "facet"} and only one run is plotted, one panel is drawn
per feature.

If multiple runs are plotted, exactly one feature must be requested, and
faceting is done by run.

Planning-unit geometry must be available in \code{x$problem$data$pu_sf}.
}
\examples{
if (requireNamespace("sf", quietly = TRUE) &&
    requireNamespace("ggplot2", quietly = TRUE)) {
  data("sim_pu_sf", package = "multiscape")

  n <- min(6, nrow(sim_pu_sf))
  ids <- sim_pu_sf$id[seq_len(n)]

  features_df <- data.frame(
    id = c(1, 2),
    name = c("feature_1", "feature_2")
  )

  dist_features_df <- data.frame(
    pu = rep(ids, times = 2),
    feature = rep(c(1, 2), each = n),
    amount = c(seq_len(n), rev(seq_len(n)))
  )

  dist_effects_df <- data.frame(
    pu = ids,
    action = "conservation",
    feature = rep(c(1, 2), length.out = n),
    benefit = rep(1, n)
  )

  actions_df <- data.frame(
    id = "conservation",
    name = "conservation"
  )

  problem <- structure(
    list(
      data = list(
        pu_sf = sim_pu_sf,
        features = features_df,
        dist_features = dist_features_df,
        dist_effects = dist_effects_df,
        actions = actions_df
      )
    ),
    class = "Problem"
  )

  sol <- structure(
    list(
      problem = problem,
      summary = list(
        actions = data.frame(
          pu = ids,
          action = "conservation",
          selected = 1L
        )
      )
    ),
    class = "Solution"
  )

  plot_spatial_features(sol, features = "feature_1", value = "final")
}

}
\seealso{
\code{\link{get_features}},
\code{\link{plot_spatial}},
\code{\link{plot_spatial_pu}},
\code{\link{plot_spatial_actions}}
}
