specmod 0.3.0__tar.gz → 0.5.0__tar.gz

specmod-0.5.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.5.0"
+}

{specmod-0.3.0 → specmod-0.5.0}/CHANGELOG.md

@@ -9,6 +9,67 @@ release could have this problem — every later one has a real predecessor tag
 so leave subsequent headings as generated. release-please only prepends to this
 file, so this edit survives. -->
 
+## [0.5.0](https://github.com/sgjholt/SpecMod/compare/v0.4.0...v0.5.0) (2026-09-19)
+
+<!-- The `acquire` entries below are edited by hand, and are the second entry
+in this file that is. The work shipped in 2af57e8, the squash merge of #45,
+whose subject is not a Conventional Commit — release-please could not parse it
+("unexpected token ' ' at 1:5") and generated nothing for it. What it did
+generate was the later commit that restored the record, which is documentation
+describing the change rather than the change. These name the change and point
+at the commit that carries it. release-please only prepends to this file, so
+the edit survives. -->
+
+### Features
+
+* **acquire:** rank co-sited instruments with `channel_priorities` and
+  `location_priorities`, so a station carrying a broadband and an
+  accelerometer contributes one record rather than two
+  ([2af57e8](https://github.com/sgjholt/SpecMod/commit/2af57e8e958d474a25e34b9065f9e54d1a1a42fa))
+
+
+### Bug Fixes
+
+* **acquire:** ask for waveforms by name, so `max_radius_km` applies to the
+  download and not only to the station query — FDSN dataselect takes no
+  geographic parameters, so a wildcard request was unbounded
+  ([2af57e8](https://github.com/sgjholt/SpecMod/commit/2af57e8e958d474a25e34b9065f9e54d1a1a42fa))
+* **acquire:** cut the radius against true WGS84 distance rather than a fixed
+  111.195 km per degree, which moved the boundary by up to half a percent with
+  latitude; `min_radius_km` now applies on its own, and a non-positive radius
+  or an inverted annulus is refused
+  ([2af57e8](https://github.com/sgjholt/SpecMod/commit/2af57e8e958d474a25e34b9065f9e54d1a1a42fa))
+
+
+### Documentation
+
+* **acquire:** upgrading notes for the station selection, and for the
+  `[smoothing] method` behaviour change in 0.4.0 ([b460d19](https://github.com/sgjholt/SpecMod/commit/b460d1922c21822a81b6aeb06aa6d5f7193d92e1))
+* **roadmap:** file v0.4.0 as shipped, and the acquire work as merged ([e113abb](https://github.com/sgjholt/SpecMod/commit/e113abb97d80737a2c4a791a6543d945bdb7ba9c))
+
+## [0.4.0](https://github.com/sgjholt/SpecMod/compare/v0.3.0...v0.4.0) (2026-09-16)
+
+
+### Features
+
+* **smoothing:** wire [smoothing] method up, and add three more methods ([fff3ab1](https://github.com/sgjholt/SpecMod/commit/fff3ab1ef01a7f4d942fd776821d0418a0642a55))
+
+
+### Bug Fixes
+
+* **config:** refuse a [smoothing] method the pipeline does not apply ([1f18c68](https://github.com/sgjholt/SpecMod/commit/1f18c68a71794c2b1612a7cf0feedcfef39b625b))
+* **test:** compare the roadmap against the published minor, not the proposed one ([1e34b4e](https://github.com/sgjholt/SpecMod/commit/1e34b4e5ab2bdef5d65f6fc0d620a42b9c3891eb))
+* **tools:** call the preprocess API that 0.3.0 left behind ([8501c8e](https://github.com/sgjholt/SpecMod/commit/8501c8ed618e5d652b9eeffc36893115a58fd7d5))
+
+
+### Documentation
+
+* keep the reasoning out of the docstrings, in comments where it belongs ([2684ec9](https://github.com/sgjholt/SpecMod/commit/2684ec923c8dcf59e882b2d11e9dc11ccbcf3766))
+* say what tagging the frozen commit does and does not trigger ([2273219](https://github.com/sgjholt/SpecMod/commit/2273219e2a78ac1c1562118c2a1b3bce4df597dd))
+* state what the smoothers are, not how they were arrived at ([4c97491](https://github.com/sgjholt/SpecMod/commit/4c97491d50aba5a1468304072ab3c6ed2904f2e0))
+* the 0.3.0 work shipped a week ago, so stop calling it unreleased ([e2aaced](https://github.com/sgjholt/SpecMod/commit/e2aaced546a247b2c5967f01586c19928bcfe297))
+* v0.1.1 is master's tip, which is what freezing it was for ([db50972](https://github.com/sgjholt/SpecMod/commit/db509729f3b7877a20b5691dddec8a6e139fb466))
+
 ## [0.3.0](https://github.com/sgjholt/SpecMod/compare/v0.2.3...v0.3.0) (2026-09-06)
 
 

{specmod-0.3.0 → specmod-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: specmod
-Version: 0.3.0
+Version: 0.5.0
 Summary: A Python toolbox for processing and modelling seismic spectra
 Project-URL: Homepage, https://github.com/sgjholt/SpecMod
 Project-URL: Repository, https://github.com/sgjholt/SpecMod

{specmod-0.3.0 → specmod-0.5.0}/datasets/magna_2020.toml

@@ -35,6 +35,12 @@ location = "*"
 # fetched too: the workflow rotates horizontals to R/T, and rotation is not a
 # reason to discard Z from the archive.
 channel = "HH*,BH*,HN*,EN*"
+# Deliberately unranked. `channel_priorities` would keep one instrument per
+# station — the right default for a regional dataset, and what silences the
+# co-sited warning this fetch prints — but here the near-source broadbands are
+# the records most likely to clip, and the accelerometer beside them is the
+# reason the paper covers that distance range at all. Both are kept and the
+# choice is made at processing time.
 max_radius_km = 400.0
 
 [window]

{specmod-0.3.0 → specmod-0.5.0}/docs/REFACTOR_PLAN.md

@@ -1087,7 +1087,7 @@ and there are presumably more in your working directories.
 Two ways out, and the first is much better:
 
 1. **Convert in the old environment.** Phase 0 is already building a Docker image
-   where the 0.1.0 code runs (§6.7). Add a small
+   where the 0.1.1 code runs (§6.7). Add a small
    `scripts/convert_legacy_spec.py` to it that loads `.spec` files with the old
    classes present and writes the new HDF5 format. This is a one-shot migration
    with no lasting cost to the codebase.
@@ -2434,6 +2434,15 @@ Two design constraints worth fixing now:
   reimplementation of `MassDownloader`, which is built for large restricted-data
   campaigns and is more machinery than this needs.
 
+  What that choice costs, recorded as it is paid: `MassDownloader` supplies
+  `CircularDomain`, `sanitize=True` and `channel_priorities` for free, and each
+  has had to be built by hand here after its absence showed up in a live fetch.
+  The radius reaching only the station query, an archive holding waveforms with
+  no metadata beside them, and 507 channels for 88 stations were all one
+  property of `Restrictions` each. The wrapper stays thin, but "ObsPy already
+  does it" is an argument for reading what ObsPy does before writing the thin
+  version.
+
 TOML is suggested for the config, read by stdlib `tomllib` on 3.11+ and
 consistent with `pyproject.toml`. YAML is equally fine if it reads better for
 nested station rules; it costs one small dependency.
@@ -2742,13 +2751,30 @@ Two further problems with reproducing the published run from this repository:
    manuscript filename (`...SRL3`) suggests a third revision, which would also
    explain a 2021 code state behind a 2020 access date.
 
-   Practical consequence: **the candidate is `ba3f7ec` or later, not the
+   The evidence narrows it: **the candidate is `ba3f7ec` or later, not the
    pre-November-2020 commits**, because the earlier code cannot perform the
    workflow the paper describes. Only `09f57b9` (removed cython) changes
    `specmod/` after that, so the realistic candidates are `ba3f7ec` and
-   `453c77c`. Pick one, record the reasoning, and move on — this is the
-   strongest possible argument for the `v0.1.0` tag (§6.7) and for `hatch-vcs`
-   (§6.4): it must never be this hard again.
+   `453c77c`.
+
+   **Answered: `453c77c`** — the tip of `master`, 2021-08-12. On the author's
+   word, and it is why `master` was frozen at that commit rather than at any
+   other: the branch *is* the v0.1.1 record (§6.7). Which of the two the
+   evidence above prefers was never the question it looked like.
+
+   What that settles and what it does not: the code is identified, so §5.2.6
+   step 2 can be run against a known commit. The dating oddity is unchanged —
+   the manuscript's access date still precedes the commit it cites, which the
+   third revision (`...SRL3`) explains without needing the code to have moved.
+   It is recorded rather than resolved, because nothing in the repository can
+   resolve it.
+
+   This is still the strongest possible argument for tagging that commit (§6.7)
+   and for `hatch-vcs` (§6.4): a version that takes a page of archaeology to
+   identify must never happen again. **No `v0.1.1` tag exists yet.** Creating
+   one is safe — `453c77c` is an ancestor of `main`, and every later release
+   tag outranks it for `hatch-vcs`, so nothing derives a version from it — but
+   it is repository state, not something a commit here can carry.
 2. **The full published pipeline is not in this repository.** The two-stage
    inversion (fit Ω/`f_c`/`t*` free, then fix event `f_c` to the
    inverse-hypocentral-distance-weighted mean of station `f_c` and refit) and the
@@ -3414,6 +3440,31 @@ been audited once is worth more than one that reads confidently throughout.
 | "`commitlint`-enforced" again, in §6.4 | The §7 instance was corrected and this one was left standing, in the same document. §6.4 corrected. |
 | `publish.yml` "GitHub Release published → PyPI" | It would never have run. release-please creates the release with the default `GITHUB_TOKEN`, and events triggered by that token do not start a workflow. The publish job moved into `release.yml`, gated on `release_created`. §6.5 corrected. |
 
+**A fourth of the same shape, found later** — the three above were corrected in
+the prose; this one was a live setting:
+
+> `[smoothing] method` — "Name -> smoother, for resolving `SmoothingConfig.method`"
+
+`SMOOTHERS` existed, `method` validated against its `Literal`, and **no code
+anywhere read it**. The comparison binned with `log_bin` unconditionally.
+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" while every spectrum went on being binned exactly as before.
+
+**Fixed rather than documented.** `SpectrumPair.compare` now takes a `smoother`,
+`[smoothing] method` resolves to one, and the registry gained `log_window`
+(constant-relative-bandwidth smoothing with a selectable window shape, and a
+median option) and `savitzky_golay` beside the two that were there.
+`tests/test_config.py::TestEverySmoothingMethodIsWiredUp` and
+`tests/test_pipeline.py::TestTheConfiguredSmootherReachesTheComparison` are the
+mechanism the comment claimed: each accepted value resolves, carries its
+section's parameters, and survives the whole path on real windows.
+
+`log_bins` stays `core.collection.log_bin` rather than `smoothing.LogBinner` —
+the two differ in clamping and in what `n_bins` counts, and the difference is
+every committed golden number. The default path is unchanged, which the golden
+suite asserts and which is why this could land without moving a number.
+
 **A claim whose mechanism is absent but whose property holds — for a different
 reason, which matters:**
 
@@ -3460,7 +3511,8 @@ of §5.2, and the two-stage fit API of §5.2.5.
 **`master` is frozen; `main` is the trunk.** `main` was branched from `master` at
 `453c77c` and is where all refactor work lands. `master` is never committed to
 again — it becomes the permanent, named record of the pre-refactor code, doing
-the job a `v0.1.0` tag would have done.
+the job a `v0.1.1` tag would have done. Its tip, `453c77c`, **is** the v0.1.1
+the Magna paper cites (§5.2.5, §8).
 
 **Every pull request must target `sgjholt/SpecMod`, never `uofuseismo/SpecMod`.**
 This is not a matter of care — it is a GitHub default working against you.
@@ -3498,7 +3550,7 @@ Two consequences worth acting on:
 - [ ] Settings → Actions → confirm workflows are enabled
 - [ ] Settings → Branches → protect `master` (no pushes, no deletion) so the
       frozen record stays frozen
-- [ ] `git tag -a v0.1.0 453c77c -m "pre-refactor snapshot" && git push origin v0.1.0`
+- [ ] `git tag -a v0.1.1 453c77c -m "the version the Magna paper cites" && git push origin v0.1.1`
 
 **No Claude session URLs in commit messages, PR bodies, or any other published
 artifact.** The repository is public and those links are private session state. A
@@ -3516,12 +3568,20 @@ needed and neither can be made from a git client:
    convention rather than a guarantee — one absent-minded `git push origin
    master` and the record is gone.
 
-Optionally also tag `453c77c` as `v0.1.0` for good measure; belt and braces, and
-it gives release-please an explicit floor to generate the first changelog from.
-The two are complementary — the tag is immutable, the branch is discoverable.
+Also tag `453c77c` as `v0.1.1` — no longer optional now that §8 records it as
+the commit the paper cites. A branch is discoverable and a tag is immutable,
+and a citation should resolve to the immutable one.
+
+Tagging it publishes nothing. No workflow triggers on tags; the PyPI upload is
+gated on release-please's `release_created`, which only a merged release PR on
+`main` can set; and `git describe` takes the nearest tag, which is a release
+far ahead of this one. **Do not create a GitHub Release from the tag**, which
+is the one action that would publish: Zenodo listens to the release webhook and
+would mint a DOI for the pre-refactor code. The commit has no `pyproject.toml`
+and is not packageable.
 
 > Note on tooling limits: tag pushes are blocked in the automation environment
-> this plan was written in (HTTP 403 on `push origin v0.1.0`, while branch
+> this plan was written in (HTTP 403 on `push origin v0.1.1`, while branch
 > pushes to the same remote succeed), which is why `main` exists as a branch
 > rather than the state being pinned by a tag. **This does not affect the release
 > automation in §6.4** — release-please creates tags from inside GitHub Actions
@@ -3531,10 +3591,10 @@ The two are complementary — the tag is immutable, the branch is discoverable.
 
 Worth being precise about what any of this does and does not preserve: it
 preserves the **code**, but the code is not **runnable** — `mtspec` no longer
-builds on any current toolchain (§2.1). Reproducing a 0.1.0 result needs three
+builds on any current toolchain (§2.1). Reproducing a 0.1.1 result needs three
 things, which is what Phase 0 delivers:
 
-1. `master` (and optionally `v0.1.0`) — the source.
+1. `master` (and the `v0.1.1` tag on its tip) — the source.
 2. A `Dockerfile` pinning `gfortran`, `python 3.9`, `numpy<2` — the environment
    that can still build `mtspec`. Also the only place existing `.spec` pickles
    can be read (§4.6).
@@ -3565,7 +3625,7 @@ Each phase ends green on CI and is independently mergeable.
 
 | Phase | Work | Depends on | Rough size |
 |---|---|---|---|
-| **0. Safety net** | Freeze `master`, default branch → `main`, optional `v0.1.0` tag (§6.7); reproducible legacy env (`Dockerfile`: gfortran + ObsPy 1.2.0 / SciPy 1.4.1 / NumPy 1.18 / pandas 1.0.0 (§5.2.6)); write `datasets/magna_2020.toml` and a first cut of `specmod.acquire`, publish the artifact as a `data-v1` release asset (§5.2); capture golden outputs for PNR **and** Magna; reproduce Table S2 / Figure 2 with 0.1.1 (§5.2.6 step 2); convert any `.spec` files (§4.6) | — | 1.5–2 days |
+| **0. Safety net** | Freeze `master`, default branch → `main`, optional `v0.1.1` tag (§6.7); reproducible legacy env (`Dockerfile`: gfortran + ObsPy 1.2.0 / SciPy 1.4.1 / NumPy 1.18 / pandas 1.0.0 (§5.2.6)); write `datasets/magna_2020.toml` and a first cut of `specmod.acquire`, publish the artifact as a `data-v1` release asset (§5.2); capture golden outputs for PNR **and** Magna; reproduce Table S2 / Figure 2 with 0.1.1 (§5.2.6 step 2); convert any `.spec` files (§4.6) | — | 1.5–2 days |
 | **1. Make it installable** | `pyproject.toml` + hatch-vcs, `src/` layout, `__init__.py`; ruff config, one-shot `ruff format` + `.git-blame-ignore-revs`, module renames to snake_case; mypy skeleton; pre-commit; `test`/`build` CI; `.gitignore`, `CITATION.cff`; fix the three hard breakages (§1) and the four `F821` bugs ruff finds (§2.5); delete `Tests/Tutorial/`, strip notebook outputs, subset the inventory (§5.1) | 0 | 3–4 days |
 | **2. De-globalise** | `config/` package per §4.8 — semantic groups, layer resolution, `config show`/`freeze`, provenance stamping; remove all module-level config reads (tracked by `PLW0603`); `Motion`/`AmplitudeKind` enums; `Spectrum` as a frozen dataclass with `duration`; mutable class attrs (`RUF012`); `isinstance` checks; `logging`. **Tag `v0.2.0`** | 1 | 3–4 days |
 | **2b. Release plumbing** ✅ | ~~Sphinx skeleton + `pydata-sphinx-theme` + autodoc/napoleon/intersphinx~~ ✅; ~~`docs.yml` → a published site~~ ✅ — Read the Docs rather than GH Pages, for versions (§6.3); ~~release-please + PyPI Trusted Publishing~~ ✅ — one `release.yml`, not two workflows (§6.5); ~~Zenodo webhook~~ ✅ documented. Five repository settings have to be turned on by hand: `docs/releasing.md` lists them. The `ci/` mirror that staged workflow files for hand-copying is gone — it existed because an agent token could not push `.github/workflows/`, and that permission is now granted. Parallel with 2 | 1 | 1–2 days |
@@ -3658,20 +3718,48 @@ changes anything shipped.
 ### Still open
 
 1. **Default estimator.** Multitaper (matching current behaviour) or FFT +
-   Konno–Ohmachi (faster, more conventional in engineering seismology)?
+   Konno–Ohmachi (more conventional in engineering seismology)? **No longer
+   blocked** — §6.6's dead `[smoothing] method` is wired up, so the second
+   option is selectable — and now measured, on the 28 PNR windows with each
+   station fitted freely:
+
+   | Against the shipped multitaper + `log_bins` | Median ΔMw | Per-station range | `fc` ratio |
+   |---|---|---|---|
+   | `fft` + `log_bins` | −0.039 | −0.85 to +1.90 | 0.003 to 5.0 |
+   | `fft` + `konno_ohmachi` | +0.027 | −0.52 to +0.51 | 0.038 to 3.2 |
+
+   **The smoothing is what makes the switch defensible, not the estimator.**
+   FFT with the shipped binner moves a station by up to 1.9 magnitude units,
+   because `log_bins` reduces the axis without reducing the variance — 151 log
+   bins over a few hundred Fourier samples is roughly one sample per bin.
+   Pairing it with a real smoother halves the worst excursion and pulls the
+   `fc` range in by a third. The median station barely moves either way.
+
+   What this event cannot settle: the *event* corner is unconstrained under all
+   three (stage-one spread 895% to 1042% of the event value), so the ensemble
+   number is not evidence. Deciding on the ensemble needs an event where it is
+   constrained.
+
+   Speed, measured rather than assumed and far too small to decide on: the
+   transform is 0.209 s against 0.323 s for the 28 windows, and the smoothing
+   adds 0.14 s (`log_bins`) to 0.83 s (`konno_ohmachi`) on top.
+
 2. **Python floor.** 3.11 is proposed. Any users stuck on 3.9/3.10?
 3. **History rewrite.** Deleting the 9.9 MB catalog and stripping the notebook
    (§5.1) shrinks the *working tree* but leaves both in history, so a fresh clone
    still pulls ~15 MiB. Rewriting history with `git-filter-repo` would recover it
    — but it rewrites every SHA, which moves what `master` and `main` currently
-   point at and invalidates any `v0.1.0` tag. Given the end state is a ~1 MB repo
+   point at and invalidates any `v0.1.1` tag. Given the end state is a ~1 MB repo
    either way, **the recommendation is to leave history alone**: a one-time 15 MiB
    clone is a much smaller cost than an unrecoverable pre-refactor record. Only
    worth revisiting if the history genuinely becomes a burden.
-4. **Which commit is "v0.1.1"?** The paper cites SpecMod v0.1.1; no such tag
-   exists and the source carries no version string (§5.2.5). Reproducing the
-   published run needs that commit identified — by submission date against the
-   history, if nothing better is available. Only you can make that call.
+4. ~~**Which commit is "v0.1.1"?**~~ **Resolved: `453c77c`**, the tip of
+   `master`, 2021-08-12 — which is what freezing `master` at that commit was
+   for (§6.7). The archaeology in §5.2.5 narrowed it to two candidates and
+   could not choose between them; the answer did not come from the repository
+   and was never going to. §5.2.6 step 2 now has a known commit to run. No
+   `v0.1.1` tag exists yet, and creating one is repository state rather than
+   something a commit can carry.
 5. ~~**Was noise rotation on for the published run?**~~ **Assumed on.** Not
    recalled, so `studies/magna_2020_paper.toml` starts from the shipped values —
    `ROTATE_NOISE = true`, `ROT_METHOD = 2`, `ROT_PARS = {inc = 0.05, space =

{specmod-0.3.0 → specmod-0.5.0}/docs/choosing-a-transform.md

@@ -582,6 +582,90 @@ narrow at low frequency, wide at high. It preserves the frequency axis, which is
 what you want before fitting on the original grid. Bandwidth `b` is inverse:
 smaller smooths harder; 40 is conventional.
 
+**`LogWindow`** is the same idea with the window shape exposed: a fixed width in
+octaves, and `boxcar`, `bartlett` (triangular), `hann`, `hamming`, `blackman` or
+`gaussian` across it. Use it when you want the constant-relative-bandwidth
+behaviour of Konno–Ohmachi and a say in how hard the taper is — or simply
+because it is faster, being a sliding window rather than a full weight matrix.
+
+Which shape matters less than it looks. On an exact `f**-2` power law, which
+every one of them has to return unchanged, the median residual runs from
+`1.3e-8` dex (`blackman`) to `3.4e-4` dex (`boxcar`) — an ordering that tracks
+the taper's smoothness and a spread far below anything a fit would notice.
+**Pick the width first and the shape second.**
+
+`statistic="median"` is the one option that is not an average: the window
+selects the samples and the median decides, so the shape is ignored. It is
+there for spectra carrying spikes — a power-line tone, a dropout, a telemetry
+glitch — which an average spreads across the whole window. With a single 60×
+spike dropped into that power law, the worst residual across the axis is
+`1.7e-2` dex for the median against `3.8e-2` for the geometric mean and
+`3.6e-1` for the arithmetic one. It will discard a genuine narrow peak just as
+happily, which is the trade.
+
+One detail in it is worth knowing about, because it is not what the textbook
+description of fractional-octave smoothing gives you. A window symmetric in log
+frequency is **not** a symmetric average over samples: a Fourier grid is uniform
+in Hz, so every window holds more samples above its centre than below in log
+terms, and a plain per-sample mean tilts. Weighting each sample by its share of
+the log axis removes it. Smoothing an exact `f**-2` power law, which has to come
+back unchanged, the median residual is `1.5e-3` dex per-sample against `3.2e-8`
+dex weighted for `hann`. It is on by default; `log_measure=False` gives the
+per-sample behaviour, which is what Konno–Ohmachi does.
+
+**`SavitzkyGolay`** fits a sliding polynomial rather than averaging, so it
+flattens a peak far less. It is fitted to `log10(amp)` against `log10(f)` on a
+uniform log-frequency grid — a polynomial in raw amplitude against raw frequency
+spends its degrees of freedom on the falloff and can return a negative
+amplitude. Ringing near the corner and the Nyquist roll-off is what it costs.
+
+### What the choice actually changes
+
+Less than it looks, and not where you would expect. **`[fitting] fit_bins` is
+`false` by default, so the fit reads the unsmoothed spectrum.** The smoother's
+whole influence on `Omega` is therefore indirect: it changes the signal-to-noise
+ratio, which changes the band that passes the gate, which changes where the
+plateau is read. The scatter column below is what the choice buys when
+`fit_bins` is on, or when the reduced arrays are what you plot.
+
+Measured on the 28 PNR windows, everything relative to the shipped default:
+
+<!-- measured: smoothing_table -->
+| Method | Banded | Band low (Hz) | Band (decades) | Δ plateau (dex) | Scatter (dex) |
+|---|---|---|---|---|---|
+| `log_bins` (default) | 28/28 | 0.94 | 1.55 | +0.000 | 0.317 |
+| `konno_ohmachi`, b=40 | 28/28 | 0.93 | 1.68 | +0.067 | 0.093 |
+| `log_window`, hann | 28/28 | 0.93 | 1.66 | +0.067 | 0.111 |
+| `log_window`, bartlett | 28/28 | 0.93 | 1.66 | +0.067 | 0.102 |
+| `log_window`, boxcar | 28/28 | 0.93 | 1.68 | +0.067 | 0.086 |
+| `log_window`, gaussian | 28/28 | 0.93 | 1.65 | +0.067 | 0.147 |
+| `log_window`, median | 28/28 | 0.93 | 1.69 | +0.067 | 0.091 |
+| `savitzky_golay` | 28/28 | 0.93 | 1.67 | +0.067 | 0.063 |
+| `none` | 28/28 | 0.94 | 1.51 | +0.000 | 0.318 |
+<!-- /measured -->
+
+Three things in that table are worth reading twice.
+
+**The default barely smooths.** `log_bins` leaves the same scatter as `none`,
+because 151 log bins over a window holding a few hundred Fourier samples puts
+roughly one sample in most bins. It reduces the *axis*, not the noise.
+
+**Every real smoother widens the band** by about a tenth of a decade. A smoothed
+ratio crosses the threshold later, so more of the high-frequency tail survives
+the gate — which is a gain if the tail is signal and a risk if it is not.
+
+**The plateau moves by the same 0.067 dex under every one of them**, which is
+0.045 in magnitude. That is not seven methods agreeing about amplitudes; it is
+the low band edge moving from 0.94 Hz to 0.93 Hz under all of them, and the
+plateau being read from there. The amplitudes the fit sees never changed.
+
+Cost, measured once at best of three for the whole comparison over the 28
+windows: `none` 63 ms,
+`savitzky_golay` 140 ms, `log_bins` 143 ms, `log_window` 313 ms,
+`log_window` with `statistic="median"` 688 ms, `konno_ohmachi` 830 ms. The
+spread is one machine's, and the shape of it — Konno–Ohmachi building a full
+weight matrix where `LogWindow` slides a window — is what generalises.
+
 ---
 
 ## Reproducing the published Magna configuration

{specmod-0.3.0 → specmod-0.5.0}/docs/development.md

@@ -114,7 +114,8 @@ with `specmod[multitaper]` installed passes tests that CI, which installs only
 
 - **`main`** is the trunk. Everything lands here, and it is the default branch.
 - **`master`** is frozen: the permanent record of the pre-refactor code, doing
-  the job a `v0.1.0` tag would have done. Never commit to it.
+  the job a `v0.1.1` tag would have done: its tip, `453c77c`, is the commit the
+  Magna paper cites. Never commit to it.
 - Feature branches are short-lived and merge into `main` via pull request.
 
 Every pull request must target **`sgjholt/SpecMod`**. See §6.7 of the plan for

{specmod-0.3.0 → specmod-0.5.0}/docs/releasing-data.md

@@ -46,6 +46,10 @@ python -m json.tool build/magna_2020/manifest.json | head -40
 - `channels` — the list *after* wildcard expansion. `HH*` does not tell you
   what you got; this does. A much shorter list than expected usually means a
   network was not open at that time, not that the request was malformed.
+- `channels_available`, `channels_requested` — what the station query offered,
+  and what was asked for after the priority lists narrowed it. A large gap
+  between `channels_requested` and `channels` means the archive did not serve
+  what its own metadata advertises.
 - `data_centre`, `obspy_version`, `specmod_version`, `fetched_at` — the
   provenance that makes the response reproducible-ish. It cannot be fully
   reproducible: FDSN is not content-addressed, archives get backfilled and
@@ -54,6 +58,49 @@ python -m json.tool build/magna_2020/manifest.json | head -40
 If any of that is wrong, fix the config and re-fetch. The artefact is about to
 become immutable.
 
+### Picking one instrument per station
+
+A `channel` pattern that names several instruments — `HH*,BH*,HN*,EN*` — returns
+every one of them at every station that has them. Magna's 88 stations return 507
+channels that way, and a station with both a broadband and an accelerometer
+contributes the same ground motion twice: two entries in a `SpectrumSet`,
+weighted as two stations by anything that averages over them.
+
+`channel_priorities` ranks them instead. The first pattern that matches anything
+at a station wins, so the list is read as "a broadband if there is one,
+otherwise an accelerometer":
+
+```toml
+[stations]
+channel = "HH*,BH*,HN*,EN*"
+channel_priorities = ["HH[ZNE]", "BH[ZNE]", "HN[ZNE]", "EN[ZNE]"]
+location_priorities = ["", "00", "10"]
+```
+
+`channel` still says what the data centre may offer; the priorities say which of
+what it offers to keep. A station matching no pattern at all is dropped — the
+list is a restriction as well as a ranking — and the written `inventory.xml` is
+pruned to match, so the archive keeps describing exactly what it holds.
+
+Patterns are matched case-sensitively against SEED codes, which are upper case.
+`["*"]` keeps everything, which is how a config says it wants both instruments
+and means it; with no list at all, `fetch` warns that it is fetching co-sited
+instruments and names the stations.
+
+### What the radius means
+
+`max_radius_km` is cut against the true WGS84 distance from the epicentre, not
+against the degrees FDSN takes. A degree of arc is 110.574 km at the equator and
+111.691 km at the poles, so converting with a single constant moves the boundary
+by up to half a percent — ±0.3 km on a 50 km radius, ±2 km on 400 km. The
+station query is sent deliberately wide and the exact cut is made locally, which
+costs a few extra stations in the query and makes the radius mean kilometres
+wherever the event is.
+
+The radii are epicentral. For a local array the depth is usually the larger
+term: every station of a 500 m array over a 2 km-deep event is at 2 km
+hypocentral distance.
+
 ## 2. Archive and hash
 
 ```bash

{specmod-0.3.0 → specmod-0.5.0}/docs/roadmap.md

@@ -35,7 +35,10 @@ The version before this one, `0.1.1`, is the pre-refactor code that produced
 the published Magna results. It is preserved unchanged on the
 [`master`](https://github.com/sgjholt/SpecMod/tree/master) branch, which is
 protected and frozen — it was never tagged or published to PyPI, so that
-branch is the only reference to it. Everything below is the delta between it
+branch is the only reference to it. Its tip,
+[`453c77c`](https://github.com/sgjholt/SpecMod/commit/453c77c), is the commit
+the paper cites as v0.1.1; cite that rather than the branch name, which is a
+moving target in principle even though this one will not move. Everything below is the delta between it
 and v0.2.0, which is why the first changelog is enormous and correctly so.
 
 ### An installable package
@@ -106,11 +109,11 @@ build**, so every figure and number on the page came from running the code
 being documented. A notebook that stops working fails the build rather than
 going quietly stale, which is why it was a 1.0 requirement.
 
-## In progress — not yet released
+## Shipped in v0.3.0
 
-### Finishing the decomposition
+### The decomposition, finished
 
-**Done, and unreleased.** This was the last item 1.0 was waiting on.
+This was the last item 1.0 was waiting on.
 
 `io.py` and `plotting.py` are now packages, alongside the spectral core, the
 fitting layer and the pick readers; the type-checking backlog is empty. The
@@ -136,13 +139,67 @@ 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
 
-**Everything this was waiting on is now done** — the documentation, and the
-decomposition above with the signature changes it implied. What remains is the
-release itself, which says that names and signatures stop moving without a
+**Everything this was waiting on shipped in v0.3.0** — the documentation, and
+the decomposition above with the signature changes it implied. What remains is
+the release itself, which says that names and signatures stop moving without a
 deprecation cycle.
 
 That promise is the whole content of the number, which is why it has to be a
@@ -151,6 +208,21 @@ is made, breaking changes bump the minor. The honest test before making it is
 whether a release goes by without one — the API is not settled because the
 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 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
@@ -175,7 +247,16 @@ 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.
+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
+released, because `release-please` writes the changelog and the manifest and
+knows nothing about this file. `tests/test_release_config.py` now fails when
+the released minor version is ahead of every version this page names, which is
+the check that was missing rather than a rule that was.
 
 Before v0.2.0 this was a list of stages, because there was no released version
 to point at and "done" could only mean merged. The full changelog for every