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() returns se_pct and plots alongside 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_area makes 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.DataFrame with the columns that matter for choosing an attribute: number, description, units, and the evaluation type it requires. The full record is available via get_attribute().

Note

FIA’s own catalog contains duplicate descriptions: 7 of the 752 appear more than once. snum 209 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 / pselected accept, and they are passed as display strings, so the exact label in 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 fullreport call.

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 returned forest_definition column 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 the db_column values from find_groupings() (P., C., PG.) are NOT accepted here: EVALIDator answers p.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 on plot..

    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, plus attribute, evaluation and forest_definition for provenance. Warnings the API attached to the estimate are in df.attrs["warnings"], and logged.

Return type:

pandas.DataFrame with 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: ValueError

A 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, Products and StudyAreas.

Releases are not interchangeable, in two ways that bite:

  • Products differ. 2025-11 carries Change / Land_Cover / Land_Use; 2025-6 is a tree-canopy release carrying only NLCD_Percent_Tree_Canopy_Cover. “The latest release” is therefore ambiguous unless you say latest of what - see latest_release().

  • The API’s summaries cover less than the imagery. The API’s pre-computed summaries for 2025-11 list only CONUS and AK, while the 2025-11 Earth 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-8 reports SummaryAreaCount = 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_Cover and Land_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.DataFrame with class_name, class_value and palette.

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, or region/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 geometry is 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 county is given.

  • county – County name.

  • region – Forest Service units. district requires forest.

  • forest – Forest Service units. district requires forest.

  • district – Forest Service units. district requires forest.

  • 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.DataFrame with year, 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, palette and classLegendDict, ready to hand to Map.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-6 is newer than 2024-10 but has no Land_Cover.

Pinning matters beyond that. Caching under the key latest means 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 with se_pct and plots.

  • comparison - a small dict with both figures, their absolute and percentage difference, and caveats, 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 from lcms_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.DataFrame with year, 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.ImageCollection of 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.ImageCollection where each image has a single band named after the product and a year property.

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 with GEOREST_USFS_CACHE for 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: USFSError

The API was reached but refused or failed the request.

Carries url and, 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.

exception geeViz.fsInsights.UpstreamUnavailable[source]

Bases: USFSError

The API could not be reached at all.

Distinct from UpstreamError because 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.