specmod 0.2.0__py3-none-any.whl

specmod/datasets.py

@@ -0,0 +1,316 @@
+"""Where an event's data lives on disk, and the events shipped with the repo.
+
+The layout follows ObsPy's ``mass_downloader``, which writes ``waveforms/``
+and ``stations/`` beneath a per-event directory. This adds the three things a
+spectral workflow needs alongside them::
+
+    tutorial/data/events/<origin>/
+        event.xml                  # QuakeML: origin, magnitudes, uncertainties
+        waveforms/                 # one miniSEED file per channel
+        stations/inventory.xml     # StationXML for those channels
+        picks/*.xml                # QuakeML picks (*.picks: Snuffler markers)
+        spectra/*.h5               # computed spectra
+        spectra/flatfiles/*.csv    # and their tabular export
+
+:class:`EventDirectory` resolves those paths and :class:`Event` carries the
+hypocentre needed to set source-station geometry. Tests, ``tools/`` and the
+documentation notebooks all read the layout from here.
+
+Datasets that ship with the repository have their own loader —
+:func:`load_pnr_2019` — and need no network. Published ones are fetched by
+:func:`load`, cached by pooch and pinned by hash. :mod:`specmod.acquire`
+produces both.
+"""
+
+from __future__ import annotations
+
+import glob
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+__all__ = [
+    "EVENTS",
+    "PNR_2019",
+    "REGISTRY",
+    "Dataset",
+    "DatasetSpec",
+    "Event",
+    "EventDirectory",
+    "data_dir",
+    "load",
+    "load_pnr_2019",
+]
+
+#: Event directories, relative to the repository root.
+EVENTS = Path("tutorial") / "data" / "events"
+
+
+@dataclass(frozen=True)
+class EventDirectory:
+    """The paths beneath one event directory.
+
+    Reads nothing on construction, so it is safe to build at import time.
+    """
+
+    root: Path
+
+    @property
+    def waveforms(self) -> Path:
+        return self.root / "waveforms"
+
+    @property
+    def stations(self) -> Path:
+        return self.root / "stations"
+
+    @property
+    def inventory(self) -> Path:
+        """The StationXML covering the channels in :attr:`waveforms`."""
+        return self.stations / "inventory.xml"
+
+    @property
+    def picks(self) -> Path:
+        return self.root / "picks"
+
+    @property
+    def spectra(self) -> Path:
+        return self.root / "spectra"
+
+    @property
+    def flatfiles(self) -> Path:
+        return self.spectra / "flatfiles"
+
+    def waveform_glob(self, pattern: str = "*") -> str:
+        """A glob over :attr:`waveforms`, as a string for ``obspy.read``."""
+        return str(self.waveforms / pattern)
+
+    @property
+    def quakeml(self) -> Path:
+        """The event's QuakeML: origin, magnitudes and their uncertainties."""
+        return self.root / "event.xml"
+
+    def picks_file(self) -> Path:
+        """The pick file for this event, QuakeML for preference.
+
+        QuakeML is the standard and carries what a marker file cannot —
+        polarity, uncertainty, evaluation status, the full SEED id. Snuffler
+        markers are still read where that is all there is.
+
+        Raises :class:`FileNotFoundError` when neither is present.
+        """
+        for pattern in ("*.xml", "*.picks"):
+            found = sorted(glob.glob(str(self.picks / pattern)))
+            if found:
+                return Path(found[0])
+        raise FileNotFoundError(f"no *.xml or *.picks file under {self.picks}")
+
+    def is_present(self) -> bool:
+        """Whether the waveforms and station metadata are both present.
+
+        Does not check ``spectra/``, which is generated rather than shipped.
+        """
+        return self.waveforms.is_dir() and self.inventory.is_file()
+
+
+@dataclass(frozen=True)
+class Event:
+    """An earthquake: where its data sits, and the hypocentre it happened at.
+
+    ``origin``, ``latitude``, ``longitude`` and ``depth_km`` are the four
+    values :func:`specmod.preprocess.set_stream_distance` takes.
+    """
+
+    origin: str
+    latitude: float
+    longitude: float
+    depth_km: float
+    #: The published magnitude and the scale it is on, e.g. ``2.9`` and
+    #: ``"Mw"``. Kept as a pair: ML and Mw diverge below about magnitude 3, so
+    #: a bare number cannot be compared against a computed one.
+    catalogue_magnitude: float | None = None
+    catalogue_magnitude_type: str | None = None
+
+    def directory(self, project_root: Path | str) -> EventDirectory:
+        """Locate this event beneath ``project_root``, the repository root."""
+        return EventDirectory(Path(project_root) / EVENTS / self.origin)
+
+
+#: Preston New Road, 26 August 2019 — the induced event the tutorial and both
+#: golden references are built around, and the largest of the PNR-2 sequence.
+#: The origin time doubles as the directory name.
+#:
+#: ``Mw 2.9`` is from the PNR-2 catalogue published with Cuadrilla's
+#: hydraulic-fracture monitoring (NGDC, `709cbc2f-af5c-4d09-a4ea-6deb5aa8c5d8
+#: <https://www2.bgs.ac.uk/nationalgeosciencedatacentre/citedData/catalogue/709cbc2f-af5c-4d09-a4ea-6deb5aa8c5d8.html>`_),
+#: which gives ``surface_ML``, ``surface_Mw`` and ``corrected_Mw`` all as 2.9.
+#:
+#: The hypocentre is the catalogue's, converted from its British National Grid
+#: easting/northing (336135.0, 432515.0; EPSG:27700) to WGS84. The catalogue
+#: gives depth as an elevation of -2040 m.
+PNR_2019 = Event(
+    origin="2019-08-26T07:30:47.000000Z",
+    latitude=53.785021,
+    longitude=-2.970780,
+    depth_km=2.04,
+    catalogue_magnitude=2.9,
+    catalogue_magnitude_type="Mw",
+)
+
+
+# --------------------------------------------------------------- consuming
+#
+# Published datasets, fetched once and cached. `specmod.acquire` produces
+# these; this half consumes them, and is offline after the first download.
+
+
+@dataclass(frozen=True)
+class DatasetSpec:
+    """A published dataset: where to get it, and what it should hash to.
+
+    The hash is what makes a regression test mean anything. A config records
+    intent and makes a dataset regenerable, but FDSN is not content-addressed,
+    so re-running the config is not guaranteed to return the same bytes — see
+    §5.2.2 of ``docs/REFACTOR_PLAN.md``.
+
+    Versioning is by name. ``magna_2020_v1`` and ``magna_2020_v2`` are separate
+    entries, so a result pinned to v1 keeps fetching v1 after v2 exists.
+    """
+
+    name: str
+    url: str
+    #: ``sha256:...`` of the archive, as pooch expects it.
+    sha256: str
+    event: Event
+    #: Path within the unpacked archive holding the event directory.
+    member: str = ""
+
+
+#: Published datasets by name. Local datasets are not listed: they ship with
+#: the package and need no download.
+REGISTRY: dict[str, DatasetSpec] = {}
+
+
+def data_dir() -> Path:
+    """Where downloaded datasets are cached.
+
+    ``SPECMOD_DATA_DIR`` overrides the platform cache directory, which matters
+    on a cluster where ``$HOME`` is small or not writable from a compute node.
+    """
+    override = os.environ.get("SPECMOD_DATA_DIR")
+    if override:
+        return Path(override)
+
+    import pooch  # noqa: PLC0415
+
+    return Path(pooch.os_cache("specmod"))
+
+
+@dataclass(frozen=True)
+class Dataset:
+    """One event's data, wherever it came from.
+
+    The readers are methods rather than eager attributes because a dataset is
+    often opened for its metadata alone, and reading a stream costs real time.
+    """
+
+    event: Event
+    paths: EventDirectory
+    #: The acquisition manifest, where the dataset was produced by
+    #: :mod:`specmod.acquire`. ``None`` for data that ships with the package.
+    manifest: dict[str, Any] | None = None
+
+    def stream(self, pattern: str = "*") -> Any:
+        """Read the waveforms. Raw counts — the response is not removed."""
+        import obspy  # noqa: PLC0415
+
+        return obspy.read(self.paths.waveform_glob(pattern))
+
+    def inventory(self) -> Any:
+        """Read the station metadata, including responses."""
+        import obspy  # noqa: PLC0415
+
+        return obspy.read_inventory(str(self.paths.inventory))
+
+    def catalog(self) -> Any:
+        """Read the event's QuakeML.
+
+        Everything the catalogue said, rather than the four numbers
+        :class:`Event` keeps: origin uncertainties, every magnitude rather than
+        the preferred one, agency and evaluation status.
+        """
+        import obspy  # noqa: PLC0415
+
+        if not self.paths.quakeml.is_file():
+            raise FileNotFoundError(
+                f"no QuakeML at {self.paths.quakeml}. It is written by "
+                f"specmod.acquire when an event is resolved from a catalogue; "
+                f"an event declared explicitly in a config has none."
+            )
+        return obspy.read_events(str(self.paths.quakeml))
+
+
+def _repository_root() -> Path:
+    """The checkout this package was imported from, if it is one.
+
+    Data that ships with the repository is not inside the installed package, so
+    it is only reachable from a source checkout or an editable install.
+    """
+    return Path(__file__).resolve().parent.parent.parent
+
+
+def load_pnr_2019() -> Dataset:
+    """The Preston New Road event committed to this repository.
+
+    Needs no download and no network: the waveforms and inventory are in the
+    checkout. Raises when they are not, rather than reaching for a URL, since
+    there is no published artefact for this one.
+    """
+    paths = PNR_2019.directory(_repository_root())
+    if not paths.is_present():
+        raise FileNotFoundError(
+            f"the PNR data is not at {paths.root}. It ships with the "
+            f"repository rather than being downloaded, so this needs a source "
+            f"checkout or an editable install."
+        )
+    return Dataset(event=PNR_2019, paths=paths)
+
+
+def load(name: str, *, downloader: Any = None) -> Dataset:
+    """Fetch a published dataset by name, from the cache after the first call.
+
+    Downloads are hash-checked by pooch: a corrupted or substituted archive
+    fails here rather than quietly becoming a new expected answer.
+
+    ``downloader`` is passed through to :func:`pooch.retrieve`. It exists so
+    the caching, hash check and unpacking can be exercised without a network —
+    pooch has no ``file://`` support — and so an operator behind an
+    authenticating proxy can supply their own.
+    """
+    try:
+        spec = REGISTRY[name]
+    except KeyError:
+        known = sorted(REGISTRY) or ["<none published yet>"]
+        raise ValueError(
+            f"Unknown dataset {name!r}. Published: {known}. Data that ships "
+            f"with the repository has its own loader, e.g. load_pnr_2019()."
+        ) from None
+
+    import pooch  # noqa: PLC0415
+
+    unpacked = pooch.retrieve(
+        url=spec.url,
+        known_hash=spec.sha256,
+        path=data_dir(),
+        processor=pooch.Untar(),
+        downloader=downloader,
+    )
+    root = Path(os.path.commonpath(unpacked)) if unpacked else data_dir()
+    paths = EventDirectory(root / spec.member if spec.member else root)
+
+    manifest_file = paths.root.parent / "manifest.json"
+    manifest = (
+        json.loads(manifest_file.read_text()) if manifest_file.is_file() else None
+    )
+    return Dataset(event=spec.event, paths=paths, manifest=manifest)

