pick_change_interval
Read-only
Scan a site's whole series and name the two passes worth narrating.
The deterministic first half of the "watch a site over time" story, and the
step that turns a wall of passes into an answer. Given the STAC URLs of a
site's passes (2 or more, any order), it co-registers them into a
``to_stack`` cube, reduces it with ``stack_stats``, and returns the *one*
consecutive pass-pair whose measured change stands **furthest clear of the
speckle detection floor** — the pair a reader should look at first. No model
is called: a number picks the frames (the determinism boundary applied to
frame selection), so the choice is reproducible and safe
to quote.
Why this exists as its own tool: ``narrate_change`` reads a *pair* of passes,
but a site has many, and "which two?" is a measurement question, not a model
one — a picture past three dates encodes nothing a model can separate, so the
pair has to be chosen before the model is called. This answers it. The
returned ``urls`` are the two chosen passes in time order, ready to hand
straight to ``narrate_change`` (or ``change_composite`` to see them): the
two tools chain into scan → narrate with no server and no model in the
selection.
Returns ``selected_interval`` (the interval's ``earlier_id`` / ``later_id``,
their datetimes, the ``changed_fraction`` and signed ``mean_delta_db``, the
cube's ``false_alarm_fraction`` speckle floor, the ``excess`` of the change
over that floor, and ``stands_clear`` — whether the change cleared the floor
by a usable margin), ``urls`` (the earlier then the later pass's STAC URL),
and the license/attribution. When ``stands_clear`` is false the series' own
largest change is still inside the speckle, so the pair is offered but the
reader is warned the difference may be interference rather than change.
``selected_interval`` is ``None`` (and ``urls`` empty) when the series has
fewer than two comparable passes or no interval reported any change — there
is no pair to narrate. ``crs="utm"`` (the default) grids the cube in the
site's UTM zone so the change fractions weigh equal ground; ``max_size`` and
``change_threshold_db`` match ``stack_stats``. Refuses to mix polarizations
(HH vs VV are not comparable). Requires the ``load`` extra.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| crs | No | utm | |
| urls | Yes | ||
| asset | No | GEC | |
| extent | No | intersection | |
| max_size | No | ||
| change_threshold_db | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||