From e113abb97d80737a2c4a791a6543d945bdb7ba9c Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 18 Sep 2026 13:41:51 +0000 Subject: [PATCH 1/2] docs(roadmap): file v0.4.0 as shipped, and the acquire work as merged The page had no v0.4.0 section a day after v0.4.0 released, and said in its closing paragraph that nothing was merged and unreleased while the acquire fixes sat on main. Both are the staleness `TestTheRoadmapKeepsUpWithTheReleases` exists to catch, and it catches the first one late by design: it compares against the second-newest minor in the changelog, because the newest is release-please's proposal rather than something a reader can install. So the v0.4 section is only required once v0.5 ships, and the check would have failed on main at that moment. Verified by injecting a simulated 0.5.0 release section: 19 passed with this change, against the failure it produces without. The 1.0 criterion needed the same update, since a release has gone past it. v0.4.0 moved no name and no signature, but `[smoothing] method` changed what it does, so a config setting `konno_ohmachi` or `none` gets different numbers from the same call. That is a weaker promise than 1.0 makes and still one that was broken, so the page counts it rather than claiming a clean release. Co-Authored-By: Claude Opus 5 --- docs/roadmap.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 66 insertions(+), 4 deletions(-) diff --git a/docs/roadmap.md b/docs/roadmap.md index e957d8a..3c5de09 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -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 @@ -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 @@ -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 From b460d1922c21822a81b6aeb06aa6d5f7193d92e1 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 18 Sep 2026 13:49:28 +0000 Subject: [PATCH 2/2] feat(acquire): document the station-selection release, and name its version MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The code shipped in 2af57e8, the squash merge of #45. Squashing replaced the two commit subjects — `fix(acquire): ask for waveforms by name, so the radius applies to them too` and `feat(acquire): rank co-sited instruments, and cut the radius in kilometres` — with the pull request's title, which is not a conventional commit. release-please could not parse it: commit could not be parsed: 2af57e8 Make the station selection mean what the config says: radius, and one instrument per station (#45) error message: Error: unexpected token ' ' at 1:5 Considering: 0 commits No commits for path: ., skipping So the work is invisible to the release machinery: no bump, and no changelog entry for a release that contains it. That is the failure `AGENTS.md` means by load-bearing commit messages, and it cannot be repaired in the commit itself — the message on `main` is what it is. This restores the record where release-please will read it, and pays the documentation the change owed either way: `docs/upgrading.md` had no entry for a radius that now cuts against WGS84 rather than a fixed 111.195 km/degree, for `min_radius_km` beginning to work on its own, for the three config errors that now raise, or for the new priority lists. The same section was missing for 0.3 to 0.4, where `[smoothing] method` began being applied — the same shape of break, where the call is unchanged and the numbers move. `Release-As` pins the version rather than leaving it to the type, so the bump is right whichever way this lands: squashed, the subject is the title of this pull request and the footer still parses. Release-As: 0.5.0 Co-Authored-By: Claude Opus 5 --- docs/upgrading.md | 45 ++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 42 insertions(+), 3 deletions(-) diff --git a/docs/upgrading.md b/docs/upgrading.md index 02b8606..6491ee9 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -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