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 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