README.md

---
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](https://huggingface.co/spaces/mowcom/er-model)

2. **(Optional) Run Locally for Development:**
   ```bash
   # 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](https://black.readthedocs.io/), [isort](https://pycqa.github.io/isort/)
- Type hints required for all public functions
- Run tests with:
  ```bash
  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)