🌾 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

Water Feature Data (Available Now)

Query federal water body and wetland datasets to identify known water features within a field.

Data Sources:

• NHD — USGS National Hydrography Dataset (lakes, ponds, reservoirs, swamps, playas)
• NWI — US Fish & Wildlife Service National Wetlands Inventory (all wetland types)

Features:

• Query by field AOI (GeoJSON polygon) via ArcGIS REST APIs
• Automatic pagination for large result sets
• Results clipped to AOI boundary and returned as Shapely geometries
• Combined WaterFeatures class unions both sources in a single call
• Non-fatal error handling — service outages don't break your pipeline

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 (USDA Cropland Data Layer):

• Query USDA's CDL ImageServer to determine which crop was planted in a field for a given year
• Identify the dominant crop by area within the field polygon, from a pixel histogram (no full raster download)
• Non-agricultural land cover (developed, forest, water, wetlands) is never reported as the crop
• Filter to years when a target crop (e.g., corn) was grown—recommended for crop-specific NDVI analysis
• Continental US, 1999–present; 30 m through 2023 and 10 m from 2024. A new year is typically published around February

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

# 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

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

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 (USDA CDL)

Resolve a field's rotation, or filter analyses to years when a target crop was actually grown:

from precision_ag.crop_data import CroplandCDL, CROP_CODES

# Field AOI as GeoJSON (WGS84) — Polygon or MultiPolygon
cdl = CroplandCDL(field_aoi_wgs84=field_geojson)

# Whole rotation, ready to store as JSON. Unresolved years are omitted.
history = cdl.get_crop_history_names([2020, 2021, 2022, 2023, 2024])
# {"2020": "corn", "2021": "soybeans", "2022": "corn", ...}

# Raw CDL codes instead of names, including None for years that did not resolve
codes = cdl.get_crop_history([2020, 2021, 2022])

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

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

# Coverage check — every year the service carries, in a single request
available = cdl.get_available_years()

CroplandCROS and CropScapeAPIError remain as aliases of CroplandCDL and CropDataError for code written against pre-0.4 releases.

Weather Classification (NASA POWER)

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

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

Water Feature Query (NHD + NWI)

Identify known water bodies and wetlands within a field:

from precision_ag.water_data import WaterFeatures, NHDWaterBodies

# Query both NHD and NWI in one call
wf = WaterFeatures()
water_geom = wf.query(field_aoi_geojson)
if water_geom:
    print(f"Found water: {water_geom.geom_type}")

# Or query individually
nhd = NHDWaterBodies()
nhd_water = nhd.query(field_aoi_geojson)

Elevation & Terrain Analysis

Fetch DEMs and compute terrain products for any field:

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:

# 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 - Agricultural indices (vegetation, soil, water)
• Water Data Module - NHD + NWI water feature queries
• Crop Data Module - USDA Cropland Data Layer integration
• Weather Data Module - NASA POWER weather and growing-season classification
• Elevation Data Module - 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 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)
│   ├── water_data.py                 # NHD + NWI water feature queries (ArcGIS REST APIs)
├── 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):

Elevation:

Water features:

• USGS NHD — National Hydrography Dataset (lakes, ponds, reservoirs, swamps)
• USFWS NWI — National Wetlands Inventory (all wetland types)

Crop and weather:

• USDA NASS Cropland Data Layer — crop type by pixel (continental US, annual; 30 m through 2023, 10 m from 2024), served from the PDI CDL ImageServer
• NASA POWER — 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

# 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 - Free satellite data access
• STAC - Standardized geospatial data catalog
• ESA Copernicus - Sentinel missions
• NASA/USGS - Landsat program
• USDA NASS Cropland Data Layer - crop type by pixel
• NASA POWER - Weather and solar radiation data
• USGS 3DEP - High-resolution elevation data
• ESA Copernicus DEM - Global 30m DEM
• USGS NHD - National Hydrography Dataset
• USFWS NWI - National Wetlands Inventory

📧 Contact

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

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