biotica-ecosystem 1.0.0

BIOTICA: Bio-Geochemical Framework for Ecosystem Resilience Assessment

🌿 BIOTICA

Bio-Geochemical Framework for Ecosystem Resilience Assessment

Living Systems as Legible Archives — A Multi-Dimensional Integrated Approach

---

Principal Investigator: Samir Baladi
Affiliation: Ronin Institute / Rite of Renaissance
ORCID: 0009-0003-8903-0029
Contact: [e-mail] · [phone]

---

📋 Table of Contents

• Overview
• Key Results
• The IBR Framework
• Project Structure
• Getting Started
• Data Architecture
• Module Documentation
• Reproducibility
• Case Studies
• Publication
• Contributing
• Citation
• License

---

🔬 Overview

BIOTICA proposes that living ecosystems are not merely biological communities but dynamic information systems — encoding millions of years of evolutionary pressure, climate history, and geochemical negotiation in the composition of their soils, the architecture of their trophic networks, and the isotopic memory of their organic matter.

The framework integrates nine analytical parameters into a single Integrated Biotic Resilience (IBR) index, validated across 3,412 ecosystem plots from 22 biome types spanning 6 continents.

IBR = 0.20·VCA* + 0.15·MDI* + 0.12·PTS* + 0.11·HFI* + 0.10·BNC*
    + 0.09·SGH* + 0.08·AES* + 0.08·TMI* + 0.07·RRC*

Each parameter Pᵢ* normalized to [0,1] relative to biome-type reference thresholds

---

📊 Key Results

Metric	Value	Description
🎯 IBR Classification Accuracy	92.6%	22-biome leave-one-biome cross-validation
🛰️ AI Remote Sensing Agreement	89.4%	vs. expert field surveys (682 held-out plots)
🦠 MDI–Carbon Correlation	r = +0.917	p < 0.001, n = 1,240 plots
🌱 Carbon Stock Precision	±31 Mg C·ha⁻¹	MDI-based measurement
📅 Phenological Drift Precision	±6.2 days	180 flux tower sites
⚠️ Tipping Point Lead Time	8–14 months	Before observed collapse events
📉 Legacy DB Error Rate	14.7%	2,100 REDD+ units flagged
🔄 Recovery Prediction	±18% biomass	At 5-year post-disturbance horizon

---

🌐 The IBR Framework

Nine Integrated Parameters

┌─────────────────────────────────────────────────────────────┐
│                    BIOTICA · IBR INDEX                       │
├──────┬─────┬────────────────────────────────────┬──────────┤
│  #   │ SYM │ PARAMETER                           │ WEIGHT  │
├──────┼─────┼────────────────────────────────────┼──────────┤
│  1   │ VCA │ Vegetative Carbon Absorption        │  20%    │
│  2   │ MDI │ Microbial Diversity Index           │  15%    │
│  3   │ PTS │ Phenological Time Shift             │  12%    │
│  4   │ HFI │ Hydrological Flux Index             │  11%    │
│  5   │ BNC │ Biogeochemical Nutrient Cycle       │  10%    │
│  6   │ SGH │ Species Genetic Heterogeneity       │   9%    │
│  7   │ AES │ Anthropogenic Encroachment Score    │   8%    │
│  8   │ TMI │ Trophic Metadata Integration        │   8%    │
│  9   │ RRC │ Regenerative Recovery Capacity      │   7%    │
└──────┴─────┴────────────────────────────────────┴──────────┘

IBR Classification Thresholds

Class	IBR Score	Condition
🟢 PRISTINE	> 0.88	Reference state, full ecological function
🟡 FUNCTIONAL	0.75 – 0.88	Near-reference, minor departures
🟠 IMPAIRED	0.60 – 0.75	Measurable degradation, recovery possible
🔴 DEGRADED	0.45 – 0.60	Significant loss, active management required
⚫ COLLAPSED	< 0.45	Alternative stable state, tipping point crossed

---

📁 Project Structure

