Kernel Density Plots for Climate-Smart Spatial Plans

splnr_plot_climKernelDensity() generates kernel density plots for a single climate-smart spatial plan, offering two distinct plotting styles: "Normal" (for publication-quality visualisation) and "Basic" (for simplified visualisation for stakeholders).

Usage

splnr_plot_climKernelDensity(
  soln,
  solution_name = "solution_1",
  climate_name = "metric",
  type = "Normal",
  colorMap = "C",
  legendTitle = expression(" °C y"^"-1" * ""),
  xAxisLab = expression("Climate warming ( °C y"^"-1" * ")"),
  base_size = 14
)

Arguments

soln

A single prioritizr solution object (sf or data.frame). For type = "Normal": must contain the columns named by solution_name and climate_name. For type = "Basic": must be an sf object with solution_1 and metric columns.

solution_name

A scalar character string naming the solution column (0/1 or logical) in soln. Used only for type = "Normal". Defaults to "solution_1".

climate_name

A scalar character string naming the climate metric column (numeric) in soln. Used only for type = "Normal". Defaults to "metric".

type

A character string specifying the plotting style. Must be either "Normal" or "Basic". Defaults to "Normal".

colorMap

A character string indicating the viridis color map to use (e.g., "A", "B", "C", "D", "E"). See https://ggplot2.tidyverse.org/reference/scale_viridis.html for all options. Defaults to "C".

legendTitle

A character string or expression for the title of the viridis colour bar legend. Defaults to expression(" \u00B0C y"^"-1" * ""), representing "°C year⁻¹".

xAxisLab

A character string or expression for the x-axis label. Defaults to expression("Climate warming ( \u00B0C y"^"-1" * ")").

base_size

A numeric value for the base font size (in points) passed to ggplot2::theme_bw(). All text elements scale proportionally from this value. Defaults to 14.

Value

A ggplot object representing the kernel density plot.

Details

This wrapper function dispatches to either splnr_plot_climKernelDensity_Fancy() (for type = "Normal") or splnr_plot_climKernelDensity_Basic() (for type = "Basic") based on the type parameter.

The "Normal" style produces a ridge plot with a viridis gradient fill for selected planning units, a grey dotted ridge for unselected units, vertical median lines, and a categorical legend. The "Basic" style is streamlined for clarity and quick interpretation.

To compare two solutions side-by-side, call this function once per solution and combine the results with patchwork::wrap_plots().

Examples

if (FALSE) { # \dontrun{
# Assuming 'dat_species_bin' and 'dat_clim' are existing sf objects
# in your package.

# Prepare data for a climate-priority area approach (CPA)
target <- dat_species_bin %>%
  sf::st_drop_geometry() %>%
  colnames() %>%
  data.frame() %>%
  setNames(c("feature")) %>%
  dplyr::mutate(target = 0.3)

CPA <- splnr_climate_priorityAreaApproach(
  features = dat_species_bin,
  metric = dat_clim,
  targets = target,
  direction = -1,
  refugiaTarget = 1
)

out_sf <- CPA$Features %>%
  dplyr::mutate(Cost_None = 1, .row_id = dplyr::row_number()) %>%
  dplyr::left_join(
    dat_clim %>%
      sf::st_drop_geometry() %>%
      dplyr::mutate(.row_id = dplyr::row_number()),
    by = ".row_id"
  ) %>%
  dplyr::select(-".row_id")

# Define features for the prioritizr problem
usedFeatures <- out_sf %>%
  sf::st_drop_geometry() %>%
  dplyr::select(-tidyselect::starts_with("Cost_"), -"metric") %>%
  names()

# Create and solve a prioritizr problem
p1 <- prioritizr::problem(out_sf, usedFeatures, "Cost_None") %>%
  prioritizr::add_min_set_objective() %>%
  prioritizr::add_relative_targets(CPA$Targets$target) %>%
  prioritizr::add_binary_decisions() %>%
  prioritizr::add_default_solver(verbose = FALSE)

dat_solnClim <- prioritizr::solve.ConservationProblem(p1)

# Example 1: Basic kernel density plot
plot_basic_kde <- splnr_plot_climKernelDensity(soln = dat_solnClim, type = "Basic")
print(plot_basic_kde)

# Example 2: Normal (Fancy) kernel density plot
plot_normal_kde <- splnr_plot_climKernelDensity(
  soln = dat_solnClim,
  type = "Normal"
)
print(plot_normal_kde)

# Example 3: Compare two solutions side-by-side using patchwork
dat_solnClim_2 <- dat_solnClim %>%
  dplyr::mutate(solution_1 = sample(c(0L, 1L), dplyr::n(), replace = TRUE))

plot_compare <- patchwork::wrap_plots(
  splnr_plot_climKernelDensity(
    soln = dat_solnClim, type = "Normal",
    legendTitle = "Scenario 1", xAxisLab = "Climate metric"
  ),
  splnr_plot_climKernelDensity(
    soln = dat_solnClim_2, type = "Normal",
    legendTitle = "Scenario 2", xAxisLab = "Climate metric"
  ),
  ncol = 1
)
print(plot_compare)

# Example 4: Custom colour map and labels
plot_custom <- splnr_plot_climKernelDensity(
  soln = dat_solnClim,
  type = "Normal",
  colorMap = "plasma",
  legendTitle = "Climate Value",
  xAxisLab = "Climate Metric (units)"
)
print(plot_custom)
} # }