% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot.R
\name{plot_spatial_actions}
\alias{plot_spatial_actions}
\title{Plot selected actions in space}
\usage{
plot_spatial_actions(
  x,
  runs = NULL,
  actions = NULL,
  layout = NULL,
  max_facets = 4L,
  ...,
  base_alpha = 0.08,
  selected_alpha = 0.95,
  base_fill = "grey95",
  base_color = NA,
  selected_color = NA,
  draw_borders = FALSE,
  show_base = TRUE,
  fill_values = NULL,
  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{actions}{Optional action subset to display. Entries may match action
ids or action-set labels.}

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

\item{max_facets}{Maximum number of action facets shown when \code{actions}
is \code{NULL} and faceting would otherwise create many panels.}

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

\item{base_alpha}{Numeric value in \eqn{[0,1]} giving the alpha of the base
planning-unit layer.}

\item{selected_alpha}{Numeric value in \eqn{[0,1]} giving the alpha of the
highlighted action layer.}

\item{base_fill}{Fill colour for the base planning-unit layer.}

\item{base_color}{Border colour for the base planning-unit layer.}

\item{selected_color}{Border colour for highlighted layers.}

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

\item{show_base}{Logical. If \code{TRUE}, draw the base planning-unit layer
underneath the highlighted output.}

\item{fill_values}{Optional named vector of colours for discrete action maps.}

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

\item{use_viridis}{Logical. If \code{TRUE} and the \pkg{viridis} package is
available, use viridis discrete scales.}
}
\value{
Invisibly returns a \code{ggplot} object.
}
\description{
Plot the spatial distribution of selected actions from a
\code{Solution} or \code{SolutionSet}.

This function maps the selected planning unit--action pairs returned by
\code{\link{get_actions}(only_selected = TRUE)} onto the planning-unit
geometry stored in the associated \code{Problem} object.
}
\details{
Let \eqn{x_{ia} \in \{0,1\}} denote whether action \eqn{a} is selected in
planning unit \eqn{i}. This function plots the selected
\code{(pu, action)} pairs in geographic space.

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

If \code{layout = "single"}, all selected actions are drawn in a single map
using discrete fills. If more than one action is selected in the same
planning unit, the action labels are collapsed using \code{"+"}.

When plotting multiple runs, only \code{layout = "single"} is supported.

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")

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

  problem <- structure(
    list(
      data = list(
        pu_sf = sim_pu_sf,
        actions = actions_df
      )
    ),
    class = "Problem"
  )

  ids <- sim_pu_sf$id[seq_len(min(6, nrow(sim_pu_sf)))]
  sol <- structure(
    list(
      problem = problem,
      summary = list(
        actions = data.frame(
          pu = c(ids[1:3], ids[4:6]),
          action = c(rep("conservation", 3), rep("restoration", 3)),
          selected = 1L
        )
      )
    ),
    class = "Solution"
  )

  plot_spatial_actions(sol, layout = "facet")
}

}
\seealso{
\code{\link{get_actions}},
\code{\link{plot_spatial}},
\code{\link{plot_spatial_pu}},
\code{\link{plot_spatial_features}}
}
