precision-ag 0.2.4
Comprehensive toolkit for precision agriculture analysis using satellite imagery and remote sensing
License: MIT
Requires Python: >=3.10
Keywords: agriculture, precision-agriculture, satellite, ndvi, remote-sensing, stac, sentinel-2, landsat, crop-monitoring

# 🌾 Precision Agriculture Analysis Toolkit

A comprehensive Python toolkit for precision agriculture analysis using satellite imagery and remote sensing data. This project provides both **analysis libraries** and **educational notebooks** to help farmers, researchers, and agronomists make data-driven decisions.

## 🎯 Project Vision

This toolkit aims to provide accessible, open-source tools for:
- 📊 **Agricultural Monitoring**: Track crop health, growth stages, and field conditions
- 🛰️ **Remote Sensing Analysis**: Process and analyze satellite imagery at scale
- 💧 **Resource Management**: Optimize irrigation, fertilization, and other inputs
- 📈 **Yield Prediction**: Forecast crop yields using multi-temporal analysis
- 🌍 **Environmental Impact**: Monitor soil health, carbon sequestration, and sustainability metrics

## 🚀 Current Capabilities

### Agricultural Index Analysis (Available Now)
Compute multiple agricultural indices from free satellite data (Sentinel-2, Landsat) to monitor crops, soil, and water resources.

**🌱 Vegetation Indices:**
- **NDVI** - Normalized Difference Vegetation Index (general vegetation health)
- **EVI** - Enhanced Vegetation Index (dense vegetation, atmospheric correction)
- **SAVI** - Soil Adjusted Vegetation Index (sparse vegetation, early season)
- **NDRE** - Normalized Difference Red Edge (chlorophyll, nitrogen status) *Sentinel-2 only*
- **GNDVI** - Green NDVI (photosynthetic activity, nitrogen)

**🏜️ Soil Indices:**
- **BSI** - Bare Soil Index (soil exposure, texture patterns)
- **SI** - Soil Index/Brightness Index (soil brightness, texture classification)

**💧 Water/Moisture Indices:**
- **NDMI** - Normalized Difference Moisture Index (vegetation water content, irrigation management)
- **NDWI** - Normalized Difference Water Index (water bodies, flood mapping)
- **MNDWI** - Modified NDWI (enhanced water detection, wetlands)

**Key Features:**
- Automatic data retrieval via STAC APIs
- Support for multiple AOI formats (GeoJSON, bounding boxes, coordinates)
- Efficient multi-index computation (loads each band once)
- Built-in side-by-side visualizations and statistics
- Interactive Jupyter tutorials for learning

### Elevation & Terrain Analysis (Available Now)
Fetch digital elevation models and compute terrain-derived products for drainage analysis, erosion risk, and zone-based field management.

**Data Sources:**
- **Copernicus GLO-30** — 30m resolution, global coverage
- **USGS 3DEP** — Up to 1m resolution, US only
- **Auto source selection** — Automatically picks the best source based on AOI location

**Terrain Products:**
- **Slope** — Terrain steepness in degrees (Horn method)
- **Aspect** — Downhill direction (0-360° from north)
- **Hillshade** — Simulated illumination for visualization
- **TWI** — Topographic Wetness Index (water accumulation and drainage)
- **Roughness** — Local elevation variability (3x3 std dev)

**Features:**
- Batch point sampling — efficiently query terrain at many lat/lon locations with a single DEM fetch
- Automatic CRS handling (geographic and projected)
- Windowed COG reads for fast remote data access

### Crop & Weather Data (Available Now)
Integrate USDA crop history and NASA weather data to filter analyses by crop type and growing-season conditions.

**Crop Data (CropScape / Cropland Data Layer):**
- Query the USDA NASS CropScape API to determine which crop was planted in a field for a given year
- Identify dominant crop by acreage within a field AOI (no full raster download)
- Filter to years when a target crop (e.g., corn) was grown—recommended for crop-specific NDVI analysis
- 30 m resolution CDL for the continental US; data typically available by February of the following year

**Weather Data (NASA POWER):**
- Query the NASA POWER API for daily weather at a point (precipitation, temperature, solar radiation, humidity, wind)
- Classify years by growing-season precipitation using 30-year climatological normals (dry / normal / wet)
- Filter NDVI or other analyses to exclude abnormally dry or wet years
- Growing-season and monthly queries; no API key required

## 🔮 Coming Soon

- **Time Series Analysis**: Track changes over growing seasons
- **Yield Modeling**: Predictive analytics for crop production
- **Field Boundary Detection**: Automated field delineation
- **Crop Classification**: Machine learning-based crop type identification
- **Integration with Ground Data**: Combine satellite indices with EC mapping, soil samples

## 🚀 Quick Start

### Installation

```bash
# Clone the repository
git clone https://github.com/chris/precision-ag.git
cd precision-ag

# Create and activate a virtual environment (recommended)
# Option 1: Using uv (fastest)
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Option 2: Using virtualenv
virtualenv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package
pip install -e .

# Or with optional dependencies for development and notebooks
pip install -e ".[dev,notebook]"
```

