Agricultural Study Area Mapping

GitHub Repository: https://github.com/RasikhAli/Agricultural-Study-Area-Mapping

Overview

This project generates publication-quality study area maps for agricultural research across two regions:

1. United States (IA, MD, MS): Three Landsat ARD tile study sites with Köppen-Geiger climate classification
2. France (PASTIS Dataset): Four Sentinel-2 tile regions covering 2,433 agricultural parcels

The maps are fully reproducible, data-driven, and use high-resolution geospatial datasets with automated processing pipelines.

Features

• ✅ Data-driven site extraction - Sites dynamically extracted from actual ARD tile geometries and PASTIS metadata
• ✅ High-resolution boundaries - Natural Earth 10m resolution for accurate state/country outlines
• ✅ Real climate data - Köppen-Geiger classification at 1 km resolution with dissolved, clean polygons
• ✅ Automated data processing from authoritative sources (Beck et al. 2018, USGS, Natural Earth)
• ✅ Publication-ready output - 300 DPI PNG maps with legends, scale bars, and black border frames
• ✅ Multiple export formats - Shapefiles, KML, and documentation
• ✅ Full reproducibility - Complete data provenance and source code included

Study Areas

Study Area 1: United States

Sites are dynamically extracted from actual Landsat ARD tile geometries in the CONUS ARD grid:

• Site IA (Iowa): Landsat ARD tile h18v07 - Center: 42.68°N, 93.43°W
• Site MD (Missouri): Landsat ARD tile h20v11 - Center: 37.21°N, 90.20°W
• Site MS (Mississippi): Landsat ARD tile h20v14 - Center: 33.19°N, 90.50°W

Climate zones (dissolved from 1km raster data):

• Cfa: Temperate, no dry season, hot summer (southern states)
• Dfa: Cold, no dry season, hot summer (Great Lakes region)
• Dfb: Cold, no dry season, warm summer (northern states)
• BSk: Arid, steppe, cold (western plains)

Study Area 2: France (PASTIS)

Regions are dynamically extracted from PASTIS dataset metadata.geojson:

• T30UXV: 531 agricultural patches - Center: 49.14°N, 0.87°W (Normandy)
• T31TFJ: 623 agricultural patches - Center: 43.75°N, 4.94°E (Provence)
• T31TFM: 723 agricultural patches - Center: 46.44°N, 5.02°E (Rhône-Alpes)
• T32ULU: 556 agricultural patches - Center: 48.24°N, 7.03°E (Alsace)

Total: 2,433 agricultural parcels from the PASTIS dataset (Garnot & Landrieu, 2021)

Installation

Prerequisites

• Python 3.8 or higher
• pip package manager

Setup

1. Clone the repository:

git clone https://github.com/RasikhAli/agricultural-study-area-mapping.git
cd agricultural-study-area-mapping

1. Create and activate virtual environment:

python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

1. Install dependencies:

pip install -r requirements.txt

Data Requirements

The script requires the following datasets (place in USDATA/ folder):

1. Köppen-Geiger Climate Classification

• Source: Beck et al. (2018) - https://doi.org/10.1038/sdata.2018.214
• File: USDATA/Beck_KG_V1/Beck_KG_V1_present_0p0083.tif
• Resolution: 1 km (0.0083 degrees)

2. Landsat ARD Tile Grid

• Source: USGS Landsat Collection 2 ARD
• File: USDATA/CONUS_C2_ARD_grid/conus_c2_ard_grid.shp
• URL: https://www.usgs.gov/landsat-missions/landsat-shapefiles-and-kml-files

3. PASTIS Dataset

• Source: Garnot & Landrieu (2021)
• File: PASTIS/PASTIS/metadata.geojson
• URL: https://github.com/VSainteuf/pastis-benchmark

Usage

Run the main script to generate both study area maps:

python study_area_map.py

The script will:

1. Download Natural Earth data (countries, states at 10m resolution) - cached locally
2. Load Köppen-Geiger climate raster from USDATA folder
3. Process and dissolve climate zones into clean polygons (4 classes)
4. Extract study sites from Landsat ARD tile grid (USDATA)
5. Extract PASTIS regions from metadata.geojson (2,433 patches)
6. Generate publication-quality maps (300 DPI) with proper styling
7. Export shapefiles, KML files, and documentation to output/ folder

Output

All outputs are saved to the output/ folder and copied to deliverables/:

U.S. Study Area

• us_study_area_map.png - Publication-ready map (300 DPI)

  • High-resolution state boundaries (Natural Earth 10m)
  • Dissolved Köppen-Geiger climate zones (clean polygons)
  • Study sites extracted from actual ARD tile geometries
  • Black border frame, scale bar, legend
  • Darkened overlay for non-US areas

• us_study_sites_shp/ - Study site boundaries (Shapefile format)

  • Actual ARD tile geometries (h18v07, h20v11, h20v14)
  • Attributes: name, id, color, ard_tile

