Overwrite README with up-to-date modular, model-driven, and active/archived model documentation

README.md

@@ -1,19 +1,13 @@
 # Mangrove Emissions Reduction Model & Dashboard
 
-This project implements a flexible, multi-model dashboard for mangrove carbon sequestration and emissions reduction, supporting several growth models:
-
-- **Chapman-Richards** (default/original)
-- **Simple Linear**
-- **Linear Plateau**
-- **Declining Increment**
+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
-- Compare multiple growth models side-by-side in a Gradio dashboard.
-- Each model is configured via a YAML file in `configs/`.
-- Each tab in the dashboard corresponds to a different model.
-- Planting schedule is editable for the Original Model tab.
-- All plots and tables update live.
-- Dashboard can be shared via a public link (`share=True`).
+- Interactive Gradio dashboard for project simulation and analysis
+- Modular growth model architecture (see `src/growth_models/`)
+- All dashboard tables and plots are driven by model outputs (no redundant calculations)
+- Editable planting schedule for Declining Increment model
+- Robust, transparent, and reproducible calculations
 
 ## Usage
 
@@ -28,100 +22,58 @@ This project implements a flexible, multi-model dashboard for mangrove carbon se
    ```
    The terminal will display a public share link.
 
-3. **Add new models:**
-   - Add a new YAML config to `configs/` (see examples for structure).
-   - Add an entry to `MODEL_CONFIGS` in `dashboard/app.py`.
-   - Optionally, add a README in the corresponding `models/` subfolder.
-
 ## Growth Models
-- **Chapman-Richards:** Flexible sigmoidal growth, suitable for most mangrove species.
-- **Simple Linear:** Constant annual increment.
-- **Linear Plateau:** Linear growth up to a plateau.
-- **Declining Increment:** Annual increment declines linearly to zero; total size is the sum of non-negative increments (never decreases or goes negative).
+- **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 `src/growth_models/chapman_richards.py`)
+  - **Simple Linear** (see `src/growth_models/linear.py`)
+  - **Linear Plateau** (see `src/growth_models/linear.py`)
+  - **Jimenez-Lugo** (see `models/jimenez_lugo/README.md`)
 
 ## File Structure
-- `dashboard/app.py` — Gradio dashboard UI and logic
-- `src/er_model.py` — Core model logic and growth functions
+- `dashboard/app.py` — Gradio dashboard UI and logic (now model-driven)
+- `src/er_model.py` — Core model logic, growth model selection, and all calculations
+- `src/growth_models/` — Modular growth model implementations (active and archived)
 - `configs/` — Model configuration YAMLs
-- `models/` — Reference model folders (see subfolder READMEs)
-
-## Notes
-- The dashboard is designed for easy extension: just add a config and a tab.
-- All growth models are robust to negative/complex values.
-- Diagnostics are included for debugging growth and biomass calculations.
-
----
-
-For more details, see the README files in each `models/` subfolder.
-
----
-
-## 🚀 Quickstart
-
-1. **Install dependencies**
-   ```bash
-   conda env create -f environment.yml
-   conda activate er-model
-   pre-commit install
-   ```
-
-2. **Launch the dashboard**
-   ```bash
-   python -m dashboard.app
-   ```
-   - The dashboard opens in your browser.
-   - Each tab represents a different model/configuration.
-
----
-
-## 🖥️ Dashboard Usage
-- **Multi-model:** Switch between models (e.g., "Original Model", "Jimenez & Lugo") using tabs.
-- **Interactive plots:** All plots are interactive (hover, zoom, export).
-- **Parameter editing:** Adjust planting schedule and see real-time results (where enabled).
-- **Tables:** View carbon, species, and survival tables for each model.
-
----
-
-## 📚 Model Documentation
-
-- [Original Model](models/original/README.md): Chapman-Richards growth, DBH-dependent mortality, field-calibrated.
-- [Jimenez & Lugo Model](models/jimenez_lugo/README.md): Literature-based, fixed annual mortality rates.
-
----
-
-## 🗂️ Directory Structure
+- `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 `src/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
 ├── src/                     # Core model code
+│   ├── er_model.py
+│   └── growth_models/
 ├── configs/                 # Model parameter YAMLs
 ├── models/                  # Model-specific docs
-│   ├── original/README.md
-│   └── jimenez_lugo/README.md
+│   ├── original/README.md   # Archived
+│   ├── jimenez_lugo/README.md # Archived
+│   └── declining_increment/README.md # Active
 ├── tests/                   # Pytest suite
 └── ...
 ```
 
----
-
-## ➕ Adding a New Model
-1. Create a new config YAML in `configs/` (e.g., `configs/my_model.yaml`).
-2. Add a new entry to `MODEL_CONFIGS` in `dashboard/app.py`:
-   ```python
-   MODEL_CONFIGS = {
-       "Original Model": "configs/params.yaml",
-       "Jimenez & Lugo": "configs/jimenez_lugo.yaml",
-       "My Model": "configs/my_model.yaml"
-   }
-   ```
-3. (Optional) Add a new subdirectory and README in `models/` for documentation.
-4. Restart the dashboard. Your model appears as a new tab.
-
----
-
-## 🧑‍💻 Development & Testing
+## 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:
@@ -130,15 +82,11 @@ er-chapman-richards/
   ```
 - Pre-commit hooks ensure code quality
 
----
-
-## 📖 References
+## 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)
 
----
-
-## 📝 License
+## License
 [License details to be added]