Metadata-Version: 2.4
Name: gridfia
Version: 0.5.1
Summary: Spatial raster analysis for USDA Forest Service BIGMAP data - Part of the FIA Python Ecosystem
Project-URL: Homepage, https://fiatools.org/tools/gridfia/
Project-URL: Documentation, https://mihiarc.github.io/gridfia/
Project-URL: Repository, https://github.com/mihiarc/gridfia.git
Project-URL: Bug Tracker, https://github.com/mihiarc/gridfia/issues
Project-URL: Changelog, https://github.com/mihiarc/gridfia/releases
Project-URL: Source Code, https://github.com/mihiarc/gridfia
Project-URL: FIA Ecosystem, https://fiatools.org
Author-email: Christopher Mihiar <christopher.mihiar@usda.gov>
Maintainer-email: Christopher Mihiar <christopher.mihiar@usda.gov>
License: MIT
License-File: LICENSE
Keywords: bigmap,biodiversity,biomass,carbon-accounting,cloud-optimized,ecological-modeling,fia,forest-analysis,forest-inventory,forestry,geospatial,gis,landsat,raster,remote-sensing,shannon-diversity,simpson-diversity,species-diversity,species-richness,tree-species,usda,zarr
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: Pydantic :: 2
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: certifi>=2023.0.0
Requires-Dist: contextily>=1.4.0
Requires-Dist: fsspec>=2023.1.0
Requires-Dist: geopandas>=0.10.0
Requires-Dist: matplotlib-scalebar>=0.8.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: numcodecs>=0.9.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rasterio>=1.2.0
Requires-Dist: requests>=2.28.0
Requires-Dist: rich>=13.0.0
Requires-Dist: scikit-learn>=1.6.1
Requires-Dist: shapely>=2.0.0
Requires-Dist: tqdm>=4.67.1
Requires-Dist: xarray>=0.19.0
Requires-Dist: zarr>=2.10.0
Provides-Extra: dev
Requires-Dist: black>=22.0.0; extra == 'dev'
Requires-Dist: flake8>=5.0.0; extra == 'dev'
Requires-Dist: isort>=5.10.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=2.20.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
Requires-Dist: mkdocs-mermaid2-plugin>=1.0.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Requires-Dist: mkdocstrings-python>=1.0.0; extra == 'docs'
Requires-Dist: mkdocstrings>=0.24.0; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.8.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Description-Content-Type: text/markdown

<div align="center">
  <a href="https://fiatools.org"><img src="https://fiatools.org/logos/gridfia_logo.png" alt="gridFIA" width="400"></a>

  <p><strong>Spatial raster analysis for USDA Forest Service BIGMAP data</strong></p>

  <p>
    <a href="https://fiatools.org"><img src="https://img.shields.io/badge/FIAtools-Ecosystem-2E7D32" alt="FIAtools Ecosystem"></a>
    <a href="https://pypi.org/project/gridfia/"><img src="https://img.shields.io/pypi/v/gridfia?color=006D6D&label=PyPI" alt="PyPI"></a>
    <a href="https://pypi.org/project/gridfia/"><img src="https://img.shields.io/pypi/dm/gridfia?color=006D6D&label=Downloads" alt="PyPI Downloads"></a>
    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-006D6D" alt="License: MIT"></a>
    <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.9+-006D6D" alt="Python 3.9+"></a>
    <a href="https://mihiarc.github.io/gridfia/"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-006D6D" alt="Documentation"></a>
  </p>

  <p>
    <strong>Part of the <a href="https://fiatools.org">FIAtools Python Ecosystem</a></strong><br>
    <a href="https://fiatools.org/tools/pyfia/">pyFIA</a> ·
    <a href="https://fiatools.org/tools/gridfia/">gridFIA</a> ·
    <a href="https://fiatools.org/tools/pyfvs/">pyFVS</a> ·
    <a href="https://fiatools.org/tools/askfia/">askFIA</a>
  </p>
</div>

---

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

## About BIGMAP

[BIGMAP](https://data.fs.usda.gov/geodata/rastergateway/bigmap/index.php) (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

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

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

## Quick Start

```python
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

```python
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

```python
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

```python
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

```bash
# 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
```

## The FIAtools Ecosystem

GridFIA is part of the [FIAtools Python ecosystem](https://fiatools.org) - a unified suite of open-source tools for forest inventory applications:

| Tool | Purpose | Key Features |
|------|---------|--------------|
| [**pyFIA**](https://fiatools.org) | Survey & plot data | DuckDB backend, 10-100x faster than EVALIDator |
| [**gridFIA**](https://fiatools.org) | Spatial raster analysis | 327 species at 30m resolution, Zarr storage |
| [**pyFVS**](https://fiatools.org) | Growth simulation | Chapman-Richards curves, yield projections |
| [**askFIA**](https://fiatools.org) | AI interface | Natural language queries for forest data |

**[Explore the full ecosystem at fiatools.org](https://fiatools.org)**

## 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

```bibtex
@software{gridfia2025,
  title = {GridFIA: Spatial Raster Analysis for USDA Forest Service BIGMAP Data},
  author = {Mihiar, Christopher},
  year = {2025},
  url = {https://fiatools.org}
}
```

---

<div align="center">
  <a href="https://fiatools.org"><strong>fiatools.org</strong></a> · Python Ecosystem for Forest Inventory Applications<br>
  <sub>Built by <a href="https://github.com/mihiarc">Chris Mihiar</a> · USDA Forest Service Southern Research Station</sub>
</div>
