+# spatialplanr
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
@@ -24,8 +24,9 @@ knitr::opts_chunk$set(
[](https://github.com/SpatialPlanning/spatialplanr/issues)
-## Overview
-This package is designed to assist students and staff in the [Mathematical Marine Ecology Lab](https://mathmarecol.github.io) at the University of Queensland. It may be useful for others as well. This code has been written to simplify the process for running a _prioritizr_ analysis on a given region use the workflows and data of the MME Lab. It is still a work in progress so feel free to submit pull requests with new features and code improvements.
+
+# Introduction to spatialplanr
+Welcome to _spatialplanr_, an R package designed to streamline and enhance spatial conservation prioritization efforts by explicitly integrating climate change considerations. Building upon the powerful _prioritizr_ package, _spatialplanr_ provides a suite of tools for conservation planners to develop more robust and climate-resilient protected area networks.
## Installation
@@ -35,3 +36,336 @@ Be aware that this package is in the very early stages of development. Functions
# install.packages("devtools")
devtools::install_github("https://github.com/SpatialPlanning/spatialplanr")
```
+
+# Purpose and Goals
+
+The escalating impacts of climate change necessitate a paradigm shift in how we approach conservation. Traditional conservation planning often focuses on static biodiversity patterns, which may not adequately account for the dynamic nature of species distributions and ecosystem processes under a changing climate. _spatialplanr_ aims to address this gap by:
+
+**Facilitating Climate-Smart Planning**: Providing functions that incorporate climate data directly into the planning process, allowing for the identification of areas critical for both biodiversity and resilience to future climate conditions.
+Offering Diverse Methodological Approaches: Implementing multiple established climate-smart conservation planning frameworks (e.g., Climate Priority Areas, Climate Features, Climate Percentiles) to offer flexibility based on specific planning goals and data availability.
+
+**Streamlining Workflow**: Offering end-to-end functionality, from data preprocessing and integration to advanced visualization of results, simplifying complex analytical tasks for users.
+
+**Enhancing Decision-Making**: Producing outputs that directly feed into spatial prioritization software like prioritizr, enabling the generation of optimal conservation solutions that balance biodiversity representation with climate resilience.
+By using spatialplanr, practitioners can move beyond reactive conservation and proactively design protected area systems better equipped to safeguard biodiversity in a rapidly changing world.
+
+# Core Climate-Smart Planning Approaches
+
+_spatialplanr_ implements several key approaches for integrating climate change into spatial prioritization, largely drawing inspiration from frameworks like that presented in Buenafe et al. (2023) "A metric‐based framework for climate‐smart conservation planning" (DOI: 10.1002/eap.2852).
+
+These approaches are designed to transform biodiversity features and conservation targets based on climate metrics, allowing for a more nuanced understanding of how climate change may impact conservation priorities. The main approaches included in _spatialplanr_ are:
+ * **Climate Priority Area (CPA) Approach**: Identifies climate-smart areas within the distribution of each conservation feature, creating new components for climate-smart and non-climate-smart areas.
+ * **Climate Feature Approach**: Treats climate-smart areas as a distinct conservation feature, allowing for explicit conservation targets on climate resilience.
+ * **Climate Percentile Approach**: Sets conservation targets based on percentile ranges of climate metrics, allowing for targeted protection of areas within specific climate resilience thresholds.
+
+# Data Acquisition and Preprocessing Utilities
+_spatialplanr_ also provides convenience functions for acquiring and preparing data, which can be crucial for climate-smart planning.
+
+```{r}
+# Load spatialplanr
+library(spatialplanr)
+library(tidyverse)
+```
+
+1. Get IUCN Red List Data
+Function: `splnr_get_IUCNRedList()`
+
+This function interfaces with the IUCN Red List API to retrieve conservation status information for a list of species. This data can be valuable for assigning species-specific targets (e.g., higher targets for more threatened species) or filtering species based on their conservation status.
+
+Note: Requires an IUCN Red List API token.
+
+```{r}
+# # Example: Fetch IUCN data for a few marine species
+# # Ensure your IUCN Red List API token is set:
+# # Sys.setenv(IUCN_REDLIST_KEY = "YOUR_API_KEY") # Replace with your actual key
+#
+# # Example species list
+# my_species <- c("Orcinus orca", "Chelonia mydas", "Thunnus thynnus")
+#
+# # Create a dataframe matching the expected input format
+# species_df <- data.frame(
+# scientific_name = my_species
+# )
+#
+# # Get IUCN data
+# iucn_data <- splnr_get_IUCNRedList(df = species_df, species_col = "scientific_name")
+# print(iucn_data)
+
+```
+
+2. Get Global Fishing Watch (GFW) Data
+Function: `splnr_get_gfw()`
+
+This function facilitates the retrieval of fishing activity data (e.g., apparent fishing hours) from Global Fishing Watch (GFW). GFW data can be used to inform cost layers (e.g., higher fishing effort areas might have higher opportunity costs for conservation) or as a proxy for human impact in planning units.
+
+Note: Requires a GFW API token.
+
+```{r}
+# Example: Get yearly fishing hours for Australia EEZ
+
+gfw_data_aus <- splnr_get_gfw(
+ region = 'Australia',
+ start_date = "2021-01-01",
+ end_date = "2021-12-31",
+ temp_res = "YEARLY",
+ spat_res = "LOW",
+ region_source = "EEZ",
+ cCRS = "EPSG:4326",
+ compress = TRUE # Returns polygons aggregated by fishing hours
+)
+print(head(gfw_data_aus))
+```
+
+## Visualization Tools
+_spatialplanr_ offers a rich set of plotting functions to visualize input data, climate metrics, and most importantly, the outputs of your spatial prioritization analyses. These functions are built on ggplot2 and sf for high-quality spatial visualizations.
+
+1. Plot Climate Data
+Function: `splnr_plot_climData()`
+
+Visualizes the spatial distribution of your climate metric, allowing you to quickly inspect patterns in climate velocity, temperature anomaly, or other relevant climate variables.
+
+```{r}
+# Assuming 'dat_clim' from previous examples is available
+# Plot the 'metric' column from dat_clim
+splnr_plot_climData(
+ df = dat_clim,
+ colInterest = "metric",
+ plotTitle = "Example Climate Metric Distribution",
+ legendTitle = "Metric Value"
+)
+```
+
+2. Plot Climate Kernel Density
+Functions: `splnr_plot_climKernelDensity_Basic()`, `splnr_plot_climKernelDensity_Fancy()`, `splnr_plot_climKernelDensity()`
+
+These functions help visualize the distribution of climate metric values within selected planning units (e.g., a proposed protected area network) compared to the overall distribution. This helps assess if climate-smart areas are being adequately captured.
+
+`_Basic()`: Simple kernel density plot.
+`_Fancy()`: More customizable kernel density plot, allowing multiple solutions and specific zones.
+`_climKernelDensity()`: A wrapper function that selects between basic and fancy plots based on input type.
+
+```{r}
+solution_df <- dat_clim %>%
+ dplyr::mutate(
+ solution_1 = sample(c(0, 1), size = dplyr::n(), replace = TRUE, prob = c(0.7, 0.3)),
+ metric_category = cut(metric, breaks = 3, labels = c("Low", "Medium", "High"))
+ )
+
+# Basic kernel density plot of the metric for selected areas vs. all areas
+splnr_plot_climKernelDensity(
+ soln = solution_df,
+ type = "Basic",
+ names = "solution_1" # Column indicating selected PUs (1=selected)
+)
+
+# Fancy kernel density plot, perhaps with zones (if your solution has them)
+# For this example, let's pretend 'solution_df' has a 'zone' column
+# (this would come from a prioritizr zoned solution)
+zoned_solution_df <- solution_df %>%
+ dplyr::mutate(
+ zone = sample(c("Zone A", "Zone B"), size = dplyr::n(), replace = TRUE)
+ )
+
+# Example for Fancy (requires a list of solutions or specific structure)
+# If you have multiple prioritizr solutions, you would put them in a list.
+# For simplicity, we'll create a mock 'soln' list:
+soln_list <- list(
+ Solution1 = zoned_solution_df,
+ Solution2 = zoned_solution_df %>% mutate(solution_1 = abs(solution_1 - 1)) # Invert selection for demo
+)
+
+# plot_climKernelDensity handles both basic and fancy automatically
+splnr_plot_climKernelDensity(
+ soln = soln_list, # Pass the list of solutions
+ names = c("metric", "metric"),
+ type = "Normal" # Explicitly request fancy
+ # zone_column = "zone" # If your solutions have zones
+)
+```
+
+3. Plot Prioritization Solutions
+Function: `splnr_plot_solution()`
+
+Visualizes the spatial output of a prioritizr problem, showing which planning units were selected for conservation. It supports both single-zone and multi-zone solutions.
+
+```{r}
+
+# Plot a single-zone solution
+splnr_plot_solution(
+ soln = solution_df,
+ colorVals = c("grey", "darkgreen"),
+ legendLabels = c("Not Selected", "Selected"),
+ plotTitle = "Prioritization Solution (Single Zone)"
+)
+
+# Plot a zoned solution (assuming 'zone' column exists)
+# In a real scenario, this 'zone' column would be part of your prioritizr output.
+# splnr_plot_solution(
+# soln = zoned_solution_df,
+# colorVals = c("red", "blue", "grey"), # Colors for each zone + not selected
+# legendLabels = c("Zone A", "Zone B", "Not Selected"),
+# plotTitle = "Prioritization Solution (Zoned)",
+# zones = TRUE
+# )
+```
+
+
+4. Plot Cost Overlay
+Function: `splnr_plot_costOverlay()`
+
+Overlays cost data on top of a prioritization solution, helping to visualize the spatial distribution of costs relative to selected areas.
+
+```{r}
+# Assuming 'solution_df' and adding a 'cost' column
+solution_with_cost <- solution_df %>%
+ dplyr::mutate(cost = runif(dplyr::n(), 100, 1000))
+
+splnr_plot_costOverlay(
+ soln = solution_with_cost,
+ costName = "cost", # Name of the cost column
+ # costName = "Acquisition Cost",
+ # colorVals = c("grey", "darkgreen"),
+ # legendLabels = c("Not Selected", "Selected"),
+ plotTitle = "Prioritization Solution with Cost Overlay"
+)
+
+```
+
+5. Plot Comparison
+Function: `splnr_plot_comparison()`
+
+Compares two different prioritization solutions, highlighting areas that are uniquely selected by each solution, or selected by both.
+
+```{r}
+# Assuming two solutions for comparison
+soln1_df <- solution_df %>%
+ dplyr::mutate(solution_1 = sample(c(0, 1), dplyr::n(), replace = TRUE, prob = c(0.6, 0.4)))
+soln2_df <- solution_df %>%
+ dplyr::mutate(solution_1 = sample(c(0, 1), dplyr::n(), replace = TRUE, prob = c(0.5, 0.5)))
+
+splnr_plot_comparison(
+ soln1 = soln1_df,
+ soln2 = soln2_df,
+)
+
+```
+
+6. Plot Selection Frequency
+Function: `splnr_plot_selectionFreq()`
+
+Visualizes the frequency with which each planning unit is selected across multiple runs of a prioritization problem (e.g., from a sensitivity analysis or robust solution generation).
+
+```{r}
+# # Create selection frequency data
+# selection_freq_df <- solution_df %>%
+# dplyr::mutate(
+# selection_frequency = runif(dplyr::n(), 0, 1) # Frequency between 0 and 1
+# )
+#
+# splnr_plot_selectionFreq(
+# selFreq = selection_freq_df,
+# plotTitle = "Selection Frequency of Planning Units",
+# legendTitle = "Selection Frequency"
+# )
+```
+
+7. Plot Importance Score
+Function: `splnr_plot_importanceScore()`
+
+Calculates and visualizes an "importance score" for each planning unit, which can represent its contribution to achieving targets or its irreplaceability. Useful for identifying key areas.
+
+```{r}
+#
+# splnr_plot_importanceScore(
+# soln = solution_df,
+# pDat = dat_species_bin, # Original biodiversity features
+# method = "basic", # Or "complex"
+# decimals = 2,
+# plotTitle = "Planning Unit Importance Score"
+# )
+```
+
+8. Plot Correlation Matrix
+Function: `splnr_plot_corrMat()`
+
+Generates a correlation matrix plot, useful for understanding relationships between different features or variables in your planning data.
+
+```{r}
+# # Create a data matrix for correlation
+#
+# corr_data <- data.frame(
+# Var1 = rnorm(100),
+# Var2 = rnorm(100, mean = 0.5, sd = 1),
+# Var3 = rnorm(100, mean = -0.2, sd = 0.5)
+# )
+# # Add some correlation
+# corr_data$Var2 <- corr_data$Var2 + 0.5 * corr_data$Var1
+# corr_data$Var3 <- corr_data$Var3 - 0.3 * corr_data$Var1
+#
+# # Calculate correlation matrix
+# corr_matrix <- cor(corr_data)
+#
+# splnr_plot_corrMat(
+# matrix = corr_matrix,
+# plotTitle = "Correlation Matrix of Variables"
+# )
+
+```
+
+9. Generic Plotting Utility
+Function: `splnr_plot()`
+
+A versatile plotting function that can be used to visualize any continuous or categorical data column within an sf dataframe, with options for color palettes and legend customization. Many other plotting functions in _spatialplanr_ internally use this function.
+
+```{r}
+# Plotting the 'metric' column from 'dat_clim' using the generic plotter
+splnr_plot(
+ df = dat_clim,
+ colNames = "metric",
+ plotTitle = "Generic Plot of Climate Metric",
+ legendTitle = "Metric Value",
+ paletteName = "viridis" # Use a viridis color palette
+)
+
+```
+
+# Example Workflow
+The following example illustrates a typical workflow using _spatialplanr_ for climate-smart conservation planning. It assumes you have already prepared your planning units, biodiversity features, and cost layers.
+
+A typical workflow using _spatialplanr_ for climate-smart conservation planning might look like this:
+
+## Data Preparation:
+
+* Load your planning units (PUs).
+* Load your biodiversity features (features).
+* Load your cost layer (costs).
+* Load your climate metric data (climate_data).
+* (Optional) Use splnr_get_IUCNRedList() to refine species targets or splnr_get_gfw() to generate a cost layer.
+
+Choose Climate-Smart Approach:
+
+* Decide which climate-smart approach best suits your planning goals:
+ * `splnr_climate_priorityAreaApproach()` for prioritizing refugia for each feature.
+ * `splnr_climate_featureApproach()` for treating climate resilience as a standalone feature.
+ * `splnr_climate_percentileApproach()` for targeting specific climate metric ranges.
+* Run the chosen function to obtain climate_features and climate_targets.
+* Define and Solve Prioritization Problem (using _prioritizr_):
+
+Create a prioritizr problem using your PUs, climate_features, and climate_targets.
+* Add objectives (e.g., `add_min_set_objective()`, `add_max_targets_objective()`).
+* Add constraints (e.g., `add_budget_constraint()`, `add_contiguity_constraint()`, `add_locked_in_constraint()` for existing MPAs).
+* Add solvers (e.g., `add_gurobi_solver()`, `add_cbc_solver()`).
+* Solve the problem to get your solution.
+
+Visualize and Analyze Results (using _spatialplanr_ plotting functions):
+* `splnr_plot_solution()` to visualize the selected planning units.
+* `splnr_plot_costOverlay()` to see costs in selected areas.
+* `splnr_plot_climKernelDensity()` to assess the climate characteristics of the solution.
+* `splnr_plot_comparison()` to compare different scenarios or solutions.
+* `splnr_plot_selectionFreq()` for robust solutions.
+* `splnr_plot_importanceScore()` to identify key planning units.
+* `splnr_plot_corrMat()` to understand feature relationships.
+
+
+# Conclusion
+_spatialplanr_ provides a powerful and flexible toolkit for integrating climate change considerations into spatial conservation prioritization. By offering multiple methodological approaches, streamlining data handling, and providing comprehensive visualization capabilities, it aims to empower conservation planners to create more resilient and effective protected area networks for the future.
diff --git a/README.md b/README.md
index 0076f51..b6133b1 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
-# spatialplanr
+# spatialplanr \
@@ -15,15 +15,14 @@ coverage](https://codecov.io/gh/SpatialPlanning/spatialplanr/branch/main/graph/b
[](https://github.com/SpatialPlanning/spatialplanr/issues)
-## Overview
+# Introduction to spatialplanr
-This package is designed to assist students and staff in the
-[Mathematical Marine Ecology Lab](https://mathmarecol.github.io) at the
-University of Queensland. It may be useful for others as well. This code
-has been written to simplify the process for running a *prioritizr*
-analysis on a given region use the workflows and data of the MME Lab. It
-is still a work in progress so feel free to submit pull requests with
-new features and code improvements.
+Welcome to *spatialplanr*, an R package designed to streamline and
+enhance spatial conservation prioritization efforts by explicitly
+integrating climate change considerations. Building upon the powerful
+*prioritizr* package, *spatialplanr* provides a suite of tools for
+conservation planners to develop more robust and climate-resilient
+protected area networks.
## Installation
@@ -36,3 +35,455 @@ development version from [GitHub](https://github.com/) with:
# install.packages("devtools")
devtools::install_github("https://github.com/SpatialPlanning/spatialplanr")
```
+
+# Purpose and Goals
+
+The escalating impacts of climate change necessitate a paradigm shift in
+how we approach conservation. Traditional conservation planning often
+focuses on static biodiversity patterns, which may not adequately
+account for the dynamic nature of species distributions and ecosystem
+processes under a changing climate. *spatialplanr* aims to address this
+gap by:
+
+**Facilitating Climate-Smart Planning**: Providing functions that
+incorporate climate data directly into the planning process, allowing
+for the identification of areas critical for both biodiversity and
+resilience to future climate conditions. Offering Diverse Methodological
+Approaches: Implementing multiple established climate-smart conservation
+planning frameworks (e.g., Climate Priority Areas, Climate Features,
+Climate Percentiles) to offer flexibility based on specific planning
+goals and data availability.
+
+**Streamlining Workflow**: Offering end-to-end functionality, from data
+preprocessing and integration to advanced visualization of results,
+simplifying complex analytical tasks for users.
+
+**Enhancing Decision-Making**: Producing outputs that directly feed into
+spatial prioritization software like prioritizr, enabling the generation
+of optimal conservation solutions that balance biodiversity
+representation with climate resilience. By using spatialplanr,
+practitioners can move beyond reactive conservation and proactively
+design protected area systems better equipped to safeguard biodiversity
+in a rapidly changing world.
+
+# Core Climate-Smart Planning Approaches
+
+*spatialplanr* implements several key approaches for integrating climate
+change into spatial prioritization, largely drawing inspiration from
+frameworks like that presented in Buenafe et al. (2023) “A metric‐based
+framework for climate‐smart conservation planning” (DOI:
+10.1002/eap.2852).
+
+These approaches are designed to transform biodiversity features and
+conservation targets based on climate metrics, allowing for a more
+nuanced understanding of how climate change may impact conservation
+priorities. The main approaches included in *spatialplanr* are: \*
+**Climate Priority Area (CPA) Approach**: Identifies climate-smart areas
+within the distribution of each conservation feature, creating new
+components for climate-smart and non-climate-smart areas. \* **Climate
+Feature Approach**: Treats climate-smart areas as a distinct
+conservation feature, allowing for explicit conservation targets on
+climate resilience. \* **Climate Percentile Approach**: Sets
+conservation targets based on percentile ranges of climate metrics,
+allowing for targeted protection of areas within specific climate
+resilience thresholds.
+
+# Data Acquisition and Preprocessing Utilities
+
+*spatialplanr* also provides convenience functions for acquiring and
+preparing data, which can be crucial for climate-smart planning.
+
+``` r
+# Load spatialplanr
+library(spatialplanr)
+library(tidyverse)
+#> ── Attaching core tidyverse packages ──────────────────────── tidyverse 2.0.0 ──
+#> ✔ dplyr 1.1.4 ✔ readr 2.1.5
+#> ✔ forcats 1.0.0 ✔ stringr 1.5.1
+#> ✔ ggplot2 3.5.2 ✔ tibble 3.3.0
+#> ✔ lubridate 1.9.4 ✔ tidyr 1.3.1
+#> ✔ purrr 1.0.4
+#> ── Conflicts ────────────────────────────────────────── tidyverse_conflicts() ──
+#> ✖ dplyr::filter() masks stats::filter()
+#> ✖ dplyr::lag() masks stats::lag()
+#> ℹ Use the conflicted package (
+
+2. Plot Climate Kernel Density Functions:
+ `splnr_plot_climKernelDensity_Basic()`,
+ `splnr_plot_climKernelDensity_Fancy()`,
+ `splnr_plot_climKernelDensity()`
+
+These functions help visualize the distribution of climate metric values
+within selected planning units (e.g., a proposed protected area network)
+compared to the overall distribution. This helps assess if climate-smart
+areas are being adequately captured.
+
+`_Basic()`: Simple kernel density plot. `_Fancy()`: More customizable
+kernel density plot, allowing multiple solutions and specific zones.
+`_climKernelDensity()`: A wrapper function that selects between basic
+and fancy plots based on input type.
+
+``` r
+solution_df <- dat_clim %>%
+ dplyr::mutate(
+ solution_1 = sample(c(0, 1), size = dplyr::n(), replace = TRUE, prob = c(0.7, 0.3)),
+ metric_category = cut(metric, breaks = 3, labels = c("Low", "Medium", "High"))
+ )
+
+# Basic kernel density plot of the metric for selected areas vs. all areas
+splnr_plot_climKernelDensity(
+ soln = solution_df,
+ type = "Basic",
+ names = "solution_1" # Column indicating selected PUs (1=selected)
+)
+
+#> Picking joint bandwidth of 0.0885
+#> Picking joint bandwidth of 0.077
+
+```
+
+
+
+``` r
+
+# Fancy kernel density plot, perhaps with zones (if your solution has them)
+# For this example, let's pretend 'solution_df' has a 'zone' column
+# (this would come from a prioritizr zoned solution)
+zoned_solution_df <- solution_df %>%
+ dplyr::mutate(
+ zone = sample(c("Zone A", "Zone B"), size = dplyr::n(), replace = TRUE)
+ )
+
+# Example for Fancy (requires a list of solutions or specific structure)
+# If you have multiple prioritizr solutions, you would put them in a list.
+# For simplicity, we'll create a mock 'soln' list:
+soln_list <- list(
+ Solution1 = zoned_solution_df,
+ Solution2 = zoned_solution_df %>% mutate(solution_1 = abs(solution_1 - 1)) # Invert selection for demo
+)
+
+# plot_climKernelDensity handles both basic and fancy automatically
+splnr_plot_climKernelDensity(
+ soln = soln_list, # Pass the list of solutions
+ names = c("metric", "metric"),
+ type = "Normal" # Explicitly request fancy
+ # zone_column = "zone" # If your solutions have zones
+)
+#> Picking joint bandwidth of 0.071
+#> Picking joint bandwidth of 0.071
+```
+
+
+
+3. Plot Prioritization Solutions Function: `splnr_plot_solution()`
+
+Visualizes the spatial output of a prioritizr problem, showing which
+planning units were selected for conservation. It supports both
+single-zone and multi-zone solutions.
+
+``` r
+
+# Plot a single-zone solution
+splnr_plot_solution(
+ soln = solution_df,
+ colorVals = c("grey", "darkgreen"),
+ legendLabels = c("Not Selected", "Selected"),
+ plotTitle = "Prioritization Solution (Single Zone)"
+)
+```
+
+
+
+``` r
+
+# Plot a zoned solution (assuming 'zone' column exists)
+# In a real scenario, this 'zone' column would be part of your prioritizr output.
+# splnr_plot_solution(
+# soln = zoned_solution_df,
+# colorVals = c("red", "blue", "grey"), # Colors for each zone + not selected
+# legendLabels = c("Zone A", "Zone B", "Not Selected"),
+# plotTitle = "Prioritization Solution (Zoned)",
+# zones = TRUE
+# )
+```
+
+4. Plot Cost Overlay Function: `splnr_plot_costOverlay()`
+
+Overlays cost data on top of a prioritization solution, helping to
+visualize the spatial distribution of costs relative to selected areas.
+
+``` r
+# Assuming 'solution_df' and adding a 'cost' column
+solution_with_cost <- solution_df %>%
+ dplyr::mutate(cost = runif(dplyr::n(), 100, 1000))
+
+splnr_plot_costOverlay(
+ soln = solution_with_cost,
+ costName = "cost", # Name of the cost column
+ # costName = "Acquisition Cost",
+ # colorVals = c("grey", "darkgreen"),
+ # legendLabels = c("Not Selected", "Selected"),
+ plotTitle = "Prioritization Solution with Cost Overlay"
+)
+```
+
+
+
+5. Plot Comparison Function: `splnr_plot_comparison()`
+
+Compares two different prioritization solutions, highlighting areas that
+are uniquely selected by each solution, or selected by both.
+
+``` r
+# Assuming two solutions for comparison
+soln1_df <- solution_df %>%
+ dplyr::mutate(solution_1 = sample(c(0, 1), dplyr::n(), replace = TRUE, prob = c(0.6, 0.4)))
+soln2_df <- solution_df %>%
+ dplyr::mutate(solution_1 = sample(c(0, 1), dplyr::n(), replace = TRUE, prob = c(0.5, 0.5)))
+
+splnr_plot_comparison(
+ soln1 = soln1_df,
+ soln2 = soln2_df,
+)
+```
+
+
+
+6. Plot Selection Frequency Function: `splnr_plot_selectionFreq()`
+
+Visualizes the frequency with which each planning unit is selected
+across multiple runs of a prioritization problem (e.g., from a
+sensitivity analysis or robust solution generation).
+
+``` r
+# # Create selection frequency data
+# selection_freq_df <- solution_df %>%
+# dplyr::mutate(
+# selection_frequency = runif(dplyr::n(), 0, 1) # Frequency between 0 and 1
+# )
+#
+# splnr_plot_selectionFreq(
+# selFreq = selection_freq_df,
+# plotTitle = "Selection Frequency of Planning Units",
+# legendTitle = "Selection Frequency"
+# )
+```
+
+7. Plot Importance Score Function: `splnr_plot_importanceScore()`
+
+Calculates and visualizes an “importance score” for each planning unit,
+which can represent its contribution to achieving targets or its
+irreplaceability. Useful for identifying key areas.
+
+``` r
+#
+# splnr_plot_importanceScore(
+# soln = solution_df,
+# pDat = dat_species_bin, # Original biodiversity features
+# method = "basic", # Or "complex"
+# decimals = 2,
+# plotTitle = "Planning Unit Importance Score"
+# )
+```
+
+8. Plot Correlation Matrix Function: `splnr_plot_corrMat()`
+
+Generates a correlation matrix plot, useful for understanding
+relationships between different features or variables in your planning
+data.
+
+``` r
+# # Create a data matrix for correlation
+#
+# corr_data <- data.frame(
+# Var1 = rnorm(100),
+# Var2 = rnorm(100, mean = 0.5, sd = 1),
+# Var3 = rnorm(100, mean = -0.2, sd = 0.5)
+# )
+# # Add some correlation
+# corr_data$Var2 <- corr_data$Var2 + 0.5 * corr_data$Var1
+# corr_data$Var3 <- corr_data$Var3 - 0.3 * corr_data$Var1
+#
+# # Calculate correlation matrix
+# corr_matrix <- cor(corr_data)
+#
+# splnr_plot_corrMat(
+# matrix = corr_matrix,
+# plotTitle = "Correlation Matrix of Variables"
+# )
+```
+
+9. Generic Plotting Utility Function: `splnr_plot()`
+
+A versatile plotting function that can be used to visualize any
+continuous or categorical data column within an sf dataframe, with
+options for color palettes and legend customization. Many other plotting
+functions in *spatialplanr* internally use this function.
+
+``` r
+# Plotting the 'metric' column from 'dat_clim' using the generic plotter
+splnr_plot(
+ df = dat_clim,
+ colNames = "metric",
+ plotTitle = "Generic Plot of Climate Metric",
+ legendTitle = "Metric Value",
+ paletteName = "viridis" # Use a viridis color palette
+)
+#> Coordinate system already present. Adding new coordinate system, which will
+#> replace the existing one.
+```
+
+
+
+# Example Workflow
+
+The following example illustrates a typical workflow using
+*spatialplanr* for climate-smart conservation planning. It assumes you
+have already prepared your planning units, biodiversity features, and
+cost layers.
+
+A typical workflow using *spatialplanr* for climate-smart conservation
+planning might look like this:
+
+## Data Preparation:
+
+- Load your planning units (PUs).
+- Load your biodiversity features (features).
+- Load your cost layer (costs).
+- Load your climate metric data (climate_data).
+- (Optional) Use splnr_get_IUCNRedList() to refine species targets or
+ splnr_get_gfw() to generate a cost layer.
+
+Choose Climate-Smart Approach:
+
+- Decide which climate-smart approach best suits your planning goals:
+ - `splnr_climate_priorityAreaApproach()` for prioritizing refugia for
+ each feature.
+ - `splnr_climate_featureApproach()` for treating climate resilience as
+ a standalone feature.
+ - `splnr_climate_percentileApproach()` for targeting specific climate
+ metric ranges.
+- Run the chosen function to obtain climate_features and
+ climate_targets.
+- Define and Solve Prioritization Problem (using *prioritizr*):
+
+Create a prioritizr problem using your PUs, climate_features, and
+climate_targets. \* Add objectives (e.g., `add_min_set_objective()`,
+`add_max_targets_objective()`). \* Add constraints (e.g.,
+`add_budget_constraint()`, `add_contiguity_constraint()`,
+`add_locked_in_constraint()` for existing MPAs). \* Add solvers (e.g.,
+`add_gurobi_solver()`, `add_cbc_solver()`). \* Solve the problem to get
+your solution.
+
+Visualize and Analyze Results (using *spatialplanr* plotting functions):
+\* `splnr_plot_solution()` to visualize the selected planning units. \*
+`splnr_plot_costOverlay()` to see costs in selected areas. \*
+`splnr_plot_climKernelDensity()` to assess the climate characteristics
+of the solution. \* `splnr_plot_comparison()` to compare different
+scenarios or solutions. \* `splnr_plot_selectionFreq()` for robust
+solutions. \* `splnr_plot_importanceScore()` to identify key planning
+units. \* `splnr_plot_corrMat()` to understand feature relationships.
+
+# Conclusion
+
+*spatialplanr* provides a powerful and flexible toolkit for integrating
+climate change considerations into spatial conservation prioritization.
+By offering multiple methodological approaches, streamlining data
+handling, and providing comprehensive visualization capabilities, it
+aims to empower conservation planners to create more resilient and
+effective protected area networks for the future.
diff --git a/data-raw/CreateHex.R b/data-raw/CreateHex.R
index 928a20a..09587ef 100644
--- a/data-raw/CreateHex.R
+++ b/data-raw/CreateHex.R
@@ -1,6 +1,6 @@
# Some code to create a hex sticker for the spatialplanr package
#
-# Last updated: Saturday 8th July 2023
+# Last updated: Friday 13th June 2025
#
# Jason D. Everett (UQ/CSIRO/UNSW)
#
@@ -95,12 +95,12 @@ hexSticker::sticker(gg,
s_height = 2.2,
# h_fill = "#9FE2BF",
h_color = "black", # "grey40",
- url = "mathmarecol.github.io/spatialplanr",
+ url = "spatialplanning.github.io/spatialplanr",
u_color = "grey90",
# u_family = "sans",
- u_size = 15.5,
- u_x = 0.99,
- u_y = 0.06,
+ u_size = 15,
+ u_x = 0.98,
+ u_y = 0.055,
dpi = 1000,
asp = 1,
filename = file.path("data-raw", "spatialplanr.png"))
diff --git a/data-raw/spatialplanr.png b/data-raw/spatialplanr.png
index e6b11af..a25c009 100644
Binary files a/data-raw/spatialplanr.png and b/data-raw/spatialplanr.png differ
diff --git a/man/figures/README-unnamed-chunk-13-1.png b/man/figures/README-unnamed-chunk-13-1.png
new file mode 100644
index 0000000..cae4a41
Binary files /dev/null and b/man/figures/README-unnamed-chunk-13-1.png differ
diff --git a/man/figures/README-unnamed-chunk-5-1.png b/man/figures/README-unnamed-chunk-5-1.png
new file mode 100644
index 0000000..009cad8
Binary files /dev/null and b/man/figures/README-unnamed-chunk-5-1.png differ
diff --git a/man/figures/README-unnamed-chunk-6-1.png b/man/figures/README-unnamed-chunk-6-1.png
new file mode 100644
index 0000000..5f48857
Binary files /dev/null and b/man/figures/README-unnamed-chunk-6-1.png differ
diff --git a/man/figures/README-unnamed-chunk-6-2.png b/man/figures/README-unnamed-chunk-6-2.png
new file mode 100644
index 0000000..ee5a463
Binary files /dev/null and b/man/figures/README-unnamed-chunk-6-2.png differ
diff --git a/man/figures/README-unnamed-chunk-7-1.png b/man/figures/README-unnamed-chunk-7-1.png
new file mode 100644
index 0000000..972ac6b
Binary files /dev/null and b/man/figures/README-unnamed-chunk-7-1.png differ
diff --git a/man/figures/README-unnamed-chunk-8-1.png b/man/figures/README-unnamed-chunk-8-1.png
new file mode 100644
index 0000000..c6f8ab9
Binary files /dev/null and b/man/figures/README-unnamed-chunk-8-1.png differ
diff --git a/man/figures/README-unnamed-chunk-9-1.png b/man/figures/README-unnamed-chunk-9-1.png
new file mode 100644
index 0000000..b008fb9
Binary files /dev/null and b/man/figures/README-unnamed-chunk-9-1.png differ
diff --git a/man/figures/logo.png b/man/figures/logo.png
index 65f2495..6b94dcb 100644
Binary files a/man/figures/logo.png and b/man/figures/logo.png differ
diff --git a/man/spatialplanr-package.Rd b/man/spatialplanr-package.Rd
index dd2e641..88adcb5 100644
--- a/man/spatialplanr-package.Rd
+++ b/man/spatialplanr-package.Rd
@@ -13,8 +13,8 @@ This package provides a range of tools for setting up, running and plotting a sp
\seealso{
Useful links:
\itemize{
- \item \url{https://github.com/MathMarEcol/spatialplanr}
- \item Report bugs at \url{https://github.com/MathMarEcol/spatialplanr/issues}
+ \item \url{https://github.com/SpatialPlanning/spatialplanr}
+ \item Report bugs at \url{https://github.com/SpatialPlanning/spatialplanr/issues}
}
}
diff --git a/man/splnr_apply_cutoffs.Rd b/man/splnr_apply_cutoffs.Rd
index 78f23d5..36f7f64 100644
--- a/man/splnr_apply_cutoffs.Rd
+++ b/man/splnr_apply_cutoffs.Rd
@@ -2,23 +2,93 @@
% Please edit documentation in R/splnr_apply_cutoffs.R
\name{splnr_apply_cutoffs}
\alias{splnr_apply_cutoffs}
-\title{Function to apply cutoffs to feature data}
+\title{Apply Cutoffs to Feature Data}
\usage{
splnr_apply_cutoffs(features, Cutoffs, inverse = FALSE)
}
\arguments{
-\item{features}{A sf dataframe with all the feature information}
+\item{features}{An \code{sf} dataframe. It must contain a \code{geometry} column and
+at least one numeric column to which cutoffs will be applied.}
-\item{Cutoffs}{A single value or a named vector of cutoffs.}
+\item{Cutoffs}{A numeric value or a named numeric vector of cutoffs.
+\itemize{
+\item If a single unnamed numeric value, it's applied to all numeric columns.
+\item If a named numeric vector, names must correspond to numeric column names in \code{features}.
+}
+All cutoff values must be between \code{0} and \code{1}.}
-\item{inverse}{If TRUE, values below the \code{Cutoffs} are used. If FALSE (default), values above are kept.}
+\item{inverse}{A logical value (\code{TRUE} or \code{FALSE}). If \code{TRUE}, values below
+the \code{Cutoffs} are converted to \code{1} (and others to \code{0}). If \code{FALSE} (default),
+values at or above the \code{Cutoffs} are converted to \code{1}.}
}
\value{
-A new sf dataframe that has cutoffs applied.
+A modified \code{sf} dataframe with the same structure and geometry as
+\code{features}, but with all targeted numeric columns transformed into binary
+(0 or 1) values based on the specified cutoffs and \code{inverse} setting.
}
\description{
-Function to apply cutoffs to feature data
+\code{splnr_apply_cutoffs()} transforms numeric feature data in an \code{sf} dataframe
+into binary (0 or 1) presence/absence values based on specified cutoffs.
+It provides flexibility to either keep values above a cutoff as 1 (default)
+or invert this logic to keep values below a cutoff as 1.
+}
+\details{
+This function is crucial for standardizing feature data, such as species
+probability distributions or habitat suitability scores, into a binary format
+often required for conservation planning and spatial analysis (e.g., in
+\code{prioritizr}).
+
+The function operates in two primary modes based on the \code{Cutoffs} parameter:
+\itemize{
+\item \strong{Single Cutoff:} If \code{Cutoffs} is a single numeric value (e.g., \code{0.5}),
+this value is applied uniformly to \strong{all numeric columns} in the
+\code{features} dataframe, excluding the \code{geometry} column.
+For each numeric cell:
+- If \code{value >= Cutoffs}, it becomes \code{1}.
+- If \code{value < Cutoffs}, it becomes \code{0}.
+- \code{NA} values are always converted to \code{0}.
+\item \strong{Named Vector of Cutoffs:} If \code{Cutoffs} is a named numeric vector
+(e.g., \code{c("feature1" = 0.5, "feature2" = 0.3)}), each specified cutoff
+is applied individually to its corresponding named column in \code{features}.
+This allows for different thresholds for different features. The same
+transformation rules as above apply to each specified column.
+}
+
+The \code{inverse} parameter provides additional control over the binarization:
+\itemize{
+\item \code{inverse = FALSE} (default): Values \strong{at or above} the cutoff become \code{1}.
+\item \code{inverse = TRUE}: Values \strong{below} the cutoff become \code{1}. After initial
+binarization (where values >= cutoff are 1), the binary results are
+flipped (0s become 1s, and 1s become 0s) to achieve the inverse effect.
+}
+All \code{NA} values in the numeric columns are consistently converted to \code{0} during
+the binarization process, regardless of the \code{inverse} setting.
}
\examples{
-df <- splnr_apply_cutoffs(dat_species_prob, Cutoffs = 0.5)
+
+# Example 1: Single cutoff (0.5) applied to all numeric feature columns
+# (Spp1_Prob, Spp2_Prob, and Cost will be binarized based on 0.5)
+df_single_cutoff <- splnr_apply_cutoffs(dat_species_prob, Cutoffs = 0.5)
+print(df_single_cutoff)
+
+# Example 2: Named cutoffs for specific columns
+# Spp1_Prob >= 0.6 becomes 1, Spp2_Prob >= 0.4 becomes 1
+df_named_cutoffs <- splnr_apply_cutoffs(
+ dat_species_prob,
+ Cutoffs = c("Spp1" = 0.6, "Spp2" = 0.4)
+)
+print(df_named_cutoffs)
+
+# Example 3: Single cutoff (0.5) with inverse logic
+# Values BELOW 0.5 become 1.
+df_inverse_cutoff <- splnr_apply_cutoffs(dat_species_prob, Cutoffs = 0.5, inverse = TRUE)
+print(df_inverse_cutoff)
+
+# Example 4: Named cutoffs with inverse logic
+df_named_inverse <- splnr_apply_cutoffs(
+ dat_species_prob,
+ Cutoffs = c("Spp1" = 0.7, "Spp2" = 0.3),
+ inverse = TRUE
+)
+print(df_named_inverse)
}
diff --git a/man/splnr_arrangeFeatures.Rd b/man/splnr_arrangeFeatures.Rd
index eee875d..0feb870 100644
--- a/man/splnr_arrangeFeatures.Rd
+++ b/man/splnr_arrangeFeatures.Rd
@@ -2,20 +2,42 @@
% Please edit documentation in R/utils.R
\name{splnr_arrangeFeatures}
\alias{splnr_arrangeFeatures}
-\title{Ensure all features are in the same order.}
+\title{Arrange Features by Spatial Coordinates}
\usage{
splnr_arrangeFeatures(df)
}
\arguments{
-\item{df}{An sf object to sort by Lon and Lat}
+\item{df}{An \code{sf} object whose rows are to be sorted.}
}
\value{
-A sorted sf object
+A sorted \code{sf} object, with rows ordered primarily by longitude (X)
+and secondarily by latitude (Y) of their centroids.
}
\description{
-\code{splnr_arrangeFeatures()} sorts your data based on longitude and latitude values.
+\code{splnr_arrangeFeatures()} sorts the rows of an \code{sf} object based on the
+longitude (X) and then latitude (Y) of its centroids. This ensures a
+consistent ordering of planning units, which can be important for
+reproducibility in some spatial analyses or data processing steps.
+}
+\details{
+This function computes the centroid for each polygon (or point/multipoint)
+in the input \code{sf} object. It then extracts the X and Y coordinates of these
+centroids and uses them to sort the entire \code{sf} object. The primary sort key
+is the longitude (X-coordinate), and the secondary sort key is the latitude
+(Y-coordinate).
+
+Sorting can be beneficial for tasks like debugging, comparing data from
+different runs, or ensuring deterministic behavior in algorithms that
+process spatial units sequentially.
}
\examples{
-df <- dat_species_prob \%>\%
- splnr_arrangeFeatures()
+\dontrun{
+print("Original order:")
+print(dat_species_prob)
+
+# Sort the features.
+df_arranged <- splnr_arrangeFeatures(df = dat_species_prob)
+print("Sorted order:")
+print(df_arranged)
+}
}
diff --git a/man/splnr_climate_featureApproach.Rd b/man/splnr_climate_featureApproach.Rd
index de729f0..24d3be1 100644
--- a/man/splnr_climate_featureApproach.Rd
+++ b/man/splnr_climate_featureApproach.Rd
@@ -2,7 +2,7 @@
% Please edit documentation in R/utils-climate.R
\name{splnr_climate_featureApproach}
\alias{splnr_climate_featureApproach}
-\title{Function to run the feature approach}
+\title{Run the Feature Climate-Smart Approach}
\usage{
splnr_climate_featureApproach(
features,
@@ -14,40 +14,92 @@ splnr_climate_featureApproach(
)
}
\arguments{
-\item{features}{feature \code{sf}object}
+\item{features}{An \code{sf} object representing conservation features (e.g., species
+distribution data).}
-\item{metric}{climate metric \code{sf} object with 'metric' as the column name of the metric values per planning unit.}
+\item{metric}{An \code{sf} object containing climate metric information. It must
+have a column named 'metric' with the climate metric values per planning unit.}
-\item{targets}{\code{data.frame}with list of features under "feature" column and their corresponding targets under "target" column}
+\item{targets}{A \code{data.frame} with two columns: \code{feature} (character, listing
+the original feature names) and \code{target} (numeric, the initial conservation
+target for each feature as a proportion, e.g., 0.3).}
-\item{direction}{If direction = 1, metric values are from low (least climate-smart) to high (most climate-smart). If direction = -1, metric values are from high (least climate-smart) to low (most climate-smart).}
+\item{direction}{An integer specifying the direction of climate-smartness:
+\itemize{
+\item \code{1}: Higher metric values mean more climate-smart areas.
+\item \code{-1}: Lower metric values mean more climate-smart areas.
+}}
-\item{percentile}{cut-off threshold for determining whether an area is a climate priority area or not (e.g., lower 35th percentile of warming or upper 65th percentile of acidification). Note that the percentile here is the lower limit of the threshold.}
+\item{percentile}{A numeric value (0-100) representing the cutoff threshold for
+determining whether an area is a climate priority area or not. This is applied
+globally to the \code{metric} data. Defaults to \code{35}.}
-\item{refugiaTarget}{target assigned to climate-smart areas}
+\item{refugiaTarget}{A numeric value (0-1) representing the target proportion
+assigned to the overall climate-smart layer. Defaults to \code{0.3} (30\%).}
}
\value{
-A \code{list} with two components: 1. is the data frame passed to \code{prioritizr} when creating a conservation problem containing the binary information per planning unit per feature. 2. are the targets for the features in the conservation problem when the CPA approach is used.
+A \code{list} with two components:
+\itemize{
+\item \code{Features}: An \code{sf} object containing the binary information per
+planning unit for each original feature, plus the new \code{climate_layer}
+feature. This is ready to be passed to \code{prioritizr}.
+\item \code{Targets}: A \code{data.frame} with the adjusted targets for all features,
+including the \code{climate_layer}. This is also ready for \code{prioritizr}.
+}
}
\description{
-Function to run the feature approach
+\code{splnr_climate_featureApproach()} implements the Feature Approach to
+climate-smart conservation planning. This involves defining a global
+"climate-smart" layer and adjusting conservation targets to ensure that
+a specified proportion of this layer is captured in the solution.
+}
+\details{
+This function orchestrates the steps for the Feature Approach:
+\enumerate{
+\item \strong{Preprocessing:} It calls \code{splnr_climate_feature_preprocess()} to
+identify a region-wide climate-smart layer based on a percentile cutoff
+of the climate metric. This layer is then added as a new binary feature
+to your conservation data.
+\item \strong{Target Assignment:} It then calls \code{splnr_climate_feature_assignTargets()}
+to calculate and assign new targets. Crucially, a specific \code{refugiaTarget}
+is set for the newly created \code{climate_layer} feature, ensuring that a
+certain proportion of the most climate-resilient areas are included in
+the final conservation plan.
+}
+
+The output is a list containing the modified features (now including the
+\code{climate_layer}) and their corresponding adjusted targets, ready to be used
+in a \code{prioritizr} conservation problem.
}
\examples{
-Features <- dat_species_bin
+\dontrun{
+# Assuming 'dat_species_bin' and 'dat_clim' are existing sf objects
+# in your package.
-targets <- Features \%>\%
+# Define initial targets for species features.
+initial_targets <- dat_species_bin \%>\%
sf::st_drop_geometry() \%>\%
colnames() \%>\%
data.frame() \%>\%
setNames(c("feature")) \%>\%
dplyr::mutate(target = 0.3)
-Feature_Approach <- splnr_climate_featureApproach(
+# Run the Feature Approach where higher climate metric values mean
+# more climate-smart areas.
+Feature_Approach_result <- splnr_climate_featureApproach(
features = dat_species_bin,
metric = dat_clim,
- targets = targets,
- direction = 1
+ targets = initial_targets,
+ direction = 1, # Example: higher metric values are more climate-smart
+ percentile = 35,
+ refugiaTarget = 0.3
)
-out_sf <- Feature_Approach$Features
-targets <- Feature_Approach$Targets
+
+# Access the processed features and targets:
+out_sf_feature <- Feature_Approach_result$Features
+targets_feature <- Feature_Approach_result$Targets
+
+print(head(out_sf_feature))
+print(head(targets_feature))
+}
}
diff --git a/man/splnr_climate_percentileApproach.Rd b/man/splnr_climate_percentileApproach.Rd
index 3a891c5..d3f93d5 100644
--- a/man/splnr_climate_percentileApproach.Rd
+++ b/man/splnr_climate_percentileApproach.Rd
@@ -2,7 +2,7 @@
% Please edit documentation in R/utils-climate.R
\name{splnr_climate_percentileApproach}
\alias{splnr_climate_percentileApproach}
-\title{Function to run the percentile approach}
+\title{Run the Percentile Climate-Smart Approach}
\usage{
splnr_climate_percentileApproach(
features,
@@ -13,37 +13,88 @@ splnr_climate_percentileApproach(
)
}
\arguments{
-\item{features}{feature \code{sf}object}
+\item{features}{An \code{sf} object representing conservation features (e.g., species
+distribution data).}
-\item{metric}{climate metric \code{sf} object with 'metric' as the column name of the metric values per planning unit.}
+\item{metric}{An \code{sf} object containing climate metric information. It must
+have a column named 'metric' with the climate metric values per planning unit.}
-\item{targets}{\code{data.frame}with list of features under "feature" column and their corresponding targets under "target" column}
+\item{targets}{A \code{data.frame} with two columns: \code{feature} (character, listing
+the original feature names) and \code{target} (numeric, the initial conservation
+target for each feature as a proportion, e.g., 0.3).}
-\item{direction}{If direction = 1, metric values are from low (least climate-smart) to high (most climate-smart). If direction = -1, metric values are from high (least climate-smart) to low (most climate-smart).}
+\item{direction}{An integer specifying the direction of climate-smartness:
+\itemize{
+\item \code{1}: Higher metric values mean more climate-smart areas.
+\item \code{-1}: Lower metric values mean more climate-smart areas.
+}}
-\item{percentile}{cut-off threshold for determining whether an area is a climate priority area or not (e.g., lower 35th percentile of warming or upper 65th percentile of acidification). Note that the percentile here is the lower limit of the threshold.}
+\item{percentile}{A numeric value (0-100) representing the cutoff threshold for
+determining whether an area is a climate priority area or not. This is applied
+\emph{per feature} to its distribution. Defaults to \code{35}.}
}
\value{
-A \code{list} with two components: 1. is the data frame passed to \code{prioritizr} when creating a conservation problem containing the binary information per planning unit per feature. 2. are the targets for the features in the conservation problem when the CPA approach is used.
+A \code{list} with two components:
+\itemize{
+\item \code{Features}: An \code{sf} object containing the binary information per
+planning unit for each feature, now filtered to include only its
+climate-smart occurrences. This is ready to be passed to \code{prioritizr}.
+\item \code{Targets}: A \code{data.frame} with the adjusted targets for the
+filtered features. This is also ready for \code{prioritizr}.
+}
}
\description{
-Function to run the percentile approach
+\code{splnr_climate_percentileApproach()} implements the Percentile Approach to
+climate-smart conservation planning. This involves filtering features to
+their most climate-resilient areas and adjusting their conservation targets
+to account for this reduced feature distribution.
+}
+\details{
+This function orchestrates the steps for the Percentile Approach:
+\enumerate{
+\item \strong{Preprocessing:} It calls \code{splnr_climate_percentile_preprocess()} to
+identify, for each feature, its occurrences within the most climate-resilient
+\code{percentile} of its distribution based on a climate metric. This effectively
+"filters" the feature data to only include its climate-smart components.
+\item \strong{Target Assignment:} It then calls \code{splnr_climate_percentile_assignTargets()}
+to calculate and assign new targets for these filtered features. The targets
+are scaled up to ensure that the original conservation goals are still met,
+but specifically by selecting areas from the climate-smart portions of the
+features' distributions.
+}
+
+The output is a list containing the modified features (filtered to their
+climate-smart occurrences) and their corresponding adjusted targets, ready
+to be used in a \code{prioritizr} conservation problem.
}
\examples{
+\dontrun{
+# Assuming 'dat_species_bin' and 'dat_clim' are existing sf objects
+# in your package.
-targets <- dat_species_bin \%>\%
+# Define initial targets for species features.
+initial_targets <- dat_species_bin \%>\%
sf::st_drop_geometry() \%>\%
colnames() \%>\%
data.frame() \%>\%
setNames(c("feature")) \%>\%
dplyr::mutate(target = 0.3)
-Percentile_Approach <- splnr_climate_percentileApproach(
+# Run the Percentile Approach where higher climate metric values mean
+# more climate-smart areas.
+Percentile_Approach_result <- splnr_climate_percentileApproach(
features = dat_species_bin,
metric = dat_clim,
- targets = targets,
- direction = 1
+ targets = initial_targets,
+ direction = 1, # Example: higher metric values are more climate-smart
+ percentile = 35
)
-out_sf <- Percentile_Approach$Features
-targets <- Percentile_Approach$Targets
+
+# Access the processed features and targets:
+out_sf_percentile <- Percentile_Approach_result$Features
+targets_percentile <- Percentile_Approach_result$Targets
+
+print(head(out_sf_percentile))
+print(head(targets_percentile))
+}
}
diff --git a/man/splnr_climate_priorityAreaApproach.Rd b/man/splnr_climate_priorityAreaApproach.Rd
index d76d4fb..fc272ec 100644
--- a/man/splnr_climate_priorityAreaApproach.Rd
+++ b/man/splnr_climate_priorityAreaApproach.Rd
@@ -2,7 +2,7 @@
% Please edit documentation in R/utils-climate.R
\name{splnr_climate_priorityAreaApproach}
\alias{splnr_climate_priorityAreaApproach}
-\title{Function to run the climate-priority-area approach}
+\title{Run the Climate Priority Area (CPA) Approach}
\usage{
splnr_climate_priorityAreaApproach(
features,
@@ -14,39 +14,94 @@ splnr_climate_priorityAreaApproach(
)
}
\arguments{
-\item{features}{feature \code{sf}object}
+\item{features}{An \code{sf} object representing conservation features (e.g., species
+distribution data). Each column (excluding geometry) should typically be a
+binary representation of a feature's presence (1) or absence (0) in each
+planning unit.}
-\item{metric}{climate metric \code{sf} object with 'metric' as the column name of the metric values per planning unit.}
+\item{metric}{An \code{sf} object containing climate metric information. It must
+have a column named 'metric' with the climate metric values per planning unit.}
-\item{targets}{\code{data.frame}with list of features under "feature" column and their corresponding targets under "target" column}
+\item{targets}{A \code{data.frame} with two columns: \code{feature} (character, listing
+the original feature names) and \code{target} (numeric, the initial conservation
+target for each feature as a proportion, e.g., 0.3).}
-\item{direction}{If direction = 1, metric values are from low (least climate-smart) to high (most climate-smart). If direction = -1, metric values are from high (least climate-smart) to low (most climate-smart).}
+\item{direction}{An integer specifying the direction of climate-smartness:
+\itemize{
+\item \code{1}: Higher metric values mean more climate-smart areas.
+\item \code{-1}: Lower metric values mean more climate-smart areas.
+}}
-\item{percentile}{cut-off threshold for determining whether an area is a climate priority area or not (e.g., lower 35th percentile of warming or upper 65th percentile of acidification). Note that the percentile here is the lower limit of the threshold.}
+\item{percentile}{A numeric value (0-100) representing the cutoff threshold for
+determining climate-smart areas. For example, \code{percentile = 5} means the
+most climate-smart 5\% of areas (based on \code{direction}) are considered.
+This value represents the lower limit of the threshold. Defaults to \code{5}.}
-\item{refugiaTarget}{target assigned to climate-smart areas}
+\item{refugiaTarget}{A numeric value (0-1) representing the target proportion
+assigned specifically to climate-smart areas (refugia). Defaults to \code{1} (100\%).}
}
\value{
-A \code{list} with two components: 1. is the data frame passed to \code{prioritizr} when creating a conservation problem containing the binary information per planning unit per feature. 2. are the targets for the features in the conservation problem when the CPA approach is used.
+A \code{list} with two components:
+\itemize{
+\item \code{Features}: An \code{sf} object containing the binary information per
+planning unit for each feature, now split into \verb{_CS} (climate-smart)
+and \verb{_NCS} (non-climate-smart) components. This is ready to be
+passed to \code{prioritizr} when creating a conservation problem.
+\item \code{Targets}: A \code{data.frame} with the adjusted targets for the
+climate-split features. This is also ready for \code{prioritizr}.
+}
}
\description{
-Function to run the climate-priority-area approach
+\code{splnr_climate_priorityAreaApproach()} implements the Climate Priority Area
+approach by splitting conservation features into climate-smart (CS) and
+non-climate-smart (NCS) components and adjusting their targets accordingly.
+This allows conservation planning to prioritize areas with higher climate resilience.
+}
+\details{
+This function orchestrates the steps required for the CPA approach:
+\enumerate{
+\item \strong{Preprocessing:} It calls \code{splnr_climate_priorityArea_preprocess()} to
+categorize each feature's occurrences into CS and NCS areas based on a
+climate metric and a specified \code{percentile} cutoff.
+\item \strong{Target Assignment:} It then calls \code{splnr_climate_priorityArea_assignTargets()}
+to calculate and assign new targets for these CS and NCS feature components.
+This ensures that conservation goals reflect the desired emphasis on climate-smart
+areas (e.g., aiming for 100\% representation of features in highly resilient areas).
+}
+
+The output of this function is a list containing the modified features (now
+split into CS/NCS components) and their corresponding adjusted targets, ready
+to be used in a \code{prioritizr} conservation problem.
}
\examples{
+\dontrun{
+# Assuming 'dat_species_bin' and 'dat_clim' are existing sf objects
+# in your package.
-targets <- dat_species_bin \%>\%
+# Define initial targets for species features.
+initial_targets <- dat_species_bin \%>\%
sf::st_drop_geometry() \%>\%
colnames() \%>\%
data.frame() \%>\%
setNames(c("feature")) \%>\%
dplyr::mutate(target = 0.3)
-CPA_Approach <- splnr_climate_priorityAreaApproach(
+# Run the Climate Priority Area Approach where lower climate metric
+# values mean more climate-smart areas.
+CPA_Approach_result <- splnr_climate_priorityAreaApproach(
features = dat_species_bin,
metric = dat_clim,
- targets = targets,
- direction = -1
+ targets = initial_targets,
+ direction = -1, # Example: lower metric values are more climate-smart
+ percentile = 5,
+ refugiaTarget = 1
)
-out_sf <- CPA_Approach$Features
-targets <- CPA_Approach$Targets
+
+# Access the processed features and targets:
+out_sf_cpa <- CPA_Approach_result$Features
+targets_cpa <- CPA_Approach_result$Targets
+
+print(head(out_sf_cpa))
+print(head(targets_cpa))
+}
}
diff --git a/man/splnr_create_polygon.Rd b/man/splnr_create_polygon.Rd
index 172f4b2..dc43c68 100644
--- a/man/splnr_create_polygon.Rd
+++ b/man/splnr_create_polygon.Rd
@@ -2,24 +2,50 @@
% Please edit documentation in R/utils.R
\name{splnr_create_polygon}
\alias{splnr_create_polygon}
-\title{Function for creating polygon}
+\title{Create Spatial Polygon from Coordinates}
\usage{
splnr_create_polygon(x, cCRS = "EPSG:4326")
}
\arguments{
-\item{x}{A named vector of lon/lat coordinates from which to make an \code{sf} polygon}
+\item{x}{A \code{tibble} (or \code{tbl_df}) object with at least two columns,
+typically named \code{x} (for longitude) and \code{y} (for latitude), representing
+the vertices of the polygon in sequence. The first and last coordinate
+pair should be the same to form a closed polygon.}
-\item{cCRS}{The CRS to use for the polygon}
+\item{cCRS}{A character string specifying the target CRS for the output polygon
+in an EPSG code format (e.g., "EPSG:4326"). Defaults to "EPSG:4326" (WGS 84).}
}
\value{
-An \code{sf} object for the polygon
+An \code{sf} object representing the created polygon, with the specified CRS.
}
\description{
-\code{splnr_create_polygon()} allows you to create a polygon based on longitude and latitude coordinates in your input data.
+\code{splnr_create_polygon()} constructs an \code{sf} polygon object from a series
+of longitude and latitude coordinates provided in a tibble.
+}
+\details{
+This utility function simplifies the creation of spatial polygons from a
+tabular format of coordinates. It takes a tibble where columns 'x' and 'y'
+represent longitude and latitude, respectively. These coordinates are
+converted into a matrix, then to an \code{sf} polygon, and finally to an \code{sf}
+object with the specified Coordinate Reference System (CRS).
+
+The function assumes that the input coordinates (\code{x}) are initially in
+WGS 84 (EPSG:4326) and then transforms them to the \code{cCRS} if a different
+CRS is specified.
}
\examples{
-splnr_create_polygon(x = dplyr::tibble(x = seq(-50, 50, by = 1), y = 120) \%>\%
- dplyr::bind_rows(dplyr::tibble(x = 50, y = seq(120, 180, by = 1))) \%>\%
- dplyr::bind_rows(dplyr::tibble(x = seq(50, -50, by = -1), y = 180)) \%>\%
- dplyr::bind_rows(dplyr::tibble(x = -50, y = seq(150, 120, by = -1))))
+# Example: Create a simple square polygon
+square_coords <- dplyr::tibble(
+ x = c(-50, 50, 50, -50, -50),
+ y = c(120, 120, 180, 180, 120)
+)
+simple_polygon <- splnr_create_polygon(x = square_coords)
+print(simple_polygon)
+
+# Example: Create a polygon and transform to a different CRS (e.g., a UTM zone)
+\dontrun{
+# Note: EPSG:32611 is UTM Zone 11N. Ensure it's appropriate for your coordinates.
+transformed_polygon <- splnr_create_polygon(x = square_coords, cCRS = "EPSG:32611")
+print(transformed_polygon)
+}
}
diff --git a/man/splnr_featureNames.Rd b/man/splnr_featureNames.Rd
index 93f5731..f5d4d8e 100644
--- a/man/splnr_featureNames.Rd
+++ b/man/splnr_featureNames.Rd
@@ -2,23 +2,55 @@
% Please edit documentation in R/utils.R
\name{splnr_featureNames}
\alias{splnr_featureNames}
-\title{Returns the feature names}
+\title{Extract Feature Names from Spatial Data}
\usage{
splnr_featureNames(dat, exclude = NA)
}
\arguments{
-\item{dat}{sf dataframe of features}
+\item{dat}{An \code{sf} dataframe representing conservation features. Each
+non-geometry column is assumed to be a feature.}
-\item{exclude}{Character vector of any columns to exclude}
+\item{exclude}{A character vector of column names (or prefixes) to exclude
+from the output. By default, it excludes columns starting with "Cost_".
+If you provide a value, it will be \emph{appended} to the default exclusion.
+Set to \code{NULL} or \code{character(0)} if you want no exclusions beyond the default.}
}
\value{
-A character vector of names
+A character vector containing the names of the conservation features.
}
\description{
-\code{splnr_featureNames()} allows you to extract the names of features you want to pass to a \code{prioritizr} prioritization.
-It requires an \code{sf} object input and returns the column names of the object excluding any columns you specify in the \code{exclude} argument.
+\code{splnr_featureNames()} extracts the names of conservation features
+from an \code{sf} dataframe, excluding geometry and any specified columns.
+}
+\details{
+This function is a utility for preparing data for \code{prioritizr} or other
+conservation planning packages that require a vector of feature names.
+It typically removes the geometry column and any columns related to cost
+(prefixed with "Cost_") by default, allowing you to specify additional
+columns to exclude.
+
+The output is a simple character vector of column names, which can be
+directly used as feature identifiers in conservation problems.
}
\examples{
-df <- dat_species_prob \%>\%
- splnr_featureNames()
+\dontrun{
+# Assuming 'dat_species_prob' is an existing sf object in your package.
+# It likely has columns like 'Spp1', 'Spp2', 'Cost_SomeMeasure', etc.
+
+# Example 1: Get all feature names, excluding default 'Cost_' columns.
+feature_names_default <- splnr_featureNames(dat = dat_species_prob)
+print(feature_names_default)
+
+# Example 2: Get feature names, excluding 'Cost_' columns and 'Spp5'.
+feature_names_custom_exclude <- splnr_featureNames(
+ dat = dat_species_prob,
+ exclude = "Spp5"
+)
+print(feature_names_custom_exclude)
+
+# Example 3: If you only want to exclude a specific column and not 'Cost_'
+# (you'd need to manually specify exclude = "geometry" and then your column)
+# This case is more complex and usually handled by direct dplyr::select.
+# This function's primary use is to remove cost columns and potentially others.
+}
}
diff --git a/man/splnr_get_IUCNRedList.Rd b/man/splnr_get_IUCNRedList.Rd
index a20c7ff..744f0bd 100644
--- a/man/splnr_get_IUCNRedList.Rd
+++ b/man/splnr_get_IUCNRedList.Rd
@@ -2,44 +2,71 @@
% Please edit documentation in R/splnr_get_IUCNRedList.R
\name{splnr_get_IUCNRedList}
\alias{splnr_get_IUCNRedList}
-\title{Match Species to IUCN RedList}
+\title{Match Species to IUCN RedList Categories}
\usage{
splnr_get_IUCNRedList(df, species_col = "Species")
}
\arguments{
-\item{df}{The dataframe containing the species to be matched with the IUCN redlist}
+\item{df}{The input dataframe containing the species names to be matched.}
-\item{species_col}{A string name for the column containting the species name}
+\item{species_col}{A character string specifying the name of the column in \code{df}
+that contains the species scientific names (e.g., "Species" or "scientific_name").
+Defaults to "Species".}
}
\value{
-A dataframe with an additional column \code{IUCN_Category}
+A dataframe identical to the input \code{df}, but with an additional column
+named \code{IUCN_Category}. If a species is not found on the IUCN Red List, its
+\code{IUCN_Category} will be \code{NA}.
}
\description{
-First of all you will need your own API key, an alphanumeric string provided by IUCN that you need to send in every request;
-the following function takes you to their website, where you will need to fill up a form (it might take 1-2 days to receive your key)
-rl_use_iucn()
-Once you receive an email with your API key, set it up as an environmental variable (it MUST be named IUCN_REDLIST_KEY)
-you will need to re-do this step everytime you restart R
-Sys.setenv(IUCN_REDLIST_KEY = "") OR add IUCN_REDLIST_KEY = "" to your .Renviron file to permanently set it
-Sys.getenv("IUCN_REDLIST_KEY") #' check
-Not Evaluated
-DD: Data Deficient
-LC: Least Concern
-NT: Near Threatened
-VU: Vulnerable
-EN: Endangered
-CR: Critically Endangered
-EW: Extinct in the Wild
-EX: Extinct
-LRlc: Low risk – least concern
-LRnt: Low risk – near threatened
-LRcd: Low risk - conservation dependent
-Categories we care about
-cate <- c("EX","EW","CR","EN","VU")
+The \code{splnr_get_IUCNRedList} function retrieves IUCN Red List category information
+for a given set of species and appends it to your input dataframe.
+}
+\details{
+To use this function, you must first obtain an API key from IUCN. This is an
+alphanumeric string required for every request. You can visit the IUCN website
+to request a key using \code{rl_use_iucn()}. Please note that receiving your key
+might take 1-2 days after submitting the form.
+
+Once you receive your API key, it is crucial to set it as an environment variable
+named \code{IUCN_REDLIST_KEY}. You can do this temporarily for the current R session
+using \code{Sys.setenv(IUCN_REDLIST_KEY = "YOUR_API_KEY_HERE")}. To set it permanently,
+you should add \code{IUCN_REDLIST_KEY = "YOUR_API_KEY_HERE"} to your \code{.Renviron} file.
+You can check if the key is set correctly using \code{Sys.getenv("IUCN_REDLIST_KEY")}.
+
+The IUCN Red List uses various categories to assess extinction risk. This function
+queries the Red List for the following categories:
+\itemize{
+\item \strong{DD}: Data Deficient
+\item \strong{LC}: Least Concern
+\item \strong{NT}: Near Threatened
+\item \strong{VU}: Vulnerable
+\item \strong{EN}: Endangered
+\item \strong{CR}: Critically Endangered
+\item \strong{EW}: Extinct in the Wild
+\item \strong{EX}: Extinct
+\item \strong{LRlc}: Lower Risk / least concern (old category)
+\item \strong{LRnt}: Lower Risk / near threatened (old category)
+\item \strong{LRcd}: Lower Risk / conservation dependent (old category)
+}
+The function will attempt to match your species against any of these categories
+present in the IUCN Red List database.
}
\examples{
\dontrun{
-df <- data.frame(Species = c("Diomedea exulans", "Hippocampus kuda", "Squatina squatina")) \%>\%
+# Ensure your IUCN_REDLIST_KEY is set as an environment variable before running.
+# For example: Sys.setenv(IUCN_REDLIST_KEY = "YOUR_API_KEY_HERE")
+
+# Example: Create a dataframe with species names and retrieve their IUCN Red List categories.
+df_species_redlist <- data.frame(Species = c("Diomedea exulans",
+ "Hippocampus kuda",
+ "Squatina squatina")) \%>\%
splnr_get_IUCNRedList()
+print(df_species_redlist)
+
+# Example with a different column name for species
+df_alt_col <- data.frame(ScientificName = c("Panthera leo", "Orcinus orca")) \%>\%
+ splnr_get_IUCNRedList(species_col = "ScientificName")
+print(df_alt_col)
}
}
diff --git a/man/splnr_get_MPAs.Rd b/man/splnr_get_MPAs.Rd
index f221eed..e184717 100644
--- a/man/splnr_get_MPAs.Rd
+++ b/man/splnr_get_MPAs.Rd
@@ -2,7 +2,7 @@
% Please edit documentation in R/splnr_get_MPAs.R
\name{splnr_get_MPAs}
\alias{splnr_get_MPAs}
-\title{Get marine parks from the WDPA.}
+\title{Get Marine Protected Areas (MPAs) from WDPA}
\usage{
splnr_get_MPAs(
PlanUnits,
@@ -14,31 +14,82 @@ splnr_get_MPAs(
)
}
\arguments{
-\item{PlanUnits}{Planning Units as an \code{sf} object}
+\item{PlanUnits}{An \code{sf} object representing the planning units to be used for intersection.
+This object should have a valid CRS defined.}
-\item{Countries}{A character vector of the countries for which to extract MPAs. To get all MPAs, use \code{"global"} here.}
+\item{Countries}{A character vector specifying the countries for which to extract MPAs.
+To retrieve all global MPAs, use the value \code{"global"}. Country names should match
+those recognized by the WDPA database.}
-\item{Status}{The status field in the WDPA provides information on whether a protected area has been established, designated, or proposed at the time the data was submitted.}
+\item{Status}{A character vector specifying the desired status of protected areas
+to include. Defaults to \code{c("Designated", "Established", "Inscribed")}.}
-\item{Desig}{The designation type is the category or type of protected area as legally/officially designated or proposed.}
+\item{Desig}{A character vector specifying the desired designation types of
+protected areas. Defaults to \code{c("National", "Regional", "International", "Not Applicable")}.}
-\item{Category}{Stores the IUCN Protected Area Management Categories (recorded in field IUCN_CAT) for each of the protected areas where these categories are reported}
+\item{Category}{A character vector specifying the desired IUCN Protected Area
+Management Categories. Defaults to \code{c("Ia", "Ib", "II", "III", "IV")}.}
-\item{...}{Other arguments passed to \code{wdpa_fetch()}}
+\item{...}{Other arguments that are passed directly to the \code{wdpa_fetch()} function
+from the \code{wdpar} package (e.g., \code{verbose = TRUE}).}
}
\value{
-A \code{sf} object with the MPAs intersected with the planning units
+An \code{sf} object. This object contains the planning units, with an
+additional \code{wdpa} column (set to 1) for areas that intersect with the
+selected MPAs.
}
\description{
-This code is a wrapper for the wonderful \code{wdpar} package written by Jeffrey O. Hanson. This data is then interfaced with the planning units.
-An \code{sf} object is returned with the PU area covered by the selected marine protected areas.
+This function serves as a wrapper for the \code{wdpar} package, facilitating the
+retrieval of Marine Protected Areas (MPAs) from the World Database on Protected
+Areas (WDPA) and intersecting them with provided planning units.
+The result is an \code{sf} object indicating the area of planning units covered by
+the selected marine protected areas.
+}
+\details{
+This function leverages the robust capabilities of the \code{wdpar} package by
+Jeffrey O. Hanson to access and process WDPA data. It allows filtering of MPAs
+based on country, status, designation type, and IUCN category, and then
+spatially intersects these MPAs with your defined planning units.
+
+For a comprehensive understanding of the WDPA data fields:
+\itemize{
+\item \strong{Status}: Refers to the establishment, designation, or proposal
+status of a protected area at the time of data submission. Valid options
+include "Designated", "Established", "Inscribed", "Proposed", and "Adopted".
+\item \strong{Desig} (Designation Type): Categorizes the legal or official
+designation of the protected area. Valid options include "National",
+"Regional", "International", and "Not Applicable".
+\item \strong{Category} (IUCN Protected Area Management Categories): Represents
+the IUCN management categories for protected areas. Valid options include
+"Ia", "Ib", "II", "III", "IV", "V", "VI", "Not Reported", "Not Applicable",
+and "Not Assigned".
+}
}
\examples{
-dat <- splnr_get_MPAs(PlanUnits = dat_PUs, Countries = "Australia")
+\dontrun{
+# Assuming 'dat_PUs' is an existing sf object of planning units in your package.
+
+# Example: Get MPAs for Australia and intersect with planning units.
+dat_mpas <- splnr_get_MPAs(PlanUnits = dat_PUs, Countries = "Australia")
+# Example: Get MPAs for multiple countries with specific status and categories.
+dat_mpas_specific <- splnr_get_MPAs(
+ PlanUnits = dat_PUs,
+ Countries = c("Australia", "New Zealand"),
+ Status = c("Designated", "Proposed"),
+ Category = c("II", "IV")
+)
+
+# Example: Visualize the result using ggplot2.
+# Assuming 'aust' is an sf object representing Australia's coastline,
+# perhaps loaded from rnaturalearth::ne_countries.
aust <- rnaturalearth::ne_countries(country = "Australia", returnclass = "sf")
gg <- ggplot2::ggplot() +
- ggplot2::geom_sf(data = dat, ggplot2::aes(fill = wdpa)) +
- ggplot2::geom_sf(data = aust, fill = "grey50")
+ ggplot2::geom_sf(data = dat_mpas, ggplot2::aes(fill = wdpa)) +
+ ggplot2::geom_sf(data = aust, fill = "grey50") +
+ ggplot2::labs(title = "Marine Protected Areas in Australia") +
+ ggplot2::theme_minimal()
+print(gg)
+}
}
diff --git a/man/splnr_get_boundary.Rd b/man/splnr_get_boundary.Rd
index a7b1c7c..a6aa7e2 100644
--- a/man/splnr_get_boundary.Rd
+++ b/man/splnr_get_boundary.Rd
@@ -2,27 +2,64 @@
% Please edit documentation in R/splnr_get_boundary.R
\name{splnr_get_boundary}
\alias{splnr_get_boundary}
-\title{Get the boundary of the planning region.}
+\title{Create a Planning Region Boundary}
\usage{
splnr_get_boundary(Limits, Type = NULL, res = 1, cCRS = "ESRI:54009")
}
\arguments{
-\item{Limits}{The limits of the boundary. This can either be a 4 element numeric named vector (c(xmin = 150, xmax = 160, ymin = -40, ymax = -30)), a vector of ocean/sea names, or a vector of EEZs.,}
+\item{Limits}{A required input that defines the spatial extent. This can be:
+\itemize{
+\item A named numeric vector of four elements: \code{c("xmin" = ..., "xmax" = ..., "ymin" = ..., "ymax" = ...)}.
+\item The string \code{"Global"} to create a worldwide boundary.
+\item A character vector of ocean/sea names (e.g., \code{"North Atlantic Ocean"}) to be used with \code{Type = "Ocean"}.
+}}
-\item{Type}{The type of Limits being provided. Options are "Ocean" or "EEZ". (not required if numeric or "Global" limits are provided)}
+\item{Type}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} The type of Limits being provided. This is only required if \code{Limits} is a character vector of ocean names, in which case it should be \code{"Ocean"}. It is no longer required and will be removed in a future version.}
-\item{res}{The resolution (in degrees) from which to create the boundary polygon if numeric limits are provided.}
+\item{res}{\verb{[numeric(1)]}\cr The resolution (in decimal degrees) used to
+construct the polygon vertices when \code{Limits} is numeric or \code{"Global"}.
+Defaults to \code{1}. Must be a positive number.}
-\item{cCRS}{The CRS the boundary is to be returned in}
+\item{cCRS}{\verb{[character(1)]}\cr The coordinate reference system (CRS) for the
+output \code{sf} object. Can be a PROJ4 string or an EPSG code. Defaults to
+\code{"ESRI:54009"} (Mollweide).}
}
\value{
-The boundary of the planning region
+An \code{sf} object containing a single polygon feature representing the
+planning boundary.
}
\description{
-\code{splnr_get_boundary()} allows to create an \code{sf} object of your planning region either based on specific coordinate information, or \code{rnaturalearth} inputs such as ocean data. Creating a boundary is often the first step in conservation planning and a requirement for downstream function sin \code{spatialplanr}.
+This function generates a spatial boundary for the planning region as an \code{sf}
+polygon object. The boundary can be defined in several ways:
+\enumerate{
+\item A simple rectangular bounding box using numeric coordinates.
+\item A global boundary spanning the entire world.
+\item A complex shape based on marine ecoregions from \code{rnaturalearth}.
+}
+}
+\details{
+A planning region boundary is the foundational first step for most spatial
+conservation planning exercises. All subsequent analyses and data preparation
+steps within the \code{spatialplanr} package rely on a defined boundary. The
+coordinate reference system (CRS) of the returned object is projected by
+default (Mollweide), which is suitable for equal-area calculations.
}
\examples{
-Bndry <- splnr_get_boundary(Limits = "North Atlantic Ocean", Type = "Ocean")
-Bndry <- splnr_get_boundary(Limits = "Global")
-Bndry <- splnr_get_boundary(Limits = c("xmin" = 150, "xmax" = 170, "ymin" = -40, "ymax" = -20))
+\dontrun{
+# Example 1: Create a boundary from an ocean name.
+# This fetches polygon data for the specified ocean.
+bndry_ocean <- splnr_get_boundary(Limits = "North Atlantic Ocean", Type = "Ocean")
+plot(bndry_ocean)
+
+# Example 2: Create a global boundary.
+bndry_global <- splnr_get_boundary(Limits = "Global")
+plot(bndry_global)
+
+# Example 3: Create a boundary from a numeric bounding box.
+bndry_coords <- splnr_get_boundary(
+ Limits = c("xmin" = 150, "xmax" = 170, "ymin" = -40, "ymax" = -20)
+)
+plot(bndry_coords)
+}
}
+\concept{planning_region}
diff --git a/man/splnr_get_distCoast.Rd b/man/splnr_get_distCoast.Rd
index 3bcc6d4..f4fce31 100644
--- a/man/splnr_get_distCoast.Rd
+++ b/man/splnr_get_distCoast.Rd
@@ -2,47 +2,68 @@
% Please edit documentation in R/splnr_get_distCoast.R
\name{splnr_get_distCoast}
\alias{splnr_get_distCoast}
-\title{Function to compute distances to nearest coastline for each centroid of each planning unit in the 'sf' object provided.}
+\title{Calculate Distance to Coastline}
\usage{
-splnr_get_distCoast(dat_sf, custom_coast = NULL, res = NULL)
+splnr_get_distCoast(dat_sf, custom_coast = NULL, res = "medium")
}
\arguments{
-\item{dat_sf}{An sf object.}
+\item{dat_sf}{\verb{[sf]} \cr An \code{sf} object containing polygon or point features
+representing the planning units. Must have a valid CRS.}
-\item{custom_coast}{An sf coastline object (optional)}
+\item{custom_coast}{\verb{[sf]} \cr An optional \code{sf} object representing a
+custom coastline. If \code{NULL} (the default), the coastline is downloaded
+from \code{rnaturalearth}.}
-\item{res}{Allow user to choose resolution (\code{small}, \code{medium}, \code{large}) of \code{rnaturalearth} data used for coastline.}
+\item{res}{\verb{[character(1)]} \cr The resolution of the \code{rnaturalearth}
+coastline to use. Options are \code{"small"}, \code{"medium"} (default), or
+\code{"large"}. This parameter is ignored if \code{custom_coast} is provided.}
}
\value{
-An \code{sf} object with distances to the nearest coast
+An \code{sf} object identical to \code{dat_sf} but with an added column
+\code{coastDistance_km} representing the distance to the nearest coastline in
+kilometers.
}
\description{
-The code takes a sf object and return it updated with a new coastDistance column.
-The output inherits the crs from this sf object so ensure it is in the correct projection for your needs
+This function calculates the shortest distance from the centroid of each
+planning unit in an \code{sf} object to the nearest coastline. It can use either
+a default coastline from the \code{rnaturalearth} package or a custom-provided
+coastline \code{sf} object.
}
\details{
-Written by Kristine Buenafe
-Written: March/April 2023
-Modified by Kilian Barreiro
-Updated: December 2023
+The function adds a new column named \code{coastDistance_km} to the input \code{sf}
+object, containing the calculated distances in kilometers. The CRS of the
+input data is preserved. It is crucial to ensure the input \code{sf} object has
+a suitable projected CRS for accurate distance calculations.
}
\examples{
+\dontrun{
+# Example 1: Calculate distance to coast for a simple grid
bbox <- sf::st_bbox(c(xmin = 0, ymin = 0, xmax = 3, ymax = 3))
-grid <- sf::st_make_grid(bbox, n = c(3, 3), what = "polygons")
-grid <- sf::st_sf(geometry = grid) \%>\%
- sf::st_set_crs("EPSG:4326")
-splnr_get_distCoast(grid)
+grid <- sf::st_as_sf(sf::st_make_grid(bbox, n = c(3, 3)))
+grid_with_dist <- splnr_get_distCoast(grid)
+plot(grid_with_dist["coastDistance_km"])
-cCRS <- "ESRI:54009"
-
-Bndry <- splnr_get_boundary(Limits = "Coral Sea",
- Type = "Oceans",
- cCRS = cCRS)
+# Example 2: Using a specific resolution for the coastline
+# Note: Requires the 'dat_sf' object to be created first, e.g., using
+# splnr_get_planning_units()
+if (exists("dat_sf")) {
+ dat_sf_dist <- splnr_get_distCoast(dat_sf, res = "large")
+ summary(dat_sf_dist$coastDistance_km)
+}
+# Example 3: Using a custom coastline
+# First, create a custom coastline (e.g., from a country polygon)
landmass <- rnaturalearth::ne_countries(
scale = "medium",
returnclass = "sf"
-) \%>\%
- sf::st_transform(cCRS)
+)
+if (exists("dat_sf") && exists("landmass")) {
+ # Transform landmass to the same CRS as the planning units
+ landmass_proj <- sf::st_transform(landmass, sf::st_crs(dat_sf))
+ dat_sf_custom_coast <- splnr_get_distCoast(dat_sf, custom_coast = landmass_proj)
+ summary(dat_sf_custom_coast$coastDistance_km)
+}
+}
}
+\concept{cost_features}
diff --git a/man/splnr_get_featureRep.Rd b/man/splnr_get_featureRep.Rd
index 90dd70e..19b80d2 100644
--- a/man/splnr_get_featureRep.Rd
+++ b/man/splnr_get_featureRep.Rd
@@ -2,7 +2,7 @@
% Please edit documentation in R/splnr_featureRep.R
\name{splnr_get_featureRep}
\alias{splnr_get_featureRep}
-\title{Prepare data to plot how well targets are met}
+\title{Prepare Data to Plot How Well Targets Are Met}
\usage{
splnr_get_featureRep(
soln,
@@ -14,27 +14,97 @@ splnr_get_featureRep(
)
}
\arguments{
-\item{soln}{The \code{prioritizr} solution}
+\item{soln}{An \code{sf} object representing the \code{prioritizr} solution, containing
+a column indicating selected planning units (default: \code{solution_1}).}
-\item{pDat}{The \code{prioritizr} problem}
+\item{pDat}{A \code{prioritizr} problem object, as defined by \code{prioritizr::problem()}.
+This object provides the original feature data and targets.}
-\item{targets}{\code{data.frame}with list of features under "feature" column and their corresponding targets under "target" column}
+\item{targets}{A \code{data.frame} (optional). If provided, it should contain a
+\code{feature} column (character) and a \code{target} column (numeric). This is used
+to override or supplement targets from \code{pDat}, especially for climate-smart
+approaches where targets might be pre-adjusted. Defaults to \code{NA}.}
-\item{climsmart}{logical denoting whether spatial planning was done climate-smart (and targets have to be calculated differently)}
+\item{climsmart}{A logical value (\code{TRUE} or \code{FALSE}). If \code{TRUE}, special
+handling for climate-smart approaches is enabled. Defaults to \code{FALSE}.}
-\item{climsmartApproach}{either 0,1,2 or 3 depending on the climate-smart approach used (0 = None; 1 = Climate Priority Area; 2 = Feature; 3 = Percentile).}
+\item{climsmartApproach}{An integer (0, 1, 2, or 3) indicating the type of
+climate-smart approach used:
+\itemize{
+\item \code{0}: No climate-smart approach.
+\item \code{1}: Climate Priority Area approach (features split into CS/NCS).
+\item \code{2}: Feature approach (not explicitly handled in this function's
+\code{climsmart} logic, targets taken from \code{pDat} by default).
+\item \code{3}: Percentile approach (features are filtered).
+}
+Defaults to \code{0}.}
-\item{solnCol}{Name of the column with the solution}
+\item{solnCol}{A character string specifying the name of the column in \code{soln}
+that contains the binary solution (1 for selected, 0 for not selected).
+Defaults to \code{"solution_1"}.}
}
\value{
-\code{tbl_df} dataframe
+A \code{tibble} dataframe containing the \code{feature} names, their
+\code{total_amount} (total units available), \code{absolute_held} (total units
+selected), \code{relative_held} (proportion held), \code{target} (conservation target),
+and \code{incidental} (TRUE if target was 0 or NA, but feature still present).
}
\description{
-Prepare data to plot how well targets are met
+\code{splnr_get_featureRep()} calculates the representation of conservation
+features within a \code{prioritizr} solution. This function determines how much
+of each feature's total abundance (or area) is captured in the selected
+planning units, and compares it against specified conservation targets.
+It can also account for different climate-smart planning approaches.
+}
+\details{
+This function processes the output of a \code{prioritizr} conservation problem
+(\code{soln}) and its corresponding problem definition (\code{pDat}) to provide a
+summary of feature representation. It is designed to work whether or not
+explicit targets are provided, and can adjust calculations based on the
+climate-smart approach used.
+
+The function calculates:
+\itemize{
+\item \code{total_amount}: The total available amount/area of each feature across all planning units.
+\item \code{absolute_held}: The total amount/area of each feature captured in the
+\emph{selected} planning units (where \code{solution_1} is 1).
+\item \code{relative_held}: The proportion of \code{absolute_held} relative to \code{total_amount},
+indicating the percentage representation of the feature in the solution.
+\item \code{target}: The conservation target for each feature (either from the
+\code{pDat} problem definition or the \code{targets} dataframe).
+\item \code{incidental}: A logical flag indicating if a feature's representation
+was 'incidental' (i.e., its target was 0 or NA, but it was still
+partially or fully captured in the solution).
+}
+
+\strong{Climate-Smart Considerations (\code{climsmart = TRUE}):}
+If \code{climsmart} is \code{TRUE}, the function adjusts its calculations based on the
+\code{climsmartApproach} parameter:
+\itemize{
+\item \code{climsmartApproach = 1} (Climate Priority Area): The function sums the
+\code{absolute_held} and \code{total_amount} for features that were split into
+\verb{_CS} (Climate-Smart) and \verb{_NCS} (Non-Climate-Smart) components. This
+provides a single, aggregated representation for the original feature,
+allowing comparison with its original target.
+\item \code{climsmartApproach = 3} (Percentile Approach): The function directly
+uses the targets provided in the \code{targets} dataframe, which are
+expected to be adjusted for the percentile approach.
+\item For other \code{climsmartApproach} values or if \code{climsmart} is \code{FALSE},
+targets are taken directly from the \code{prioritizr} problem's target data.
+}
+
+The output dataframe is designed to be directly plottable by functions
+like \code{splnr_plot_featureRep()}.
}
\examples{
-pDat <- prioritizr::problem(dat_species_bin \%>\% dplyr::mutate(Cost = runif(n = dim(.)[[1]])),
- features = c("Spp1", "Spp2", "Spp3"),
+\dontrun{
+# Assuming 'dat_species_bin' is an existing sf object with binary species data
+# and 'Cost' column.
+
+# Create a dummy prioritizr problem for basic demonstration
+pDat_basic <- prioritizr::problem(
+ dat_species_bin \%>\% dplyr::mutate(Cost = runif(n = dim(.)[[1]])),
+ features = c("Spp1", "Spp2", "Spp3", "Spp4", "Spp5"),
cost_column = "Cost"
) \%>\%
prioritizr::add_min_set_objective() \%>\%
@@ -42,11 +112,62 @@ pDat <- prioritizr::problem(dat_species_bin \%>\% dplyr::mutate(Cost = runif(n =
prioritizr::add_binary_decisions() \%>\%
prioritizr::add_default_solver(verbose = FALSE)
-soln <- pDat \%>\%
+# Solve the problem
+soln_basic <- pDat_basic \%>\%
prioritizr::solve.ConservationProblem()
-df <- splnr_get_featureRep(
- soln = soln,
- pDat = pDat
+# Get feature representation for a basic (non-climate-smart) solution
+df_basic_rep <- splnr_get_featureRep(
+ soln = soln_basic,
+ pDat = pDat_basic
+)
+print(df_basic_rep)
+
+# Example with Climate Priority Area (CPA) approach
+# Assuming 'dat_clim' is an sf object with a 'metric' column.
+# These would typically come from splnr_climate_priorityAreaApproach()
+# For example purposes, we'll create some dummy data and targets.
+
+# Simulate CPA processed features and targets
+cpa_features_sim <- dat_species_bin \%>\%
+ dplyr::mutate(
+ Spp1_CS = ifelse(Spp1 == 1 & runif(n()) < 0.5, 1, 0),
+ Spp1_NCS = ifelse(Spp1 == 1 & Spp1_CS == 0, 1, 0),
+ Spp2_CS = ifelse(Spp2 == 1 & runif(n()) < 0.6, 1, 0),
+ Spp2_NCS = ifelse(Spp2 == 1 & Spp2_CS == 0, 1, 0),
+ Spp3_CS = ifelse(Spp3 == 1 & runif(n()) < 0.7, 1, 0),
+ Spp3_NCS = ifelse(Spp3 == 1 & Spp3_CS == 0, 1, 0)
+ ) \%>\%
+ dplyr::select(Spp1_CS, Spp1_NCS, Spp2_CS, Spp2_NCS, Spp3_CS, Spp3_NCS, geometry)
+
+cpa_targets_sim <- data.frame(
+ feature = c("Spp1_CS", "Spp1_NCS", "Spp2_CS", "Spp2_NCS", "Spp3_CS", "Spp3_NCS"),
+ target = c(0.8, 0.2, 0.9, 0.1, 0.7, 0.3) # Example targets for CS/NCS parts
)
+
+# Create a problem with the simulated CPA features
+pDat_cpa_sim <- prioritizr::problem(
+ cpa_features_sim \%>\% dplyr::mutate(Cost = runif(n = dim(.)[[1]])),
+ features = c("Spp1_CS", "Spp1_NCS", "Spp2_CS", "Spp2_NCS", "Spp3_CS", "Spp3_NCS"),
+ cost_column = "Cost"
+) \%>\%
+ prioritizr::add_min_set_objective() \%>\%
+ prioritizr::add_relative_targets(cpa_targets_sim$target, cpa_targets_sim$feature) \%>\%
+ prioritizr::add_binary_decisions() \%>\%
+ prioritizr::add_default_solver(verbose = FALSE)
+
+# Solve the CPA problem
+soln_cpa_sim <- pDat_cpa_sim \%>\%
+ prioritizr::solve.ConservationProblem()
+
+# Get feature representation for CPA approach
+df_cpa_rep <- splnr_get_featureRep(
+ soln = soln_cpa_sim,
+ pDat = pDat_cpa_sim,
+ targets = cpa_targets_sim, # Pass the original CPA targets
+ climsmart = TRUE,
+ climsmartApproach = 1 # Indicate CPA approach
+)
+print(df_cpa_rep)
+}
}
diff --git a/man/splnr_get_gfw.Rd b/man/splnr_get_gfw.Rd
index 85dc2cd..c99b60d 100644
--- a/man/splnr_get_gfw.Rd
+++ b/man/splnr_get_gfw.Rd
@@ -2,8 +2,7 @@
% Please edit documentation in R/splnr_get_gfw.R
\name{splnr_get_gfw}
\alias{splnr_get_gfw}
-\title{The \code{get_gfwData} function recover the data of Global Fishing Watch and
-returns it as a sf object.}
+\title{Retrieve Global Fishing Watch Data}
\usage{
splnr_get_gfw(
region,
@@ -18,54 +17,88 @@ splnr_get_gfw(
)
}
\arguments{
-\item{region}{Region studied (character) or a geojson shape to filter raster}
+\item{region}{A character string specifying the name of the region (e.g., an EEZ name)
+or a numeric ID for the region, or an \code{sf} object if \code{region_source} is set
+to "USER_SHAPEFILE".}
-\item{start_date}{Start date (waited format : "\%Y-\%m-\%d").}
+\item{start_date}{The start date for data retrieval, expected in "\%Y-\%m-\%d" format (e.g., "2021-01-01").}
-\item{end_date}{End date (waited format : "\%Y-\%m-\%d").}
+\item{end_date}{The end date for data retrieval, expected in "\%Y-\%m-\%d" format (e.g., "2022-12-31").}
-\item{temp_res}{Temporal resolution ("daily","monthly","yearly").}
+\item{temp_res}{The desired temporal resolution for the data. Must be one of:
+"DAILY", "MONTHLY", or "YEARLY".}
-\item{spat_res}{Spatial resolution ("low" for 0.1 degree, "high" for 0.01 degree).}
+\item{spat_res}{The desired spatial resolution for the data. Must be one of:
+"LOW" (0.1 degree) or "HIGH" (0.01 degree). Defaults to "LOW".}
-\item{region_source}{source of the region ('eez','mpa', 'rfmo' or 'user_json')}
+\item{region_source}{The source of the region definition. Must be one of:
+'EEZ', 'MPA', 'RFMO', or 'USER_SHAPEFILE'. Defaults to "EEZ".}
-\item{key}{Token for GFW API (see details GlobalFishingWatch vignette).}
+\item{key}{Your API token for the GFW API. If not provided, it attempts to
+authenticate using \code{gfwr::gfw_auth()}. See the GlobalFishingWatch vignette
+for details on obtaining a key.}
-\item{cCRS}{The crs to which the sf will be returned (default = "EPSG:4326").}
+\item{cCRS}{The Coordinate Reference System (CRS) to which the output \code{sf} object
+will be transformed. Defaults to "EPSG:4326".}
-\item{compress}{Binary operator to compress (aggregate) the data per coordinates (default = FALSE).}
+\item{compress}{A logical value. If \code{TRUE}, the data will be compressed (aggregated)
+by coordinates, summing fishing hours for each unique location. If \code{FALSE},
+the raw data points are returned. Defaults to \code{FALSE}.}
}
\value{
-An \code{sf} object with gfw data.
+An \code{sf} object containing the requested GFW data. The structure of
+the \code{sf} object will vary depending on the \code{compress} and \code{temp_res}
+parameters.
}
\description{
-The possibilities offered by this function are explained in \code{vignette("GlobalFishingWatch")}
+The \code{splnr_get_gfw} function retrieves Global Fishing Watch (GFW) data and
+returns it as an \code{sf} (simple features) object. This function allows for
+flexible data queries based on geographical region, time range, and desired
+spatial and temporal resolutions.
}
\details{
-We have the same parameters than the \code{get_raster} function, plus \code{cCRS}
-which is the crs for the sf_modification \if{html}{\out{gfwr)The gfwr package provides convenient functions to pull
-GFW data directly into R into usable formats. It contains three main
-functions, including : get_vessel_info(),
-get_event() and get_raster(). The two first
-being devoted to retrieving information and features on one ore several
-specific vessels. The last is of particular interest to us because it
-allows us to gather information from global fishing watch raster on the
-fishing effort (further details in the function appropriate section).
-Here we mainly use the splnr_get_gfw function which has
-been created to enable data to be retrieved and processed in a variety
-of ways, some of which are described here.
The time spent fishing is computed using Automatic Identification -System (AIS) data, which is transmitted by most industrial fishing -vessels. The AIS data provides information on the location, speed, and -direction of the vessel, which can be used to identify when the vessel -is actively fishing.
-The AIS coverage of vessels has several limitations such as:
-1. The number of vessels that are captured (AIS provides approximately
-70’000 of the 2.8 million identified fishing vessels).
-2. The size of the vessels (52-85% for vessels larger than 24 meters
-against 1% for vessels under 12 meters).
-Good to know: IMO mandates AIS for most vessels larger than 36
-meters.
-3. AIS interference with each other in areas of high vessel
-density.
-4. Some terrestrial satellites only receive messages near shore.
To access GFW APIs, you need to :
1. register for a GFW account
-here.
-2. Request API key here.
Once you have your token, add it to your .Renviron file (by executing
-the chunk below), by writing (GFW_TOKEN = “YOUR_TOKEN”) in the file.
-
(You could be asked to restart R for changes to take
-effect.)
We save the key in an object that will be used in gfwr functions.
- -A region_id is necessary to use the get_raster
-function.
region_id <- gfwr::get_region_id(region_name = "Australia",
- region_source = "EEZ",
- key = gfwr::gfw_auth())$idThe get_raster function gets a raster of fishing effort
-from the API and converts the response to a data frame which contains
-occurrences for each vessel and for each grid cell (data is binned into
-grid cells of different resolution), the Vessel IDs,
-Flag, Geartype and
-Apparent fishing Hours which are basically the amount of
-fishing hours of each vessel per grid cell (geometry).
Data can be provided through :
- DAILY,
-MONTHLY and YEARLY temporal resolutions.
-- LOW (0.1 deg) and HIGH (0.01 deg) spatial
-resolutions.
- VESSEL_ID, FLAG,
-GEARTYPE, FLAGANDGEARTYPE.
gfwr::get_raster(
- spatial_resolution = "LOW",
- temporal_resolution = "MONTHLY",
- group_by = "FLAGANDGEARTYPE",
- start_date = "2022-01-01",
- end_date = "2023-01-01",
- region = region_id,
- region_source = "EEZ",
- key = gfwr::gfw_auth()
-)(You can remove the option message = FALSE
-to see the columns types.)
get_raster caveats and limitations.Date range is limited to 1-year. Nevertheless, with some
-modifications, we can get round these problems through
-splnr_get_gfw.
To display the data, we load :
- The coastline from
-rnaturalearth package and modify it to get an sf object,
-and we constrain it to the boundaries of the given data.
- EEZ
-Polygons from oceandatr package
# Check and modify if necessary the spatial reference of data_sf_combined
-data_sf_combined <- sf::st_set_crs(data_sf_combined,
- sf::st_crs(rnaturalearth::ne_coastline(scale = "large")))
-
-coast_clipped <- rnaturalearth::ne_coastline(scale = "large") %>%
- sf::st_as_sf() %>%
- sf::st_intersection(sf::st_as_sfc(sf::st_bbox(data_sf_combined)))
-
-# Load EEZ polygons
-eezs <- spatialgridr::get_boundary(name = "Australia", type = "eez", country_type = "country") %>%
- sf::st_transform(crs = sf::st_crs(data_sf_combined)) %>%
- sf::st_make_valid() %>%
- sf::st_intersection(sf::st_as_sfc(sf::st_bbox(data_sf_combined)))
We may need to compare different timeframes, such as seasons, to see
-if there are any patterns.
Note : As more vessels
-have adopted AIS (mainly in economically developed countries) since the
-deployment of these technologies, the rise in activities must be seen in
-the context of this increase and not necessarily of more intense fishing
-activity.
# We need to change the temporal range according to our need group by it to display the total fishing hours. <br>
-data_sf_combined <- splnr_get_gfw(region = "Australia",
- start_date = "2019-01-01",
- end_date = "2023-12-31",
- temp_res = "MONTHLY",
- key = gfwr::gfw_auth()) %>%
- dplyr::group_by(Year, Month) %>%
- dplyr::summarize(Total_Fishing_Hours = sum(ApparentFishingHrs))
Here we display the Vessel activity in ‘Micronesia’ in 2020 according -to the fishing gear type.
-data_sf_combined <- splnr_get_gfw(region = "Micronesia",
- start_date = "2019-12-31",
- end_date = "2021-01-01",
- temp_res = "MONTHLY")
Here we display the Vessel activity in Papua New Guinea according to -Vessels flags.
-
The fishing detection model was trained on AIS data from 503 vessels -and identified fishing activity with over 90% accuracy, which means that -it can identify a fishing and non-fishing activity with high accuracy. -More details on AIS operation and limitations here.
-
-
Source : https://globalfishingwatch.org/datasets-and-code-vessel-identity/ -
-