specmod 0.2.0__py3-none-any.whl

specmod/smoothing/konno_ohmachi.py

@@ -0,0 +1,83 @@
+"""Konno & Ohmachi (1998) smoothing.
+
+A constant-width window in log-frequency: narrow at low frequency, wide at
+high. That is what makes it the convention in engineering seismology — it
+avoids over-smoothing the low-frequency band that constrains the long-period
+level, while still suppressing scatter in the high-frequency tail.
+
+The window is ``[sin(b log10(f/fc)) / (b log10(f/fc))]^4``, with ``b`` the
+bandwidth. Smaller ``b`` smooths harder; 40 is the conventional value.
+
+ObsPy already implements this and is already a hard dependency, so this is a
+thin adapter rather than a reimplementation. It keeps the frequency axis
+unchanged, unlike :class:`~specmod.smoothing.log_bins.LogBinner`, which is
+often what you want before fitting on the original grid.
+
+References
+----------
+Konno, K. & Ohmachi, T. (1998). Ground-motion characteristics estimated from
+spectral ratio between horizontal and vertical components of microtremor.
+*BSSA* 88(1), 228-241.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+
+import numpy as np
+from obspy.signal.konnoohmachismoothing import konno_ohmachi_smoothing
+
+from ..core.spectrum import Spectrum
+from .base import record_smoothing
+
+__all__ = ["KonnoOhmachi"]
+
+
+@dataclass(frozen=True)
+class KonnoOhmachi:
+    """Konno-Ohmachi smoothing at fixed log-frequency bandwidth.
+
+    Parameters
+    ----------
+    bandwidth
+        The ``b`` coefficient. Smaller values smooth more aggressively.
+    count
+        Number of times to apply the window. More than one is occasionally
+        used for very noisy spectra.
+    normalize
+        Normalise each window to unit area. Without this the smoothed
+        amplitudes are biased low where the window is truncated at the edges of
+        the frequency axis.
+    """
+
+    bandwidth: float = 40.0
+    count: int = 1
+    normalize: bool = True
+    name: str = "konno_ohmachi"
+
+    def __post_init__(self) -> None:
+        if self.bandwidth <= 0:
+            raise ValueError(f"bandwidth must be positive, got {self.bandwidth}")
+        if self.count < 1:
+            raise ValueError(f"count must be at least 1, got {self.count}")
+
+    def smooth(self, spectrum: Spectrum) -> Spectrum:
+        # ObsPy needs float32 or float64 and rejects anything else outright.
+        smoothed = konno_ohmachi_smoothing(
+            np.asarray(spectrum.amp, dtype=np.float64),
+            np.asarray(spectrum.freq, dtype=np.float64),
+            bandwidth=self.bandwidth,
+            count=self.count,
+            normalize=self.normalize,
+        )
+        return replace(
+            spectrum,
+            amp=np.asarray(smoothed, dtype=np.float64),
+            meta=record_smoothing(
+                spectrum.meta,
+                self.name,
+                bandwidth=self.bandwidth,
+                count=self.count,
+                normalize=self.normalize,
+            ),
+        )

specmod/smoothing/log_bins.py

@@ -0,0 +1,171 @@
+"""Log-spaced frequency binning.
+
+Replaces ``Spectrum.__bin_spectrum``, which had four problems:
+
+1. Bin edges were hardcoded to 0.001-200 Hz regardless of the record. For a
+   100 Hz trace that puts a third of the bins above Nyquist and a third below
+   ``1/T``, where there is no data — so they came out empty.
+2. Empty bins produced ``nan`` and a ``RuntimeWarning`` per bin, then were
+   dropped. Dropping means the binned axis has a *different length* for
+   different traces, which the SNR code then compares element-wise.
+3. The bin count actually used came from a config dict the caller could not
+   override per-call.
+4. It ran unconditionally inside ``__init__``.
+
+Here the default edges are derived from the record — ``1/T`` to Nyquist, the
+band where data actually exists — and empty bins are handled explicitly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Literal
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ..core.spectrum import Spectrum
+from .base import record_smoothing
+
+__all__ = ["LogBinner"]
+
+Statistic = Literal["geometric", "mean", "median"]
+
+
+@dataclass(frozen=True)
+class LogBinner:
+    """Average a spectrum into log-spaced frequency bins.
+
+    Parameters
+    ----------
+    f_min, f_max
+        Bin edges in Hz. ``None`` derives them from the record: ``1/T`` for
+        ``f_min`` and Nyquist for ``f_max``. Deriving is the sensible default
+        because it is exactly the band the record can represent.
+    n_bins
+        Number of bins.
+    statistic
+        How to combine samples within a bin. ``geometric`` is the mean of
+        ``log10(amp)``, which is what the pre-refactor code computed and the
+        right choice for a quantity spanning orders of magnitude — an
+        arithmetic mean over a decade of amplitudes is dominated by its largest
+        member.
+    min_count
+        Minimum samples for a bin to be kept when ``drop_empty`` is set.
+    drop_empty
+        Drop bins holding fewer than ``min_count`` samples. Log bins over a
+        linearly-spaced frequency axis are inevitably sparse at the low end —
+        a bin is only reliably populated above roughly ``1 / (2.3 * dlog10f * T)``
+        — so dropping is usually what you want for plotting or fitting.
+
+        Set ``False`` to keep a **fixed-length** axis with ``nan`` in the empty
+        bins. Combined with explicit ``f_min``/``f_max`` that guarantees two
+        spectra bin onto identical axes, which is what an element-wise
+        signal-to-noise ratio requires.
+    """
+
+    f_min: float | None = None
+    f_max: float | None = None
+    n_bins: int = 151
+    statistic: Statistic = "geometric"
+    min_count: int = 1
+    drop_empty: bool = True
+    name: str = "log_bins"
+
+    def __post_init__(self) -> None:
+        if self.n_bins < 1:
+            raise ValueError(f"n_bins must be at least 1, got {self.n_bins}")
+        if self.min_count < 1:
+            raise ValueError(f"min_count must be at least 1, got {self.min_count}")
+        if self.f_min is not None and self.f_min <= 0:
+            raise ValueError(
+                f"f_min must be positive for log spacing, got {self.f_min}"
+            )
+        if (
+            self.f_min is not None
+            and self.f_max is not None
+            and self.f_min >= self.f_max
+        ):
+            raise ValueError(f"f_min ({self.f_min}) must be below f_max ({self.f_max})")
+
+    def edges_for(self, spectrum: Spectrum) -> NDArray[np.float64]:
+        """Bin edges for a given spectrum.
+
+        Explicit ``f_min``/``f_max`` are honoured **exactly** and never clamped
+        to the spectrum's own range. That matters more than it looks: signal and
+        noise windows have different durations, so clamping would bin them onto
+        different axes, and the SNR ratio compares them element-wise. Pinning
+        both edges is how a caller guarantees a shared axis.
+
+        Only derived bounds are clamped, since deriving already means "whatever
+        this record supports".
+        """
+        if self.f_min is not None:
+            lo = self.f_min
+        else:
+            lo = max(spectrum.frequency_resolution, float(spectrum.freq[0]))
+        if self.f_max is not None:
+            hi = self.f_max
+        else:
+            hi = min(spectrum.nyquist, float(spectrum.freq[-1]))
+        if lo >= hi:
+            raise ValueError(
+                f"Binning range [{lo:.4g}, {hi:.4g}] Hz is empty for a spectrum "
+                f"spanning [{spectrum.freq[0]:.4g}, {spectrum.freq[-1]:.4g}] Hz."
+            )
+        return np.logspace(np.log10(lo), np.log10(hi), self.n_bins + 1)
+
+    def smooth(self, spectrum: Spectrum) -> Spectrum:
+        edges = self.edges_for(spectrum)
+        # Bin centres are the geometric midpoints, matching the log spacing.
+        centres = np.sqrt(edges[:-1] * edges[1:])
+
+        idx = np.digitize(spectrum.freq, edges) - 1
+        valid = (idx >= 0) & (idx < self.n_bins)
+        if not valid.any():
+            raise ValueError(
+                f"Binning range [{edges[0]:.4g}, {edges[-1]:.4g}] Hz does not "
+                f"overlap the spectrum, which spans "
+                f"[{spectrum.freq[0]:.4g}, {spectrum.freq[-1]:.4g}] Hz."
+            )
+        idx, amp = idx[valid], spectrum.amp[valid]
+
+        counts = np.bincount(idx, minlength=self.n_bins)
+        values = np.full(self.n_bins, np.nan)
+
+        if self.statistic == "median":
+            for b in np.flatnonzero(counts):
+                values[b] = np.median(amp[idx == b])
+        else:
+            data = np.log10(amp) if self.statistic == "geometric" else amp
+            sums = np.bincount(idx, weights=data, minlength=self.n_bins)
+            with np.errstate(invalid="ignore", divide="ignore"):
+                means = sums / counts
+            values = 10**means if self.statistic == "geometric" else means
+
+        sparse = counts < self.min_count
+        values[sparse] = np.nan
+        if sparse.all():
+            raise ValueError(
+                f"No bin reached min_count={self.min_count}. The spectrum has "
+                f"{len(spectrum)} samples across {self.n_bins} bins spanning "
+                f"[{edges[0]:.4g}, {edges[-1]:.4g}] Hz; use fewer bins, a lower "
+                f"min_count, or a narrower range."
+            )
+        keep = ~sparse if self.drop_empty else np.ones(self.n_bins, dtype=bool)
+
+        return replace(
+            spectrum,
+            freq=centres[keep],
+            amp=values[keep],
+            meta=record_smoothing(
+                spectrum.meta,
+                self.name,
+                n_bins=self.n_bins,
+                statistic=self.statistic,
+                f_min=float(edges[0]),
+                f_max=float(edges[-1]),
+                counts=counts[keep].tolist(),
+                drop_empty=self.drop_empty,
+            ),
+        )