biotica/
│
├── README.md                             # This file
├── LICENSE                               # CC-BY-4.0
├── CHANGELOG.md                          # Version history
├── CONTRIBUTING.md                       # Contribution guidelines
├── CODE_OF_CONDUCT.md                    # Community standards
├── CITATION.cff                          # Machine-readable citation
├── pyproject.toml                        # Python project config & dependencies
├── environment.yml                       # Conda environment specification
├── .gitlab-ci.yml                        # CI/CD pipeline definition
├── .gitignore
│
├── biotica/                              # Core Python package
│   ├── __init__.py
│   ├── __version__.py
│   │
│   ├── parameters/                       # Individual parameter modules
│   │   ├── __init__.py
│   │   ├── vca.py                        # Vegetative Carbon Absorption
│   │   ├── mdi.py                        # Microbial Diversity Index
│   │   ├── pts.py                        # Phenological Time Shift
│   │   ├── hfi.py                        # Hydrological Flux Index
│   │   ├── bnc.py                        # Biogeochemical Nutrient Cycle
│   │   ├── sgh.py                        # Species Genetic Heterogeneity
│   │   ├── aes.py                        # Anthropogenic Encroachment Score
│   │   ├── tmi.py                        # Trophic Metadata Integration
│   │   └── rrc.py                        # Regenerative Recovery Capacity
│   │
│   ├── ibr/                              # IBR composite index engine
│   │   ├── __init__.py
│   │   ├── composite.py                  # IBR aggregation & sigmoid correction
│   │   ├── weights.py                    # Bayesian weight determination
│   │   ├── normalization.py              # Per-biome normalization engine
│   │   └── thresholds.py                 # Classification threshold registry
│   │
│   ├── ai/                               # AI classification system
│   │   ├── __init__.py
│   │   ├── mi_cnn.py                     # Multi-Input CNN architecture
│   │   ├── spectral_stream.py            # Hyperspectral 1D-CNN stream
│   │   ├── temporal_stream.py            # VI time-series processing
│   │   ├── climate_stream.py             # Bioclimatic variable stream
│   │   ├── terrain_stream.py             # Terrain morphometry stream
│   │   ├── trainer.py                    # Training loop & Adam scheduler
│   │   ├── evaluator.py                  # Validation & confusion matrix
│   │   ├── gradcam.py                    # Grad-CAM interpretability
│   │   └── augmentation.py               # Spectral data augmentation
│   │
│   ├── preprocessing/                    # Data ingestion & cleaning
│   │   ├── __init__.py
│   │   ├── spectral.py                   # Hyperspectral preprocessing
│   │   ├── flux_tower.py                 # Eddy covariance data parsing
│   │   ├── metagenomics.py               # eDNA / metagenomic pipelines
│   │   ├── phenocam.py                   # PhenoCam GCC time series
│   │   ├── genomics.py                   # Population genomics (VCF)
│   │   ├── landscape.py                  # Fragmentation (FRAGSTATS)
│   │   └── trophic.py                    # Food web metabarcoding
│   │
│   ├── statistics/                       # Statistical framework
│   │   ├── __init__.py
│   │   ├── cross_validation.py           # Leave-one-biome CV
│   │   ├── bayesian_weights.py           # 3-stage Bayesian PCA weight
│   │   ├── uncertainty.py                # Uncertainty propagation
│   │   ├── sensitivity.py                # Parameter sensitivity analysis
│   │   └── tipping_points.py             # Critical slowing-down detection
│   │
│   ├── remote_sensing/                   # Satellite data interface
│   │   ├── __init__.py
│   │   ├── desis.py                      # DESIS hyperspectral parser
│   │   ├── prisma.py                     # PRISMA satellite interface
│   │   ├── landsat.py                    # Landsat archive (historical PTS)
│   │   ├── sentinel.py                   # Sentinel-2 multispectral
│   │   └── indices.py                    # NDVI, NDRE, SWIR, EVI, LAI
│   │
│   ├── biome/                            # Biome classification system
│   │   ├── __init__.py
│   │   ├── registry.py                   # 22-biome type registry
│   │   ├── transition_zones.py           # Transition zone resolver
│   │   └── iucn_typology.py              # IUCN GET v2.0 compatibility
│   │
│   ├── tei/                              # Traditional Ecological Knowledge
│   │   ├── __init__.py
│   │   ├── tek_integration.py            # TEK-IBR integration protocol
│   │   └── community_protocols.py        # Indigenous data sovereignty
│   │
│   └── utils/                            # Shared utilities
│       ├── __init__.py
│       ├── io.py                         # File I/O (NetCDF, GeoTIFF, CSV)
│       ├── geo.py                        # Geospatial transformations
│       ├── logging.py                    # Structured logging
│       └── constants.py                  # Physical & biological constants
│
├── r/                                    # R statistical analysis package
│   ├── DESCRIPTION
│   ├── NAMESPACE
│   ├── R/
│   │   ├── ibr_composite.R               # IBR index computation
│   │   ├── bayesian_weights.R            # brms / Stan weight estimation
│   │   ├── tipping_points.R              # Early warning signals (earlywarnings)
│   │   ├── food_web.R                    # Network analysis (igraph)
│   │   └── population_genetics.R         # adegenet / poppr genomics
│   └── man/                              # R documentation (.Rd files)
│
├── models/                               # Trained model artifacts
│   ├── README.md                         # Model registry & checksums
│   ├── mi_cnn_v1/                        # MI-CNN v1.0 (primary classifier)
│   │   ├── config.json
│   │   ├── weights.pt                    # PyTorch state dict
│   │   └── training_log.csv
│   ├── biome_thresholds/                 # Per-biome normalization params
│   │   └── thresholds_v1.json
│   └── bayesian_weights/                 # Stan posterior samples
│       └── weight_posterior.rds
│
├── data/                                 # Data management
│   ├── README.md                         # Data access instructions
│   ├── raw/                              # Raw input data (DVC tracked)
│   │   ├── spectral/                     # Hyperspectral ENVI files
│   │   ├── flux_towers/                  # FLUXNET / ICOS NetCDF
│   │   ├── metagenomes/                  # MGnify-formatted FASTQ
│   │   ├── genomics/                     # VCF population files
│   │   ├── phenocam/                     # GCC time series CSV
│   │   └── field_plots/                  # Ground-truth plot data
│   ├── processed/                        # Cleaned, parameter-ready data
│   │   ├── parameters/                   # Computed VCA, MDI, PTS … per plot
│   │   ├── ibr_scores/                   # Final IBR assessments
│   │   └── validation/                   # Held-out test set (682 plots)
│   └── reference/                        # Biome reference distributions
│       ├── biome_thresholds.csv
│       ├── redd_plus_units.geojson
│       └── iucn_get_v2.shp
│
├── notebooks/                            # Jupyter analysis notebooks
│   ├── 00_data_exploration.ipynb
│   ├── 01_parameter_computation.ipynb
│   ├── 02_ibr_validation.ipynb
│   ├── 03_ai_training_evaluation.ipynb
│   ├── 04_tipping_point_analysis.ipynb
│   ├── 05_case_amazon.ipynb
│   ├── 06_case_australia_fires.ipynb
│   ├── 07_case_serengeti.ipynb
│   ├── 08_case_arctic_tundra.ipynb
│   ├── 09_carbon_accounting_implications.ipynb
│   └── 10_figures_publication.ipynb
│
├── scripts/                              # Standalone execution scripts
│   ├── compute_ibr.py                    # Full pipeline: raw → IBR score
│   ├── train_classifier.py               # Train MI-CNN from scratch
│   ├── evaluate_classifier.py            # Run held-out validation
│   ├── flag_redd_units.py                # Screen REDD+ DB for errors
│   ├── generate_figures.py               # Reproduce all paper figures
│   └── batch_process.sh                  # HPC batch submission (SLURM)
│
├── workflows/                            # Snakemake reproducible pipelines
│   ├── Snakefile                         # Master Snakemake workflow
│   ├── rules/
│   │   ├── preprocessing.smk
│   │   ├── parameter_computation.smk
│   │   ├── ibr_aggregation.smk
│   │   ├── ai_classification.smk
│   │   └── validation.smk
│   └── config/
│       ├── config.yaml                   # Pipeline configuration
│       └── cluster.yaml                  # HPC cluster settings
│
├── tests/                                # Test suite
│   ├── conftest.py
│   ├── unit/
│   │   ├── test_vca.py
│   │   ├── test_mdi.py
│   │   ├── test_pts.py
│   │   ├── test_ibr_composite.py
│   │   ├── test_normalization.py
│   │   └── test_thresholds.py
│   ├── integration/
│   │   ├── test_full_pipeline.py
│   │   └── test_ai_classifier.py
│   └── fixtures/
│       └── synthetic_plot_data.csv       # Minimal synthetic test data
│
├── docs/                                 # Documentation (MkDocs)
│   ├── mkdocs.yml
│   └── docs/
│       ├── index.md
│       ├── framework.md                  # IBR conceptual framework
│       ├── parameters.md                 # All 9 parameters documented
│       ├── installation.md
│       ├── quickstart.md
│       ├── api_reference.md              # Auto-generated from docstrings
│       ├── data_protocols.md
│       ├── tek_integration.md
│       └── changelog.md
│
├── paper/                                # Publication materials
│   ├── BIOTICA_Research_Paper_Part1.docx
│   ├── BIOTICA_Research_Paper_Part2.docx
│   ├── figures/                          # High-resolution figure exports
│   │   ├── fig01_ibr_framework.svg
│   │   ├── fig02_classification_accuracy.svg
│   │   ├── fig03_mdi_carbon_correlation.svg
│   │   ├── fig04_tipping_point_signals.svg
│   │   ├── fig05_amazon_case_study.svg
│   │   ├── fig06_australia_fires.svg
│   │   ├── fig07_serengeti_tmi.svg
│   │   └── fig08_arctic_pts.svg
│   └── supplementary/
│       ├── S1_extended_methods.pdf
│       ├── S2_validation_tables.xlsx
│       └── S3_plot_database_subset.csv
│
└── .gitlab/                              # GitLab project configuration
    ├── ISSUE_TEMPLATE/
    │   ├── bug_report.md
    │   └── feature_request.md
    └── MERGE_REQUEST_TEMPLATE.md

