Skip to content

GridFIA Documentation

Welcome to GridFIA - a Python API for spatial forest analysis using USDA Forest Service BIGMAP data.

What is GridFIA?

GridFIA is a user-friendly wrapper that makes it easy to work with BIGMAP 2018 forest biomass data. BIGMAP provides 30-meter resolution estimates of tree species biomass across the contiguous United States, and GridFIA gives you a clean Python API to:

  • Download species biomass rasters for any state, county, or custom region
  • Store data efficiently in Zarr format
  • Calculate diversity metrics (Shannon, Simpson, richness, evenness)
  • Generate publication-ready maps and visualizations

Quick Start

# Install with uv (recommended)
uv pip install gridfia

# Or with pip
pip install gridfia

from gridfia import GridFIA

api = GridFIA()

# Download species data for Montana
files = api.download_species(
    state="Montana",
    species_codes=["0202", "0122"],  # Douglas-fir, Ponderosa pine
    output_dir="downloads/"
)

# Create Zarr store
zarr_path = api.create_zarr("downloads/", "data/montana.zarr")

# Calculate diversity metrics
results = api.calculate_metrics(
    zarr_path,
    calculations=["species_richness", "shannon_diversity"]
)

# Create maps
maps = api.create_maps(zarr_path, map_type="diversity", state="MT")

Key Features

Simple API

One class with a clean, discoverable interface:

api = GridFIA()

# Core workflow
api.list_species()                # See available species
api.download_species()            # Download raster data
api.create_zarr()                 # Convert to Zarr format
api.calculate_metrics()           # Run forest calculations
api.calculate_metrics_with_stats()  # Metrics with confidence intervals
api.create_maps()                 # Generate visualizations

# Configuration & utilities
api.get_location_config()         # Configure geographic extents
api.list_calculations()           # See available metrics
api.validate_zarr()               # Validate data stores
api.set_seed()                    # Set seed for reproducibility

15+ Forest Metrics

Category Metrics
Diversity Species richness, Shannon index, Simpson index, Evenness
Biomass Total biomass, Species proportion, Threshold analysis
Species Dominant species, Presence/absence, Rare/common species

Zarr Storage

GridFIA uses Zarr for efficient storage and processing of large raster datasets with configurable chunking and compression.

Any Geographic Extent

Download data for any US location:

# Entire state
api.download_species(state="California")

# Specific county
api.download_species(state="Texas", county="Harris")

# Custom bounding box
api.download_species(bbox=(-123.5, 45.0, -122.0, 46.5), crs="EPSG:4326")

Documentation

About BIGMAP Data

BIGMAP (Biomass and Carbon Mapping) provides modeled estimates of live tree biomass at 30-meter resolution. The data is derived from:

  • FIA plot measurements
  • Landsat imagery
  • Topographic variables
  • Climate data

Species-level biomass estimates are available for 300+ tree species. See the FIA BIGMAP documentation for methodology details.

Contributing

We welcome contributions! See our Contributing Guide for development setup and guidelines, or visit our GitHub repository to report issues and submit pull requests.

Learn More

  • GitHub - Source code and issue tracker
  • PyPI - Package installation

License

GridFIA is released under the MIT License.

Built by Chris Mihiar ยท USDA Forest Service Southern Research Station