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 |
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
Affiliation
Developed in collaboration with USDA Forest Service Research & Development. gridFIA provides access to Forest Service spatial data products but is not part of the official FIA Program.
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}
}
Metadata
Release files for gridfia 0.5.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gridfia-0.5.2.tar.gz | 412.5 kB | Without provenance | Details for gridfia-0.5.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gridfia-0.5.2-py3-none-any.whl | Python 3 | none | any | Details for gridfia-0.5.2-py3-none-any.whl |
Total release size: 537.6 kB
Release files / gridfia-0.5.2.tar.gz
| Download URL | gridfia-0.5.2.tar.gz |
|---|---|
| Size | 412.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ff6ad24de79ecef83b7f5399042ede050f9497cff9c9e9b703970869d950b227
|
|
BLAKE2b-256 checksum How to use checksums |
eeb0fe22555ce214bef029e3967f96814c02eac06b2cb48a3368a5f0b7865852
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.10
|
Release files / gridfia-0.5.2-py3-none-any.whl
| Download URL | gridfia-0.5.2-py3-none-any.whl |
|---|---|
| Size | 125.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3f88c936443de2c4c9b37604ceca5f99e56521ce4f3f978bd7d8a53f410c4f68
|
|
BLAKE2b-256 checksum How to use checksums |
fb8da630025511b27fddecfc78995f069e7eabae5f01082b4c80e08e01408155
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.10
|
Security for gridfia 0.5.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.