---

🚀 Getting Started

Prerequisites

• Python ≥ 3.11
• R ≥ 4.3
• CUDA ≥ 11.8 (optional, for GPU training)
• GDAL ≥ 3.6
• ~50 GB disk space (full dataset)

Installation

1. Clone the repository

git clone https://gitlab.com/gitdeeper07/biotica.git
cd biotica

2. Create the conda environment

conda env create -f environment.yml
conda activate biotica

3. Install the Python package

pip install -e ".[dev]"

4. Install R dependencies

install.packages(c("brms", "igraph", "adegenet", "poppr", "earlywarnings", "vegan"))

5. Pull reference data via DVC

dvc remote add -d zenodo https://zenodo.org/record/biotica2026
dvc pull data/reference/          # Reference data only (~2 GB)
# dvc pull                        # Full dataset (~48 GB)

6. Verify installation

python -m pytest tests/unit/ -v
python -c "import biotica; print(biotica.__version__)"

---

💾 Data Architecture

Dataset Summary

Collection	Records	Format	Access
Ecosystem plots	3,412 plots	CSV + GeoJSON	Zenodo (open)
Hyperspectral imagery	2,891 time series	ENVI / NetCDF	DESIS/PRISMA portal
Soil metagenomes	1,847 samples	FASTQ	MGnify / EBI
Population genomes	480 populations	VCF	NCBI SRA
Eddy covariance	180 sites	NetCDF	FLUXNET 2015
Recovery chronosequences	340 sites	CSV	Zenodo (open)
Collapse/recovery events	67 events	CSV + metadata	Zenodo (open)

