A Novel Framework for Automated Compositional Dissimilarity and Biodiversity Turnover Analysis

Introduction

Quantifying dissimilarity is central to ecology and biodiversity science. Whether comparing communities across landscapes, examining functional distances between species, or assessing environmental contrasts, dissimilarity metrics underpin analyses of diversity, turnover, and ecological change. However, these metrics are often scattered across packages, calculated inconsistently, or tailored to a single data type (e.g., species composition only).

dissmapr provides a unified, transparent, and reproducible workflow for calculating and analysing dissimilarities in biodiversity composition. The package supports data acquisition, environmental linking, computation of order-wise dissimilarity, and mapping of bioregional patterns, leveraging tools like zetadiv (for multi-site generalized dissimilarity modelling, MS-GDM), terra, sf, and ggplot2.

By combining flexible metric choice with consistent data handling and mapping functions, dissmapr is designed to streamline biodiversity workflows, support cross-study comparability, and provide decision-relevant outputs for conservation and global change research.

Core Concepts

Occurrence data – harmonising raw biodiversity records and linking them to spatial grids.
Environmental data – retrieving, processing, and attaching environmental predictors to sites.
Order-wise dissimilarity – extending beyond pairwise turnover to higher-order zeta diversity metrics.
Predictive modelling – using MS-GDM to model compositional turnover across spatial and environmental gradients.
Bioregional mapping – clustering and interpolating sites to delineate bioregions and track changes.

Together, these concepts provide a workflow for exploring biodiversity structure across ecological, functional, and environmental dimensions.

Main Functions

The package is structured around modular steps, so users can build end-to-end workflows or extract individual components.

Data Handling

get_occurrence_data() – Import and harmonise biodiversity-occurrence data.
generate_grid() – Generate spatial grids and gridded summaries.
assign_mapsheet() – Add nearest mapsheet codes and centre coordinates.
get_enviro_data() – Retrieve, crop, resample, and link environmental rasters to sites.
format_df() – Format biodiversity records to long/wide forms for analysis.

Dissimilarity & Metrics

compute_orderwise() – Compute order-wise metrics, including zeta diversity and dissimilarities.
rm_correlated() – Remove highly correlated predictors to avoid redundancy.
Helper metrics available via helper_indices, e.g.:
- geodist_helper() – Geographic distance (Haversine).
- richness() – Species richness.
- turnover() – Species turnover/beta diversity.
- diss_bcurt() – Bray–Curtis dissimilarity.
- orderwise_diss_gower() – Gower dissimilarity.

Prediction & Mapping

predict_dissim() – Predict pairwise compositional turnover (zeta-dissimilarity) with richness.
map_bioreg() – Raster-based clustering and interpolation of bioregional data.
map_bioregDiff() – Map bioregional change metrics between categorical raster layers.

ζ-MSGDM Workflow

Functions to automate multi-site GDM workflows: * run_ispline_models() – Fit multiple zetadiv::Zeta.msgdm I-spline models.
* plot_ispline_lines() – Plot I-spline partial effects.
* plot_ispline_boxplots() – Plot facetted boxplots for I-spline basis functions.

Applications

dissmapr is designed for use across a wide range of biodiversity research and conservation contexts, including:

Community ecology – comparing species composition across landscapes, ecoregions, or time periods.
Macroecology – exploring turnover and nestedness at regional to global scales.
Environmental filtering – quantifying how abiotic differences shape community assembly.
Conservation planning – mapping bioregions and their shifts to identify hotspots, refugia, or vulnerable sites.

Why Use `dissmapr`?

Unified workflow – integrates occurrence, environment, dissimilarity, and mapping in a consistent manner.
Transparent & reproducible – modular design supports repeatable workflows across datasets and studies.
Interpretable outputs – order-wise dissimilarities, predictive models, and mapped bioregions.
Flexible & extensible – built on standard R data structures and interoperable with packages like zetadiv, terra, sf, and ggplot2.

Installation

Install from GitHub using:

{r} # install.packages("remotes") remotes::install_github("b-cubed-eu/dissmapr")

Minimal Example

Below is a short workflow showing how to move from occurrence data to order-wise dissimilarity and bioregional mapping.

```{r} library(dissmapr)

1. Import or simulate occurrence data (here using built-in example dataset)

occ = get_occurrence_data(example = TRUE)

2. Generate a grid for spatial aggregation

grid = generate_grid(occ, res = 0.5)

3. Format the data for analysis

df = format_df(occ, grid)

4. Compute order-wise dissimilarities (zeta diversity, turnover, etc.)

diss = compute_orderwise(df, func = richness)

5. Map bioregions using clustering and interpolation

bio_map = map_bioreg(diss, grid)

6. Plot the resulting bioregionalisation

plot(bio_map) ```

This workflow illustrates the package’s modular design: each function can be run independently or chained together for end-to-end biodiversity workflows.

Citation

If you use dissmapr, please cite the package and associated methods. See citation("dissmapr") and the repository’s CITATION files.

dissmapr