### Usage Examples

#### Simple NDVI Analysis

```python
from precision_ag import compute_ndvi_for_aoi

results = compute_ndvi_for_aoi(
    aoi_input=[-121.0, 37.0, -120.5, 37.5],
    start_date="2024-06-01",
    end_date="2024-06-30"
)
```

#### Multi-Index Agricultural Analysis

```python
from precision_ag import compute_agricultural_indices_for_aoi

# Compute multiple indices efficiently (loads each band once)
results = compute_agricultural_indices_for_aoi(
    aoi_input="field.geojson",
    start_date="2024-06-01",
    end_date="2024-06-30",
    indices=['ndvi', 'evi', 'bsi', 'ndmi', 'ndwi'],
    output_dir="my_analysis",
    visualize=True  # Creates side-by-side comparison plots
)
```

#### Crop History (CropScape)

Filter analyses to years when a target crop was actually grown:

```python
from precision_ag.crop_data import CroplandCROS, CROP_CODES

# Field AOI as GeoJSON (WGS84)
cros = CroplandCROS(field_aoi_wgs84=field_geojson)

# Years when corn was the dominant crop
corn_years = cros.get_corn_years([2019, 2020, 2021, 2022, 2023])

# Or filter by any CDL crop code
soy_years = cros.get_crop_years([2019, 2020, 2021, 2022, 2023], target_crop_code=CROP_CODES["soybeans"])
```

#### Weather Classification (NASA POWER)

Classify years by growing-season precipitation and fetch weather parameters:

```python
from precision_ag.weather_data import NASAPowerWeather

# Field centroid (lat, lon)
weather = NASAPowerWeather(latitude=41.5, longitude=-93.5)

# Classify years by precipitation vs 30-year normals
classification = weather.classify_years([2019, 2020, 2021, 2022, 2023])
# e.g. {"dry": [2021], "normal": [2019, 2022], "wet": [2020, 2023]}

# Growing-season weather for a single year
precip_mm = weather.get_growing_season_precipitation(2023)
all_params = weather.get_all_weather_parameters(2023)  # precip, temp, solar, humidity, wind
```

#### Elevation & Terrain Analysis

Fetch DEMs and compute terrain products for any field:

```python
from precision_ag import ElevationComputer, compute_elevation_for_aoi

# Quick elevation fetch for an AOI
dem, meta = compute_elevation_for_aoi([-96.56, 38.44, -96.55, 38.45])

# Full terrain analysis with visualization and statistics
ec = ElevationComputer()  # auto-selects USGS 3DEP (~1m) for US, Copernicus (30m) elsewhere
results = ec.compute_terrain_products(
    [-96.56, 38.44, -96.55, 38.45],  # bbox
    products=["elevation", "slope", "aspect", "twi"],
    visualize=True,
    print_stats=True,
)

# Batch sample at specific points (one DEM fetch for all points)
points = [(38.45, -96.55), (38.46, -96.54), (38.47, -96.53)]
point_data = ec.sample_points(points, products=["elevation", "slope", "twi"])
# [{"lat": 38.45, "lon": -96.55, "elevation": 412.3, "slope": 2.1, "twi": 11.8}, ...]
```

### Interactive Tutorials

Launch the Jupyter notebooks to learn interactively:

```bash
# Tutorial 1: Introduction to NDVI
jupyter notebook notebooks/NDVI_Tutorial.ipynb

# Tutorial 2: Comprehensive Vegetation Health Analysis
jupyter notebook notebooks/Vegetation_Health_Tutorial.ipynb

# Tutorial 3: Elevation & Terrain Analysis
jupyter notebook notebooks/Elevation_Data_Tutorial.ipynb
```

**Documentation:**
- [Satellite Indices Module](precision-ag/satellite_indices.py) - Agricultural indices (vegetation, soil, water)
- [Crop Data Module](precision-ag/crop_data.py) - USDA CropScape / Cropland Data Layer integration
- [Weather Data Module](precision-ag/weather_data.py) - NASA POWER weather and growing-season classification
- [Elevation Data Module](precision-ag/elevation_data.py) - DEM retrieval and terrain analysis

## 📁 Project Structure

```
precision-ag/
├── precision-ag/                      # Analysis libraries
│   ├── satellite_indices.py          # Agricultural indices (vegetation, soil, water)
│   ├── crop_data.py                  # USDA CropScape / Cropland Data Layer (crop history by field)
│   ├── weather_data.py               # NASA POWER weather and growing-season classification
│   ├── elevation_data.py             # DEM retrieval and terrain analysis (slope, aspect, TWI)
├── notebooks/                         # Educational tutorials
│   ├── NDVI_Tutorial.ipynb           # Tutorial 1: NDVI basics
│   ├── Vegetation_Health_Tutorial.ipynb  # Tutorial 2: Multi-index analysis
│   ├── GeoTIFF_Deep_Dive_Tutorial.ipynb  # Tutorial 3: Working with GeoTIFFs
│   └── Elevation_Data_Tutorial.ipynb   # Tutorial 4: Elevation & terrain analysis
├── tests/                             # Unit tests
├── .github/workflows/                 # CI/CD (GitHub Actions)
├── pyproject.toml                     # Project configuration
├── Makefile                           # Development commands
└── README.md                          # This file
```