External Data Sources

Resource	URL
Project GitLab	https://gitlab.com/gitdeeper07/biotica
Project GitHub (mirror)	https://github.com/gitdeeper07/biotica
Plot Database (Zenodo)	https://doi.org/10.5281/zenodo.biotica.2026
Carbon Flux (FLUXNET)	https://fluxnet.org
Satellite (DESIS/PRISMA)	https://www.dlr.de/eoc/desis
Metagenomics (MGnify)	https://www.ebi.ac.uk/metagenomics
Genomics (NCBI SRA)	https://www.ncbi.nlm.nih.gov/sra
Forest Cover (GFW)	https://www.globalforestwatch.org

---

📦 Module Documentation

Computing Individual Parameters

from biotica.parameters import VCA, MDI, PTS, HFI, BNC, SGH, AES, TMI, RRC

# Each parameter follows a consistent interface
mdi = MDI(metagenome_path="data/processed/metagenomes/plot_0042.tsv")
score       = mdi.compute()       # float in [0, 1]
uncertainty = mdi.uncertainty()   # ± value
report      = mdi.report()        # full diagnostic dict

Computing the IBR Composite Index

from biotica.ibr import IBRComposite

ibr = IBRComposite(plot_id="amazon_plot_0042")
ibr.load_parameters({
    "VCA": 0.831, "MDI": 0.847, "PTS": 0.911,
    "HFI": 0.789, "BNC": 0.802, "SGH": 0.714,
    "AES": 0.923, "TMI": 0.823, "RRC": 0.761,
})

