README.md

---
pipeline_tag: text-classification
library_name: transformers
tags:
- transformers
- crop-yield
- multi-temporal
- regression
- yield-estimation
- yield-weather-soil
license: mit
---

# Yield Estimation Transformer

A Hugging Face Transformers model for county-level corn yield estimation using multi-temporal 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`.

### Tags

- Crop Yield Estimation
- Digital Agriculture
- Transformers
- Multi-Temporal Modeling
- Regression
- Hugging Face Transformers
- FlexServ

### License

- [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## References

### USA County Level Crop Yield Dataset

This model uses the USA County Level Crop Yield Dataset. 

```bibtex

@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

---

# Tutorials

### Overview

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.

The model accepts six weekly weather variables:

- `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
```

A cutoff determines how many weeks of weather information are available to the model. A cutoff of `52` represents full-season inference.

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
```

---

# 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
├── configuration_yield.py
├── model.safetensors
├── modeling_yield.py
├── requirements.txt
├── sample_input_weekly.json
├── tokenization_yield.py
├── tokenizer_config.json
└── yield_transformer.py
```

A complete inference example is provided in:

```text
sample_input_weekly.json
```

### Installation

Clone the model repository:

```bash
git clone https://huggingface.co/ICICLE-AI/yield-estimation
cd yield-estimation
```

Create and activate a Python environment:

```bash
conda create -n yield_hf python=3.10
conda activate yield_hf
```

Install the required dependencies:

```bash
pip install -r requirements.txt
```

### Usage

#### Local Hugging Face Inference

Load the model through the Hugging Face `text-classification` pipeline:

```python
import json
from transformers import pipeline

pipe = pipeline(
    "text-classification",
    model="ICICLE-AI/yield-estimation",
    tokenizer="ICICLE-AI/yield-estimation",
    trust_remote_code=True,
)

with open("sample_input_weekly.json") as f:
    sample = json.load(f)

prediction = pipe(json.dumps(sample))

print(prediction)
```

Example output:

```python
[
    {
        "label": "YIELD_BU_ACRE",
        "score": 165.1769561767578
    }
]
```

The `score` is the predicted corn yield in bushels per acre.

#### Input Format

The structured input contains:

```json
{
  "crop": "corn",
  "weather_format": "weekly",
  "cutoff": 52,
  "weather": {
    "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": {
    "bdod_mean_0-5cm": 0.0,
    "...": "remaining soil features"
  }
}
```

The complete set of 66 soil variables and their expected ordering are stored in `config.json`.

The tokenizer:

1. parses the JSON-formatted string,
2. validates the expected input fields,
3. constructs the weather, soil, crop, and cutoff tensors.

The Hugging Face pipeline then passes these tensors to the pretrained model for inference.

#### FlexServ Inference

The model has been tested for inference through FlexServ using:

```text
Task: text-classification
Model: ICICLE-AI/yield-estimation
```

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.

Conceptually, a FlexServ request has the following form:

```json
{
  "task": "text-classification",
  "inputs": "{\"crop\":\"corn\",\"weather_format\":\"weekly\",\"cutoff\":52,\"weather\":{...},\"soil\":{...}}",
  "parameters": {},
  "model": "ICICLE-AI/yield-estimation"
}
```

A successful response has the form:

```json
[
  {
    "label": "YIELD_BU_ACRE",
    "score": 165.1769561767578
  }
]
```

The returned `score` is the estimated yield in `bu/acre`.

#### 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(
    "text-classification",
    model=".",
    tokenizer=".",
    trust_remote_code=True,
)

print(pipe(json.dumps(sample)))
PY
```

Expected output for the included sample is approximately:

```text
[{'label': 'YIELD_BU_ACRE', 'score': 165.1769561767578}]
```

---

# Explanation

### 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.