Update README.md

README.md

@@ -1,5 +1,5 @@
 ---
-pipeline_tag: tabular-regression
+pipeline_tag: text-classification
 library_name: transformers
 tags:
 - transformers
@@ -7,267 +7,348 @@ tags:
 - multi-temporal
 - regression
 - yield-estimation
+- yield-weather-soil
+license: mit
 ---
 
 # Yield Estimation Transformer
 
-A Hugging Face Transformers model for crop yield prediction using weather time-series and soil properties.
+A Hugging Face Transformers model for county-level corn yield estimation using multi-temporal weather observations and static soil properties.
 
-This repository contains a pretrained transformer model packaged for inference through the Hugging Face Transformers API and a custom Hugging Face Pipeline. The pipeline automatically performs preprocessing, feature normalization, model inference, and returns the predicted crop yield from daily weather observations and static soil properties.
+The model combines weekly weather time-series with static soil features to estimate corn yield in bushels per acre (`bu/acre`). It is packaged for inference using Hugging Face Transformers and has been tested for deployment through FlexServ.
 
----
+The Hugging Face `text-classification` task is used as the FlexServ-compatible serving interface. The underlying model performs scalar regression, and the returned `score` represents predicted corn yield in `bu/acre`.
 
-# Features
+### Tags
 
-- Transformer-based crop yield prediction
-- Weather time-series and static soil feature integration
-- Automatic preprocessing and normalization
-- Daily weather input support
-- Hugging Face AutoClass compatible
-- Custom Hugging Face Pipeline
-- CPU and GPU inference
+- Crop Yield Estimation
+- Digital Agriculture
+- Transformers
+- Multi-Temporal Modeling
+- Regression
+- Hugging Face Transformers
+- FlexServ
 
----
+### License
 