result = ibr.compute()
print(result.score)           # → 0.834
print(result.classification)  # → "FUNCTIONAL"
print(result.report())        # → full diagnostic report

Running the AI Classifier

from biotica.ai import MICNNClassifier

model = MICNNClassifier.from_pretrained("models/mi_cnn_v1/")
prediction = model.predict(
    spectral="data/processed/spectral/plot_0042.npy",
    climate="data/reference/worldclim_plot_0042.csv",
    terrain="data/reference/terrain_plot_0042.csv",
)
print(prediction.biome, prediction.confidence)

Tipping Point Detection

from biotica.statistics import TippingPointDetector

detector = TippingPointDetector(window=24, lag=1)
signals  = detector.analyze(ibr_timeseries_df)

if signals.critical_slowing_down:
    print(f"⚠️  Warning: collapse risk in ~{signals.estimated_months} months")

---

🔁 Reproducibility

All results can be reproduced via the Snakemake workflow:

# Full validation pipeline (requires complete dataset, ~72h on 32-core HPC)
snakemake --cores 32 --use-conda all

# Reproduce publication figures only (requires processed data)
snakemake --cores 8 figures

# Reproduce a single case study
snakemake --cores 4 results/case_studies/amazon/

Software environment hash: sha256:b4f2a19...
Tested on: Ubuntu 22.04 LTS · macOS 14.2 · Rocky Linux 8.9

---

🗺️ Case Studies

Study	Region	Biome	Key Finding
Case A	Brazilian Amazon	Tropical moist forest	MDI collapse precedes canopy loss by 4–7 years
Case B	SE Australia	Temperate broadleaf	SGH < 0.38 → arrested recovery post-megafire
Case C	Serengeti-Mara	Tropical savanna	Predator loss → TMI drop 0.823 → 0.621
Case D	Arctic tundra	Tundra	PTS 18.4-day advance → 18–34% chick mortality

---

📰 Publication

Baladi, S. (2026). BIOTICA: A Multi-Dimensional Bio-Geochemical Framework for the Systematic Assessment, Predictive Modeling, and Cosmological Contextualization of Ecosystem Resilience. Submitted to Nature Sustainability. DOI: 10.14293/BIOTICA.2026.001

Companion framework: METEORICA — Multi-parameter extraterrestrial materials classification, which directly inspired BIOTICA's integration methodology.

---

🤝 Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a Merge Request.

Priority areas for contribution:

• Aquatic systems extension (BIOTICA-Aquatic, roadmap 2027)
• Additional rare biome plot submissions (cave, sub-Antarctic, tropical alpine)
• Language support for TEK integration protocols
• Optimized GPU training pipeline

git checkout -b feature/your-feature-name
# ... make changes, add tests ...
pytest tests/
git push origin feature/your-feature-name
# Open a Merge Request on GitLab

---

📝 Citation

@article{baladi2026biotica,
  title   = {{BIOTICA}: A Multi-Dimensional Bio-Geochemical Framework for
             the Systematic Assessment, Predictive Modeling, and Cosmological
             Contextualization of Ecosystem Resilience},
  author  = {Baladi, Samir},
  journal = {Nature Sustainability},
  year    = {2026},
  doi     = {10.14293/BIOTICA.2026.001},
  note    = {Submitted March 2026}
}

---

📄 License

Licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).
See LICENSE for full terms.

Data from field partners are subject to individual data-sharing agreements detailed in data/README.md. Traditional Ecological Knowledge components are governed by community-specific protocols compliant with the Nagoya Protocol on Access and Benefit-Sharing.

---

🌿 BIOTICA · Samir Baladi · Ronin Institute · 2026

Four billion years of biological negotiation, encoded in soil and gene and trophic web.
BIOTICA makes it legible.