README.md

metadata

title: Mangrove ER Model Dashboard
emoji: 🌱
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 5.29.0
app_file: dashboard/app.py
pinned: false

Mangrove Emissions Reduction Model & Dashboard

This project implements a flexible, modular dashboard for mangrove carbon sequestration and emissions reduction, supporting multiple growth models. Currently, only the Declining Increment model is active; all other models are archived for reference.

Features

• Interactive Gradio dashboard for project simulation and analysis
• Updated: grouped accordions, tooltips as labels, reset-to-defaults button, and compact two-column mortality layout
• Modular growth model architecture (see er_model_core/growth_models/)
• All dashboard tables and plots are driven by model outputs (no redundant calculations)
• Editable planting schedule and all model parameters for Declining Increment model
• Robust, transparent, and reproducible calculations

Usage

1. Access the Dashboard (Recommended):

   • The Mangrove ER Model Dashboard is hosted online.
   • Access it here: https://huggingface.co/spaces/mowcom/er-model

2. (Optional) Run Locally for Development:

   # Using conda (recommended)
   conda env create -f environment.yml
   conda activate er-model
   python dashboard/app.py
   

   • To stop the local server, press Ctrl+C in the terminal.

Growth Models

• Declining Increment (ACTIVE):
  • Annual increment declines linearly to zero; total size is the sum of non-negative increments (never decreases or goes negative).
  • Both discrete and continuous versions are available (toggle via config).
• Archived Models:
  • Chapman-Richards (see er_model_core/growth_models/chapman_richards.py)
  • Simple Linear (see er_model_core/growth_models/linear.py)
  • Linear Plateau (see er_model_core/growth_models/linear.py)
  • Jimenez-Lugo (see models/jimenez_lugo/README.md)

File Structure

• dashboard/app.py — Gradio dashboard UI and logic (now model-driven, with grouped accordions and tooltips)
• er_model_core/er_model.py — Core model logic, growth model selection, and all calculations
• er_model_core/growth_models/ — Modular growth model implementations (active and archived)
• er_model_core/types.py — Shared dataclasses for model config
• er_model_core/config_loader.py — Config loading and parsing
• configs/ — Model configuration YAMLs
• models/ — Reference model folders and documentation
• tests/ — Unit tests for model logic and outputs

Model-Driven Dashboard

• All per-year, per-species metrics (surviving trees, DBH, height, biomass per tree, total biomass) are calculated and stored in the model (model.species_metrics).
• Dashboard tables and plots read directly from model outputs for speed, consistency, and maintainability.
• No redundant calculations in the dashboard.

Adding or Re-enabling Models

1. To add a new model:
   • Implement the growth function in er_model_core/growth_models/.
   • Add a config YAML to configs/.
   • Add a tab/entry in dashboard/app.py (if you want it visible in the UI).
2. To re-enable an archived model:
   • Uncomment the relevant import and config entry.
   • Ensure the model is listed in MODEL_CONFIGS in dashboard/app.py.
   • Add or update documentation in models/ as needed.

Directory Structure

er-chapman-richards/
├── README.md                # This file
├── environment.yml          # Conda environment
├── dashboard/               # Gradio dashboard app
├── er_model_core/           # Core model code
│   ├── er_model.py
│   ├── growth_models/
│   ├── types.py
│   └── config_loader.py
├── configs/                 # Model parameter YAMLs
├── models/                  # Model-specific docs
│   ├── original/README.md   # Archived
│   ├── jimenez_lugo/README.md # Archived
│   └── declining_increment/README.md # Active
├── tests/                   # Pytest suite
└── ...

Development & Testing

• Code style: black, isort
• Type hints required for all public functions
• Run tests with:

  pytest
  

• Pre-commit hooks ensure code quality

References

• Chapman-Richards growth model literature
• Jimenez, J.A. & Lugo, A.E. (1985, 1987)
• Zanvo et al. (2023) for allometric equations
• Field data from Nigeria mangrove sites (2024)