stack_stats
Read-only
Measure how much a site changed across its passes, as numbers.
The quantitative counterpart to ``change_composite`` / ``timescan``: those
return a picture of *where* change is, this returns the *how much*. Pass the
STAC URLs of a site's passes (2 or more, any order); they are co-registered
onto one shared grid and reduced to a per-pass statistics series plus a net
baseline-to-latest record — mean/median/spread of each pass, the signed
decibel change against the pass before it, the fraction of ground that moved
past ``change_threshold_db``, and that fraction as an **area in km²**.
Change is always reported in decibels (a ratio of backscatter is a difference
on the log scale). The default ``crs="utm"`` puts the grid in the site's UTM
zone so every cell covers the same ground and the area figures mean
something; pass ``crs="EPSG:4326"`` for a lon/lat grid, and the areas come
back ``None`` rather than wrong. ``extent="intersection"`` (the default)
compares only ground every pass covers; ``"union"`` keeps all of it and
compares per cell where two passes overlap. ``bbox`` (lon/lat
``[min_lon, min_lat, max_lon, max_lat]``) narrows the measurement to a
sub-area, e.g. one facility inside the scene.
``blocks=N`` adds the *where* to the *how much*: the scene is cut into an
N x N grid (6 is a good default; 0, the default, skips it) and the extra
``spatial`` key reports each block's own net change, a compass label and
lon/lat centre to locate it by, and the consecutive pair of passes that
block moved most between — plus ``peak_block`` and an ASCII ``grid_text``
heat-map of the net change. Ask for it whenever the question is *where on
this site* something happened, or when a scene-wide mean looks small but the
picture from ``change_composite`` shows an obvious hot spot: a change
confined to one corner is averaged away scene-wide and stands out per block.
``block_series=True`` (which needs ``blocks``) keeps each block's *whole*
pass-to-pass sequence rather than only its peak interval, so a block that
drifted a little every pass reads differently from one that jumped once and
held. It is the largest payload this tool emits — ``blocks`` × ``blocks`` ×
(passes − 1) records — so ask for it only when the *shape* of the history is
the question, not the size of the change.
``speckle_filter="boxcar"`` or ``"lee"`` averages **speckle** down before
anything is measured. Speckle is not sensor noise: it is the interference
pattern coherent illumination makes on rough ground, and on single-look
imagery it scatters as widely as its own mean — so on a quiet site an
unfiltered per-cell decibel delta is mostly interference rather than change.
``"boxcar"`` averages every window (most variance removed, blind to the edges
it averages across); ``"lee"`` averages only where a window is no more
variable than speckle alone explains, so edges and bright points survive.
Reach for it when the change you are looking for is small, or when the
numbers look noisy against a picture that looks quiet; leave it off when the
question is about *fine* structure, because what it spends is resolution — a
``speckle_window``-cell window (odd, 5 by default) makes each cell report
ground that many cells across. The returned ``caveats`` say so, so a quoted
figure carries the trade with it.
Refuses to mix polarizations (HH and VV are not comparable). **No model is
called** — this is arithmetic over streamed COG overviews, so the numbers are
reproducible and safe to quote. Read the ``caveats`` before interpreting
them: Umbra's open products are not radiometrically calibrated, so a decibel
value is relative to the same ground on another date, and look geometry moves
backscatter too.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| crs | No | utm | |
| bbox | No | ||
| urls | Yes | ||
| asset | No | GEC | |
| blocks | No | ||
| extent | No | intersection | |
| max_size | No | ||
| block_series | No | ||
| speckle_filter | No | ||
| speckle_window | No | ||
| change_threshold_db | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||