specmod 0.2.0__py3-none-any.whl

specmod/fitting/event.py

@@ -0,0 +1,284 @@
+"""Fitting every passing station in an event, and the table that comes out."""
+
+from __future__ import annotations
+
+import logging
+import warnings
+from typing import TYPE_CHECKING, Any
+
+import matplotlib.pyplot as plt
+import pandas as pd
+
+from .. import config as cfg
+from ..tables import read_table, write_table
+from .base import SpectraLike, plot_columns
+from .guess import fittable_signal, initial_guess
+from .spectrum import FitSpectrum
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Mapping
+    from pathlib import Path
+
+__all__ = ["FitSpectra"]
+
+
+#: Per-station progress goes here rather than to stdout. A library must not
+#: configure logging for its host, so there is no `basicConfig` anywhere in
+#: this package: a caller that wants to see these calls `logging.basicConfig`
+#: itself, and one that does not is not written to by surprise.
+logger = logging.getLogger(__name__)
+
+
+class FitSpectra:
+    """Fit every passing station in an event."""
+
+    #: Declarations, as on :class:`FitSpectrum`. `models = {}` at class level
+    #: was one dictionary shared by every `FitSpectra` ever built; `__init__`
+    #: rebinds it, so nothing reached the shared copy, but nothing prevented it
+    #: either. `guess = {}` was never assigned anywhere at all — a class
+    #: attribute recording a constructor argument that is not kept.
+    spectra: SpectraLike
+    models: dict[str, FitSpectrum]
+    table: pd.DataFrame
+
+    def __init__(
+        self,
+        spectra: SpectraLike,
+        model: Any = None,
+        guess: Mapping[str, Mapping[str, float]] | None = None,
+        fit_bins: bool | None = None,
+    ) -> None:
+        """``guess=None`` derives one, rather than fitting nothing.
+
+        It used to skip `init_fitting` entirely, so `FitSpectra(spectra)` built
+        an object with no models and `fit_spectra()` silently did nothing and
+        produced an empty table. There is a sensible guess available — see
+        :func:`initial_guess` — so that is now the default and an explicit
+        ``guess={}`` is how you say "none".
+        """
+        self.models = {}
+        self.table = pd.DataFrame([])
+        self.set_spectra(spectra)
+        if fit_bins is None:
+            fit_bins = cfg.load_config().config.fitting.fit_bins
+        if guess is None:
+            guess = initial_guess(spectra, model)
+        self.init_fitting(model, guess, fit_bins)
+
+    def __len__(self) -> int:
+        return len(self.models)
+
+    def set_spectra(self, spectra: SpectraLike) -> None:
+        if self.__check_spectra(spectra):
+            self.spectra = spectra
+
+    def get_spectra(self) -> SpectraLike:
+        return self.spectra
+
+    def get_fit(self, id: str) -> FitSpectrum | None:
+        if id.upper() in self.models:
+            return self.models[id.upper()]
+        warnings.warn(
+            f"{id.upper()} is not among the fitted stations "
+            f"({', '.join(sorted(self.models)) or 'none'}); returning None.",
+            stacklevel=2,
+        )
+        return None
+
+    def fit_spectra(self, weight_method: str | None = None, **kwargs: Any) -> None:
+        """Fit every station, with the configured minimiser unless told otherwise.
+
+        ``method`` and ``weight_method`` both come from ``[fitting]`` when not
+        given. Neither used to: `fit_spectra()` fell through to lmfit's default
+        minimiser, so a study file saying ``method = "powell"`` was ignored and
+        the caller had to remember ``fit_spectra(method="powell")`` — which the
+        tutorial does and nothing enforced.
+
+        It matters. On the 28 PNR windows lmfit's default returns a **negative
+        corner frequency** on one station where Powell does not; a corner
+        frequency below zero is not a degraded measurement but a meaningless
+        one, and nothing downstream rejects it.
+        """
+        fitting = cfg.load_config().config.fitting
+        if weight_method is None:
+            weight_method = fitting.weight_method
+        kwargs.setdefault("method", fitting.method)
+        wm = self.__check_wm(weight_method)
+        for name, mod in self.models.items():
+            try:
+                if wm == "log":
+                    mod.fit_mod(weights=1 / mod.mod_freq, **kwargs)
+                else:
+                    mod.fit_mod(**kwargs)
+            except ValueError as error:
+                # `logging`, not `warnings`, and the difference matters here:
+                # warnings are deduplicated per code location by default, so a
+                # run that skipped twenty stations would report one. Each skip
+                # is a station missing from the results and has to be visible.
+                logger.warning("skipping %s: %s", name, error)
+
+        self.__set_fit_models_to_spectrum()
+        self.__generate_group_fit_table()
+
+    def init_fitting(
+        self,
+        model: Any,
+        guess: Mapping[str, Mapping[str, float]],
+        fit_bins: bool,
+    ) -> None:
+        """Build a fit per passing station.
+
+        ``model=None`` resolves through the configuration once per station,
+        which is cheap and keeps every fit in a run agreeing on what it is
+        fitting.
+        """
+        # Iterate the container rather than reaching into `.group`. `Spectra`
+        # and `core.SpectrumSet` both present this interface, which is what
+        # lets the container be swapped underneath without touching the fitter.
+        # A station is fitted when it passed the gate *and* has a guess.
+        # Indexing `guess[id]` unconditionally made a partial guess dict a
+        # `KeyError` naming a station, rather than a way to fit a subset —
+        # and made `guess={}` a crash instead of "fit nothing".
+        tmp: dict[str, FitSpectrum] = {}
+        for id in self.spectra:
+            signal = fittable_signal(self.spectra[id], id)
+            if signal is None or id not in guess:
+                continue
+            tmp[id] = FitSpectrum(signal, model, **guess[id], fit_bins=fit_bins)
+        self.models = tmp
+
+    def set_const(self, pname: str, value: float, id: str | None = None) -> None:
+        if id is None:
+            for mod in self.models.values():
+                mod.set_const(pname, value)
+        elif id in self.models:
+            self.models[id].set_const(pname, value)
+
+    def set_bounds(
+        self, pname: str, min: float | None = None, max: float | None = None
+    ) -> None:
+        for mod in self.models.values():
+            mod.set_bounds(pname, min, max)
+
+    def reset(self, name: str = "all") -> None:
+        """Unbind every parameter, on one station or all of them.
+
+        The lookup tested ``name.upper()`` for membership and then indexed with
+        ``name``, so any id not already upper-case passed the check and raised
+        ``KeyError`` on the next line. Station ids are upper-case in practice,
+        which is why it never fired.
+        """
+        if name.upper() == "ALL":
+            for mod in self.models.values():
+                mod.reset()
+            return
+
+        id = name.upper()
+        if id in self.models:
+            self.models[id].reset()
+        else:
+            warnings.warn(
+                f"{id} is not among the fitted stations; nothing was reset.",
+                stacklevel=2,
+            )
+
+    def quick_vis(self, save: str | None = None) -> None:
+        rows = self.__num_rows()
+        fig, axes = plt.subplots(rows, plot_columns(), figsize=(17, int(rows * 5)))
+        # `strict=False`: the grid is rounded up to whole rows, so there are
+        # more axes than models by construction.
+        for ax, mod in zip(axes.flatten(), self.models.values(), strict=False):
+            if mod.result is None or not mod.pass_fitting:
+                ax.set_title(f"Fitting Failed for {mod.sig.id}")
+            else:
+                mod.quick_vis(ax)
+
+        if save is not None:
+            if type(save) is str:
+                fig.savefig(save)
+            else:
+                raise ValueError("Must provide valid path as str.")
+
+    @staticmethod
+    def write_flatfile(path: str | Path, fits: FitSpectra) -> Path:
+        """Write the group fit table, in the format ``path``'s suffix names.
+
+        ``.parquet`` is typed, compressed and queryable without loading;
+        ``.csv`` is what journal supplements want. See :mod:`specmod.tables`.
+
+        The previous implementation was ``os.makedirs(os.path.join(
+        *path.split("/")[:-1]))``, which raised ``TypeError: join() missing 1
+        required positional argument`` for any path without a directory
+        component — ``write_flatfile("out.csv", fits)`` could not work. It also
+        split on ``/`` literally, so it did nothing useful on Windows.
+        """
+        return write_table(path, fits.table)
+
+    @staticmethod
+    def read_flatfile(path: str | Path) -> pd.DataFrame:
+        """Read a fit table back. Format follows the suffix."""
+        return read_table(path)
+
+    def __check_wm(self, wm: str) -> str:
+        if wm not in ["log", "none"]:
+            warnings.warn(
+                f"Unknown weight method {wm!r}; expected 'log' or 'none'. "
+                "Falling back to 'none'.",
+                stacklevel=3,
+            )
+            wm = "none"
+        return wm
+
+    def __generate_group_fit_table(self) -> None:
+        ds = [m.meta for m in self.models.values()]
+        df1 = pd.DataFrame([])
+        for i, d in enumerate(ds):
+            df1 = pd.concat(
+                [df1, pd.DataFrame(d, index=[i])], ignore_index=True, sort=False
+            )
+        self.table = df1
+
+    def __set_fit_models_to_spectrum(self) -> None:
+        """Hand each fit back to the spectrum it came from, where that is possible.
+
+        The legacy `Signal` carries its own fit so that plotting and
+        serialisation can reach it from the spectrum. `core.SpectrumPair` is
+        frozen and cannot, by design — a result writing itself back into its
+        own input is how a container stops being trustworthy.
+
+        Nothing is lost by skipping it: `self.models` is the source of truth
+        either way, and the write-back was only ever a convenience. So this
+        writes where the container accepts it and moves on where it does not,
+        rather than requiring every container to be mutable.
+        """
+        for id, mod in self.models.items():
+            spectrum = self.spectra[id]
+            signal = getattr(spectrum, "signal", spectrum)
+            setter = getattr(signal, "set_model", None)
+            if setter is not None:
+                setter(mod)
+
+    def __check_spectra(self, spectra: SpectraLike) -> bool:
+        """Accept anything that maps trace ids to paired spectra.
+
+        Was ``isinstance(spectra, spectral.Spectra)``, which is why the fitter
+        could not be handed a :class:`~specmod.core.SpectrumSet` even though it
+        only ever iterates and indexes. Requiring one concrete class was the
+        last thing tying the fitter to the legacy module.
+        """
+        required = ("__iter__", "__getitem__", "__len__")
+        missing = [name for name in required if not hasattr(spectra, name)]
+        if missing:
+            raise ValueError(
+                f"{type(spectra).__name__} cannot be fitted: it must map trace "
+                f"ids to paired spectra, and is missing {', '.join(missing)}. "
+                f"Use specmod.pipeline.spectrum_set_from_streams."
+            )
+        return True
+
+    def __num_rows(self) -> int:
+        count = len(self)
+        cols = plot_columns()
+        if count % cols > 0:
+            return int((cols * (int(count / cols) + 1)) / cols)
+        return int(count / cols)

