specmod 0.2.2__tar.gz → 0.2.3__tar.gz

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

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

{specmod-0.2.2 → specmod-0.2.3}/CHANGELOG.md

@@ -9,6 +9,23 @@ 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.2.3](https://github.com/sgjholt/SpecMod/compare/v0.2.2...v0.2.3) (2026-09-05)
+
+
+### Bug Fixes
+
+* correct four documented equations and behaviours that the code contradicts ([821792b](https://github.com/sgjholt/SpecMod/commit/821792b66d418b9c0048d717975b5a3716c52c20))
+* point the DOI badge at the concept DOI, not v0.2.0's ([11e7f7a](https://github.com/sgjholt/SpecMod/commit/11e7f7a056fc17c91b22c1dc9d834f19b8b6dbe3))
+
+
+### Documentation
+
+* an upgrade guide, and a table of contents with a shape ([4f35388](https://github.com/sgjholt/SpecMod/commit/4f353885cfd0768edeac225d7db4672a20c9120e))
+* derive the roadmap's version, and say when its entries move ([1917d43](https://github.com/sgjholt/SpecMod/commit/1917d432c6fdae1969dacb506bdac986152e40d8))
+* document moment and magnitude, which the page said were absent ([026abec](https://github.com/sgjholt/SpecMod/commit/026abecb9c6ed33017b306e825a6f84db2b343e4))
+* state what is true now, not what the page used to say ([b17339b](https://github.com/sgjholt/SpecMod/commit/b17339b6ad383afd936f7f2a972549b313e19906))
+* the documentation 1.0 was waiting on is done ([9693334](https://github.com/sgjholt/SpecMod/commit/9693334434738ae000bf61f1908524ee983ced17))
+
 ## [0.2.2](https://github.com/sgjholt/SpecMod/compare/v0.2.1...v0.2.2) (2026-09-05)
 
 

{specmod-0.2.2 → specmod-0.2.3}/CITATION.cff

@@ -12,7 +12,7 @@ identifiers:
   # mints a version DOI per release; cite that one instead when reproducibility
   # matters and you need the reader to land on the exact version you ran.
   - type: doi
-    value: "10.5281/zenodo.22071455"
+    value: "10.5281/zenodo.22071454"
     description: "Concept DOI — resolves to the latest release."
 keywords:
   - seismology

{specmod-0.2.2 → specmod-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: specmod
-Version: 0.2.2
+Version: 0.2.3
 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
@@ -38,6 +38,7 @@ Provides-Extra: docs
 Requires-Dist: myst-nb>=1.1; extra == 'docs'
 Requires-Dist: myst-parser>=3.0; extra == 'docs'
 Requires-Dist: pydata-sphinx-theme>=0.15; extra == 'docs'
+Requires-Dist: sphinx-togglebutton>=0.3; extra == 'docs'
 Requires-Dist: sphinx>=7.3; extra == 'docs'
 Provides-Extra: io
 Requires-Dist: h5py>=3.11; extra == 'io'
@@ -58,7 +59,7 @@ Description-Content-Type: text/markdown
 
 [![PyPI](https://img.shields.io/pypi/v/specmod.svg)](https://pypi.org/project/specmod/)
 [![Documentation](https://readthedocs.org/projects/specmod/badge/?version=stable)](https://specmod.readthedocs.io/en/stable/)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22071455.svg)](https://doi.org/10.5281/zenodo.22071455)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22071454.svg)](https://doi.org/10.5281/zenodo.22071454)
 
 A Python toolbox for processing and modelling seismic spectra, following the
 method of Edwards *et al.* (2010).
@@ -237,7 +238,7 @@ The full documentation — the pipeline with its equations, the estimator
 comparison, pick formats, and an API reference — builds with Sphinx:
 
 ```bash
-uv pip install -e '.[docs]'
+uv pip install -e '.[docs,io,tutorial]'
 sphinx-build -b html docs docs/_build/html
 ```
 

{specmod-0.2.2 → specmod-0.2.3}/README.md

@@ -2,7 +2,7 @@
 
 [![PyPI](https://img.shields.io/pypi/v/specmod.svg)](https://pypi.org/project/specmod/)
 [![Documentation](https://readthedocs.org/projects/specmod/badge/?version=stable)](https://specmod.readthedocs.io/en/stable/)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22071455.svg)](https://doi.org/10.5281/zenodo.22071455)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22071454.svg)](https://doi.org/10.5281/zenodo.22071454)
 
 A Python toolbox for processing and modelling seismic spectra, following the
 method of Edwards *et al.* (2010).
@@ -181,7 +181,7 @@ The full documentation — the pipeline with its equations, the estimator
 comparison, pick formats, and an API reference — builds with Sphinx:
 
 ```bash
-uv pip install -e '.[docs]'
+uv pip install -e '.[docs,io,tutorial]'
 sphinx-build -b html docs docs/_build/html
 ```
 

{specmod-0.2.2 → specmod-0.2.3}/docs/choosing-a-transform.md

@@ -253,11 +253,8 @@ or **0.03 magnitude units**. Against the 0.13 m.u. scatter quoted for spectral
 `Mw` that is small, but it is systematic rather than random, so it does not
 average away across stations at similar distance.
 
-> Earlier revisions of this page reported 89% for flat weighting and 650% for
-> adaptive here. The 650% was the adaptive collapse described above and is
-> gone. The remaining figures come from a differently-constructed sweep than
-> the original and are not directly comparable to it; this table is the one
-> `tools/measure_docs.py` reproduces.
+> Every figure in this table is regenerated by `tools/measure_docs.py`, and
+> `tests/test_docs_are_current.py` fails if the page and the code disagree.
 
 ### It costs you a diagnostic
 

{specmod-0.2.2 → specmod-0.2.3}/docs/conf.py

@@ -2,7 +2,7 @@
 
 Build with::
 
-    uv pip install -e '.[docs]'
+    uv pip install -e '.[docs,io,tutorial]'
     sphinx-build -b html docs docs/_build/html
 
 ``-W`` is deliberately **not** used. Intersphinx resolves seven inventories
@@ -41,6 +41,11 @@ extensions = [
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
+    #: Makes `:class: dropdown` collapse an admonition. The alpha warning on the
+    #: landing page is the reason: it has to be read once and then stops earning
+    #: the screen it occupies, and a caveat nobody scrolls past is worse than
+    #: one folded behind its own headline.
+    "sphinx_togglebutton",
 ]
 #: `sphinx_autodoc_typehints` is deliberately not used. `autodoc_typehints`
 #: below is built into `sphinx.ext.autodoc` and does the same job here, and the
@@ -88,11 +93,11 @@ if _TUTORIAL_SRC.is_dir():
     shutil.rmtree(_TUTORIAL_DST, ignore_errors=True)
     shutil.copytree(_TUTORIAL_SRC, _TUTORIAL_DST)
 
-#: `force`, not `auto`. `auto` executes only notebooks that arrive without
-#: outputs, and the tutorial is committed *with* 28 cells of them — so `auto`
-#: would publish whatever was last saved by hand, which is the silent rot this
-#: is meant to end. Forcing it means the page can only show output the code
-#: actually produced against the code being documented.
+#: `force`, not `auto`. The `nbstripout` hook means the notebook arrives with no
+#: outputs, so `auto` would execute it today and quietly stop the moment anyone
+#: committed a notebook with outputs saved — publishing whatever was last run by
+#: hand. Forcing it means the page can only ever show output the code produced
+#: against the code being documented, whatever is in the file.
 nb_execution_mode = "force"
 #: Matches `tests/test_tutorial.py`. The whole notebook runs in ~40s; the
 #: default 30s is per cell, and the two-stage fit is the one that would trip it.
@@ -126,6 +131,13 @@ myst_enable_extensions = [
 #: Heading anchors down to h3, so `docs/*.md` can link to each other's sections.
 myst_heading_anchors = 3
 
+#: `{{ release }}` in a page resolves to the version this site was built from.
+#: The roadmap used to state it in prose, which meant it was wrong from the
+#: moment of the next release — it said v0.2.0 through two that followed. A
+#: version is derivable, so deriving it removes the only part of that page that
+#: went stale on a timetable rather than on a decision.
+myst_substitutions = {"release": release}
+
 # ------------------------------------------------------------------ autodoc
 
 autodoc_typehints = "description"
@@ -160,5 +172,19 @@ html_theme_options = {
     "github_url": "https://github.com/sgjholt/SpecMod",
     "show_prev_next": True,
     "navigation_with_keys": False,
+    #: This theme puts *top-level* toctree entries in the header and gives the
+    #: sidebar the current section's children. A flat toctree therefore
+    #: produces a header of ten items and an empty sidebar, with `:caption:`
+    #: nowhere to render — which is what this site had. The four section pages
+    #: are what give the sidebar something to nest.
+    #:
+    #: `show_nav_level: 1` expands each section's own entries rather than
+    #: leaving them behind a disclosure triangle, so a reader can see a
+    #: section's contents without a click.
+    "show_nav_level": 1,
+    #: Deep enough for a section, its pages, and their headings — which is what
+    #: makes a long page like `processing` navigable from the sidebar rather
+    #: than by scrolling.
+    "navigation_depth": 3,
 }
 html_static_path: list[str] = []

specmod-0.2.3/docs/contributing.md

@@ -0,0 +1,31 @@
+# Working on SpecMod
+
+Where the project is going, how to work on it, and how a merged commit becomes
+a release.
+
+[Roadmap](roadmap.md)
+: What has shipped and in which version, what is being worked on, and what 1.0
+  will mean. Milestones, not dates.
+
+[Developer guide](development.md)
+: Quick start, the repository mapped, the daily loop, every tool and check, and
+  where development stops and releasing begins. Includes working with coding
+  agents.
+
+[Documentation workflow](documentation.md)
+: Building this site locally, previewing a pull request's build, how the
+  tutorial is executed into it, and how to add a page.
+
+[Releasing the software](releasing.md)
+: How a merged commit becomes a tag, a PyPI release and a DOI — and the
+  one-time repository settings none of it works without.
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+roadmap
+development
+documentation
+releasing
+```

{specmod-0.2.2 → specmod-0.2.3}/docs/development.md

@@ -246,12 +246,12 @@ bounded rather than explained, and says so in as many words.
 
 ## What CI runs
 
-Five jobs in `test.yml`, plus two more workflows. All of them run on every pull
-request.
+Six jobs in `test.yml`, plus three more workflows. All of them run on every
+pull request except `release.yml`, which fires only on a push to `main`.
 
 | Job | Workflow | Does |
 |---|---|---|
-| `lint` | `test.yml` | `ruff check`, `ruff format --check`, and the `ci/` mirror check |
+| `lint` | `test.yml` | `ruff check` and `ruff format --check` over `src/ tests/ tools/` |
 | `typecheck` | `test.yml` | `mypy`, strict, over the whole package |
 | `test` | `test.yml` | pytest on 3.11/3.12/3.13 × ubuntu/macOS, coverage to Codecov from one cell |
 | `floors` | `test.yml` | installs the *declared minimum* versions and runs the suite |
@@ -403,9 +403,12 @@ has happened here:
   not there. Three commits went out with session trailers before this was
   noticed; the config now installs both hook types from one command, and the
   first thing `AGENTS.md` says is to run it.
-- **An agent's token cannot push `.github/workflows/`.** This is what the
-  `ci/` mirror exists for. An agent that does not know about it will either
-  fail the push or, worse, quietly drop the change.
+- **An agent's token may not be able to push `.github/workflows/`.** The
+  permission is granted here now, and the `ci/` mirror that used to work around
+  it is gone — keeping two copies of every workflow in step cost more than the
+  problem it solved. If the permission is ever withdrawn the push is rejected
+  loudly, naming `workflows`; the answer is to ask for it back, not to rebuild
+  the mirror.
 - **A development container often lacks the optional extras**, so an agent's
   green run can be greener than CI's. `--without-optional-extras` is the check.
 - **A harness may append its own commit trailers.** The repository's rules take

{specmod-0.2.2 → specmod-0.2.3}/docs/documentation.md

@@ -32,7 +32,7 @@ those are separate clocks.
 ## Building it locally
 
 ```sh
-uv pip install -e '.[docs]'
+uv pip install -e '.[docs,io,tutorial]'
 sphinx-build -b html docs docs/_build/html
 python -m http.server -d docs/_build/html 8000   # then open localhost:8000
 ```
@@ -136,9 +136,11 @@ Two things in it are load-bearing and easy to lose:
   clones shallow to save time, and `hatch-vcs` derives the version from
   `git describe`. Without those two lines every build — including a tagged one
   — reports the fallback `0.0.0` in the sidebar.
-- **`extra_requirements: [docs, io]`.** The `io` extra is there because autodoc
-  imports `specmod.io`, which imports h5py and pyarrow. The CI job installs the
-  same pair for the same reason.
+- **`extra_requirements: [docs, io, tutorial]`.** `io` because autodoc imports
+  `specmod.io`, which imports h5py and pyarrow — and because the tutorial saves
+  an HDF5 file while executing. `tutorial` for the Jupyter kernel that executes
+  it. The CI `docs` job installs the same three for the same reasons; keep them
+  in step or one of the two builds fails on a missing kernel.
 
 ## Versions, and what to link to
 
@@ -168,11 +170,19 @@ page depends on is documentation whatever its folder is called.
 ### Adding a page
 
 1. Write `docs/<name>.md` in MyST Markdown.
-2. Add it to the `toctree` at the bottom of `docs/index.md`, and usually to the
-   "Where to start" list above it.
+2. **Add it to the `toctree` of the section it belongs to** — not to
+   `index.md`. The site has four section pages, each owning its own toctree:
+   `getting-started.md`, `guides.md`, `api.md` and `contributing.md`. Add a
+   description to the list on that page too, since the sidebar shows titles
+   only.
 3. Build. A page in no toctree builds but warns, and is reachable only by a
    direct link.
 
+`index.md`'s toctree holds only those four. That is what gives the sidebar its
+nesting: this theme puts top-level toctree entries in the header and gives the
+sidebar the current section's children, so a page added at the top level lands
+in the header and flattens the navigation for everything else.
+
 If a page is a supporting note rather than a top-level one, put it in a hidden
 toctree on the page that cites it — that is how `notes/window-position.md` is
 attached to `choosing-a-transform.md`:
@@ -226,7 +236,7 @@ the first build:
 
 Type hints come from the annotations via `autodoc_typehints = "description"`.
 `sphinx-autodoc-typehints` is deliberately **not** used: measured, it produced
-the same 367 documented objects while calling an API Sphinx 10 removes.
+the same number of documented objects while calling an API Sphinx 10 removes.
 
 ### The tutorial notebook
 
@@ -258,9 +268,12 @@ committed output is never what a reader sees — only a stale diff.
 The kernel comes from the `tutorial` extra. Both `.readthedocs.yaml` and
 `.github/workflows/docs.yml` install `[docs,io,tutorial]`; keep them in step or
 one of the two builds fails on a missing kernel. This does mean the notebook
-executes twice per pull request — once here and once in the `notebook` CI job,
-which also checks imports and that deleted modules stay unmentioned. Roughly
-40 seconds, paid twice, for two genuinely different failures.
+executes twice per pull request — once here, and once in the `notebook` CI job,
+which runs the single `-m notebook` test that executes it in a `tmp_path` copy.
+Roughly 40 seconds, paid twice, to catch a broken notebook either as a failed
+build or as a failed test. The cheaper checks around it — that every name the
+notebook imports resolves, and that deleted modules stay unmentioned even in
+prose — are unmarked, so they run in the `test` matrix job instead.
 
 ### Numbers in prose
 

specmod-0.2.3/docs/getting-started.md

@@ -0,0 +1,41 @@
+# Getting started
+
+Install it, run one event end to end, and find out what moved if you have code
+written against `0.1`.
+
+```sh
+pip install specmod
+```
+
+Python 3.11 or newer. Saving and loading spectra needs the `io` extra —
+`pip install "specmod[io]"` — without which SpecMod computes and plots normally
+but cannot write a result. The other extras are listed in the
+[README](https://github.com/sgjholt/SpecMod#installation).
+
+While this is `0.x`, pin an exact version in anything you intend to publish.
+The [roadmap](roadmap.md) says what has shipped and what 1.0 will mean.
+
+[Tutorial](tutorial/SpecModTutorial.ipynb)
+: One event from waveforms and picks to source parameters. Every figure and
+  number on the page is produced by executing the notebook when this site is
+  built, so it cannot describe an API that no longer exists. **Start here.**
+
+[Upgrading from 0.1](upgrading.md)
+: For code written against the pre-refactor `0.1.1` on `master`. Modules moved,
+  were renamed to snake_case, and several were deleted, so old code fails at
+  its imports rather than running and quietly giving different numbers.
+
+## Then
+
+[How a spectrum is processed](processing.md) is the reference for what each
+stage does and the conventions it uses — the amplitude convention, the Parseval
+contract, and the moment and magnitude equations. It is the page to read once
+the tutorial has run.
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+tutorial/SpecModTutorial
+upgrading
+```

specmod-0.2.3/docs/guides.md

@@ -0,0 +1,55 @@
+# Guides
+
+What each stage does, why it is done that way, and what the choices cost.
+
+## The pipeline, and the conventions
+
+[How a spectrum is processed](processing.md)
+: Every step from a raw waveform to a moment magnitude, with the equation it
+  applies and a pointer to the code that applies it.
+
+This is also where the conventions are stated, deliberately in the sections
+that apply them rather than on a page of their own:
+
+[Amplitude convention](processing.md#4-amplitude-convention)
+: `FAS` is the folded $2\lvert X\rvert$; `MAGNITUDE` is the unfolded
+  $\lvert X\rvert$, **and that is the one $\Omega$ is defined in**. Reading a
+  folded plateau as $\Omega$ puts $M_0$ out by two — 0.2 magnitude units.
+
+[The Parseval contract](processing.md#the-parseval-contract)
+: The one energy check every estimator is held to, which is what lets
+  multitaper, Welch, FFT and the CWT be interchangeable rather than merely
+  similar.
+
+[Moment and magnitude](processing.md#9-moment-and-magnitude)
+: The $M_0$ and $M_w$ equations, the medium constants and where they come
+  from, and the two distances that are in different units on purpose.
+
+## Choices that change the answer
+
+[Choosing a transform](choosing-a-transform.md)
+: What each estimator does to your data, measured. On real windows the plateau
+  moves by 7–15% between estimators — about 0.03 magnitude units — and window
+  position alone reaches 0.08. Small against the 0.13 m.u. scatter quoted for
+  spectral $M_w$, but systematic rather than random, so it does not average
+  away across stations at similar distance.
+
+[Reading picks](pick-formats.md)
+: What arrival formats are read out of the box, how to add one, and how a pick
+  is matched to a trace.
+
+## Working with data
+
+[Publishing a dataset](releasing-data.md)
+: Taking an event from an FDSN archive to a hash-pinned entry in the registry,
+  so a result can be reproduced from the same bytes.
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+processing
+choosing-a-transform
+pick-formats
+releasing-data
+```

{specmod-0.2.2 → specmod-0.2.3}/docs/index.md

@@ -4,9 +4,11 @@ A Python toolbox for processing and modelling seismic spectra: cut a window,
 estimate its spectrum, decide which part of it is above the noise, and fit a
 source model to that band.
 
-:::{warning}
-**Alpha. Pre-1.0, and mid-refactor.** SpecMod is being rebuilt in the open, so
-treat everything here as provisional until the API settles at 1.0:
+:::{admonition} Alpha, pre-1.0 — pin an exact version for anything you publish
+:class: warning, dropdown
+
+SpecMod is being rebuilt in the open, so treat everything here as provisional
+until the API settles at 1.0:
 
 - **Names and signatures move between `0.x` releases**, without a deprecation
   cycle. Breaking changes land in minor bumps by design — that is what `0.x`
@@ -43,47 +45,24 @@ fits.fit_spectra()
 print(fits.table[["id", "llpsp", "fc", "ts"]])
 ```
 
-## Where to start
-
-[Tutorial](tutorial/SpecModTutorial.ipynb)
-: One event end to end — waveforms and picks in, source parameters out. Every
-  figure and number on the page is produced by running the notebook at build
-  time, so it cannot describe an API that no longer exists.
-
-[Processing](processing.md)
-: Every step of the pipeline with the equation it implements — what a window
-  is, how the noise is compared against it, and what the bandwidth selector
-  does.
-
-[Choosing a transform](choosing-a-transform.md)
-: What each estimator does to your data, measured. The choices here change
-  recovered amplitude by factors of three on real windows, which is about 0.3
-  magnitude units.
-
-[Reading picks](pick-formats.md)
-: What arrival formats are read out of the box, how to add one, and how a pick
-  is matched to a trace.
-
-[Publishing a dataset](releasing-data.md)
-: Taking an event from an FDSN archive to a hash-pinned entry in the registry.
-
-[Releasing the software](releasing.md)
-: How a merged commit becomes a tag, a PyPI release and a DOI, and the six
-  settings that have to be turned on once.
+## Where to go
 
-[Roadmap](roadmap.md)
-: What has shipped and in which version, what is being worked on, and what 1.0
-  will mean. Milestones, not dates.
+[Getting started](getting-started.md)
+: Install it, run one event end to end with the tutorial, and — if you have
+  code written against `0.1` — find out what moved.
 
-## Working on SpecMod
+[Guides](guides.md)
+: What each stage does and why, and where the conventions are stated: the
+  amplitude convention, the Parseval contract, and the moment and magnitude
+  equations.
 
-[Developer guide](development.md)
-: Quick start, the repository mapped, the daily loop, every tool and check, and
-  where development stops and releasing begins.
+[API reference](api.md)
+: Every public object. `specmod.api` is the narrower, more stable subset to
+  import from if you are building on this.
 
-[Documentation workflow](documentation.md)
-: Building the site locally, previewing a pull request's build, what the
-  official site is, and how versions would work.
+[Working on SpecMod](contributing.md)
+: The roadmap, the developer guide, how this site is built, and how a merged
+  commit becomes a release.
 
 ## Two things worth knowing early
 
@@ -99,17 +78,11 @@ model carries a motion factor, so the plateau it reports is the displacement
 one either way.
 
 ```{toctree}
-:maxdepth: 2
+:maxdepth: 3
 :hidden:
 
-tutorial/SpecModTutorial
-processing
-choosing-a-transform
-pick-formats
-development
-documentation
-releasing-data
-releasing
-roadmap
+getting-started
+guides
 api
+contributing
 ```