GridFIA API¶

The GridFIA class is the primary interface for all GridFIA functionality. It provides methods for downloading species data, creating Zarr stores, calculating forest metrics, and generating visualizations.

Overview¶

GridFIA follows an API-first design pattern, providing a single clean interface that:

Downloads species biomass rasters from the FIA BIGMAP service
Converts GeoTIFF files to cloud-optimized Zarr arrays
Calculates diversity metrics (Shannon, Simpson, richness)
Generates publication-ready maps and visualizations

Quick Start¶

from gridfia import GridFIA

# Initialize the API
api = GridFIA()

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

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

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

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

Class Reference¶

gridfia.api.GridFIA ¶

GridFIA(config: Optional[Union[str, Path, GridFIASettings]] = None, seed: Optional[int] = None)

Main API interface for GridFIA spatial forest analysis.

GridFIA provides spatial raster analysis of USDA Forest Service BIGMAP data, including species biomass mapping, diversity metrics, and visualization.

Examples¶

from gridfia import GridFIA api = GridFIA()

Download species data for North Carolina¶

api.download_species(state="NC", species_codes=["0131", "0068"])

Create zarr store from downloaded data¶

api.create_zarr("downloads/", "data/nc_forest.zarr")

Calculate forest metrics¶

results = api.calculate_metrics( ... "data/nc_forest.zarr", ... calculations=["species_richness", "shannon_diversity"] ... )

Create visualization¶

api.create_maps("data/nc_forest.zarr", map_type="diversity")

Initialize GridFIA API.

Parameters¶

config : str, Path, or GridFIASettings, optional Configuration file path or settings object. If None, uses default settings. seed : int, optional Random seed for reproducibility. If provided, all random operations (bootstrap, permutation tests, etc.) will be deterministic.

Examples¶

api = GridFIA(seed=42) # Reproducible results result1 = api.calculate_metrics(zarr_path)

api2 = GridFIA(seed=42) # Same seed = same results result2 = api2.calculate_metrics(zarr_path)

seed `property` ¶

seed: Optional[int]

Get current random seed.

rest_client `property` ¶

rest_client: BigMapRestClient

Lazy-load REST client for FIA BIGMAP service (thread-safe).

processor `property` ¶

processor: ForestMetricsProcessor

Lazy-load forest metrics processor (thread-safe).

set_seed ¶

set_seed(seed: int) -> None

Set random seed for reproducibility.

Parameters¶

seed : int Random seed value.

Examples¶

api = GridFIA() api.set_seed(42)

list_species ¶

list_species() -> List[SpeciesInfo]

List all available tree species from FIA BIGMAP service.

Returns¶

List[SpeciesInfo] List of available species with codes and names.

Examples¶

api = GridFIA() species = api.list_species() print(f"Found {len(species)} species") for s in species[:5]: ... print(f"{s.species_code}: {s.common_name}")

download_species ¶

download_species(output_dir: Union[str, Path] = 'downloads', species_codes: Optional[List[str]] = None, state: Optional[str] = None, county: Optional[str] = None, bbox: Optional[Tuple[float, float, float, float]] = None, polygon: Optional[Union[str, Path, GeoDataFrame]] = None, location_config: Optional[Union[str, Path]] = None, crs: str = '102100', use_boundary_clip: bool = False) -> List[Path]

Download species data from FIA BIGMAP service.

Parameters¶

output_dir : str or Path, default="downloads" Directory to save downloaded files. species_codes : List[str], optional Specific species codes to download. If None, downloads all. state : str, optional State name or abbreviation. county : str, optional County name (requires state). bbox : Tuple[float, float, float, float], optional Custom bounding box (xmin, ymin, xmax, ymax). polygon : str, Path, or GeoDataFrame, optional Custom polygon boundary. Data will be downloaded for the polygon's bbox and can be clipped to the polygon during create_zarr. location_config : str or Path, optional Path to location configuration file. crs : str, default="102100" Coordinate reference system for bbox. use_boundary_clip : bool, default=False If True, stores actual state/county boundary for later clipping. Only affects state/county downloads, ignored for bbox/polygon.