specmod/sources/__init__.py

@@ -0,0 +1,65 @@
+"""Source, attenuation and motion models, and the registry that names them.
+
+The spectrum being fitted is a product of three things, so this package keeps
+them separate and composes them:
+
+.. code-block:: text
+
+    log10 A(f) = log10 S(f)  +  log10 D(f)  +  log10 G(f)
+                 source         attenuation    motion
+
+Splitting them matters because they are chosen independently and confused
+easily. A Brune source with frequency-dependent attenuation is a legitimate
+combination; so is a Boatwright source with constant ``t*``. The legacy code
+bound the pair together at import time through ``MODEL = which_model(...)``,
+which is why a Brune and a Boatwright could not be fitted in one session.
+
+What a source model has to carry
+--------------------------------
+Not just a spectral shape. **The relation between corner frequency and source
+radius belongs to the model**, and forgetting that is a specific trap:
+
+Madariaga is omega-squared like Brune and sits at the *same* ``(gamma, n)``, so
+adding it as a shape alone changes no fitted parameter — the fit is identical
+— while the source radius it implies is quite different. Stress drop goes as
+``r**-3``, so that is roughly an order of magnitude on identical data, arriving
+silently. :attr:`SourceModel.corner_frequency_coefficient` exists so the
+difference cannot be lost that way, and so that a model which changes nothing
+about the fit still changes what is derived from it.
+"""
+
+from __future__ import annotations
+
+from .attenuation import (
+    ATTENUATION_MODELS,
+    AttenuationModel,
+    ConstantQ,
+    FrequencyDependentQ,
+    get_attenuation_model,
+)
+from .composite import SpectralModel, build_model, from_config
+from .motion import motion_scaling
+from .source import (
+    SOURCE_MODELS,
+    BoatwrightSource,
+    BruneSource,
+    SourceModel,
+    get_source_model,
+)
+
+__all__ = [
+    "ATTENUATION_MODELS",
+    "SOURCE_MODELS",
+    "AttenuationModel",
+    "BoatwrightSource",
+    "BruneSource",
+    "ConstantQ",
+    "FrequencyDependentQ",
+    "SourceModel",
+    "SpectralModel",
+    "build_model",
+    "from_config",
+    "get_attenuation_model",
+    "get_source_model",
+    "motion_scaling",
+]

