BONs.jl

Appearance

Samplers ​

SimpleRandom ​

BiodiversityObservationNetworks.SimpleRandom Type
julia
SimpleRandom <: BONSampler

Simple random sampling (or weighted random sampling when inclusion weights are non-uniform). Selects n candidates without replacement.

source

BalancedAcceptance ​

BiodiversityObservationNetworks.BalancedAcceptance Type
julia
BalancedAcceptance <: BONSampler

Balanced Acceptance Sampling (BAS) using Halton sequences, proposed by (Robertson et al., 2025).

Generates spatially balanced samples by mapping Halton sequences to the candidate coordinate space. When inclusion weights are non-uniform, a third Halton dimension acts as a threshold for acceptance, preferentially selecting higher-weighted candidates.

Fields

  • n::Int: number of sites to select (default 50)
source

GRTS ​

BiodiversityObservationNetworks.GRTS Type
julia
GRTS <: BONSampler

Generalized Random Tessellation Stratified (GRTS) sampling.

GRTS produces spatially balanced samples by recursively partitioning the domain into quadrants, assigning each cell a hierarchical address. The recursive tessellation ensures spatial spread without requiring distance computations.

Originally proposed by (Stevens and Olsen, 2004).

Fields

  • n::Int: number of sites to select (default 50)
source

CubeSampling ​

BiodiversityObservationNetworks.CubeSampling Type
julia
CubeSampling <: BONSampler

Balanced sampling with respect to auxiliary variables, using the Cube method from (Deville and Tillé, 2022).

Selects a sample whose Horvitz–Thompson estimates of auxiliary variables match the population as closely as possible. The algorithm runs in two phases:

  1. Flight phase: a random walk on inclusion probabilities that preserves balance constraints while driving inclusion probabilities toward 0 or 1.

  2. Landing phase: uses integer programming (via the JuMP + HiGHS packages) to resolve any remaining fractional probabilities once the flight phase terminates.

Requires a CandidatePool with features; pass a vector of matrices or construct a pool with explicit features.

Fields

  • n::Int: number of sites to select (default 50)
source

AdaptiveHotspot ​

BiodiversityObservationNetworks.AdaptiveHotspot Type
julia
AdaptiveHotspot <: BONSampler

Sampling for hotspots. Takes an auxiliary variable (e.g. uncertainty) to target samples toward. Proposed by (Andrade-Pacheco et al., 2022).

Starts at the global maximum of the target/uncertainty surface. Subsequent points are chosen to maximize a trade-off between the target value and spatial diversity (measured via the determinant of a kernel matrix).

Requires a CandidatePool with features. The first feature row is used as the target/uncertainty surface; subsequent rows are ignored.

Fields

  • n::Int: number of sites to select (default 50)

  • scale: Matérn kernel range parameter ρ (default 1.0)

  • smoothness: Matérn kernel smoothness ν (default 0.5, equivalent to an exponential kernel)

source

Stratified ​

BiodiversityObservationNetworks.Stratified Type
julia
Stratified <: BONSampler

Stratified sampling. The first feature row of the CandidatePool is treated as a discrete stratum label. Draws are allocated across strata via a Multinomial draw on the stratum weights; within each stratum, sites are drawn without replacement.

Recommended usage is to pass a single matrix/SDMLayer of discrete integer stratum labels.

Fields

  • n::Int: number of sites to select

  • weights::Union{Vector, Missing}: per-stratum weights. Index corresponds to label. missing (default) uses weights proportional to area.

Notes

Does not guarantee exactly n selected sites when a Multinomial draw allocates more draws to a stratum than it has candidates. In that case the stratum is exhausted and the total falls short.

Usage

julia
weights = [0.1, 0.2, 0.5, 0.1, 0.1]
domain = rand(1:5, (30, 30))
sample(Stratified(weights = weights), domain)
source

Pivotal ​

BiodiversityObservationNetworks.Pivotal Type
julia
Pivotal <: BONSampler

Local Pivotal Method (LPM) for spatially balanced sampling.

Iteratively pairs nearby candidates and updates their inclusion probabilities so that one tends toward selection and the other toward exclusion. Repeating over the domain produces a spatially balanced sample that respects per-unit inclusion probabilities.

Proposed in (Grafström et al., 2022).

Fields

  • n::Int: number of sites to select (default 50)
source

SpatiallyCorrelatedPoisson ​

BiodiversityObservationNetworks.SpatiallyCorrelatedPoisson Type
julia
SpatiallyCorrelatedPoisson <: BONSampler

Implements Spatially Correlated Poisson Sampling (SCPS) from (Grafström, 2025).

Fields

  • n::Int: expected number of sites to select (default 50)

Description

Iterates through units, selecting them based on inclusion probabilities, and dynamically adjusting the probabilities of neighboring units to maintain spatial balance.

source