Returns¶

List[Path] Paths to downloaded files.

Examples¶

api = GridFIA()

Download for entire state¶

files = api.download_species(state="Montana", species_codes=["0202"])

Download for specific county with boundary stored¶

files = api.download_species( ... state="Texas", ... county="Harris", ... species_codes=["0131", "0068"], ... use_boundary_clip=True ... )

Download with custom polygon¶

files = api.download_species( ... polygon="study_area.geojson", ... species_codes=["0131"] ... )

Download with custom bbox¶

files = api.download_species( ... bbox=(-104, 44, -104.5, 44.5), ... crs="4326" ... )

create_zarr ¶

create_zarr(input_dir: Union[str, Path], output_path: Union[str, Path], species_codes: Optional[List[str]] = None, chunk_size: Tuple[int, int, int] = (1, 1000, 1000), compression: str = 'lz4', compression_level: int = 5, include_total: bool = True, clip_to_polygon: Optional[Union[bool, str, Path, GeoDataFrame]] = None) -> Path

Create a Zarr store from GeoTIFF files.

Parameters¶

input_dir : str or Path Directory containing GeoTIFF files. output_path : str or Path Output path for Zarr store. species_codes : List[str], optional Specific species codes to include. chunk_size : Tuple[int, int, int], default=(1, 1000, 1000) Chunk dimensions (species, height, width). compression : str, default="lz4" Compression algorithm. compression_level : int, default=5 Compression level (1-9). include_total : bool, default=True Whether to include or calculate total biomass. clip_to_polygon : bool, str, Path, or GeoDataFrame, optional Clip GeoTIFFs to polygon boundary before creating Zarr. - If True: looks for *_config.yaml in input_dir and uses its polygon - If str/Path: path to polygon file or config file - If GeoDataFrame: uses the provided polygon

Returns¶

Path Path to created Zarr store.

Examples¶

api = GridFIA() zarr_path = api.create_zarr( ... "downloads/montana_species/", ... "data/montana.zarr", ... chunk_size=(1, 2000, 2000) ... ) print(f"Created Zarr store at {zarr_path}")

With polygon clipping¶

