Skip to content

feat(acquire): name the station-selection release, and file v0.4.0 as shipped #46

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sgjholt merged 2 commits into from
Sep 19, 2026
Merged

feat(acquire): name the station-selection release, and file v0.4.0 as shipped #46

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e113abb
docs(roadmap): file v0.4.0 as shipped, and the acquire work as merged
claude Sep 18, 2026
b460d19
feat(acquire): document the station-selection release, and name its v…
claude Sep 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 66 additions & 4 deletions docs/roadmap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,60 @@ signposted from [Guides](guides.md) rather than split onto a page of their own.
[Upgrading](upgrading.md) covers moving code off the pre-refactor
`master`.

## Shipped in v0.4.0

### Smoothing became a choice, and the choice is applied

`[smoothing] method` selected nothing. The registry mapped the names, the config
validated against them, and no code read the result: every spectrum was
log-binned whatever the setting said. Measured on the 28 PNR windows,
`log_bins`, `konno_ohmachi` and `none` produced bit-identical output — `none`
included, which reads as "leave my spectra unsmoothed".

It is wired now, with three methods beside the two:

- **`log_window`** — constant relative bandwidth over a window you name:
boxcar, Bartlett, Hann, Hamming, Blackman or Gaussian, a fraction of an
octave wide everywhere. Konno–Ohmachi is this family with its own window.
`statistic="median"` discards a spike rather than averaging it in, and
discards a genuine narrow peak with it.
- **`savitzky_golay`** — a local polynomial fit in log–log, which keeps peak
amplitude and width where a running mean flattens both.
- **`none`** — no smoothing, which now means it.

Log-binning replaces the frequency axis; the others preserve it. That is the
distinction the setting had no way to express, and the reason wiring it up was
a design change rather than a patch.

One detail that is easy to get wrong and is worth knowing about: a window
symmetric in log frequency is not a symmetric average over samples, because a
Fourier grid is uniform in Hz. Weighting samples equally tilts the result by
1.5e-3 dex on an `f**-2` power law; weighting each by its share of the log
axis brings that to 3.2e-8 dex. The latter is the default. Konno–Ohmachi
applies the former, by definition, and keeps it.

## In progress — not yet released

Merged on `main`, and it will name its version when a release goes out.

### The station selection means what the config says

Three ways a fetched dataset did not match the config that asked for it, all
found by a live fetch rather than by the suite:

- `max_radius_km` reached the station query and never the waveform request,
because FDSN dataselect has no geographic parameters. A 50 km fetch returned
channels from 225 km out, with no metadata beside them. Waveforms are now
asked for by name, from the inventory the station query returned.
- The radius was converted at 111.195 km per degree. A degree of arc is
110.574 km at the equator and 111.691 km at the poles, so the boundary moved
with latitude — ±0.3 km at 50 km, ±2 km at 400 km. The query is now sent
deliberately wide and the cut made against the true WGS84 distance.
- A `channel` pattern naming several instruments returned all of them at every
station, so a broadband and the accelerometer beside it entered the pipeline
as two independent records of one ground motion. `channel_priorities` and
`location_priorities` rank them, first match wins per station.

## Planned

### 1.0 — the API stops moving
Expand All @@ -157,10 +211,18 @@ backlog is empty, it is settled when it stops moving.
**By that test, 1.0 is not ready.** v0.3.0 is the release that emptied the
backlog and it carried two breaking changes itself: the ten renamed
`preprocess` functions, and the tutorial's page moving. So what 1.0 now waits
on is the next release going out without one — which is a thing that has to be
on is a release going out without one — which is a thing that has to be
observed rather than declared, and cannot be brought forward by finishing
anything.

**v0.4.0 is the first observation, and it is not clean.** No name or signature
moved: the smoothing work was additive, and the `SpectrumPair.compare`
parameter it added is optional. But `[smoothing] method` changed what it does,
so a config that set `konno_ohmachi` or `none` gets different numbers out of
the same code path. Nothing breaks at import or at the call; results move. That
is a weaker promise than the one 1.0 makes and a real one to have broken, so
the count starts again rather than standing at one.

## After 1.0

Designed but deliberately not on the path to 1.0, because each is blocked on
Expand All @@ -185,9 +247,9 @@ guess written from documentation cannot substitute for:
Each shipped entry names the version that carries it, so a reader can install
that version and check the claim. Work that is merged but unreleased sits under
*In progress* and gets its version when a release goes out — merged is not
shipped, and this page does not blur the two. **There is no such section right
now**, because nothing is merged and unreleased; that is the state the page
should be in between releases, not a section that went missing.
shipped, and this page does not blur the two. Between releases there is no such
section at all, which is a state the page should be in rather than a section
that went missing.

The move at release time is the step this page got wrong once. The v0.3.0 work
sat under *In progress — not yet released* for a week after v0.3.0 was
Expand Down
45 changes: 42 additions & 3 deletions docs/upgrading.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,52 @@
# Upgrading

Two moves are documented here. Most readers want the first: `0.3.0` renamed
ten functions in `specmod.preprocess` and changed what they do with the stream
they are given.
Four moves are documented here. Most readers porting code want `0.2` to `0.3`,
which renamed ten functions in `specmod.preprocess` and changed what they do
with the stream they are given. The two moves above it rename nothing: they are
settings that began doing what they always said, so the break is in the numbers
rather than in the call.

`0.x` ships breaking changes in minor bumps without a deprecation cycle,
because shimming an API still being worked out costs more than it protects.
See [Releasing the software](releasing.md#what-a-version-number-means-while-this-is-0x).

## From 0.4 to 0.5

**`max_radius_km` and `min_radius_km` now mean kilometres.** They were converted
to degrees at a fixed 111.195 km per degree and handed to the station query. A
degree of arc is 110.574 km at the equator and 111.691 km at the poles, so the
boundary moved with latitude — up to 0.3 km on a 50 km radius and 2 km on 400
km. The query is now sent deliberately wide and the cut made locally against the
true WGS84 epicentral distance. **A config whose radius falls near a station's
distance can select a different set of stations than it did before**, and
`verify` on an existing artefact is unaffected: nothing on disk changes.

Three more changes to the same block:

| Before | From 0.5 |
|---|---|
| `min_radius_km` was only sent alongside `max_radius_km`, so on its own it did nothing | It applies on its own |
| `max_radius_km = 0`, a negative radius, or `min_radius_km >= max_radius_km` selected nothing, silently | Each raises `ValueError` when the config is read |
| Waveforms were requested with the config's wildcards, so the radius reached the station query and never the download | Waveforms are requested by name, from the inventory the station query returned |

**New:** `channel_priorities` and `location_priorities` rank co-sited
instruments, first match wins per station. Leaving them unset fetches every
channel as before and warns, naming the stations that carry more than one
instrument. See
[Publishing a dataset](releasing-data.md#picking-one-instrument-per-station).

## From 0.3 to 0.4

**`[smoothing] method` is applied.** It selected nothing: every spectrum was
log-binned whatever the setting said, and `log_bins`, `konno_ohmachi` and
`none` produced bit-identical output. A config that set `konno_ohmachi` or
`none` was getting log-binned spectra and now gets what it asked for, so
**results move for those two values** — `none` most of all, since it now means
no smoothing rather than the default binning.

`log_window` and `savitzky_golay` are new, and nothing needs changing to keep
the previous behaviour: `log_bins` is still the default.

## From 0.2 to 0.3

**`specmod.preprocess` no longer modifies the stream it is given.** Every
Expand Down
Loading