gridfia 0.3.1

Spatial raster analysis for USDA Forest Service BIGMAP data - Part of the FIA Python Ecosystem

Spatial raster analysis for USDA Forest Service BIGMAP data

_{Part of the FIAtools ecosystem: pyFIA · gridFIA · pyFVS · askFIA}

---

GridFIA provides efficient Zarr-based storage and processing for localized forest biomass analysis using USDA Forest Service BIGMAP data.

About BIGMAP

BIGMAP (FIA Tree Species Aboveground Biomass Layers) provides tree species biomass estimates at 30-meter resolution across the continental United States.

Attribute	Value
Resolution	30 meters
Species	327 individual tree species + total biomass
Coverage	Coterminous United States (CONUS)
Data Year	2018
Units	Tons per acre
Source Data	Landsat 8 OLI (2014-2018) + 212,978 FIA plots

The methodology uses harmonic regression to characterize vegetation phenology from Landsat time series imagery, then K-nearest neighbors imputation to associate pixels with similar FIA plots based on ecological gradients across 36 ecological provinces.

Wilson, B.T., Knight, J.F., and McRoberts, R.E., 2018. "Harmonic regression of Landsat time series for modeling attributes from national forest inventory data." ISPRS Journal of Photogrammetry and Remote Sensing, 137: 29-46.

What GridFIA Does

• Converts BIGMAP GeoTIFF data into cloud-optimized Zarr arrays
• Enables localized analysis for any US state, county, or custom region
• Calculates forest diversity metrics (Shannon, Simpson, richness)
• Optimizes data access patterns for scientific computing workflows
• Visualizes publication-ready maps with automatic boundary detection

Installation

# Using uv (recommended)
uv venv
uv pip install -e ".[dev]"

# Using pip
pip install -e ".[dev]"

Quick Start

from gridfia import GridFIA

# Initialize API
api = GridFIA()

# List available species
species = api.list_species()

# Download species data for a location
files = api.download_species(
    state="North Carolina",
    county="Wake",
    species_codes=["0131", "0068"],  # Loblolly Pine, Red Maple
    output_dir="data/wake"
)

# Create Zarr store from downloaded data
zarr_path = api.create_zarr(
    input_dir="data/wake",
    output_path="data/wake_forest.zarr"
)

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

# Create visualization maps
maps = api.create_maps(
    zarr_path=zarr_path,
    map_type="diversity",
    output_dir="maps/"
)

Using Bounding Boxes

from gridfia import GridFIA

api = GridFIA()

# Download using explicit bounding box (Web Mercator)
files = api.download_species(
    bbox=(-8792000, 4274000, -8732000, 4334000),
    crs="3857",
    species_codes=["0131"],
    output_dir="data/custom"
)

Supported Locations

• All 50 US States with automatic State Plane CRS detection
• Any US County within a state
• Custom Regions via bounding box
• Multi-State Regions by combining multiple states

Available Calculations

Calculation	Description	Units
species_richness	Number of tree species per pixel	count
shannon_diversity	Shannon diversity index	index
simpson_diversity	Simpson diversity index	index
evenness	Pielou's evenness (J)	ratio
total_biomass	Total biomass across all species	Mg/ha
dominant_species	Most abundant species by biomass	species_id
species_proportion	Proportion of specific species	ratio

API Reference

GridFIA Class

from gridfia import GridFIA
from gridfia.config import GridFIASettings, CalculationConfig

# Initialize with default settings
api = GridFIA()

# Initialize with custom settings
settings = GridFIASettings(
    output_dir=Path("output"),
    calculations=[
        CalculationConfig(name="species_richness", enabled=True),
        CalculationConfig(name="shannon_diversity", enabled=True)
    ]
)
api = GridFIA(config=settings)

Methods

Method	Description
list_species()	List available species from BIGMAP
download_species()	Download species data for a location
create_zarr()	Create Zarr store from GeoTIFF files
calculate_metrics()	Run forest metric calculations
create_maps()	Create visualization maps
validate_zarr()	Validate a Zarr store
get_location_config()	Get location configuration

Integration with pyFIA

from pyfia import FIA
from gridfia import GridFIA

# Get species information from pyFIA
with FIA() as fia:
    species_info = fia.species()

# Use species codes with GridFIA
api = GridFIA()
files = api.download_species(
    state="Oregon",
    species_codes=species_info["spcd"].tolist()
)

Development

# Run tests
uv run pytest

# Format code
uv run black gridfia/
uv run isort gridfia/

# Type checking
uv run mypy gridfia/

# Build documentation
uv run mkdocs serve

Citation

@software{gridfia2025,
  title = {GridFIA: Spatial Raster Analysis for USDA Forest Service BIGMAP Data},
  author = {Mihiar, Christopher},
  year = {2025},
  url = {https://github.com/mihiarc/gridfia}
}

---

_{Built by Chris Mihiar · USDA Forest Service Southern Research Station}