• us_study_sites.kml - Study sites for Google Earth/GIS software

France PASTIS Study Area

• france_pastis_study_area_map.png - Publication-ready map (300 DPI)

  • Satellite basemap (contextily)
  • 4 Sentinel-2 tile regions dynamically extracted
  • Study regions with patch counts
  • Scale bar, legend, north arrow

• france_pastis_regions_shp/ - Region boundaries (Shapefile)

  • Dynamically extracted from PASTIS metadata
  • Attributes: name, tile, id, color, n_patches

• france_pastis_regions.kml - Regions for Google Earth

Documentation

• data_sources.txt - Complete data provenance and layer list
• study_area_map.py - Full source code for reproducibility

Project Structure

agricultural-study-area-mapping/
├── study_area_map.py              # Main script (1,200+ lines)
├── requirements.txt                # Python dependencies
├── README.md                       # This file
├── .gitignore                      # Git ignore rules
│
├── output/                         # Generated outputs (auto-created)
│   ├── us_study_area_map.png      # U.S. map (300 DPI)
│   ├── us_study_sites_shp/        # U.S. sites shapefile
│   ├── us_study_sites.kml         # U.S. sites KML
│   ├── france_pastis_study_area_map.png  # France map (300 DPI)
│   ├── france_pastis_regions_shp/ # France regions shapefile
│   ├── france_pastis_regions.kml  # France regions KML
│   └── data_sources.txt           # Data provenance
│
├── deliverables/                   # Final deliverables (copied from output/)
│   ├── us_study_area_map.png
│   ├── france_pastis_study_area_map.png
│   ├── study_area_map.py          # Source code
│   └── README.md                   # Deliverables documentation
│
├── cache/                          # Downloaded Natural Earth data (auto-created)
│   ├── ne_countries_110m.gpkg     # Low-res countries
│   ├── ne_states_110m.gpkg        # Low-res states
│   ├── ne_countries_10m.gpkg      # High-res countries
│   └── ne_states_10m.gpkg         # High-res states (for accurate outlines)
│
├── USDATA/                         # User-provided data (not in git)
│   ├── Beck_KG_V1/                # Köppen-Geiger climate classification
│   │   └── Beck_KG_V1_present_0p0083.tif  # 1km resolution raster
│   └── CONUS_C2_ARD_grid/         # Landsat ARD tile grid
│       └── conus_c2_ard_grid.shp  # ARD tile boundaries
│
└── PASTIS/                         # PASTIS dataset (not in git)
    └── PASTIS/
        └── metadata.geojson        # 2,433 agricultural parcels

References

1. Beck, H.E., et al. (2018). Present and future Köppen-Geiger climate classification maps at 1-km resolution. Scientific Data, 5, 180214. https://doi.org/10.1038/sdata.2018.214

2. Garnot, V.S.F., & Landrieu, L. (2021). Panoptic Segmentation of Satellite Image Time Series with Convolutional Temporal Attention Networks. ICCV 2021.

3. Natural Earth Data. Free vector and raster map data. https://www.naturalearthdata.com/

4. USGS Landsat ARD. Analysis Ready Data tile grid. https://www.usgs.gov/landsat-missions/

License

This project is licensed under the MIT License - see the LICENSE file for details.

Technical Details

Data Processing Pipeline

1. Natural Earth Data Download

   • Automatically downloads and caches country/state boundaries
   • Uses high-resolution 10m data for accurate outlines
   • Stored in cache/ folder as GeoPackage files

2. Köppen-Geiger Climate Processing

   • Reads 1km resolution GeoTIFF raster
   • Vectorizes climate zones (Cfa, Dfa, Dfb, BSk)
   • Dissolves fragmented polygons into clean shapes
   • Simplifies geometry (0.01° tolerance) for cleaner appearance

3. Study Site Extraction

   • U.S.: Dynamically extracts ARD tile geometries from shapefile
   • France: Dynamically extracts regions from PASTIS metadata
   • Both approaches ensure 100% data accuracy

4. Map Styling

   • 300 DPI for publication quality
   • Black border frames (2.0pt linewidth)
   • Scale bars with proper projection calculations
   • Legends with white background and black borders
   • Darkened overlays for non-study areas

Key Technologies

• GeoPandas: Geospatial data manipulation
• Rasterio: Raster data processing (Köppen-Geiger)
• Matplotlib: Map visualization and styling
• Shapely: Geometric operations (dissolve, simplify, clip)
• Contextily: Satellite basemap tiles for France map
• Natural Earth: High-quality administrative boundaries

Citation

If you use this code or maps in your research, please cite:

@software{agricultural_study_area_mapping,
  author = {Rasikh Ali},
  title = {Agricultural Study Area Mapping: Multi-Region GIS Analysis},
  year = {2025},
  url = {https://github.com/RasikhAli/Agricultural-Study-Area-Mapping}
}

Contact

For questions or issues, please open an issue on GitHub or contact the repository maintainer.