specmod 0.2.0__py3-none-any.whl

specmod/__init__.py

@@ -0,0 +1,17 @@
+"""SpecMod — a toolbox for processing and modelling seismic spectra.
+
+The public API is re-exported here. Submodules may be imported directly for
+anything not listed in ``__all__``.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+try:
+    __version__ = _version("specmod")
+except PackageNotFoundError:  # pragma: no cover - only when running from source
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

specmod/_vendor/__init__.py

@@ -0,0 +1,21 @@
+"""Third-party code vendored into SpecMod.
+
+Everything here was written by someone else and is redistributed under its own
+licence, which is reproduced in the module that carries it. The rules for this
+package:
+
+1. **Nothing in here is public API.** Callers go through the wrapper in
+   :mod:`specmod.transforms`, so a vendored implementation can be replaced by a
+   native one without anybody noticing.
+2. **Changes are recorded.** Each module lists what was altered from upstream
+   and why, so the diff against the original stays legible.
+3. **Our tests own it.** Vendored code is held to the same contracts as
+   everything else — a vendored function that cannot satisfy the Parseval check
+   in :mod:`specmod.core.spectrum` is a bug on our side of the fence now.
+
+The point of the quarantine is that upstream code arrives with upstream
+conventions, and mixing those into ``specmod.transforms`` is how a codebase
+ends up with two of everything.
+"""
+
+from __future__ import annotations

specmod/_vendor/qiinv.py

@@ -0,0 +1,243 @@
+"""Quadratic inverse spectrum estimation, vendored from Prieto's ``multitaper``.
+
+Upstream: https://github.com/gaprieto/multitaper — ``multitaper/utils.py``,
+functions ``qiinv`` and ``sft``, version 1.2.0.
+
+    MIT License
+    Copyright (c) 2022 Germán A. Prieto
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+
+Why this is vendored rather than imported
+-----------------------------------------
+``multitaper`` remains an optional extra and is still the better route to
+jackknife intervals and the F-test. This one function is carried here because
+it does not run at all on the version of numpy SpecMod requires — see change 1
+— so importing it would make the quadratic estimator unavailable by default.
+Vendoring keeps it a core capability with no optional dependency.
+
+Changes from upstream
+---------------------
+1. **numpy 2 compatibility (the reason this is here).** ``scipy.optimize.nnls``
+   and ``scipy.linalg.lstsq`` return shape-``(1,)`` arrays for a single-column
+   system, and upstream assigns them into scalar slots of a 1-D buffer. That
+   was deprecated in numpy 1.25 and raises in 2.0, so ``qiinv`` fails for every
+   weighting scheme. Four lines now index the scalar out explicitly: ``cte2``,
+   ``cte``, ``slope``, ``quad``.
+
+2. **``sft`` replaced by a vectorised equivalent, dropping numba.** Upstream's
+   ``sft`` is a Goertzel recursion decorated with ``@njit``; it is called
+   ``kspec * nxi`` times, so without numba it would be unusably slow. It
+   computes a single-frequency DFT, ``sum_j x[j] exp(-i w j)``, and the whole
+   ``Vj`` block collapses to one complex matmul. Verified against upstream to
+   1e-12 absolute over 300 randomised cases — the residual is the recursion's
+   own accumulation error, so the form here is the more accurate of the two.
+   This removes numba from the dependency graph entirely.
+
+3. **The ``nfft``-long solve loop is unchanged.** It is the slow part and it
+   vectorises, but leaving it identical keeps the diff against upstream
+   readable. Optimise it only with the cross-validation test in place.
+
+4. The ``Cjk``/``Pjk`` construction is vectorised out of its double loop,
+   ``spec`` is dropped from the signature (upstream accepts it and never reads
+   it), the eigenvalue warning goes through ``warnings`` rather than ``print``,
+   and the unused ``cte``/``sigma2``/``cte_var``/``slope_var`` buffers are gone.
+
+5. Formatting and type annotations.
+
+References
+----------
+Prieto, G.A., Parker, R.L., Thomson, D.J., Vernon, F.L., Graham, R.L. (2007).
+Reducing the bias of multitaper spectrum estimates.
+*Geophysical Journal International* 171(3), 1269-1281.
+
+Thomson, D.J. (1990). Quadratic-inverse spectrum estimates: applications to
+palaeoclimatology. *Phil. Trans. R. Soc. Lond. A* 332, 539-597.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+import scipy.linalg
+import scipy.optimize
+from numpy.typing import NDArray
+
+__all__ = ["qiinv"]
+
+
+def _single_frequency_dft(
+    tapers: NDArray[np.float64], omega: NDArray[np.float64]
+) -> NDArray[np.complex128]:
+    """``sum_j tapers[j, k] exp(-i omega_i j)`` for every ``(i, k)``.
+
+    Replaces upstream's ``sft`` Goertzel recursion (see change 2 above). The
+    frequencies here are a handful of points inside the inner band, not an FFT
+    grid, so there is nothing to gain from an FFT and a direct sum is both
+    exact and fast enough as one matmul.
+    """
+    phase = np.exp(-1j * np.outer(omega, np.arange(tapers.shape[0])))
+    result: NDArray[np.complex128] = phase @ tapers
+    return result
+
+
+def qiinv(
+    yk: NDArray[np.complex128],
+    wt: NDArray[np.float64],
+    vn: NDArray[np.float64],
+    lamb: NDArray[np.float64],
+    nw: float,
+) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
+    """Quadratic inverse spectrum estimate, after Prieto et al. (2007).
+
+    Estimates the spectrum's first two derivatives inside the inner band and
+    subtracts the bias that curvature — the second derivative — introduces into
+    an ordinary multitaper estimate. That bias is largest exactly where the
+    spectrum bends most sharply, which for a Brune source is the corner.
+
+    Parameters
+    ----------
+    yk
+        Eigencoefficients, shape ``(nfft, kspec)``: the **two-sided** FFT of
+        each tapered copy of the record, in numpy's FFT ordering.
+    wt
+        Per-taper, per-frequency weights, shape ``(nfft, kspec)``. Pass ones
+        for flat weighting.
+    vn
+        DPSS tapers, shape ``(npts, kspec)``. Note the orientation: this is the
+        transpose of what :func:`scipy.signal.windows.dpss` returns.
+    lamb
+        Taper eigenvalues (concentration ratios), shape ``(kspec,)``.
+    nw
+        The time-bandwidth product.
+
+    Returns
+    -------
+    qispec
+        The quadratic estimate, shape ``(nfft,)``, in the units of
+        ``|yk|**2``.
+    slope, quad
+        First and second derivative of the spectrum with respect to frequency.
+        Returned because they are diagnostics in their own right — ``quad`` is
+        what the correction is built from, so a caller can see how much work it
+        did.
+    """
+    npts, kspec = np.shape(vn)
+    nfft = np.shape(yk)[0]
+    nxi = 79
+    n_cross = kspec * kspec
+
+    if np.min(lamb) < 0.9:
+        # Upstream prints; a caller of ours has no console to watch.
+        warnings.warn(
+            f"Poorest taper eigenvalue is {np.min(lamb):.4f} (< 0.9), so the "
+            f"higher-order tapers leak badly and the quadratic estimate will "
+            f"inherit that. Reduce n_tapers or raise time_bandwidth.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+
+    # ---------------------------------------------- inner-band frequencies
+    bp = nw / npts  # half-bandwidth W
+    xi = np.linspace(-bp, bp, num=nxi)
+    dxi = xi[2] - xi[1]
+
+    xk = wt * yk
+    vj = _single_frequency_dft(vn, 2.0 * np.pi * xi) / np.sqrt(lamb)
+
+    # ------------------------- vectorised Cjk (data) and Pjk = {Vj Vk*}
+    i_idx, k_idx = np.divmod(np.arange(n_cross), kspec)
+    cross = np.conjugate(xk[:, i_idx]) * xk[:, k_idx]  # (nfft, L)
+    proj = np.conjugate(vj[:, i_idx]) * vj[:, k_idx]  # (nxi, L)
+
+    cross = cross.T  # (L, nfft), as upstream orders it
+    proj = proj.T  # (L, nxi)
+    proj[:, 0] *= 0.5  # trapezoid end weights
+    proj[:, nxi - 1] *= 0.5
+
+    # ------------------ Chebyshev basis: constant, slope, curvature
+    hcte = np.ones(nxi)
+    hslope = xi / bp
+    hquad = 2.0 * (xi / bp) ** 2 - 1.0
+
+    h1 = (proj @ hcte) * dxi
+    hk = np.empty((n_cross, 3), dtype=complex)
+    hk[:, 0] = h1
+    hk[:, 1] = (proj @ hslope) * dxi
+    hk[:, 2] = (proj @ hquad) * dxi
+    nh = hk.shape[1]
+
+    # --------------------------- least squares via QR, factored once
+    q_mat, r_mat = scipy.linalg.qr(hk)
+    qt = np.transpose(q_mat)
+    ri = scipy.linalg.lstsq(r_mat, np.eye(n_cross))[0]
+    covb = np.real(ri @ np.transpose(ri))
+
+    cte2 = np.zeros(nfft)
+    slope = np.zeros(nfft)
+    quad = np.zeros(nfft)
+    quad_var = np.zeros(nfft)
+
+    h1_real = np.real(h1)[:, None]
+    for i in range(nfft):
+        cjk = cross[:, i : i + 1]
+
+        # Constrain the constant term to be non-negative: a power spectrum
+        # cannot go below zero, and the unconstrained fit will happily do so.
+        cte2[i] = np.real(scipy.optimize.nnls(h1_real, np.real(cjk[:, 0]))[0])[0]
+
+        # Solve the derivatives against what the constant term left behind.
+        residual = cjk - h1_real * cte2[i]
+        hmodel = scipy.linalg.lstsq(r_mat, qt @ residual)[0]
+        slope[i] = -np.real(hmodel[1])[0]
+        quad[i] = np.real(hmodel[2])[0]
+
+        pred = hk @ np.real(hmodel)
+        sigma2 = np.sum(np.abs(residual - pred) ** 2) / (n_cross - nh)
+        quad_var[i] = sigma2 * covb[2, 2]
+
+    slope = slope / bp
+    quad = quad / bp**2
+    quad_var = quad_var / bp**4
+
+    # Damp the correction where the curvature estimate is itself noisy, so a
+    # poorly-determined second derivative cannot drag the spectrum around.
+    #
+    # Guarded against a zero or non-finite denominator, which upstream divides
+    # through blindly and so returns NaN for the whole spectrum. The case that
+    # matters is 0/0: a dead channel or a zero-filled gap demeans to all zeros,
+    # every cross-spectrum is zero, and NaN from here propagates silently into
+    # a fit. Weight zero is the right answer — no usable curvature information
+    # means apply no correction.
+    #
+    # The non-finite arm only triggers for amplitudes around 1e150, where the
+    # squares approach the top of float64. It is cheap insurance rather than a
+    # real case: above roughly 1e155 ``scipy.optimize.nnls`` rejects the input
+    # outright, so the failure is loud either way.
+    denominator = quad**2 + quad_var
+    weight = np.divide(
+        quad**2,
+        denominator,
+        out=np.zeros_like(denominator),
+        where=np.isfinite(denominator) & (denominator > 0.0),
+    )
+    qispec = cte2 - weight * (1.0 / 6.0) * bp**2 * quad
+
+    return qispec, slope, quad

specmod/acquire.py

@@ -0,0 +1,358 @@
+"""Fetch an event from an FDSN data centre into the layout tests and users read.
+
+The request is declared in TOML and the response is written as an
+:class:`specmod.datasets.EventDirectory`, beside a manifest recording what was
+asked for and what came back::
+
+    from specmod.acquire import fetch
+    fetch("datasets/pnr_2019.toml", out="build/pnr_2019")
+
+or ``specmod fetch datasets/pnr_2019.toml -o build/pnr_2019``.
+
+**Waveforms are stored raw.** Counts and the response, never a deconvolved
+trace: baking ``remove_response`` into the artefact takes it out of test
+coverage and freezes one ObsPy version's behaviour into the fixture.
+
+**A config makes the request reproducible, not the response.** FDSN is not
+content-addressed — responses are corrected retroactively, archives are
+backfilled, catalogue solutions revised. That is what :func:`verify` and the
+manifest are for, and why published artefacts are pinned by hash rather than
+re-fetched. See §5.2.2 of ``docs/REFACTOR_PLAN.md``.
+
+Every network call goes through the ``client`` argument, which defaults to an
+ObsPy FDSN client and is injected in tests. Nothing here calls the network on
+import.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import tomllib
+from dataclasses import dataclass, field, replace
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .datasets import Event, EventDirectory
+
+__all__ = [
+    "AcquisitionConfig",
+    "EventSpec",
+    "StationSpec",
+    "WindowSpec",
+    "fetch",
+    "read_config",
+    "verify",
+]
+
+
+@dataclass(frozen=True)
+class EventSpec:
+    """Which earthquake, and where its parameters come from.
+
+    ``eventid`` resolves the hypocentre from the data centre's catalogue, which
+    is preferable to retyping it: a retyped origin is a second source of truth
+    that can disagree with the catalogue silently. The explicit fields are for
+    events the catalogue does not carry — induced sequences monitored privately,
+    most often — and one of the two must be given.
+    """
+
+    eventid: str | None = None
+    #: FDSN service to resolve ``eventid`` against, when it is not the one
+    #: serving the waveforms. Event ids are issued per catalogue — a USGS
+    #: ComCat id means nothing to IRIS — so the two are genuinely separable
+    #: and the config has to be able to say so.
+    catalogue: str | None = None
+    origin: str | None = None
+    latitude: float | None = None
+    longitude: float | None = None
+    depth_km: float | None = None
+    catalogue_magnitude: float | None = None
+    catalogue_magnitude_type: str | None = None
+
+    def __post_init__(self) -> None:
+        explicit = (self.origin, self.latitude, self.longitude, self.depth_km)
+        if self.eventid is None and any(v is None for v in explicit):
+            raise ValueError(
+                "an event needs either `eventid`, to resolve from the "
+                "catalogue, or all of `origin`, `latitude`, `longitude` and "
+                "`depth_km`"
+            )
+
+    def resolved(self) -> Event:
+        """The :class:`~specmod.datasets.Event` these fields describe."""
+        if self.origin is None:
+            raise ValueError(
+                "this event is declared by eventid and has not been resolved "
+                "against a catalogue yet"
+            )
+        assert self.latitude is not None
+        assert self.longitude is not None
+        assert self.depth_km is not None
+        return Event(
+            origin=self.origin,
+            latitude=self.latitude,
+            longitude=self.longitude,
+            depth_km=self.depth_km,
+            catalogue_magnitude=self.catalogue_magnitude,
+            catalogue_magnitude_type=self.catalogue_magnitude_type,
+        )
+
+
+@dataclass(frozen=True)
+class StationSpec:
+    """Which channels to ask for.
+
+    The patterns are FDSN wildcards, so the config alone does not say what you
+    got — which is why the manifest records the channel list after expansion.
+    """
+
+    network: str = "*"
+    station: str = "*"
+    location: str = "*"
+    channel: str = "*"
+    #: Kilometres from the epicentre. ``None`` means no limit.
+    max_radius_km: float | None = None
+    min_radius_km: float | None = None
+
+
+@dataclass(frozen=True)
+class WindowSpec:
+    """How much record to take, relative to the origin time."""
+
+    before_origin_s: float = 10.0
+    after_origin_s: float = 120.0
+
+    def __post_init__(self) -> None:
+        if self.before_origin_s + self.after_origin_s <= 0:
+            raise ValueError("the window must have positive length")
+
+
+@dataclass(frozen=True)
+class AcquisitionConfig:
+    """A complete, declarative description of one fetch."""
+
+    name: str
+    #: FDSN data centre, by short name (``"IRIS"``) or base URL. Recorded in
+    #: the manifest because different centres serve different holdings for the
+    #: same event.
+    data_centre: str = "IRIS"
+    event: EventSpec = field(default_factory=EventSpec)
+    stations: StationSpec = field(default_factory=StationSpec)
+    window: WindowSpec = field(default_factory=WindowSpec)
+    #: The TOML this was parsed from, kept verbatim for the manifest.
+    source_toml: str = ""
+
+    @classmethod
+    def from_dict(
+        cls, data: dict[str, Any], *, source_toml: str = ""
+    ) -> AcquisitionConfig:
+        known = {"name", "data_centre", "event", "stations", "window"}
+        unknown = set(data) - known
+        if unknown:
+            raise ValueError(
+                f"unknown key(s) in acquisition config: {sorted(unknown)}. "
+                f"Known: {sorted(known)}"
+            )
+        if "name" not in data:
+            raise ValueError("an acquisition config needs a `name`")
+        return cls(
+            name=str(data["name"]),
+            data_centre=str(data.get("data_centre", "IRIS")),
+            event=EventSpec(**data.get("event", {})),
+            stations=StationSpec(**data.get("stations", {})),
+            window=WindowSpec(**data.get("window", {})),
+            source_toml=source_toml,
+        )
+
+
+def read_config(path: str | Path) -> AcquisitionConfig:
+    """Parse an acquisition config, keeping the text for the manifest."""
+    text = Path(path).read_text()
+    return AcquisitionConfig.from_dict(tomllib.loads(text), source_toml=text)
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for block in iter(lambda: handle.read(1 << 20), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def _default_client(data_centre: str) -> Any:
+    from obspy.clients.fdsn import Client  # noqa: PLC0415
+
+    return Client(data_centre)
+
+
+def _resolve_event(
+    config: AcquisitionConfig, client: Any, event_client: Any = None
+) -> tuple[EventSpec, Any]:
+    """Fill in the hypocentre from the catalogue when only an id was given.
+
+    Returns the resolved spec **and the catalogue it came from**, so the caller
+    can write the QuakeML rather than keeping only the handful of numbers this
+    reads off it.
+    """
+    if config.event.eventid is None:
+        return config.event, None
+
+    if event_client is None:
+        event_client = (
+            client
+            if config.event.catalogue in (None, config.data_centre)
+            else _default_client(config.event.catalogue)
+        )
+    catalogue = event_client.get_events(eventid=config.event.eventid)
+    if len(catalogue) != 1:
+        raise ValueError(
+            f"eventid {config.event.eventid!r} matched {len(catalogue)} events; "
+            f"it must identify exactly one"
+        )
+    origin = catalogue[0].preferred_origin() or catalogue[0].origins[0]
+    magnitude = catalogue[0].preferred_magnitude()
+    magnitudes = catalogue[0].magnitudes
+    if magnitude is None and magnitudes:
+        magnitude = magnitudes[0]
+
+    resolved = replace(
+        config.event,
+        origin=str(origin.time),
+        latitude=float(origin.latitude),
+        longitude=float(origin.longitude),
+        depth_km=float(origin.depth) / 1000.0,
+        catalogue_magnitude=None if magnitude is None else float(magnitude.mag),
+        catalogue_magnitude_type=(
+            None if magnitude is None else str(magnitude.magnitude_type)
+        ),
+    )
+    return resolved, catalogue
+
+
+def fetch(
+    config: str | Path | AcquisitionConfig,
+    out: str | Path,
+    *,
+    client: Any = None,
+    event_client: Any = None,
+) -> dict[str, Any]:
+    """Fetch one event and write it as an :class:`EventDirectory`.
+
+    Returns the manifest, which is also written to ``manifest.json`` beside the
+    data. ``client`` accepts anything with the ObsPy FDSN client's
+    ``get_events``, ``get_stations`` and ``get_waveforms`` methods; tests pass a
+    fake so that no test touches the network.
+    """
+    import obspy  # noqa: PLC0415
+
+    if not isinstance(config, AcquisitionConfig):
+        config = read_config(config)
+    if client is None:
+        client = _default_client(config.data_centre)
+
+    spec, catalogue = _resolve_event(config, client, event_client)
+    event = spec.resolved()
+    origin_time = obspy.UTCDateTime(event.origin)
+    start = origin_time - config.window.before_origin_s
+    end = origin_time + config.window.after_origin_s
+
+    station_kwargs: dict[str, Any] = {
+        "network": config.stations.network,
+        "station": config.stations.station,
+        "location": config.stations.location,
+        "channel": config.stations.channel,
+        "starttime": start,
+        "endtime": end,
+        "level": "response",
+    }
+    if config.stations.max_radius_km is not None:
+        station_kwargs["latitude"] = event.latitude
+        station_kwargs["longitude"] = event.longitude
+        station_kwargs["maxradius"] = config.stations.max_radius_km / 111.195
+        if config.stations.min_radius_km is not None:
+            station_kwargs["minradius"] = config.stations.min_radius_km / 111.195
+
+    inventory = client.get_stations(**station_kwargs)
+    stream = client.get_waveforms(
+        network=config.stations.network,
+        station=config.stations.station,
+        location=config.stations.location,
+        channel=config.stations.channel,
+        starttime=start,
+        endtime=end,
+    )
+
+    paths = EventDirectory(Path(out) / event.origin)
+    paths.waveforms.mkdir(parents=True, exist_ok=True)
+    paths.stations.mkdir(parents=True, exist_ok=True)
+    paths.picks.mkdir(parents=True, exist_ok=True)
+
+    written: dict[str, str] = {}
+    for trace in stream:
+        # One file per channel, named as the shipped data is, so a fetched
+        # event and a committed one are read by the same code.
+        name = f"{trace.id}_{trace.stats.starttime}"
+        target = paths.waveforms / name
+        trace.write(str(target), format="MSEED")
+        written[str(target.relative_to(Path(out)))] = _sha256(target)
+
+    inventory.write(str(paths.inventory), format="STATIONXML")
+    written[str(paths.inventory.relative_to(Path(out)))] = _sha256(paths.inventory)
+
+    # The catalogue in full, not just the six numbers read off it above.
+    # Origin uncertainties, every magnitude rather than the preferred one,
+    # agency and evaluation status are all in here and nowhere else.
+    if catalogue is not None:
+        catalogue.write(str(paths.quakeml), format="QUAKEML")
+        written[str(paths.quakeml.relative_to(Path(out)))] = _sha256(paths.quakeml)
+
+    manifest = {
+        "name": config.name,
+        "fetched_at": datetime.now(UTC).isoformat(),
+        "data_centre": config.data_centre,
+        "event_catalogue": config.event.catalogue or config.data_centre,
+        "specmod_version": __version__,
+        "obspy_version": obspy.__version__,
+        "config": config.source_toml,
+        "quakeml": catalogue is not None,
+        "resolved": {
+            "origin": event.origin,
+            "latitude": event.latitude,
+            "longitude": event.longitude,
+            "depth_km": event.depth_km,
+            "catalogue_magnitude": event.catalogue_magnitude,
+            "catalogue_magnitude_type": event.catalogue_magnitude_type,
+            "eventid": spec.eventid,
+            # After wildcard expansion: the config alone does not say what the
+            # request actually returned.
+            "channels": sorted({trace.id for trace in stream}),
+            "window": {"start": str(start), "end": str(end)},
+        },
+        "files": dict(sorted(written.items())),
+    }
+    (Path(out) / "manifest.json").write_text(json.dumps(manifest, indent=1) + "\n")
+    return manifest
+
+
+def verify(out: str | Path) -> list[str]:
+    """Re-hash what is on disk and report anything that no longer matches.
+
+    Integrity only: it says whether the files changed since they were written,
+    not whether the data centre has revised its holdings. That needs a re-fetch
+    and a diff against the manifest, which is the fuller ``--verify`` §5.2.2
+    describes and which needs the network.
+    """
+    root = Path(out)
+    manifest = json.loads((root / "manifest.json").read_text())
+
+    problems = []
+    for name, digest in manifest["files"].items():
+        path = root / name
+        if not path.is_file():
+            problems.append(f"missing: {name}")
+        elif _sha256(path) != digest:
+            problems.append(f"changed: {name}")
+    return problems