CHE — Combining Convex Hulls and Elliptical Envelopes for Niche and Niche-Overlap Estimation

Code and reproducibility materials for the paper On the implications of combining convex hulls and elliptical envelopes to delineate ecological hypervolumes (submitted to Ecological Modelling).

The CHE approach builds a parsimonious, robust, exactly-intersectable representation of the environmental niche by taking the convex hull of the occurrences retained inside a fitted elliptical envelope, and characterises the implications of that combination (size, discrimination, robustness, symmetry and niche overlap) against the convex hull, the classical/robust ellipsoids and a MaxEnt benchmark, on 25 Iberian bat species.

Exact polyhedral niche overlap of two species’ CHE hypervolumes (𝒫 ∩ 𝒬) in the first three principal components; the shaded solid is the exact intersection. Full vector figure: figures/che_overlap.pdf.

Repository structure

Path	Description
run_all.py	One-command driver: reproduces every table and figure into outputs/.
CHE_reproducibility.ipynb	Guided notebook that reproduces every result and figure step by step.
che.py	Core geometry: convex hull, elliptical envelopes (COV, MCD), the CHE construction.
overlap.py	Exact polyhedral intersection, Monte-Carlo ellipsoid overlap, geographic projection.
validation.py	Spatial-block cross-validation; omission–volume frontier.
discrimination.py	AUC and continuous Boyce index.
robustness.py	Sample-size and outlier robustness.
asymmetry.py	Symmetry diagnostics.
maxent.py	maxnet-style MaxEnt benchmark.
overlap_all.py	Unified grid-based overlap (Schoener's D, Warren's I).
tests/	Fast deterministic tests (pytest) guarding the core invariants.
reference_outputs/	Reference table and values used by the tests.
databats.csv	Presence/absence of 25 Iberian bat species over the 6169-cell 10×10 km grid (accessible area M) plus the environmental variables (whitespace-delimited).
requirements.txt / environment.yml	Pinned computational environment (pip / conda).

Quick start

Create the pinned environment (isolated), then reproduce everything:

# conda
conda env create -f environment.yml && conda activate che
# or pip, in a fresh virtual environment
pip install -r requirements.txt

python run_all.py              # full run (a few minutes) -> outputs/
python run_all.py --quick      # fast subset (smoke test)

run_all.py writes all figures (PDF) and tables (CSV) to outputs/. Every computation is deterministic (fixed seeds); the MaxEnt, cross-validation and robustness stages are the slowest. Set nothing else — the driver is self-contained.

Notebook

CHE_reproducibility.ipynb reproduces the same results interactively, section by section. Set SAVE_FIGURES = True in its environment cell to write each figure with the exact filename used by the manuscript. Part 1 of the notebook also mirrors the modules via %%writefile, so it runs even in isolation.

Tests

pytest -q

The tests check fast, deterministic invariants against reference_outputs/: the PCA variance structure, the published convex-hull overlap (Bbar × Eisa ≈ 22.92), the recomputed hypervolume sizes, the CHE nesting property (CHE ⊆ CH and CHE ⊆ ellipsoid), the Monte-Carlo ellipsoid-overlap sanity limits, and the symmetry ordering.

Notation

The environmental dimension is written n in the paper and figures and d in the code (the number of retained principal components); the sample size (number of records) is m in the paper. The Monte-Carlo overlap uses N for the number of samples.

Data

databats.csv is the presence/absence matrix over the study grid M with the associated environmental variables. Please confirm the data-sharing terms of the original sources before redistribution.

Citation

See CITATION.cff. Please cite the associated paper if you use this code.

License

Released under the MIT License (see LICENSE).