# Agricultural Model Adapter: User's Manual & Scientific Guide (A MAD Toolbelt)

Welcome to the **Agricultural Model Adapter (A MAD Toolbelt)**. This manual is designed to guide crop modelers, agricultural economists, livestock researchers, and data managers through the process of evaluating, validating, and translating agricultural simulation datasets. 

By utilizing this toolbelt, you can score the completeness of your experimental datasets, evaluate suitability against major biophysical and economic simulation models, perform uncertainty simulations, and export data in model-ready formats—all entirely in your browser with zero server-side dependencies.

---

## Table of Contents
1. [Scientific Background & Origins](#1-scientific-background--origins)
2. [The Dynamic Scoring Engine (V1 vs. V2)](#2-the-dynamic-scoring-engine-v1-vs-v2)
3. [Evaluating Core Crop & Environmental Data Checklist](#3-evaluating-core-crop--environmental-data-checklist)
4. [Activating V2 Extensions (Sensors, Satellites, & Genetics)](#4-activating-v2-extensions-sensors-satellites--genetics)
5. [LiveM (Livestock) & TradeM (Economics) Integration](#5-livem-livestock--tradem-economics-integration)
6. [The FAIR Axis Matrix & Wallach 2024 Support Checklist](#6-the-fair-axis-matrix--wallach-2024-support-checklist)
7. [In-Browser Dirichlet Uncertainty Quantification](#7-in-browser-dirichlet-uncertainty-quantification)
8. [Model Repository & Compatibility Matches](#8-model-repository--compatibility-matches)
9. [Cross-Model Linkage Validation System](#9-cross-model-linkage-validation-system)
10. [AgMIP ACE JSON Import & Exporters Guide](#10-agmip-ace-json-import--exporters-guide)
11. [Step-by-Step Workflows](#11-step-by-step-workflows)
12. [Troubleshooting & FAQs](#12-troubleshooting--faqs)

---

## 1. Scientific Background & Origins

The Agricultural Model Adapter is born out of **FACCE MACSUR** (Modelling European Agriculture with Climate Change for Food Security), a joint programming initiative that spanned 17 countries and 71 organizations. Modellers across crop (CropM), livestock (LiveM), and economic (TradeM) disciplines struggled with two foundational bottlenecks:
1. **Dataset Completeness:** Validating whether historical experimental data was complete enough to run and calibrate models.
2. **Interoperability:** Translating data across 75+ crop, herd, and economic simulation models.

To address the quality gap, **Kollas et al. (2015)** established a standardized quality ranking framework. Under the direction of **Dr. Jason S. Jorgenson** (University of Reading) within MACSUR Work Package 1 (WP1), the desktop Qt/C++ toolbelt was designed. This web-native port retains the mathematical fidelity of those original Qt desktop algorithms, while expanding it with modern open-science standards (DataRanking V2).

---

## 2. The Dynamic Scoring Engine (V1 vs. V2)

In the header panel, you can switch between three distinct scoring configurations, depending on your publication target or historical regression requirements:

| Version Select | Scientific Context | Core Characteristics |
| :--- | :--- | :--- |
| **`2015-kersebaum`** | Classic Qt C++ Desktop Baseline | Implements the original 2015 crop quality weights. Platinum threshold is set to **180**. |
| **`2015-kersebaum-paper`** | Kollas et al. (2015) Paper Variant | Excludes specific variables (such as leaf wetness and soil temperature) from the weather score. Platinum threshold is reduced to **173**. |
| **`2026-modern`** | DataRanking V2 Extension | Integrates remote sensing, sensor telemetry, genetics, livestock, economics, soil PTF extensions, and FAIR multipliers. Platinum threshold is set to **320**. |

---

## 3. Evaluating Core Crop & Environmental Data Checklist

For biophysical crop modeling, data is organized into seven legacy categories:

### Management
Tracks active agricultural operations in the field.
*   **Sowing, Variety, Seed Density, Fertilisation, Irrigation, Tillage, Harvest:** Each parameter has a checkbox and an observations count box.
*   *Scoring Logic:* Management points are determined by the equation:
    $$\text{Points} = \text{Events Count} \times \text{Weight}$$
    *(Note: If a required parameter has 0 observations, the block score collapses to 0 and flags a `MinData Missing!` exception).*

### Phenology & Previous Crop
*   **Phenology:** Requires recording the growth stages observed (e.g., emergence, anthesis, maturity). Points decay if growth stage observations are missing.
*   **Previous Crop:** Captures preceding crop types and residual management, crucial for calculating initial soil mineral nitrogen.

### Soil & Pedotransfer Functions (PTF)
*   **Soil Properties:** Tracks bulk density, organic carbon, soil texture, pH, and water limits (field capacity, wilting point).
*   **PTF Soil Extension (`2026-modern` only):** Evaluates if you have documented Pedotransfer Functions (equations used to estimate hydraulic boundaries from soil texture and carbon). This documentation adds **2.0 weight per tier**.

### Initial Soil Values
*   **Water, Nitrate, Ammonium, Organic Matter:** Evaluates observations count and depth of sampling.
*   *Mathematical Rule:* Initial values score is clamped by depth:
    $$\text{Points} = \min(\text{Depth}, 1.25\,\text{m}) \times \min\left(\frac{\text{Observations}}{2}, 1.2\right) \times \text{Weight}$$

### Weather (Meteorological Timelines)
*   **Precipitation, Solar Radiation, Air Temperatures (Max/Min), Relative Humidity, Wind Speed:**
*   *Spatial Decay Math:* The weather score accounts for distance and altitude variance between the weather station and the field:
    $$\text{Distance Penalty} = \frac{\text{Weight}}{\max\left(1, \frac{\text{Distance}}{\text{Optimal Distance}}\right)}$$
    $$\text{Altitude Penalty} = \max\left(\text{Weight} - \text{Decay Factor} \times \frac{\Delta\text{Altitude}}{30\,\text{m}}, 0\right)$$
    The final parameter score is the minimum of the distance-penalized weight and the altitude-penalized weight.

### Observed State Variables
*   **Crop Yield, Biomass time-series, LAI, Soil Water dynamics, Soil Nitrate dynamics:** checklist of variables measured during the growing season to calibrate model outputs.

---

## 4. Activating V2 Extensions (Sensors, Satellites, & Genetics)

Under `2026-modern` mode, the sidebar unlocks three advanced biophysical checklist panels:

1.  **🛰️ Remote Sensing:** Evaluates high-resolution satellite arrays (Sentinel-2, Landsat) utilized to track crop growth. You rank parameters (spatial resolution, revisit cadence, cloud mask quality) from **N/A** up to **Platinum**.
2.  **🔌 In-situ Sensors:** Evaluates on-site telemetry feeds (soil moisture probes, flux towers). Rank parameters such as sensor calibration frequency and gap-filling algorithms.
3.  **🧬 Genetic/Cultivar:** Scores genetic data depth (e.g. genomic sequencing vs. manual cultivar phenological matching) and phenotypic trial linkages.

---

## 5. LiveM (Livestock) & TradeM (Economics) Integration

To support cross-disciplinary research, the V2 framework integrates two checklist blocks for livestock and socio-economics:

### 🐄 Livestock Checklist (LiveM)
Designed for pasture-based and intensive livestock modeling (e.g., PaSim, LiGHT):
*   **Animal Type:** Defines species (beef, dairy, sheep) and breed profiles.
*   **Herd Size & Demographics:** Captures stocking rates and herd age/sex distributions.
*   **Grazing Management:** Checklist for rotational grazing schedules, stocking adjustments, and pasture resting periods.
*   **Feed Intake & Diet Composition:** Checks if feed rations, nutritional indices, and supplementary concentrates are measured.
*   **Manure Management & GHG Emissions:** Checks for nitrous oxide, methane, and manure recycling records.

### 💰 Economics Checklist (TradeM)
Designed for bio-economic farm models and sector-level economic simulation (e.g., TOA-MD, CAPRI):
*   **Product Prices:** Commodity market prices and regional crop/livestock gate prices.
*   **Input Costs:** Costs of fertilizer, seed, machinery, energy, and hired labor.
*   **Production Volume & Farm Size Distribution:** Regional agricultural land distribution and farm stratification registries.
*   **Adoption Rate & Net Returns:** Farmer adoption timelines and net household returns.
*   **Policy Scenarios & Off-Farm Income:** Socio-economic drivers, agricultural subsidies, and household income diversity.

---

## 6. The FAIR Axis Matrix & Wallach 2024 Support Checklist

### FAIR Principles Evaluation
For each of the active rating categories (up to 13 blocks in V2), you can rank its **Findability, Accessibility, Interoperability, and Reusability** from N/A to Platinum.
*   **Multipliers:** The system averages the FAIR ratings for a block. A Platinum FAIR ranking yields a **1.0× multiplier** (no penalty). An N/A FAIR ranking applies a **0.5× penalty multiplier** to that category's biophysical score.
*   $$\text{Final Block Score} = \text{Raw Biophysical Score} \times \text{FAIR Multiplier}$$

### Wallach 2024 Support Checklist
This utility automatically translates your dataset's scores into supportable categories outlined in *Wallach's Guidelines for Crop Model Calibration (2024)*:
*   **Phenology Support:** Active if crop phenology observations have at least a Silver tier.
*   **Biomass Support:** Active if biomass observations have at least a Silver tier.
*   **Soil Water / Soil N Support:** Active if initial soil values and dynamic soil observations are recorded.
*   **Multi-Site / Multi-Year Support:** Evaluates dataset metadata flags to verify if spatial multi-site calibrations or temporal multi-year calibrations can be supported.

---

## 7. In-Browser Dirichlet Uncertainty Quantification

Subjective weights are always open to scientific debate. To illustrate how variation in category weights affects overall rankings, the toolbelt runs a **Dirichlet Monte Carlo simulation**:
1.  **Prior Distribution:** Applies a symmetric Dirichlet prior (concentration factor $\alpha = 0.85$) centered on the active framework weights.
2.  **Sampling:** Draws 10,000 random weight vector combinations.
3.  **Simulation:** Scores the active dataset using each sampled weight vector.
4.  **Percentiles:** Extracts the **p05 (worst-case)**, **p50 (median)**, and **p95 (best-case)** tier rankings.
5.  *PRNG seed:* A seed value is exposed (e.g. `12345`) to initialize a custom Mulberry32 pseudo-random number generator, ensuring identical uncertainty bounds are reproduced across runs.

---

## 8. Model Repository & Compatibility Matches

The Model Repository maps the parameters you check in your dataset against the input/output dependencies of major simulation models:

```mermaid
graph TD
    A[User Dataset Checklist] -->|Scored & Mapped| B(The Integrator Core)
    B -->|Check Dependencies| C{Model Catalog}
    C -->|Biophysical Crop| D[HERMES, DSSAT, APSIM, WOFOST, MONICA, AquaCrop, STICS]
    C -->|Pasture & Herd| E[PaSim, LiGHT]
    C -->|Bio-Economic| F[TOA-MD, CAPRI]
```

### Compatibility Indicators
1.  **Visual Conic Progress Gauges:** Displays the percentage of mandatory and optional parameters matched.
    *   `Suitable` (100% mandatory parameters met)
    *   `Partially Suitable` (Some mandatory parameters checked, but others are missing)
    *   `Unsuitable` (Missing key essential parameters)
2.  **`⚠ No Data` Warning Badge:** Triggers if a parameter is checked in the UI but its corresponding observation count is 0. This flags structural completeness checks.

---

## 9. Cross-Model Linkage Validation System

When transitioning from single-crop modeling to integrated assessments (linking crop biomass, animal feeds, and economic returns), datasets must maintain consistent cross-disciplinary parameters. The validation system flags inconsistencies:

*   **PaSim (Pasture):** Triggers a warning if PaSim is selected, but the grazing stocking rate (`livestock.stockingRate`) is unchecked.
*   **LiGHT (Livestock Herd):** Triggers a warning if livestock herd modeling is selected, but crop biomass and yield observations are missing (no linkage to forage feed availability).
*   **TOA-MD (Economic Adoption):** Triggers a warning if the economic adoption model is selected, but neither crop yield observations nor animal productivity metrics are checked (no bio-physical productivity inputs to drive the economic adoption curves).
*   **CAPRI (Agricultural Sector Economics):** Triggers a warning if regional sector economics are run without price indices or production input cost structures.

---

## 10. AgMIP ACE JSON Import & Exporters Guide

The toolbelt serves as an interactive translation bridge for standard agricultural data networks:

### AgMIP ACE JSON Parser
Click **Import AgMIP JSON** and load an AgMIP crop experiment file. The parser translates standard AgMIP schemas:
*   Daily weather arrays map to weather checklist observations counts.
*   Soil profiles layers (pH, bulk density, depth) map to soil depth grids.
*   Management timeline operations map to management event counts.
*   Dynamic crop measurements (HWAH, LAI) map to state variables checklists.

### DSSAT .SOL Exporter
Translates soil profiles into a strict, space-padded, fixed-width `.SOL` format:
*   Generates `@SITE` header cards.
*   Translates clay, silt, organic carbon, pH, bulk density, and water limits.
*   Pads headers and float fields to guarantee parsing by the DSSAT Fortran engine.

### APSIM Soil & Management JSON Exporters
*   **APSIM Soil JSON:** Builds structured JSON profiles containing albedo (`salb`), evaporation limits (`u`), and layered grids (`slll`, `sldul`, `slsat`, `sllb`) readable by APSIM 7.x/APSIM NextGen.
*   **APSIM Management JSON:** Outputs chronological sequences of management events (sowing populations, fertilizer applications, and irrigation events).

---

## 11. Step-by-Step Workflows

### Workflow A: Rating an Experimental Dataset
1.  Navigate to the **Dashboard** (`app.html`).
2.  Select a dataset from the **Dataset Select** dropdown (e.g. `Müncheberg Crop Rotation`).
3.  Choose your scoring framework in the header (e.g. `2015-kersebaum`).
4.  Expand the checklist sections (Management, Soil, Weather, etc.) and check parameters that were measured at your site. Input the number of observations or sample depth.
5.  Observe the dynamic overall score and tier badge updating instantly in the top-right card.

### Workflow B: Evaluating Integrated Model Compatibility & Warnings
1.  Switch the version select in the header to **`2026-modern`** to activate V2 extensions.
2.  Open the **Livestock** and **Economics** tabs, check some parameters, and provide observations counts.
3.  Navigate to the **Models** tab in the sidebar.
4.  Select a model from the list (e.g. **TOA-MD**).
5.  Inspect the **Circular Conic Gauges** for input/output matching rates.
6.  Look at the **Cross-Model Linkages** panel below. If any linkages are missing (e.g. neither crop yield nor animal productivity is checked), read the specific warning description and update your dataset checklist to satisfy the model linkage.

### Workflow C: Exporting Model Configurations
1.  Import your dataset or enter details manually.
2.  Select the **Exporters** tab in the sidebar.
3.  Review the raw file preview boxes (DSSAT Soil, APSIM Soil, APSIM Management).
4.  Click **Download DSSAT .SOL**, **Download APSIM Soil**, or **Download APSIM Management** to save the formatted files locally.

---

## 12. Troubleshooting & FAQs

**Q: Why does my overall score suddenly drop to 0 with a "MinData Missing!" badge?**
*   *A:* In crop modeling, certain parameters are scientifically critical. If a required parameter (such as sowing date or precipitation) is checked in your dataset but has an observation count of 0 (or a soil depth of 0), the algorithm collapses the score to enforce data completeness. Add the missing data counts or uncheck the parameter to resolve this.

**Q: Can I use the toolbelt offline?**
*   *A:* Yes! The MAD Web Toolbelt is designed as a zero-dependency client-side utility. You can download the files locally and double-click `app.html` or `index.html` to run the entire suite without an internet connection.

**Q: How do I save my changes?**
*   *A:* Click **Export JSON** to download a local `.json` file containing your entire dataset state. You can reload this file at any time by clicking **Import JSON** and selecting the file.

**Q: Why is my remote sensing or livestock score not showing up under `2015-kersebaum`?**
*   *A:* Extension blocks (Remote Sensing, Sensors, Genetics, Livestock, Economics) and FAIR multipliers are exclusive to the `2026-modern` framework. If a legacy framework is selected, these blocks are disabled to preserve backwards compatibility with the original Qt outputs.