zarr_path = api.create_zarr( ... "downloads/lane_county/", ... "data/lane.zarr", ... clip_to_polygon=True # Auto-detect from saved config ... )

calculate_metrics ¶

calculate_metrics(zarr_path: Union[str, Path], calculations: Optional[List[str]] = None, output_dir: Optional[Union[str, Path]] = None, config: Optional[Union[str, Path, GridFIASettings]] = None) -> List[CalculationResult]

Calculate forest metrics from Zarr data.

Parameters¶

zarr_path : str or Path Path to Zarr store containing biomass data. calculations : List[str], optional Specific calculations to run. If None, uses config or defaults. output_dir : str or Path, optional Output directory for results. config : str, Path, or GridFIASettings, optional Configuration to use for calculations.

Returns¶

List[CalculationResult] Results from each calculation.

Examples¶

api = GridFIA() results = api.calculate_metrics( ... "data/forest.zarr", ... calculations=["species_richness", "shannon_diversity", "total_biomass"] ... ) for r in results: ... print(f"{r.name}: {r.output_path}") ... print(f" Stats: {r.statistics}")

calculate_metrics_with_stats ¶

calculate_metrics_with_stats(zarr_path: Union[str, Path], calculations: Optional[List[str]] = None, n_bootstrap: int = 1000, confidence_level: float = 0.95) -> Dict[str, StatisticalResult]

Calculate forest metrics with bootstrap confidence intervals.

This method provides statistical context for each calculation, including confidence intervals and standard error estimates.

Parameters¶

zarr_path : str or Path Path to Zarr store containing biomass data. calculations : List[str], optional Specific calculations to run. If None, runs default calculations: ["species_richness", "shannon_diversity", "simpson_diversity", "total_biomass"]. n_bootstrap : int, default=1000 Number of bootstrap resamples for confidence intervals. confidence_level : float, default=0.95 Confidence level for intervals (e.g., 0.95 for 95% CI).

Returns¶

Dict[str, StatisticalResult] Dictionary mapping calculation names to StatisticalResult objects containing point estimates, confidence intervals, and metadata.

Examples¶

api = GridFIA(seed=42) # Reproducible results results = api.calculate_metrics_with_stats( ... "data/forest.zarr", ... calculations=["shannon_diversity", "species_richness"], ... n_bootstrap=1000, ... confidence_level=0.95 ... ) for name, result in results.items(): ... print(f"{name}:") ... print(f" Value: {result.value:.3f}") ... print(f" 95% CI: [{result.confidence_interval[0]:.3f}, " ... f"{result.confidence_interval[1]:.3f}]") ... print(f" SE: {result.standard_error:.3f}")

Notes¶

This method computes aggregate statistics across all pixels in the Zarr store. For pixel-level confidence intervals, use the underlying ForestCalculation.calculate_with_stats() method directly.

The bootstrap confidence intervals are computed by resampling the pixel values and computing the mean for each bootstrap sample.

create_maps ¶

create_maps(zarr_path: Union[str, Path], map_type: str = 'species', species: Optional[List[str]] = None, output_dir: Union[str, Path] = 'maps', format: str = 'png', dpi: int = 300, cmap: Optional[str] = None, show_all: bool = False, state: Optional[str] = None, basemap: Optional[str] = None) -> List[Path]

Create maps from Zarr data.

Parameters¶

zarr_path : str or Path Path to Zarr store. map_type : str, default="species" Type of map: "species", "diversity", "richness", "comparison". species : List[str], optional Species codes for species/comparison maps. output_dir : str or Path, default="maps" Output directory for maps. format : str, default="png" Output format. dpi : int, default=300 Output resolution. cmap : str, optional Colormap name. show_all : bool, default=False Create maps for all species. state : str, optional State boundary to overlay. basemap : str, optional Basemap provider.

Returns¶

List[Path] Paths to created map files.

Examples¶

api = GridFIA()

Create species map¶

maps = api.create_maps( ... "data/forest.zarr", ... map_type="species", ... species=["0202"], ... state="MT" ... )

Create diversity maps¶

maps = api.create_maps( ... "data/forest.zarr", ... map_type="diversity" ... )

Create comparison map¶

maps = api.create_maps( ... "data/forest.zarr", ... map_type="comparison", ... species=["0202", "0122", "0116"] ... )

get_location_config ¶

get_location_config(state: Optional[str] = None, county: Optional[str] = None, bbox: Optional[Tuple[float, float, float, float]] = None, crs: str = 'EPSG:4326', output_path: Optional[Union[str, Path]] = None) -> LocationConfig

Create or retrieve location configuration.

Parameters¶

state : str, optional State name or abbreviation. county : str, optional County name (requires state). bbox : Tuple[float, float, float, float], optional Custom bounding box. crs : str, default="EPSG:4326" CRS for custom bbox. output_path : str or Path, optional Path to save configuration.

Returns¶

LocationConfig Location configuration object.

Examples¶

api = GridFIA()

Get state configuration¶

config = api.get_location_config(state="Montana") print(f"Bbox: {config.web_mercator_bbox}")

Get county configuration¶

config = api.get_location_config(state="Texas", county="Harris")

Custom bbox configuration¶

config = api.get_location_config( ... bbox=(-104, 44, -104.5, 44.5), ... crs="EPSG:4326" ... )

list_calculations ¶

list_calculations() -> List[str]

List all available calculations.

Returns¶

List[str] Names of available calculations.

Examples¶

api = GridFIA() calcs = api.list_calculations() print(f"Available calculations: {calcs}")

validate_zarr ¶

validate_zarr(zarr_path: Union[str, Path]) -> Dict[str, Any]

Validate a Zarr store and return metadata.

Parameters¶

zarr_path : str or Path Path to Zarr store.

Returns¶

Dict[str, Any] Zarr store metadata including shape, species, chunks, etc.

Examples¶

api = GridFIA() info = api.validate_zarr("data/forest.zarr") print(f"Shape: {info['shape']}") print(f"Species: {info['num_species']}")

Method Details¶

Downloading Species Data¶

The download_species method supports multiple ways to specify the geographic extent:

By StateBy CountyBy Bounding BoxFrom Config File

# Download all species for an entire state
files = api.download_species(
    state="California",
    output_dir="data/california"
)

# Download specific species
files = api.download_species(
    state="Oregon",
    species_codes=["0202", "0122", "0015"],
    output_dir="data/oregon"
)

# Download for a specific county
files = api.download_species(
    state="North Carolina",
    county="Wake",
    species_codes=["0131", "0068"],
    output_dir="data/wake_county"
)

# Download for a custom bounding box (WGS84)
files = api.download_species(
    bbox=(-123.5, 45.0, -122.0, 46.5),
    crs="4326",
    output_dir="data/custom_region"
)

# Use a pre-configured location
files = api.download_species(
    location_config="config/montana_study_area.yaml",
    output_dir="data/study_area"
)

Working with Zarr Stores¶

The create_zarr method converts GeoTIFF files to cloud-optimized Zarr arrays:

# Basic usage
zarr_path = api.create_zarr(
    input_dir="downloads/",
    output_path="data/forest.zarr"
)

# With custom chunking for large datasets
zarr_path = api.create_zarr(
    input_dir="downloads/",
    output_path="data/forest.zarr",
    chunk_size=(1, 2000, 2000),  # Larger chunks for faster reads
    compression="zstd",
    compression_level=3
)

# Validate the created store
info = api.validate_zarr(zarr_path)
print(f"Shape: {info['shape']}")
print(f"Species count: {info['num_species']}")
print(f"CRS: {info['crs']}")

Calculating Metrics¶

GridFIA provides 15+ forest metrics through the calculation registry:

# List all available calculations
calcs = api.list_calculations()
print(f"Available: {calcs}")
# ['species_richness', 'shannon_diversity', 'simpson_diversity',
#  'evenness', 'total_biomass', 'dominant_species', ...]

# Run specific calculations
results = api.calculate_metrics(
    zarr_path,
    calculations=["species_richness", "shannon_diversity", "total_biomass"],
    output_dir="output/metrics"
)

# Process results
for result in results:
    print(f"{result.name}: {result.output_path}")

Creating Visualizations¶

Generate publication-ready maps with various options:

# Species biomass map
maps = api.create_maps(
    zarr_path,
    map_type="species",
    species=["0202"],
    state="MT",
    dpi=300
)

# Diversity map with basemap
maps = api.create_maps(
    zarr_path,
    map_type="diversity",
    state="MT",
    basemap="CartoDB.Positron"
)

# Species comparison (side-by-side)
maps = api.create_maps(
    zarr_path,
    map_type="comparison",
    species=["0202", "0122", "0116"]
)

# All species in store
maps = api.create_maps(
    zarr_path,
    map_type="species",
    show_all=True,
    output_dir="maps/all_species"
)

Downloading with Custom Polygon¶

# Download data clipped to a custom study area polygon
files = api.download_species(
    polygon="study_area.geojson",
    species_codes=["0131", "0068"],
    output_dir="data/study_area"
)

# Create Zarr with polygon clipping
zarr_path = api.create_zarr(
    input_dir="data/study_area",
    output_path="data/study_area.zarr",
    clip_to_polygon=True  # Auto-detect from saved config
)

Cloud and Sample Data¶

Load pre-hosted datasets without downloading from the FIA API:

# Load a pre-hosted state dataset (streaming access)
store = api.load_state("RI")
print(f"Shape: {store.shape}, Species: {store.num_species}")

# Load a sample dataset for quick testing
store = api.load_from_cloud(sample="durham_nc")

# Download a sample for faster repeated local access
local_path = api.download_sample("durham_nc", output_path="data/durham.zarr")

# List available datasets
print(api.list_sample_datasets())
print(api.list_state_datasets())

Reproducibility¶

Set a random seed for reproducible bootstrap confidence intervals:

# Set seed at initialization
api = GridFIA(seed=42)

# Or set seed later
api.set_seed(42)

# calculate_metrics_with_stats uses the seed for bootstrap sampling
results = api.calculate_metrics_with_stats(
    "data/forest.zarr",
    calculations=["shannon_diversity"],
    n_bootstrap=1000
)

Configuration¶

The GridFIA class accepts an optional configuration:

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

# Use default settings
api = GridFIA()

# Load from file
api = GridFIA(config="config/production.yaml")

# Programmatic configuration
settings = GridFIASettings(
    output_dir="results",
    calculations=[
        CalculationConfig(name="species_richness", enabled=True),
        CalculationConfig(name="shannon_diversity", enabled=True),
    ]
)
api = GridFIA(config=settings)

Thread Safety¶

The GridFIA class is thread-safe. Internal components (REST client, processor) use double-checked locking for lazy initialization:

from concurrent.futures import ThreadPoolExecutor
from gridfia import GridFIA

api = GridFIA()

def process_state(state):
    files = api.download_species(state=state, output_dir=f"data/{state}")
    return len(files)

# Safe to use from multiple threads
with ThreadPoolExecutor(max_workers=4) as executor:
    results = executor.map(process_state, ["MT", "WY", "ID", "WA"])

Error Handling¶

All methods raise domain-specific exceptions for clear error handling:

from gridfia import GridFIA
from gridfia.exceptions import (
    InvalidZarrStructure,
    SpeciesNotFound,
    CalculationFailed,
    APIConnectionError,
    InvalidLocationConfig,
    DownloadError,
)

api = GridFIA()

try:
    files = api.download_species(state="Montana", species_codes=["9999"])
except SpeciesNotFound as e:
    print(f"Species not found: {e.species_code}")

try:
    results = api.calculate_metrics("invalid.zarr")
except InvalidZarrStructure as e:
    print(f"Invalid Zarr store: {e.zarr_path}")

try:
    api.list_species()
except APIConnectionError as e:
    print(f"API error (status {e.status_code}): {e.message}")

GridFIA API¶

Overview¶

Quick Start¶

Class Reference¶

gridfia.api.GridFIA ¶

Examples¶

Download species data for North Carolina¶

Create zarr store from downloaded data¶

Calculate forest metrics¶

Create visualization¶

Parameters¶

Examples¶

seed property ¶

rest_client property ¶

processor property ¶

set_seed ¶

Parameters¶

Examples¶

list_species ¶

Returns¶

Examples¶

download_species ¶

Parameters¶

Returns¶

Examples¶

Download for entire state¶

Download for specific county with boundary stored¶

Download with custom polygon¶

Download with custom bbox¶

create_zarr ¶

Parameters¶

Returns¶

Examples¶

With polygon clipping¶

calculate_metrics ¶

Parameters¶

Returns¶

Examples¶

calculate_metrics_with_stats ¶

Parameters¶

Returns¶

Examples¶

Notes¶

create_maps ¶

Parameters¶

Returns¶

Examples¶

Create species map¶

Create diversity maps¶

Create comparison map¶

get_location_config ¶

Parameters¶

Returns¶

Examples¶

Get state configuration¶

Get county configuration¶

Custom bbox configuration¶

list_calculations ¶

Returns¶

Examples¶

validate_zarr ¶

Parameters¶

Returns¶

Examples¶

Method Details¶

Downloading Species Data¶

Working with Zarr Stores¶

Calculating Metrics¶

Creating Visualizations¶

Downloading with Custom Polygon¶

Cloud and Sample Data¶

Reproducibility¶

Configuration¶

Thread Safety¶

Error Handling¶

See Also¶

seed `property` ¶

rest_client `property` ¶

processor `property` ¶