specmod/sources/attenuation.py

@@ -0,0 +1,110 @@
+"""Path attenuation, parameterised by ``t*``."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+import numpy as np
+from numpy.typing import NDArray
+
+__all__ = [
+    "ATTENUATION_MODELS",
+    "AttenuationModel",
+    "ConstantQ",
+    "FrequencyDependentQ",
+    "get_attenuation_model",
+]
+
+
+@runtime_checkable
+class AttenuationModel(Protocol):
+    """Anything that attenuates a source spectrum along the path."""
+
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def parameters(self) -> tuple[str, ...]:
+        """Free parameter names, in the order the fitter should take them."""
+        ...
+
+    def log10_decay(
+        self, freq: NDArray[np.float64], *values: float
+    ) -> NDArray[np.float64]:
+        """``log10 D(f)``, given this model's parameters in order."""
+        ...
+
+
+@dataclass(frozen=True)
+class ConstantQ:
+    """Frequency-independent ``t*``.
+
+    .. math:: \\log_{10} D(f) = -\\pi f t^{*} / \\ln 10
+
+    The ``ln 10`` is the conversion into base-10 logs, which is the space the
+    fit is performed in. Getting it wrong scales ``t*`` by 2.3 and leaves the
+    spectrum looking plausible.
+    """
+
+    @property
+    def name(self) -> str:
+        return "constant_q"
+
+    @property
+    def parameters(self) -> tuple[str, ...]:
+        return ("ts",)
+
+    def log10_decay(
+        self, freq: NDArray[np.float64], *values: float
+    ) -> NDArray[np.float64]:
+        (ts,) = values
+        return np.asarray(
+            -(np.pi * np.asarray(freq, dtype=np.float64) * ts / np.log(10))
+        )
+
+
+@dataclass(frozen=True)
+class FrequencyDependentQ:
+    """``t*`` with a power-law frequency dependence.
+
+    .. math:: \\log_{10} D(f) = -\\pi f^{1-a} t^{*} / \\ln 10
+
+    ``a = 0`` recovers :class:`ConstantQ`. The two are separate models rather
+    than one with a switch because they have different free parameters, and a
+    fitter needs to know that before it starts.
+    """
+
+    @property
+    def name(self) -> str:
+        return "frequency_dependent_q"
+
+    @property
+    def parameters(self) -> tuple[str, ...]:
+        return ("ts", "a")
+
+    def log10_decay(
+        self, freq: NDArray[np.float64], *values: float
+    ) -> NDArray[np.float64]:
+        ts, a = values
+        f = np.asarray(freq, dtype=np.float64)
+        return np.asarray(-(np.pi * f ** (1.0 - a) * ts / np.log(10)))
+
+
+#: Registered attenuation models.
+ATTENUATION_MODELS: dict[str, type[ConstantQ] | type[FrequencyDependentQ]] = {
+    "constant_q": ConstantQ,
+    "frequency_dependent_q": FrequencyDependentQ,
+}
+
+
+def get_attenuation_model(name: str) -> AttenuationModel:
+    """Resolve a registered attenuation model by name."""
+    try:
+        cls = ATTENUATION_MODELS[name]
+    except KeyError:
+        raise ValueError(
+            f"Unknown attenuation model {name!r}. "
+            f"Available: {sorted(ATTENUATION_MODELS)}."
+        ) from None
+    return cls()