specmod/distance.py

@@ -0,0 +1,190 @@
+"""Source-to-site distance, as a registry rather than a stat name.
+
+Which distance you mean is a modelling choice, and at short range it is not a
+small one. On the PNR data the nearest station is **1.02 km epicentral against
+2.30 km hypocentral** — a factor of 2.24 — while the farthest agree to 1.004.
+Anything weighted by inverse distance, or corrected for geometric spreading,
+therefore depends on the choice most strongly at exactly the station that
+matters most.
+
+Two are implemented here because they are the two a point source supports.
+Both read a value :func:`specmod.preprocess.set_stream_distance` has already
+computed:
+
+``repi``
+    Epicentral. Horizontal distance from the epicentre.
+``rhyp``
+    Hypocentral. Slant distance from the hypocentre.
+
+**Epicentral is the honest choice when sensor depths are unknown**, and that
+is more often than it sounds. ``rhyp`` is built from the source depth and the
+station *elevation*, which silently assumes every sensor sits at the surface.
+For a borehole deployment that is wrong by the burial depth, and nothing in
+the metadata announces it — the PNR inventory records channel ``depth`` as
+``123456.0``, a placeholder, so on that dataset ``rhyp`` is an assumption
+wearing a measurement's name.
+
+Finite-fault measures
+---------------------
+``Rrup`` (closest distance to the rupture surface) and ``Rjb`` (Joyner-Boore,
+closest horizontal distance to the surface projection of the rupture) are the
+measures ground-motion work generally wants, and they are **not implemented**
+— deliberately, rather than by omission.
+
+Both need a rupture *surface*: strike, dip, length, width and a hypocentre
+position on it. SpecMod carries a point source, so there is nothing to compute
+them from, and a version that quietly degenerated to ``rhyp`` and ``repi``
+would be worse than an error — those are exactly what `Rrup` and `Rjb` reduce
+to for a point source, so the substitution would be invisible in the output
+and wrong for any event large enough to warrant asking.
+
+They are registered all the same, raising with what they would need. A name
+that resolves to a clear failure is a better extension point than a name that
+does not resolve at all, and it puts the requirement where someone adding
+finite-fault support will read it.
+
+The registry is the same shape as :data:`specmod.transforms.ESTIMATORS`,
+:data:`specmod.core.noise.NOISE_MODELS` and
+:data:`specmod.staged.WEIGHT_MODELS`, so a study names a distance the way it
+names anything else and the choice travels with the resolved configuration.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+import numpy as np
+
+from .config import load_config
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Sequence
+
+    from numpy.typing import NDArray
+
+__all__ = [
+    "DISTANCE_MEASURES",
+    "DistanceMeasure",
+    "Epicentral",
+    "FiniteFaultDistance",
+    "Hypocentral",
+    "get_distance_measure",
+    "resolve_distance_measure",
+]
+
+
+@runtime_checkable
+class DistanceMeasure(Protocol):
+    """One distance per channel, in kilometres."""
+
+    name: str
+
+    def distances(
+        self, spectra: Any, ids: Sequence[str]
+    ) -> NDArray[np.float64]: ...  # pragma: no cover
+
+
+@dataclass(frozen=True, slots=True)
+class _FromMeta:
+    """A distance already computed onto the trace metadata."""
+
+    key: str
+    name: str
+
+    def distances(self, spectra: Any, ids: Sequence[str]) -> NDArray[np.float64]:
+        out = np.empty(len(ids), dtype=np.float64)
+        for i, id in enumerate(ids):
+            meta = spectra[id].signal.meta
+            if self.key not in meta:
+                raise ValueError(
+                    f"{id} carries no {self.key!r}, so its {self.name} distance "
+                    f"is unknown. Set the geometry with "
+                    f"specmod.preprocess.set_stream_distance."
+                )
+            value = float(meta[self.key])
+            if value <= 0:
+                raise ValueError(
+                    f"{id} has {self.key}={value}, which is not a distance"
+                )
+            out[i] = value
+        return out
+
+
+@dataclass(frozen=True, slots=True)
+class Epicentral(_FromMeta):
+    key: str = "repi"
+    name: str = "epicentral"
+
+
+@dataclass(frozen=True, slots=True)
+class Hypocentral(_FromMeta):
+    key: str = "rhyp"
+    name: str = "hypocentral"
+
+
+@dataclass(frozen=True, slots=True)
+class FiniteFaultDistance:
+    """``Rrup`` and ``Rjb``: registered, and not implemented.
+
+    Raising here rather than omitting the name is the point. For a point source
+    these degenerate exactly to hypocentral and epicentral, so an
+    implementation that silently fell back would produce plausible numbers that
+    are wrong for any event big enough to justify asking for them.
+    """
+
+    name: str
+    needs: str
+
+    def distances(self, spectra: Any, ids: Sequence[str]) -> NDArray[np.float64]:
+        raise NotImplementedError(
+            f"{self.name} is not implemented. It needs {self.needs}, and "
+            f"SpecMod carries a point source — there is no rupture surface to "
+            f"measure from. For a point source {self.name} degenerates to "
+            f"{'hypocentral' if self.name == 'rrup' else 'epicentral'}; name "
+            f"that instead if it is what you mean, rather than getting it by "
+            f"accident."
+        )
+
+
+#: Registered distance measures, resolved by name from configuration.
+DISTANCE_MEASURES: dict[str, Any] = {
+    "repi": Epicentral,
+    "rhyp": Hypocentral,
+    "rrup": lambda: FiniteFaultDistance(
+        name="rrup", needs="a rupture surface — strike, dip, length and width"
+    ),
+    "rjb": lambda: FiniteFaultDistance(
+        name="rjb",
+        needs="the surface projection of a rupture — strike, dip, length and width",
+    ),
+}
+
+
+def get_distance_measure(name: str) -> DistanceMeasure:
+    """Resolve a registered measure by name."""
+    try:
+        factory = DISTANCE_MEASURES[name]
+    except KeyError:
+        raise ValueError(
+            f"Unknown distance measure {name!r}. "
+            f"Available: {sorted(DISTANCE_MEASURES)}."
+        ) from None
+    measure: DistanceMeasure = factory()
+    return measure
+
+
+def resolve_distance_measure(
+    measure: str | DistanceMeasure | None = None,
+) -> DistanceMeasure:
+    """A measure from a name, an instance, or the configuration.
+
+    ``None`` takes ``[geometry] distance_measure``, which is the project-wide
+    choice. It lived in ``[windows]`` and had no reader at all until this
+    module; cutting a window does not depend on how distance is measured.
+    """
+    if measure is None:
+        measure = str(load_config().config.geometry.distance_measure)
+    if isinstance(measure, str):
+        return get_distance_measure(measure)
+    return measure

specmod/exceptions.py

@@ -0,0 +1,58 @@
+"""The exception hierarchy :mod:`specmod.api` raises.
+
+Three kinds, because a caller does three different things with them:
+
+- :class:`InvalidInputError` — the caller's data or arguments are wrong. A
+  program shows a form error; a person fixes the input.
+- :class:`MissingBackendError` — the code is fine and the environment is not:
+  an optional extra is not installed. Fixed by installing something, and
+  avoidable up front with :func:`specmod.api.available_estimators`.
+- :class:`InternalError` — an invariant inside SpecMod is broken. Nothing the
+  caller can do; it is a bug report.
+
+Each also inherits the builtin exception the corresponding internal code
+raises today, so ``except ValueError`` keeps working and internals can migrate
+one at a time without a flag day.
+
+**Internals still raise the builtins.** :mod:`specmod.api` translates at its
+own boundary, so the guarantee is specific: functions reached *through
+`specmod.api`* raise this hierarchy. Reaching around it gets the builtins.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "InternalError",
+    "InvalidInputError",
+    "MissingBackendError",
+    "SpecModError",
+]
+
+
+class SpecModError(Exception):
+    """Base class for every error SpecMod raises deliberately."""
+
+
+class InvalidInputError(SpecModError, ValueError):
+    """The data or arguments given to SpecMod are not usable.
+
+    A record containing NaN, a frequency axis that does not belong to its
+    record, an unknown estimator name, a band with no samples in it.
+    """
+
+
+class MissingBackendError(SpecModError, ImportError):
+    """An optional backend is not installed.
+
+    Raised at call time rather than import time, so a default install stays
+    importable. :func:`specmod.api.available_estimators` answers the same
+    question without provoking the error.
+    """
+
+
+class InternalError(SpecModError, RuntimeError):
+    """An invariant inside SpecMod does not hold.
+
+    Not caused by the caller and not fixable by them. If one of these reaches
+    you, it is a bug in SpecMod.
+    """

