geeViz.fsInsights¶
Forest Service FIA and LCMS data: now georest.usfs.
The FIA (Forest Inventory and Analysis) and LCMS (Landscape Change
Monitoring System) clients that lived here moved to georest, RedCastle’s
library of geospatial REST clients, in georest 0.5.0. This package is
the front door that keeps the geeViz names working: every function, the
submodules (geeViz.fsInsights.fia is georest.usfs.fia, the same
module object) and the errors (FSInsightsError is
georest.usfs.USFSError). New code can import georest directly:
from georest.usfs import fia, lcms
fia.estimate(wc=412022, snum=2, rselected="County code and name")
lcms.lcms_summary(state="Oregon", county="Crook")
Quick start, through geeViz:
from geeViz import fsInsights as fs
fs.find_attributes("carbon") # what can I estimate?
fs.find_evaluations("Oregon") # which inventory? -> wc=412022
fs.estimate(wc=412022, snum=2, # run it
rselected="County code and name")
fs.lcms_summary(state="Oregon", county="Crook")
Two things worth knowing before trusting a number out of here:
FIA estimates always carry their sampling error.
estimate()returnsse_pctandplotsalongside every value and flags cells that are too thin to report. An FIA estimate without its error is not a fact: a real query for white/red/jack pine in Alabama returns 15,748 acres with a 54.9% standard error from four plots.LCMS and FIA are not directly comparable. One is a classified map, the other a probability sample. Comparing map-derived area to a design-based estimate conflates map accuracy with sampling error.
compare_areamakes the comparison and labels it; it will not hand you a single blended number that hides which is which.
- geeViz.fsInsights.find_attributes(query: str = '', *, land_basis: str = '', eval_typ: str = '', limit: int | None = None) Any[source]¶
Search the 752 FIA estimate attributes.
- Parameters:
query – Free text matched against description and group, e.g.
"carbon","net growth volume","mortality".land_basis – Restrict to
"Forest land"or"Timberland".eval_typ – Restrict to an evaluation type:
EXPCURR,EXPVOL,EXPGROW,EXPMORT,EXPREMV,EXPCHNG,EXPDWM.limit – Return at most this many rows. By default every match is returned, best first.
- Returns:
A
pandas.DataFramewith the columns that matter for choosing an attribute: number, description, units, and the evaluation type it requires. The full record is available viaget_attribute().
Note
FIA’s own catalog contains duplicate descriptions: 7 of the 752 appear more than once.
snum209 and 956, for instance, are identical across description, estimate group, evaluation type, estimation basis and tree portion. Both are returned rather than silently de-duplicated, because they are distinct attribute numbers upstream and collapsing them would hide a real property of the catalog. Where descriptions match on every field, either number should produce the same estimate.Example:
from georest.usfs import fia # Every carbon attribute measured on forest land, best match first fia.find_attributes("carbon", land_basis="Forest land") # Attributes that need growth accounting (growth, removals, mortality) fia.find_attributes("mortality", eval_typ="EXPMORT")
- geeViz.fsInsights.get_attribute(snum: int) dict | None[source]¶
Full record for one attribute number, or None.
Example:
from georest.usfs import fia fia.get_attribute(2)["ATTRIBUTE_DESCR"] # 'Area of forest land, in acres'
- geeViz.fsInsights.find_groupings(query: str = '', *, limit: int | None = None) Any[source]¶
Search the 96 FIA grouping variables.
These are what
rselected/cselected/pselectedaccept, and they are passed as display strings, so the exactlabelin this result is what the query needs, character for character.- Parameters:
query – Free text matched against the label and database column.
limit – Return at most this many rows. By default every match is returned, best first.
Example:
from georest.usfs import fia fia.find_groupings("owner") # labels to pass as rselected= / cselected=
- geeViz.fsInsights.describe_grouping(label: str) str[source]¶
Prose documentation for a grouping variable, codes included.
FIA ships this as
PRC_METADATA, an HTML fragment that usually enumerates what each code value means. It is the difference between a column of integers and a column you can interpret, so it is worth surfacing rather than leaving buried in the catalog.Example:
from georest.usfs import fia # What each code of a grouping means, as plain text fia.describe_grouping("Ownership group - Major")
- geeViz.fsInsights.find_evaluations(state: str = '', *, most_recent: bool = True, growth_only: bool = False, limit: int | None = None) Any[source]¶
Search the 1,143 FIA evaluations.
- Parameters:
state – State name, matched case-insensitively on a prefix.
most_recent – Keep only each state’s current evaluation. Almost always what you want; set False to see the back catalog.
growth_only – Keep only evaluations with growth accounting (
GROWTH_ACCT == 'Y'), which is a prerequisite for every growth, removals, and mortality attribute.limit – Return at most this many rows. By default every match is returned.
Example:
from georest.usfs import fia fia.find_evaluations("Oregon") # the current inventory fia.find_evaluations("Oregon", most_recent=False) # and every earlier one fia.find_evaluations("Oregon", growth_only=True) # usable for growth and mortality
- geeViz.fsInsights.get_evaluation(wc: int) dict | None[source]¶
Full record for one evaluation group, or None.
Example:
from georest.usfs import fia fia.get_evaluation(412024)["REPORT_YEAR_NM"] # '2015;2016;...;2024'
- geeViz.fsInsights.estimate(wc: int | Sequence[int], snum: int, *, rselected: str = '', cselected: str = '', pselected: str = '', sdenom: int | None = None, forest_definition: str = 'FIADEF', str_filter: str = '', max_se_pct: float = 30.0, min_plots: int = 30, validate_first: bool = True) Any[source]¶
Run an FIA estimate and return it tidy, with its sampling error.
This is the EVALIDator
fullreportcall.- Parameters:
wc – Evaluation group, see
find_evaluations(). Pass several ([102025, 242025]) to estimate across them in one request. That is the only way to get a correct combined standard error: estimating each separately gets a summed total right, but not its error.snum – Estimate attribute - see
find_attributes().rselected – Row grouping, as the exact display string from
find_groupings().cselected – Column grouping. Optional.
pselected – Page grouping. Optional.
sdenom – Denominator attribute, to produce a ratio estimate.
forest_definition –
"FIADEF"(the default) or"RPADEF". The two define forest land differently and give different areas, so it is always sent explicitly. The returnedforest_definitioncolumn carries the definition the server reports having applied, so a saved frame records it.str_filter –
SQL-style filter passed through as
strFilter. Qualify columns with the FULL table name -plot.unitcd,cond.owncd,tree.spcd. The short aliases that appear in FIA documentation and in thedb_columnvalues fromfind_groupings()(P.,C.,PG.) are NOT accepted here: EVALIDator answersp.unitcd in (0, 1, 2)with HTTP 200 carrying an “Internal Server Error - SQL Error” page, which says nothing about the alias being the problem. Two separate agent sessions burned several turns guessing before landing onplot..Example - western Oregon survey units only:
estimate(wc=412022, snum=98, rselected="Unit code", str_filter="plot.unitcd in (0, 1, 2)")
max_se_pct – Flag cells whose standard error exceeds this.
min_plots – Flag cells resting on fewer plots than this.
validate_first – Check attribute/evaluation compatibility locally before sending. Turn off only to probe the API directly.
- Returns:
row,column,estimate,se_pct,plots,units,unreliable,unreliable_reason, plusattribute,evaluationandforest_definitionfor provenance. Warnings the API attached to the estimate are indf.attrs["warnings"], and logged.- Return type:
pandas.DataFramewith one row per cell- Raises:
FIAValidationError – The request would fail upstream.
UpstreamError / UpstreamUnavailable – The API refused or could not be reached.
Example:
from georest.usfs import fia oregon = fia.find_evaluations("Oregon")["wc"].iloc[0] # Forest land (attribute 2) by county, each cell with its sampling error df = fia.estimate(oregon, 2, rselected="County code and name") df[["row", "estimate", "se_pct", "plots", "unreliable"]] # Oregon and Washington as one estimate, with a correct combined error washington = fia.find_evaluations("Washington")["wc"].iloc[0] both = fia.estimate([oregon, washington], 2) both[both["row"] == "Total"] both.attrs["warnings"] # anything FIADB-API flagged about the estimate
- geeViz.fsInsights.validate(wc: int | Sequence[int], snum: int) None[source]¶
Check an attribute is answerable by an evaluation. Raises if not.
Pre-flight for the EVALIDator request, so a bad pairing fails here with a named reason instead of arriving as EVALIDator’s own “Key Error / Received an Error” HTML page.
Attributes declare the evaluation type they need (
EXPCURR,EXPVOL,EXPGROW,EXPMORT,EXPREMV,EXPCHNG,EXPDWM); evaluations advertise whether they support growth accounting. The pairing is knowable before the request leaves.Example:
from georest.usfs import fia # Wyoming's current inventory has no growth accounting, so a # mortality attribute is refused here, with the reason, before any # request is sent. wyoming = fia.find_evaluations("Wyoming")["wc"].iloc[0] mortality = fia.find_attributes("mortality", eval_typ="EXPMORT")["snum"].iloc[0] try: fia.validate(wyoming, mortality) except fia.FIAValidationError as err: print(err)
- geeViz.fsInsights.reliable(df) Any[source]¶
Drop cells flagged unreliable.
Separate from
estimate()on purpose. The data layer returns everything with a reason attached; discarding is the caller’s decision, and a silent drop at fetch time would hide how much of a cross-tabulation is too thin to use.Example:
from georest.usfs import fia oregon = fia.find_evaluations("Oregon")["wc"].iloc[0] df = fia.estimate(oregon, 2, rselected="Forest type group") fia.reliable(df) # the same table without the cells flagged too uncertain
- exception geeViz.fsInsights.FIAValidationError[source]¶
Bases:
ValueErrorA request that would fail upstream, caught locally first.
Every check here is cheap and offline. Turning an opaque server error into a specific local one matters most for agents, where a rejected call costs a whole turn.
- geeViz.fsInsights.lcms_releases(*, product: str = '', refresh: bool = False) list[dict][source]¶
Every published LCMS release, newest first.
Each entry carries
VersionNumber,StartYear,EndYear,ProductsandStudyAreas.Releases are not interchangeable, in two ways that bite:
Products differ.
2025-11carriesChange/Land_Cover/Land_Use;2025-6is a tree-canopy release carrying onlyNLCD_Percent_Tree_Canopy_Cover. “The latest release” is therefore ambiguous unless you say latest of what - seelatest_release().The API’s summaries cover less than the imagery. The API’s pre-computed summaries for
2025-11list only CONUS and AK, while the2025-11Earth Engine asset itself covers CONUS, AK, HI and PRUSVI through 2025. For Hawaii or Puerto Rico, summarize the asset over a geometry (the Earth Engine path) rather than pin an older release for the API.
Note also that
2022-8reportsSummaryAreaCount = 0- it has no summary areas, so the API cannot answer area queries against it even though it lists products.- Parameters:
product – Keep only releases that publish this product.
Example:
from georest.usfs import lcms [r["VersionNumber"] for r in lcms.lcms_releases()] # every release [r["VersionNumber"] for r in lcms.lcms_releases(product="Land_Cover")] # those with land cover
- geeViz.fsInsights.lcms_products(release: str = '', *, refresh: bool = False) list[dict][source]¶
Products in a release, each with its full class list.
Currently
Change,Land_CoverandLand_Use.Example:
from georest.usfs import lcms [p["Name"] for p in lcms.lcms_products()] # products in the newest release
- geeViz.fsInsights.lcms_classes(product: str, release: str = '') Any[source]¶
Class table for one product - name, pixel value, and palette hex.
Returns a
pandas.DataFramewithclass_name,class_valueandpalette.- Raises:
ValueError – The release does not publish this product, naming the releases that do.
Example:
from georest.usfs import lcms lcms.lcms_classes("Land_Cover") # class_name, class_value and palette per class
- geeViz.fsInsights.lcms_summary_areas(release: str = '', *, type: str = '', refresh: bool = False) Any[source]¶
The precomputed areas this API can summarize.
3,643 of them in release 2025-11: 3,137 US counties, 502 ranger districts, and four rollups (political and Forest Service, CONUS and All-Lands).
- Parameters:
release – Release version; defaults to latest.
type – Filter on area type, e.g.
"US-COUNTIES"or"RANGER-DISTRICTS".
Example:
from georest.usfs import lcms lcms.lcms_summary_areas(type="RANGER-DISTRICTS") # the districts the API can summarize
- geeViz.fsInsights.lcms_summary(product: str = 'Land_Cover', *, state: str = '', county: str = '', region: str = '', forest: str = '', district: str = '', year: int | None = None, startyear: int | None = None, endyear: int | None = None, geometry: Any = None, scale: int = 30, release: str = '') Any[source]¶
Class areas for an area and period, as a tidy frame.
Dispatches on what it is given:
A named area (
state/county, orregion/forest/district) goes to the LCMS API - instant, precomputed, and no Earth Engine authentication required.A geometry goes to Earth Engine, computing the same class areas over an arbitrary polygon. Slower, needs EE initialized, and only available when
geometryis passed.
The returned frame records which backend produced it, because the two are not guaranteed to agree to the pixel and a reader should not have to guess.
- Parameters:
product –
"Land_Cover","Land_Use"or"Change".state – State name. Required when
countyis given.county – County name.
region – Forest Service units.
districtrequiresforest.forest – Forest Service units.
districtrequiresforest.district – Forest Service units.
districtrequiresforest.year – Single year. Omit for the full time series - the whole 1985-2025 range is ~64 KB, small enough to fetch eagerly.
startyear – Inclusive year range.
endyear – Inclusive year range.
geometry – An
ee.Geometry/ee.Feature/ee.FeatureCollection. Routes to the Earth Engine backend.scale – Reduction scale in meters for the EE backend. LCMS is a 30 m product; coarsening trades accuracy for speed.
release – Release version; defaults to latest.
- Returns:
pandas.DataFramewithyear,class_name,square_meters,acres,hectares,product,area,source.
Example:
from georest.usfs import lcms # A county's land cover through time, from the API's precomputed summaries crook = lcms.lcms_summary("Land_Cover", state="Oregon", county="Crook") crook.pivot_table(index="year", columns="class_name", values="acres") # One year of change in the same county lcms.lcms_summary("Change", state="Oregon", county="Crook", year=2024)
- geeViz.fsInsights.lcms_vis_params(product: str, release: str = '') dict[source]¶
Build geeViz/Earth Engine visualization parameters for a product.
Returns a dict with
min,max,paletteandclassLegendDict, ready to hand toMap.addLayer:Map.addLayer(lcms_change, fs.lcms_vis_params("Change"), "LCMS Change")
Taking the palette from the API rather than a hardcoded constant means the legend cannot drift out of sync with the release - the classes and their colors arrive from the same place as the data.
The palette is emitted as a dense, value-ordered list so it lines up with a contiguous
min..``max`` range. Gaps in the class values are filled with a neutral grey rather than silently shifting every subsequent color, which is the failure mode that makes a legend look right and read wrong.
- geeViz.fsInsights.latest_release(product: str = '') str[source]¶
Resolve to a concrete version string, e.g.
2025-11.- Parameters:
product – Resolve to the newest release carrying this product. Without it you get the newest release overall, which may not publish what you are about to ask for -
2025-6is newer than2024-10but has noLand_Cover.
Pinning matters beyond that. Caching under the key
latestmeans a new release silently changes the answer to a question asked last year; resolving to a version once keeps an old analysis reproducible.Example:
from georest.usfs import lcms lcms.latest_release("Land_Cover") # newest release that has land cover, e.g. '2025-11'
- geeViz.fsInsights.release_products(release: str = '') list[str][source]¶
Product names published by one release (default: newest overall).
Example:
from georest.usfs import lcms lcms.release_products("2025-11") # ['Change', 'Land_Cover', 'Land_Use']
- geeViz.fsInsights.compare_area(*, wc: int, state: str = '', county: str = '', year: int | None = None, tree_classes: tuple | None = None, release: str = '') dict[str, Any][source]¶
Put an LCMS treed area and an FIA forest-land estimate side by side.
Returns a dict rather than a single frame, because the two halves are not rows of one table - they are two different estimators of two related-but-distinct quantities, and stacking them would imply a comparability that does not exist.
Keys:
lcms- per-year treed area frame.fia- forest-land estimate withse_pctandplots.comparison- a small dict with both figures, their absolute and percentage difference, andcaveats, a list of the reasons they can legitimately disagree.
The difference is offered as an observation, never as an error term. A 15% gap between these does not mean either is 15% wrong.
Example:
from georest.usfs import align, fia oregon = fia.find_evaluations("Oregon")["wc"].iloc[0] result = align.compare_area(wc=oregon, state="Oregon", county="Crook", year=2024) result["comparison"] # both figures, their difference, and the caveats
- geeViz.fsInsights.fia_forest_area(wc: int, *, rselected: str = '', snum: int = 2, **kwargs) Any[source]¶
FIA forest-land area with its sampling error.
Thin wrapper over
estimate()that stamps the estimator label, so a frame from here and a frame fromlcms_tree_area()can be concatenated without losing track of which is which.Example:
from georest.usfs import align, fia oregon = fia.find_evaluations("Oregon")["wc"].iloc[0] align.fia_forest_area(oregon) # forest land with se_pct and plots, labelled as FIA
- geeViz.fsInsights.lcms_tree_area(state: str = '', county: str = '', *, region: str = '', forest: str = '', district: str = '', year: int | None = None, tree_classes: tuple | None = None, release: str = '') Any[source]¶
LCMS area in tree-bearing land cover classes, by year.
- Parameters:
tree_classes – Override which classes count as treed. The default includes the mixed classes, which matters: excluding them understates treed area in exactly the transitional stands where LCMS and FIA are most likely to disagree.
- Returns:
pandas.DataFramewithyear,acres,classes_used,source,estimator.
Example:
from georest.usfs import align # Acres in tree-bearing LCMS land cover classes, per year align.lcms_tree_area(state="Oregon", county="Crook")
- geeViz.fsInsights.summarize_comparison(result: dict[str, Any]) str[source]¶
One readable paragraph from
compare_area(), caveats included.Written to be pasted into a report. The caveat is part of the sentence rather than a footnote, because a number this easy to quote is a number that travels without its footnotes.
Example:
from georest.usfs import align, fia oregon = fia.find_evaluations("Oregon")["wc"].iloc[0] result = align.compare_area(wc=oregon, state="Oregon", county="Crook", year=2024) print(align.summarize_comparison(result)) # one paragraph, caveats included
- geeViz.fsInsights.lcms_asset_id(release: str = '') str[source]¶
Asset id for a release. Defaults to the current one.
Example:
from georest.usfs import lcms_ee lcms_ee.lcms_asset_id() # the current release's Earth Engine asset lcms_ee.lcms_asset_id("2024-10") # an earlier release, to reproduce an old analysis
- geeViz.fsInsights.lcms_ee_collection(product: str, release: str = '', study_area: str | None = None)[source]¶
An
ee.ImageCollectionof one LCMS product, one image per year.- Parameters:
product –
"Change","Land_Cover"or"Land_Use".release – Release version; defaults to current.
study_area – Restrict to one study area (e.g.
"CONUS","AK","PRUSVI"). Leave unset to keep all of them - they do not overlap, so a geometry naturally selects the right one and a reduction over the union is correct.
- Returns:
ee.ImageCollectionwhere each image has a single band named after the product and ayearproperty.
Example:
import ee from georest.usfs import lcms_ee ee.Initialize() land_cover = lcms_ee.lcms_ee_collection("Land_Cover") land_cover_2025 = land_cover.filter(ee.Filter.eq("year", 2025)).mosaic()
- geeViz.fsInsights.lcms_class_properties(product: str, release: str = '') dict[source]¶
Class names, values, and palette straight off the asset.
A second source of truth for the class table, independent of the API. Useful when Earth Engine is reachable but the API is not, and as a cross-check that the two backends agree about what the pixel values mean - if they ever disagree, that is worth knowing loudly rather than discovering through a mislabeled map.
Example:
import ee from georest.usfs import lcms_ee ee.Initialize() props = lcms_ee.lcms_class_properties("Land_Cover") props["values"], props["palette"], props["names_unreliable"]
- geeViz.fsInsights.refresh_all(*, quiet: bool = False) dict[str, int][source]¶
Force-refresh every catalog. Returns
{name: record_count}.The escape hatch for “a new evaluation just dropped and I do not want to wait out the TTL”. Normal use should never need it.
Example:
from georest.usfs import vocab vocab.refresh_all() # prints each catalog's record count; returns {name: count}
- geeViz.fsInsights.cache_dir() Path[source]¶
Directory for refreshed catalogs.
~/.georest/usfs, beside the ArcGIS sign-in that georest keeps in~/.georest. Overridable withGEOREST_USFS_CACHEfor tests and for locked-down machines where the home directory is not writable.Example:
from georest.usfs import vocab vocab.cache_dir() # Path to ~/.georest/usfs in your home directory
- geeViz.fsInsights.FSInsightsError¶
alias of
USFSError
- exception geeViz.fsInsights.UpstreamError(message: str, *, url: str = '', provided: dict | None = None)[source]¶
Bases:
USFSErrorThe API was reached but refused or failed the request.
Carries
urland, when the upstream provided one, the parameters it echoed back. LCMS returns those, and they are usually enough to see the mistake without re-reading the call site.
Bases:
USFSErrorThe API could not be reached at all.
Distinct from
UpstreamErrorbecause callers respond to it differently: a bad parameter needs a code change, an unreachable host needs a retry later or a fall back to cached data.