## 🔧 Requirements

- Python >= 3.9
- numpy >= 1.20.0
- scipy >= 1.7.0
- rasterio >= 1.3.0
- matplotlib >= 3.5.0
- pystac-client >= 0.7.0
- planetary-computer >= 1.0.0
- requests >= 2.28.0
- shapely >= 2.0.0

## 🌍 Data Sources

This tool uses free, public data from the following sources:

**Satellite imagery (STAC APIs):**

| Satellite | Resolution | Revisit | Coverage | STAC Catalog |
|-----------|-----------|---------|----------|--------------|
| **Sentinel-2** | 10m | 5 days | Global | [Microsoft Planetary Computer](https://planetarycomputer.microsoft.com/) |
| **Landsat 8/9** | 30m | 16 days | Global | [Earth Search AWS](https://earth-search.aws.element84.com/) |

**Elevation:**

| Source | Resolution | Coverage | STAC Catalog |
|--------|-----------|----------|--------------|
| **Copernicus GLO-30** | 30m | Global | [Microsoft Planetary Computer](https://planetarycomputer.microsoft.com/) |
| **USGS 3DEP** | 1-60m | US | [Microsoft Planetary Computer](https://planetarycomputer.microsoft.com/) |

**Crop and weather:**
- **[USDA CropScape / NASS CDL](https://nassgeodata.gmu.edu/CropScape)** — Cropland Data Layer (30 m, continental US, annual)
- **[NASA POWER](https://power.larc.nasa.gov/)** — Daily weather (precipitation, temperature, solar, etc.) at 0.5° resolution; no API key required

## 💡 Use Cases

This toolkit supports various precision agriculture applications:

- 🌾 **Crop Health Monitoring**: Detect stress, disease, and nutrient deficiencies early
- 💧 **Irrigation Management**: Optimize water usage based on vegetation and soil data
- 🌱 **Growth Stage Tracking**: Monitor crop development throughout the season
- 📊 **Yield Forecasting**: Predict harvest outcomes using multi-temporal analysis
- 🏔️ **Terrain Analysis**: Assess drainage patterns, erosion risk, and water accumulation from DEMs
- 🌍 **Sustainability Reporting**: Track environmental metrics and carbon footprint
- 🔬 **Research & Development**: Support agricultural research with reproducible analysis

## 🛠️ Development

```bash
# Set up development environment
make install-dev

# Run all tests (unit + notebooks)
make test

# Run only unit tests
make test-unit

# Format code
make format

# Run linters
make lint

# Start Jupyter
make jupyter

# See all commands
make help
```

## 📝 Outputs

Analysis tools generate georeferenced raster files (GeoTIFF), visualizations (PNG/PDF), and statistical summaries. All outputs are compatible with standard GIS software (QGIS, ArcGIS) and can be used for further analysis or reporting.

## 📚 Learning & Documentation

This project emphasizes both **practical tools** and **educational resources**:

- **Analysis Libraries**: Production-ready Python modules for data processing
- **Tutorial Notebooks**: Interactive Jupyter notebooks explaining concepts, methods, and best practices
- **Documentation**: Inline code documentation and detailed docstrings
- **Examples**: Real-world use cases demonstrating various agricultural scenarios

Whether you're a researcher, agronomist, or developer, you'll find resources suited to your needs.

## 🤝 Contributing

Contributions are welcome! This project is in active development. Areas where you can help:
- Adding new analysis modules (vegetation indices, soil metrics, yield models)
- Creating educational notebooks and tutorials
- Improving documentation and examples
- Bug fixes and performance improvements

Please feel free to submit a Pull Request or open an issue to discuss new features.

## 📄 License

MIT License - see LICENSE file for details

## 🙏 Acknowledgments

- [Microsoft Planetary Computer](https://planetarycomputer.microsoft.com/) - Free satellite data access
- [STAC](https://stacspec.org/) - Standardized geospatial data catalog
- [ESA Copernicus](https://www.copernicus.eu/) - Sentinel missions
- [NASA/USGS](https://www.usgs.gov/landsat-missions) - Landsat program
- [USDA NASS CropScape](https://nassgeodata.gmu.edu/CropScape) - Cropland Data Layer
- [NASA POWER](https://power.larc.nasa.gov/) - Weather and solar radiation data
- [USGS 3DEP](https://www.usgs.gov/3d-elevation-program) - High-resolution elevation data
- [ESA Copernicus DEM](https://spacedata.copernicus.eu/collections/copernicus-digital-elevation-model) - Global 30m DEM

## 📧 Contact

For questions or issues, please open an issue on GitHub.

---

**Building the future of precision agriculture, one pixel at a time 🌾🛰️**