specmod/fitting/__init__.py

@@ -0,0 +1,58 @@
+"""Fitting a source model to one spectrum, and to a whole event.
+
+:func:`fittable_signal` decides what to fit, :func:`initial_guess` where to
+start, :class:`FitSpectrum` fits one station and :class:`FitSpectra` an event.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+from .base import (
+    REQUIRED_SPECTRUM_ATTRIBUTES,
+    SpectraLike,
+    Spectrumish,
+    plot_columns,
+)
+from .event import FitSpectra
+from .guess import fittable_signal, initial_guess, selected_band
+from .spectrum import FitSpectrum
+
+__all__ = [
+    "PLOT_COLUMNS",
+    "REQUIRED_SPECTRUM_ATTRIBUTES",
+    "FitSpectra",
+    "FitSpectrum",
+    "SpectraLike",
+    "Spectrumish",
+    "fittable_signal",
+    "initial_guess",
+    "plot_columns",
+    "selected_band",
+]
+
+
+def __getattr__(name: str) -> object:
+    """Keep ``PLOT_COLUMNS`` importable, resolved at each access.
+
+    It was a module-level constant evaluated at import time, which froze the
+    configuration of whatever directory the process started in. Reading it now
+    resolves configuration per access, so the value is at least correct — but
+    a name that looks like a constant and performs a lookup is a poor bargain
+    either way, hence the warning and :func:`plot_columns`.
+
+    Deliberately *not* ``from .base import ...``: a from-import would run this
+    once at import time and rebind the result, which is the frozen behaviour
+    this replaced, reintroduced one level up.
+    """
+    if name == "PLOT_COLUMNS":
+        warnings.warn(
+            "specmod.fitting.PLOT_COLUMNS is deprecated and will be removed "
+            "in 0.4.0; call specmod.fitting.plot_columns() instead, which "
+            "resolves the current configuration rather than the one that "
+            "happened to be in effect at import.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return plot_columns()
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

specmod/fitting/base.py

@@ -0,0 +1,50 @@
+"""What the fitting layer expects of whatever it is handed.
+
+Structural rather than nominal: :class:`~specmod.fitting.FitSpectrum` reads
+attributes off its input and does not care what class provides them, which is
+what lets it take a :class:`~specmod.core.collection.FittableView`, a bare
+spectrum, or something assembled by hand in a notebook.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .. import config as cfg
+
+__all__ = [
+    "REQUIRED_SPECTRUM_ATTRIBUTES",
+    "SpectraLike",
+    "Spectrumish",
+    "plot_columns",
+]
+
+#: What a spectrum-like object handed to :class:`FitSpectrum` looks like.
+#: Structural rather than nominal on purpose — see :meth:`FitSpectrum.__check_input`.
+Spectrumish = Any
+#: A container mapping trace ids to paired spectra; see
+#: :meth:`FitSpectra.__check_spectra`.
+SpectraLike = Any
+
+
+def plot_columns() -> int:
+    """How many columns a multi-panel figure uses, from ``[viz]``.
+
+    A function rather than a constant, and that is the whole point. This was
+    ``PLOT_COLUMNS = cfg.load_config().config.viz.plot_columns`` evaluated at
+    import time, so importing :mod:`specmod.fitting` resolved configuration
+    against whatever directory the process happened to start in and froze the
+    answer for the life of the interpreter. Measured: importing from a project
+    whose ``specmod.toml`` says 5, then moving to one that resolves to 3, left
+    the constant at 5 — a worker serving two projects would use the first
+    one's layout for both.
+
+    One home for the setting either way: it used to be defined in *both* the
+    SPECTRAL and FITTING dicts, and the two copies could disagree.
+    """
+    return int(cfg.load_config().config.viz.plot_columns)
+
+
+#: What :class:`FitSpectrum` reads off whatever it is given. Kept as data so
+#: the requirement is stated once and can be asserted against.
+REQUIRED_SPECTRUM_ATTRIBUTES = ("id", "meta", "freq", "amp", "bfreq", "bamp")