-# Quick Start
+- [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-```python
-import json
-from transformers import pipeline
+## References
 
-pipe = pipeline(
-    "yield-estimation",
-    model="Sarikaa-Sridhar/yield-estimation-transformer",
-    trust_remote_code=True,
-)
+### USA County Level Crop Yield Dataset
 
-with open("sample_input_daily.json") as f:
-    sample = json.load(f)
-
-prediction = pipe(sample)
-
-print(prediction)
-````
+This model uses the USA County Level Crop Yield Dataset. 
 
-Example output
+```bibtex
+@inproceedings{hasan2026vita,
+      title={VITA: Variational Pretraining of Transformers for Climate-Robust Crop Yield Forecasting},
+      author={Adib Hasan and Mardavij Roozbehani and Munther Dahleh},
+      booktitle={Proceedings of the 40th AAAI Conference on Artificial Intelligence},
+      year={2026},
+      url={https://arxiv.org/abs/2508.03589},
+}
 
-```json
-{
-  "predicted_yield": 182.28,
-  "cutoff": 4,
-  "effective_cutoff": 4,
-  "crop": "corn",
-  "weather_format": "daily"
+@article{Khaki2020CNNRNN,
+  author    = {Khaki, Saeed and Wang, Liang and Archontoulis, Sotirios V.},
+  title     = {A CNN-RNN Framework for Crop Yield Prediction},
+  journal   = {Frontiers in Plant Science},
+  volume    = {10},
+  pages     = {1750},
+  year      = {2020},
+  doi       = {10.3389/fpls.2019.01750},
+  publisher = {Frontiers Media SA}
 }
+
 ```
 
+### FlexServ
+
+The model is packaged and validated for deployment with FlexServ.
+
+FlexServ documentation: https://zhangwei217245.github.io/FlexServ/
+
+## Acknowledgements
+
+This work was developed as part of the ICICLE AI Institute.
+
+*National Science Foundation (NSF) AI Institute for Intelligent Cyberinfrastructure with Computational Learning in the Environment (ICICLE), Award OAC-2112606.*
+
+## Issue reporting
+
+Contact:
+
+For questions or support:
+
+Sarikaa Sridhar: sridhar.86@buckeyemail.osu.edu
+
 ---
 
-# Installation
+# Tutorials
 
-Clone the repository.
+### Overview
 
-```bash
-git clone https://huggingface.co/Sarikaa-Sridhar/yield-estimation-transformer
-cd yield-estimation-transformer
-```
+The Yield Estimation Transformer is a pretrained model for county-level corn yield estimation. It combines multi-temporal weekly weather observations with static soil properties and produces a scalar yield prediction in bushels per acre.
 
-Create a Python environment.
+The model accepts six weekly weather variables:
 
-```bash
-conda create -n yield_hf python=3.10
-conda activate yield_hf
+- `prcp`
+- `srad`
+- `swe`
+- `tmax`
+- `tmin`
+- `vp`
+
+It also uses 66 static soil features defined in `config.json`.
+
+The model supports prediction cutoffs at:
+
+```text
+20, 24, 28, 32, 36, 40, 44, 48, 52
 ```
 
-Install the required dependencies.
+A cutoff determines how many weeks of weather information are available to the model. A cutoff of `52` represents full-season inference.
 
-```bash
-pip install -r requirements.txt
+For deployment through FlexServ, the model uses the Hugging Face `text-classification` pipeline as its serving interface. This is an interface choice for inference compatibility; the underlying prediction task remains regression.
+
+### Prerequisites
+
+- Python 3.10+
+- PyTorch
+- Hugging Face Transformers
+- Dependencies listed in `requirements.txt`
+- FlexServ environment for service deployment
+
+Because the repository provides custom model configuration, tokenizer, and architecture code, Hugging Face loading requires:
+
+```python
+trust_remote_code=True
 ```
 
 ---
 
-# Repository Structure
+# How-To Guides
+
+### Problem Description
+
+The model estimates county-level corn yield from weather and soil information.
+
+The pretrained architecture expects structured numerical inputs rather than natural-language text. To make the model deployable through FlexServ's supported pipeline tasks, the model is exposed through the Hugging Face `text-classification` interface.
+
+The structured yield input is serialized as a JSON string. The custom tokenizer parses this string and converts the weather, soil, crop, and cutoff information into the tensors expected by the pretrained model.
+
+The resulting inference path is:
+
+```text
+JSON-formatted input string
+        ↓
+YieldTokenizer
+        ↓
+weather + soil + crop + cutoff tensors
+        ↓
+Yield Estimation Transformer
+        ↓
+scalar yield prediction
+        ↓
+YIELD_BU_ACRE score
+```
+
+The `score` returned by the pipeline is therefore a yield estimate in `bu/acre`, not a classification probability.
+
+### Getting Started
+
+The repository contains the files required for standalone Hugging Face and FlexServ inference:
 
 ```text
 .
+├── README.md
 ├── config.json
-├── model.safetensors
 ├── configuration_yield.py
+├── model.safetensors
 ├── modeling_yield.py
-├── pipeline_yield.py
-├── yield_transformer.py
-├── sample_input_daily.json
 ├── requirements.txt
-└── README.md
+├── sample_input_weekly.json
+├── tokenization_yield.py
+├── tokenizer_config.json
+└── yield_transformer.py
 ```
 
----
+A complete inference example is provided in:
 
-# Loading the Model
+```text
+sample_input_weekly.json
+```
 
-The model can be loaded directly using the Hugging Face AutoModel interface.
+### Installation
 
-```python
-from transformers import AutoModel
+Clone the model repository:
 
-model = AutoModel.from_pretrained(
-    "Sarikaa-Sridhar/yield-estimation-transformer",
-    trust_remote_code=True,
-)
+```bash
+git clone https://huggingface.co/Sarikaa-Sridhar/yield-estimation-transformer
+cd yield-estimation-transformer
 ```
 
-For most users, the recommended interface is the custom Hugging Face Pipeline shown in the Quick Start example.
+Create and activate a Python environment:
 
----
+```bash
+conda create -n yield_hf python=3.10
+conda activate yield_hf
+```
 
-# Input Format
+Install the required dependencies:
 
-The pipeline accepts a single JSON dictionary.
+```bash
+pip install -r requirements.txt
+```
 
-## Required fields
+### Usage
 
-* `crop`
-* `weather`
-* `soil`
+#### Local Hugging Face Inference
 
-## Optional fields
+Load the model through the Hugging Face `text-classification` pipeline:
 
-* `cutoff`
-* `weather_format`
+```python
+import json
+from transformers import pipeline
 
----
+pipe = pipeline(
+    "text-classification",
+    model="Sarikaa-Sridhar/yield-estimation-transformer",
+    tokenizer="Sarikaa-Sridhar/yield-estimation-transformer",
+    trust_remote_code=True,
+)
+
+with open("sample_input_weekly.json") as f:
+    sample = json.load(f)
 
-# Daily Weather Input
+prediction = pipe(json.dumps(sample))
 
-The recommended input format is `"daily"`.
+print(prediction)
+```
+
+Example output:
+
+```python
+[
+    {
+        "label": "YIELD_BU_ACRE",
+        "score": 165.1769561767578
+    }
+]
+```
 
-Example:
+The `score` is the predicted corn yield in bushels per acre.
+
+#### Input Format
+
+The structured input contains:
 
 ```json
 {
   "crop": "corn",
-  "weather_format": "daily",
-  "cutoff": 16,
+  "weather_format": "weekly",
+  "cutoff": 52,
   "weather": {
-    "dayl": [...],
-    "prcp": [...],
-    "srad": [...],
-    "tmax": [...],
-    "gdd": [...],
-    "tmin": [...],
-    "vp": [...],
-    "tmean": [...],
-    "precip_3day_avg_perday": [...],
-    "precip_7day_avg_perday": [...],
-    "precip_14day_avg_perday": [...]
+    "prcp": ["52 weekly values"],
+    "srad": ["52 weekly values"],
+    "swe": ["52 weekly values"],
+    "tmax": ["52 weekly values"],
+    "tmin": ["52 weekly values"],
+    "vp": ["52 weekly values"]
   },
   "soil": {
-    "ph": 6.5,
-    "om": 3.2,
-    "cec": 15.0,
-    "awc": 0.18,
-    "clay": 25.0,
-    "p_ppm": 30.0,
-    "k_ppm": 150.0,
-    "mg_ppm": 220.0,
-    "ca_ppm": 1800.0,
-    "k_te": 3.0,
-    "mg_te": 12.0,
-    "ca_te": 70.0,
-    "s_ppm": 15.0,
-    "zn_ppm": 1.2,
-    "fe_ppm": 50.0,
-    "mn_ppm": 20.0,
-    "cu_ppm": 0.8,
-    "b_ppm": 0.5,
-    "na_ppm": 10.0,
-    "sand": 40.0,
-    "silt": 35.0,
-    "bd": 1.3,
-    "elevation": 280.0,
-    "slope": 2.0
+    "bdod_mean_0-5cm": 0.0,
+    "...": "remaining soil features"
   }
 }
 ```
 
-The pipeline automatically:
+The complete set of 66 soil variables and their expected ordering are stored in `config.json`.
 
-* converts daily weather observations into the feature representation expected by the model
-* applies the normalization statistics stored with the model
-* performs inference
-* returns the predicted crop yield
+The tokenizer:
 
-No external preprocessing is required.
-
----
+1. parses the JSON-formatted string,
+2. validates the expected input fields,
+3. constructs the weather, soil, crop, and cutoff tensors.
 
-# Supported Crops
+The Hugging Face pipeline then passes these tensors to the pretrained model for inference.
 
-Current supported crop identifiers are:
+#### FlexServ Inference
 
-* `corn`
-* `maize`
-* `soy`
-* `soybean`
+The model has been tested for inference through FlexServ using:
 
----
+```text
+Task: text-classification
+Model: Sarikaa-Sridhar/yield-estimation-transformer
+```
 
-# Device Support
+FlexServ's `inputs` field expects a string. Therefore, the structured yield input must be supplied as a **JSON-formatted string**, rather than directly as a nested JSON object.
 
-The pipeline supports both CPU and NVIDIA CUDA GPUs.
+Conceptually, a FlexServ request has the following form:
 
-GPU inference:
+```json
+{
+  "task": "text-classification",
+  "inputs": "{\"crop\":\"corn\",\"weather_format\":\"weekly\",\"cutoff\":52,\"weather\":{...},\"soil\":{...}}",
+  "parameters": {},
+  "model": "Sarikaa-Sridhar/yield-estimation-transformer"
+}
+```
 
-```python
-from transformers import pipeline
+A successful response has the form:
 
-pipe = pipeline(
-    "yield-estimation",
-    model="Sarikaa-Sridhar/yield-estimation-transformer",
-    device=0,
-    trust_remote_code=True,
-)
+```json
+[
+  {
+    "label": "YIELD_BU_ACRE",
+    "score": 165.1769561767578
+  }
+]
 ```
 
-CPU inference:
+The returned `score` is the estimated yield in `bu/acre`.
 
-```python
+#### Validation
+
+The packaged model can be validated locally against the included sample:
+
+```bash
+python - <<'PY'
+import json
 from transformers import pipeline
 
+with open("sample_input_weekly.json") as f:
+    sample = json.load(f)
+
 pipe = pipeline(
-    "yield-estimation",
-    model="Sarikaa-Sridhar/yield-estimation-transformer",
-    device=-1,
+    "text-classification",
+    model=".",
+    tokenizer=".",
     trust_remote_code=True,
 )
-```
-
----
-
-# Pipeline Output
 
-The pipeline returns a Python dictionary.
+print(pipe(json.dumps(sample)))
+PY
+```
 
-Example:
+Expected output for the included sample is approximately:
 
-```json
-{
-  "predicted_yield": 182.28,
-  "cutoff": 16,
-  "effective_cutoff": 16,
-  "crop": "corn",
-  "weather_format": "daily"
-}
+```text
+[{'label': 'YIELD_BU_ACRE', 'score': 165.1769561767578}]
 ```
 
 ---
 
-# Acknowledgements
+# Explanation
 
-This work was developed as part of the ICICLE AI Institute.
-
-*National Science Foundation (NSF) AI Institute for Intelligent Cyberinfrastructure with Computational Learning in the Environment (ICICLE), Award OAC-2112606.*
+### Features
 
-```
-```
+- **Transformer-Based Yield Estimation:** Uses a transformer architecture to model temporal weather information for corn yield prediction.
+- **Weather and Soil Integration:** Combines six weekly weather variables with 66 static soil properties.
+- **Multi-Temporal Inference:** Supports yield estimation at multiple seasonal cutoffs from week 20 through week 52.
+- **Automatic Preprocessing:** The custom tokenizer converts JSON-formatted structured inputs into the tensors expected by the pretrained model.
+- **Automatic Normalization:** Weather and soil features are normalized using statistics stored with the model configuration.
+- **Regression Output:** Produces a scalar corn yield estimate in bushels per acre.
+- **Hugging Face Integration:** Uses the standard Transformers pipeline interface with repository-provided model and tokenizer code.
+- **FlexServ Deployment:** Uses the supported `text-classification` task to expose the regression model as a FlexServ inference service.
+- **CPU and GPU Support:** Supports PyTorch inference on CPU and compatible CUDA GPUs.
+- **Safetensors Weights:** Model weights are distributed using the Safetensors format.