AGB Calibration

The /calibrate_agb endpoint allows users to calibrate the API's above-ground biomass (AGB) model using field-collected tree inventory data. This produces calibrated biomass estimates that account for site-specific allometric relationships, improving accuracy for carbon accounting use cases that require field-validated results.

Overview

Epoch's default AGB model is trained on GEDI LiDAR L4A footprints and produces globally consistent predictions. However, for high-confidence carbon accounting (e.g. insetting, voluntary carbon credits, verified removals), field-collected data is needed to calibrate the model to local conditions — species composition, wood density, allometric equations, and stand structure.

The /calibrate_agb endpoint accepts tree inventory data (big trees and small trees CSVs) alongside plot coordinates, and triggers a calibration pipeline that:

1. Uploads field data to cloud storage
2. Runs the AGB calibration notebook (Vertex AI) which fits a site-specific allometric model
3. Produces calibrated biomass estimates for each plot
4. Stores results in *_calibrated tables for retrieval via the Fetch API

Parameters

Parameter	Type	Required	Default	Description
filename	string	Yes	-	Collection name to assign to the calibrated results
big_trees	File	Yes	-	CSV of large tree measurements (DBH, height, species)
small_trees	File	Yes	-	CSV of small tree/sapling measurements
plot_coordinates	File	Yes	-	CSV or GeoJSON of field plot coordinates
table_type	string	No	batch_calibrated	Output table type(s). Options: batch_calibrated, stat_calibrated, or both (comma-separated)
start_date	string	No	2017-01-01	Start date for zonal statistics (YYYY-MM-DD)
end_date	string	No	today	End date for zonal statistics (YYYY-MM-DD)
wood_density	float	No	0.55	Wood density ratio (g/cm³) for AGB allometry
buffer_size	int	No	100	Buffer size (meters) for batch_buffer table type
stat_region	string	No	watershed	Region for statistical comparison: watershed, admin, or supply_shed
ignore_strata	string	No	[]	Strata numbers to exclude from removals accounting

Table Types

Table Type	Description
batch_calibrated	Plot-level calibrated results (default)
stat_calibrated	Statistical region-level calibrated results
batch	Standard (non-calibrated) batch results
stat	Standard statistical region results
batch_buffer	Buffered plot results (uses buffer_size)

Use table_type=batch_calibrated,stat_calibrated to generate both plot-level and regional calibrated results.

Input File Formats

Big Trees CSV

Tree-level measurements for trees above a diameter threshold (typically > 10 cm DBH). Expected columns:

Column	Description
plot_id	Identifier linking the tree to a field plot
species	Tree species name
dbh_cm	Diameter at breast height (cm)
height_m	Total tree height (m)
wood_density	Species-specific wood density (g/cm³), optional — overrides the global wood_density parameter

Small Trees CSV

Measurements for saplings and small trees below the large-tree diameter threshold. Same column structure as big trees.

Plot Coordinates

Field plot locations as CSV (with latitude/longitude columns) or GeoJSON. Each plot should have:

Column	Description
plot_id	Unique plot identifier (must match IDs in tree CSVs)
latitude / longitude	Plot centre coordinates (WGS84)

How It Works

1. Field data files are uploaded to Google Cloud Storage under field_data/{user_id}/{collection_id}/
2. A Vertex AI notebook execution is triggered with the calibration parameters
3. The notebook fits an allometric model using the field measurements and the satellite-derived covariates
4. Calibrated AGB estimates are produced for each plot and (optionally) aggregated to statistical regions
5. Results are stored in BigQuery *_calibrated tables

The calibration uses the same satellite covariates as the default model (Dynamic World, Sentinel-2, Sentinel-1) but fits site-specific coefficients to the field data, accounting for local wood density, species composition, and stand structure.

Retrieving Results

Calibrated results are available through the same Fetch API endpoints as standard results, using the same collection name:

• /fetch_biomass_emissions — returns calibrated AGB and emissions when calibrated tables exist
• /fetch_plots — returns plot-level calibrated data
• /fetch_stat_regions — returns statistical region calibrated data (when stat_calibrated was computed)

The response format is identical to non-calibrated results, with the calibrated values replacing the default model predictions.

Key Considerations

1. Field data quality is critical — the calibration is only as good as the input measurements. Ensure DBH and height measurements follow standardised forestry inventory protocols.
2. Minimum sample size — a sufficient number of field plots (typically 20+) is needed for meaningful calibration. Small sample sizes may produce overfitted models.
3. Species-specific wood density — providing species-level wood density values (rather than using the global default) significantly improves calibration accuracy.
4. Temporal alignment — field measurements should be temporally aligned with the satellite imagery used for prediction. Calibrating with 2019 field data against 2024 satellite imagery introduces mismatch.
5. Processing time — AGB calibration is computationally intensive (Vertex AI notebook execution). Expect processing times of 30 minutes to several hours depending on the number of plots and monitoring period.