Utilities

Utilities for quantifying network quality and producing inputs (inclusion probabilities, rarity surfaces) useful when designing a BiodiversityObservationNetwork.

Spatial Balance

Two metrics evaluate how evenly selected sites cover the domain. Both are called via evaluate(metric, domain, bon).

`MoransI`

Spatial autocorrelation of the inclusion indicator (1 if sampled, 0 otherwise). Computes the normalized Moran's I statistic. Negative values indicate spatial inhibition (spread), which is desirable.

BiodiversityObservationNetworks.MoransI Type

julia

MoransI <: SamplingMetric

Computes Moran's I on the inclusion indicator variable.

Description

Calculates spatial autocorrelation of the sample indicator $δ$ (1 if sampled, 0 otherwise). Negative values indicate spatial inhibition (spread), which is desired for balanced sampling.

This version was proposed by (Tillé et al., 2025).

source

Assigns every domain cell to its nearest selected site (Voronoi tessellation), then measures how far each cell's total inclusion weight deviates from 1. Defined as (1/n) Σ(vᵢ - 1)²; smaller is better.

BiodiversityObservationNetworks.VoronoiVariance Type

julia

VoronoiVariance <: SamplingMetric

The VoronoiVariance method for characterizing the spatial balance of a sample is based on the initial method proposed by (Stevens and Olsen, 2004), and then extended by (Grafström, 2025).

For a given BiodiversityObservationNetwork bon, the Voronoi tesselation splits the plane into a series of polygons, where the i-th polygon consists of all points in the plane whose nearest node in bon is the i-th node.

These polygons can then be used to assess the spatial balance of a sample.

In an ideally balanced sample, the sum of the inclusion probabilities across each polygon i would equal 1, because in expectation exactly one unit would be sampled in that region.

If we define $v_{i}$ as the total inclusion probability across all elements of the population in Voronoi polygon i, i.e.

v_{i} = \sum_{j \in i} π_{j}

then we can assess the spatial balance of a sample by measuring the distance of $v_{i}$ from 1 for each polygon. (Grafström, 2025) proposes the metric B, defined as

B = \frac{1}{n} \sum_{i = 1}^{n} (v_{i} - 1)^{2}

to measure spatial balance, where smaller values indicate better spatial balance.

source

Environmental Representativeness

JensenShannon measures how well the selected sites represent the distribution of environmental predictors across the domain, using Jensen-Shannon divergence between per-feature empirical distributions. Returns average JS divergence across features, where smaller values mean the BON is more representative.

BiodiversityObservationNetworks.JensenShannon Type

julia

JensenShannon

The JensenShannon method for evaluating BiodiversityObservationNetwork design computes how representative the selected BON sites are of the environmental variables across the domain using Jensen-Shannon divergence, a method for measuring the distance between two distributions.

Fields

nbins::Int: number of bins to use when computing empirical probability mass

source

Climate Rarity

All rarity metrics are subtypes of RarityMetric and called via evaluate(metric, layers) or evaluate(metric, layers, bon) for BON-relative metrics. layers is a Vector{<:Matrix} (or Vector{<:SDMLayer} with SDT loaded). Output is a matrix of rarity scores.

Metric	Requires BON	Description
`DistanceToMedian`	No	Euclidean distance in z-scored feature space to the per-feature median. Higher = more rare.
`MultivariateEnvironmentalSimilarity`	No	MESS surface. Per-cell minimum over features of an ECDF-derived similarity score. Negative indicates outside BON site range.
`DistanceToAnalogNode`	Yes	Distance in z-scored feature space to the nearest selected BON site. Higher = less represented.
`WithinRange`	Yes	Whether each cell falls within the feature-space hyper-rectangle spanned by BON sites.

BiodiversityObservationNetworks.DistanceToMedian Type

julia

DistanceToMedian

Rarity score defined as Euclidean distance in feature space to the per-feature median across the raster stack. Optionally, features can be PCA-transformed prior to z-scoring.

source

BiodiversityObservationNetworks.MultivariateEnvironmentalSimilarity Type

julia

MultivariateEnvironmentalSimilarity

Multivariate Environmental Similarity Surface (MESS). For each cell, compute the minimum over features of a per-feature similarity score derived from the ECDF of the training distribution, following the standard MESS definition.

source

BiodiversityObservationNetworks.DistanceToAnalogNode Type

julia