Package overview

The ReefPartitionUniversal R package provides functions for partitioning coral reef spatial areas into smaller sites (such as for logistic and monitoring purposes) based on raster data layers. The package provides functions for extracting points on a reef based on habitat types, extracting values for additional raster layers such as bathymetry. Points can then be clustered into sites within habitat types based on their geographic attributes as well as additional variable values such as point depth.

The package uses a flexible framework allowing multiple additional raster layers to be used, along with user defined point clustering algorithms. The package itself defines three spatial clustering algorithm options, using adespatial::constr.hclust (Guénard and Legendre, 2022), spdep::skater (AssunÇão et al. 2007), and an adaptation of the skater algorithm that is optimised for performance using igraph methods.

Installation

# Install package using GitHub repo
remotes::install_github("open-AIMS/ReefPartitionUniversal")

The package combines functionality from raster and vector data processing packages. Dependencies include: sf, terra, sfnetworks, h3, igraph, spdep, adespatial, dplyr and magrittr

Development installation

The most convenient way to install the package for local development is to clone the GitHub repository, create a branch and use the following command to install the package from source code.

# Install package from local source folder/repo
devtools::install("path to package folder")

Basic demonstration

The following code demonstrates a basic usage of ReefPartitionUniversal using an adapted version of the spdep::skater clustering algorithm and Minimum Spanning Tree inputs. For more information on partitioning workflows using different types of data see Articles.

library(ReefPartitionUniversal)

# Load input data (ensuring all are use the same CRS)
target_reef <- sf::st_read("target_reef.gpkg") # Defines the spatial extent of the reef
habitat <- terra::rast("habitat_raster.tif") # Defines the habitat points to extract from
bathymetry <- terra::rast("bathymetry_raster.tif") # Contains additional variable values for extraction and clustering

habitat_categories <- c(1, 10, 20) # Assess only habitat points with these values

# Extract point values from raster layers
points <- extract_point_pixels(target_reef, habitat, bathymetry, habitat_categories)
points$UNIQUE_ID <- "ReefOne"

# Cluster points using skater_igraph algorithm
clustered_points <- cluster_reef_points(points)

# Collate points from each site/cluster into polygons
clustered_sites <- pixels_to_polygons(clustered_points)

# Optional: Apply post-processing to point clusters to ensure that non-contiguous
# clusters adhere to a maximum distance between areas.
sites_post_processed <- site_postprocessing(clustered_sites)

Using multiple additional variable sources

To use multiple additional data sources for clustering, each data source must be extracted separately and then joined together. Two point datasets are created containing the same habitat points, but different additional data columns. Once joined these additional data columns can be passed onto clustering.

Using the above basic demonstration example while adding wave exposure as a second additional variable.

library(ReefPartitionUniversal)
library(tidyverse)

# Load input data (ensuring all are use the same CRS)
target_reef <- sf::st_read("target_reef.gpkg") # Defines the spatial extent of the reef
habitat <- terra::rast("habitat_raster.tif") # Defines the habitat points to extract from
bathymetry <- terra::rast("bathymetry_raster.tif") # Contains additional variable values for extraction and clustering
wave_exposure <- terra::rast("wave_exposure_raster.tif")

habitat_categories <- c(1, 10, 20) # Assess only habitat points with these values

# Extract point values from raster layers
point_depth_data <- extract_point_pixels(
    target_reef, 
    habitat, 
    bathymetry, 
    habitat_categories,
    additional_variable_name = "depth"
)
point_wave_data <- extract_point_pixels(
    target_reef, 
    habitat, 
    wave_exposure, 
    habitat_categories,
    additional_variable_name = "wave_exposure"
)

# point_depth_data and point_wave_data contain the same habitat points, but
# different extracted continuous variables. These can be combined using `left_join`.
points <- left_join(
    point_depth_data, 
    point_wave_data[, c("X", "Y", "wave_exposure"), drop = TRUE],
    by = c("X", "Y")
)

points <- points[!is.na(points$depth), ]
points <- points[!is.na(points$wave_exposure), ]
points$UNIQUE_ID <- "ReefOne"

# Cluster points using adespatial::constr.hclust algorithm
# The default column arguments must be altered to include wave exposure
clustered_points <- cluster_reef_points(
    points,
    additional_variable_cols = c("depth", "wave_exposure"),
    clustering_function_args = list(
        additional_variable_cols = c("depth_standard", "wave_exposure_standard")
    )
)

License

This repository is licensed under MIT License.

Development

Any problems and/or suggestions encountered with this package can be logged in as GitHub issues.

This R package follows the tidyverse styleguide.

Formatting

Code in this package can be auto-formatted to follow the tidyverse styleguide using a formatter such as Air. Once installed for the chosen IDE, using Air commands will reformat R files, modifying the whitespace, linespace and punctuation to follow the tidyverse styleguide.

Additionally, Air has been set up to check file formatting when a new Pull Request is made.