specmod/fitting/guess.py

@@ -0,0 +1,170 @@
+"""Choosing what to fit, and where the fit starts from."""
+
+from __future__ import annotations
+
+import inspect
+import warnings
+from typing import Any
+
+import numpy as np
+
+from .. import config as cfg
+from .. import sources
+from ..core.units import Motion
+from .base import SpectraLike, Spectrumish
+
+__all__ = ["fittable_signal", "initial_guess", "selected_band"]
+
+
+def fittable_signal(pair: Any, id: str = "") -> Spectrumish | None:
+    """The signal to fit from a paired spectrum, or ``None`` to skip it.
+
+    Skipping is a decision the container should not have to spell out at every
+    call site: a pair is unfittable when the signal-to-noise gate rejected it.
+
+    What comes back for a :class:`~specmod.core.SpectrumPair` is its
+    :class:`~specmod.core.collection.FittableView`, not its ``signal``. The
+    pair keeps the unbinned and binned spectra as separate objects, which is
+    right for the comparison and wrong for a fitter that wants ``freq``,
+    ``amp``, ``bfreq`` and ``bamp`` side by side; the view is what puts them
+    there. ``id`` names the station on it, since a frozen pair does not carry
+    one of its own.
+
+    The ``getattr`` fallback below is what a spectrum-like object that is not
+    a pair takes — a bare view, or anything else presenting the same
+    attributes. It is not a legacy shim; it is what lets the fitter be given
+    something constructed by hand.
+    """
+    view = getattr(pair, "for_fitting", None)
+    if view is not None:
+        return pair.for_fitting(id) if pair.passes else None
+
+    signal = getattr(pair, "signal", pair)
+    passes = getattr(pair, "passes", None)
+    if passes is None:
+        passes = getattr(signal, "pass_snr", True)
+    return signal if passes else None
+
+
+def _warn_if_peak_is_meaningless(signal: Spectrumish, id: str) -> None:
+    """Warn when the peak-as-``fc`` guess is being read off the wrong domain.
+
+    A no-op for velocity, and for a spectrum that does not say what motion it
+    carries — something assembled by hand is the caller's business.
+    """
+    motion = getattr(signal, "motion", None)
+    if motion is None or Motion(motion) is Motion.VELOCITY:
+        return
+    warnings.warn(
+        f"{id or 'this spectrum'} is in {Motion(motion).value}, and the "
+        f"initial guess for fc is the frequency of the spectral peak — which "
+        f"is the corner only in velocity. A {Motion(motion).value} spectrum "
+        f"falls monotonically across the band, so the guess will be a band "
+        f"edge and the fit will settle near it. Fit the velocity spectrum; "
+        f"`llpsp` is the displacement plateau either way.",
+        stacklevel=3,
+    )
+
+
+def initial_guess(
+    spectra: SpectraLike, model: Any = None
+) -> dict[str, dict[str, float]]:
+    """Starting parameters for every fittable spectrum in ``spectra``.
+
+    Replaces ``model_guess.create_simple_guess`` and its ``_fdep`` twin, which
+    were two near-identical functions differing only in whether they added an
+    ``a`` for frequency-dependent Q — so adding a third model meant writing a
+    third guess function, and picking the wrong one gave lmfit a parameter the
+    model did not take.
+
+    **Which parameters are needed is asked of the model, not assumed.** The
+    fitted callable declares them in its signature, so a model gets exactly the
+    guesses it takes and nothing else. Values that cannot be read off the
+    spectrum come from ``[fitting]`` in the configuration.
+
+    The two that *are* read off the spectrum:
+
+    ``llpsp``
+        ``log10`` of the largest amplitude inside the selected band — the
+        long-period plateau, which is what ``Omega`` is.
+    ``fc``
+        the frequency at which that maximum falls.
+
+    Both assume a **velocity** spectrum, which is where a fit belongs anyway:
+    the model carries a motion factor, so ``llpsp`` is the displacement plateau
+    whichever domain is fitted, but converting first is not a neutral change of
+    view — integrating implicitly low-passes and differentiating amplifies
+    high-frequency noise, so the record to fit is the one the sensor recorded.
+
+    In velocity the peak is not merely near the corner, it *is* the corner, for
+    any omega-squared source: the stationary point of
+    ``f * [1 + (f/fc)**(gamma*n)]**(-1/gamma)`` sits at ``f = fc`` whenever
+    ``n == 2``, whatever the corner sharpness. In displacement and acceleration
+    the spectrum is monotonic across the band, so the peak is whichever band
+    edge it was handed and the guess is meaningless. Handed one of those, this
+    warns rather than proceeding quietly.
+
+    Stations with no band are omitted rather than given ``None`` guesses. The
+    old version emitted ``{"llpsp": None, "fc": None, "ts": None}`` on
+    ``IndexError``, which lmfit cannot use — the failure simply moved to the
+    fit call.
+    """
+    if model is None:
+        model = sources.from_config()
+    callable_ = (
+        model.as_callable() if isinstance(model, sources.SpectralModel) else model
+    )
+    wanted = set(inspect.signature(callable_).parameters) - {"f"}
+
+    fitting = cfg.load_config().config.fitting
+    #: Parameters no spectrum can suggest a value for.
+    defaults = {
+        "ts": fitting.initial_t_star,
+        "a": fitting.initial_alpha,
+    }
+
+    guesses: dict[str, dict[str, float]] = {}
+    for id in spectra:
+        signal = fittable_signal(spectra[id], id)
+        if signal is None:
+            continue
+        band = selected_band(signal)
+        if band is None:
+            continue
+        inside = (signal.freq >= band[0]) & (signal.freq <= band[1])
+        if not inside.any():
+            continue
+
+        _warn_if_peak_is_meaningless(signal, id)
+
+        amp, freq = signal.amp[inside], signal.freq[inside]
+        peak = int(amp.argmax())
+        available = {
+            "llpsp": float(np.log10(amp[peak])),
+            "fc": float(freq[peak]),
+            **defaults,
+        }
+        missing = wanted - set(available)
+        if missing:
+            raise ValueError(
+                f"no initial guess is defined for {sorted(missing)}, which "
+                f"{getattr(model, 'describe', lambda: callable_.__name__)()} "
+                f"takes. Add it to specmod.config.FittingConfig and to "
+                f"`initial_guess`, or pass explicit guesses."
+            )
+        guesses[id] = {k: v for k, v in available.items() if k in wanted}
+
+    return guesses
+
+
+def selected_band(spectrum: Any) -> tuple[float, float] | None:
+    """The band to fit over, or ``None`` to fit everything available.
+
+    ``None`` rather than an empty array, because "no band survived" and "a band
+    from 0 to 0" are different claims and the legacy spelling — an empty
+    ``ubfreqs`` — could be read as either.
+    """
+    band = getattr(spectrum, "band", None)
+    if band is None:
+        return None
+    return (float(band[0]), float(band[1]))