specmod/sources/composite.py

@@ -0,0 +1,135 @@
+"""Composing source, attenuation and motion into something a fitter can call."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ..core.units import Motion
+from .attenuation import AttenuationModel, get_attenuation_model
+from .motion import motion_scaling
+from .source import SourceModel, get_source_model
+
+__all__ = ["SpectralModel", "build_model", "from_config"]
+
+
+@dataclass(frozen=True)
+class SpectralModel:
+    """A source, an attenuation law and a motion, evaluated together.
+
+    .. math::
+
+        \\log_{10} A(f) = \\log_{10} S(f) + \\log_{10} D(f) + \\log_{10} G(f)
+
+    Immutable and self-describing: it knows its own parameter names, so a
+    fitter does not have to be told them separately and cannot be told them
+    wrongly. That is what the legacy could not do — ``FitSpectra.set_model``
+    took a bare function, and the parameter names came from introspecting its
+    signature, so the model and its parameters could disagree.
+    """
+
+    source: SourceModel
+    attenuation: AttenuationModel
+    motion: Motion
+
+    @property
+    def parameters(self) -> tuple[str, ...]:
+        """Free parameters, in the order :meth:`evaluate` takes them."""
+        return ("llpsp", "fc", *self.attenuation.parameters)
+
+    def evaluate(
+        self, freq: NDArray[np.float64], *values: float
+    ) -> NDArray[np.float64]:
+        """``log10 A(f)`` for the given parameter values, in order."""
+        expected = len(self.parameters)
+        if len(values) != expected:
+            raise TypeError(
+                f"{self.describe()} takes {expected} parameters "
+                f"{self.parameters}, got {len(values)}"
+            )
+        log10_omega, f_c, *decay = values
+        return np.asarray(
+            self.source.log10_shape(freq, log10_omega, f_c)
+            + self.attenuation.log10_decay(freq, *decay)
+            + motion_scaling(freq, self.motion)
+        )
+
+    def describe(self) -> str:
+        """One line naming every choice this model makes."""
+        return (
+            f"{self.source.name}+{self.attenuation.name} in {Motion(self.motion).value}"
+        )
+
+    def as_callable(self) -> Callable[..., NDArray[np.float64]]:
+        """A plain function of ``(f, llpsp, fc, ...)``, for ``lmfit.Model``.
+
+        ``lmfit`` discovers parameter names with :func:`inspect.signature`
+        (checked, rather than assumed — it does not read ``co_varnames``), so
+        attaching a ``__signature__`` is enough and no code has to be
+        generated. A wrapper taking ``*args`` would give the fit a single
+        positional parameter and nothing to vary.
+        """
+
+        names = self.parameters
+
+        def evaluate(
+            f: NDArray[np.float64], *args: float, **kwargs: float
+        ) -> NDArray[np.float64]:
+            # lmfit reads the names off `__signature__` but calls with
+            # keywords, so both forms have to work — and the keyword form has
+            # to be put back into the declared order, not the caller's.
+            values = args if args else tuple(kwargs[name] for name in names)
+            return self.evaluate(f, *values)
+
+        evaluate.__signature__ = inspect.Signature(  # type: ignore[attr-defined]
+            [inspect.Parameter("f", inspect.Parameter.POSITIONAL_OR_KEYWORD)]
+            + [
+                inspect.Parameter(name, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+                for name in self.parameters
+            ]
+        )
+        evaluate.__name__ = self.describe()
+        return evaluate
+
+
+def from_config() -> SpectralModel:
+    """The model the current configuration asks for.
+
+    One call, so that ``[model] source = "boatwright"`` in a study file is what
+    decides the shape being fitted — which it was not before.
+    """
+    from ..config import load_config  # noqa: PLC0415 - avoids a config->sources cycle
+
+    model = load_config().config.model
+    return build_model(
+        source=model.source,
+        motion=model.motion,
+        frequency_dependent_attenuation=model.frequency_dependent_attenuation,
+    )
+
+
+def build_model(
+    *,
+    source: str = "brune",
+    motion: Motion | str = Motion.VELOCITY,
+    frequency_dependent_attenuation: bool = False,
+) -> SpectralModel:
+    """Assemble a :class:`SpectralModel` from configuration names.
+
+    This is the join that did not exist. ``ModelConfig.source`` was a
+    ``Literal["brune", "boatwright"]`` that nothing read: ``FitSpectra`` took
+    the model *function* as an argument, so the caller supplied Brune or
+    Boatwright by hand and the configured value was decorative. Anything
+    reading configuration now comes through here.
+    """
+    return SpectralModel(
+        source=get_source_model(source),
+        attenuation=get_attenuation_model(
+            "frequency_dependent_q" if frequency_dependent_attenuation else "constant_q"
+        ),
+        motion=Motion(motion),
+    )

specmod/sources/motion.py

@@ -0,0 +1,40 @@
+"""Converting a displacement source spectrum to the recorded motion."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ..core.units import Motion
+
+__all__ = ["motion_scaling"]
+
+#: Differentiation in the frequency domain multiplies by ``2 pi f`` per order.
+_ORDERS: dict[Motion, int] = {
+    Motion.DISPLACEMENT: 0,
+    Motion.VELOCITY: 1,
+    Motion.ACCELERATION: 2,
+}
+
+
+def motion_scaling(
+    freq: NDArray[np.float64], motion: Motion | str
+) -> NDArray[np.float64]:
+    """``log10 G(f)``: the factor taking displacement to ``motion``.
+
+    Source models are written for displacement, because that is where
+    ``Omega`` and hence ``M0`` are defined. Records are usually velocity. Each
+    order of differentiation multiplies by ``2 pi f``, so in log space it is
+    that many copies of ``log10(2 pi f)``.
+
+    The order comes from :class:`specmod.core.units.Motion` rather than a
+    string comparison, so an unrecognised motion fails at the enum instead of
+    silently returning zero — which would fit a displacement model to velocity
+    data and put ``Omega`` out by a factor of ``2 pi f``.
+    """
+    order = _ORDERS[Motion(motion)]
+    if order == 0:
+        return np.zeros_like(np.asarray(freq, dtype=np.float64))
+    return np.asarray(
+        order * np.log10(2.0 * np.pi * np.asarray(freq, dtype=np.float64))
+    )