specmod 0.2.0__py3-none-any.whl

specmod/picks/base.py

@@ -0,0 +1,250 @@
+"""Record types and the reader contract.
+
+A :class:`Pick` names an arrival on a :class:`SensorID`, which may be partial —
+``None`` for a field the source did not state. :class:`PickSet` groups the picks
+of one event; :class:`Resolution` is what :func:`specmod.picks.resolve` returns.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal, Protocol, runtime_checkable
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Iterable, Sequence
+    from os import PathLike
+
+    from obspy import UTCDateTime
+
+__all__ = [
+    "EMPTY_LOCATION",
+    "AmbiguousPolicy",
+    "DuplicatePolicy",
+    "Pick",
+    "PickReader",
+    "PickSet",
+    "Resolution",
+    "SensorID",
+]
+
+#: How an unset location code is spelled in a sensor key. Snuffler marker files
+#: use it, and it keeps the key's field count fixed.
+EMPTY_LOCATION = "--"
+
+DuplicatePolicy = Literal["prefer_reviewed", "earliest", "highest_weight", "error"]
+AmbiguousPolicy = Literal["error", "broadcast", "skip"]
+
+
+@dataclass(frozen=True, order=True)
+class SensorID:
+    """A sensor identity, possibly partial.
+
+    ``None`` means the source did not state the field, and matches anything.
+    ``""`` means stated and empty, and matches only an empty field.
+
+    Readers apply that distinction asymmetrically: an empty network code is not
+    a valid SEED network and becomes ``None``, while an empty location code is
+    the ordinary single-sensor case and is kept as ``""``.
+    """
+
+    network: str | None
+    station: str
+    location: str | None
+
+    @classmethod
+    def parse(cls, text: str) -> SensorID:
+        """Build from ``NET.STA.LOC``, reading ``--`` as an empty location."""
+        parts = text.split(".")
+        if len(parts) != 3:
+            raise ValueError(
+                f"sensor id {text!r} is not NET.STA.LOC (got {len(parts)} fields)"
+            )
+        network, station, location = parts
+        return cls(
+            network=network or None,
+            station=station,
+            location="" if location == EMPTY_LOCATION else location,
+        )
+
+    def __str__(self) -> str:
+        network = self.network if self.network is not None else "*"
+        location = "*" if self.location is None else self.location or EMPTY_LOCATION
+        return f"{network}.{self.station}.{location}"
+
+    @property
+    def is_complete(self) -> bool:
+        """Whether every field is stated, so this names exactly one sensor."""
+        return self.network is not None and self.location is not None
+
+    def matches(self, other: SensorID) -> bool:
+        """Whether this identity is consistent with ``other``.
+
+        Every field this one specifies must agree. Fields left ``None`` do not
+        constrain the match, so a partial identity can match several sensors —
+        which is a condition :func:`resolve` reports rather than resolves.
+        """
+        return all(
+            mine is None or theirs is None or mine == theirs
+            for mine, theirs in (
+                (self.station, other.station),
+                (self.network, other.network),
+                (self.location, other.location),
+            )
+        )
+
+
+@dataclass(frozen=True)
+class Pick:
+    """One phase arrival, with whatever provenance its format carried.
+
+    Only ``sensor``, ``phase`` and ``time`` are always present. The rest is
+    absent wherever the source format has no field for it, and is what a
+    :class:`DuplicatePolicy` uses to choose between competing picks.
+    """
+
+    sensor: SensorID
+    phase: str
+    time: UTCDateTime
+    raw_phase: str | None = None
+    uncertainty: float | None = None
+    polarity: str | None = None
+    weight: float | None = None
+    automatic: bool | None = None
+    reviewed: bool | None = None
+    channel: str | None = None
+    author: str | None = None
+
+
+@dataclass(frozen=True)
+class PickSet:
+    """The picks of a single event."""
+
+    picks: tuple[Pick, ...] = ()
+    event_id: str | None = None
+    origin: UTCDateTime | None = None
+
+    def __len__(self) -> int:
+        return len(self.picks)
+
+    def __iter__(self) -> Any:
+        return iter(self.picks)
+
+    def sensors(self) -> tuple[SensorID, ...]:
+        """The distinct sensor identities picked, in sorted order."""
+        return tuple(sorted({pick.sensor for pick in self.picks}))
+
+    def mapping(
+        self, *, duplicates: DuplicatePolicy = "prefer_reviewed"
+    ) -> dict[str, dict[str, UTCDateTime]]:
+        """The picks as ``{"NET.STA.LOC": {"P": UTCDateTime}}``.
+
+        Keyed on each pick's own identity, so an unstated field appears as
+        ``*`` and matches no trace. Use :func:`resolve` to match against a
+        stream.
+        """
+        out: dict[str, dict[str, UTCDateTime]] = {}
+        for (sensor, phase), picks in _grouped(self.picks).items():
+            chosen = _choose(picks, duplicates, sensor, phase)
+            out.setdefault(str(sensor), {})[phase] = chosen.time
+        return out
+
+
+@dataclass(frozen=True)
+class Resolution:
+    """The outcome of matching a :class:`PickSet` against a set of sensors."""
+
+    #: Attached picks, keyed by the *sensor's* complete id, then by phase.
+    attached: dict[str, dict[str, Pick]] = field(default_factory=dict)
+    #: Picks that matched no sensor.
+    unused: tuple[Pick, ...] = ()
+    #: Picks skipped because they matched several sensors.
+    ambiguous: tuple[Pick, ...] = ()
+    #: ``(sensor, phase)`` where a policy chose between competing picks.
+    duplicated: tuple[tuple[str, str], ...] = ()
+
+    @property
+    def n_attached(self) -> int:
+        return sum(len(phases) for phases in self.attached.values())
+
+    def summary(self) -> str:
+        """One line, suitable for printing or asserting on."""
+        return (
+            f"{self.n_attached} attached to {len(self.attached)} sensors, "
+            f"{len(self.unused)} unused, {len(self.ambiguous)} ambiguous, "
+            f"{len(self.duplicated)} resolved by policy"
+        )
+
+
+def _grouped(picks: Iterable[Pick]) -> dict[tuple[SensorID, str], list[Pick]]:
+    grouped: dict[tuple[SensorID, str], list[Pick]] = {}
+    for pick in picks:
+        grouped.setdefault((pick.sensor, pick.phase), []).append(pick)
+    return grouped
+
+
+def _choose(
+    picks: Sequence[Pick], policy: DuplicatePolicy, sensor: Any, phase: str
+) -> Pick:
+    """Reduce competing picks for one sensor and phase to one."""
+    if len(picks) == 1:
+        return picks[0]
+
+    if policy == "error":
+        times = ", ".join(str(pick.time) for pick in picks)
+        raise ValueError(
+            f"{sensor} has {len(picks)} {phase} picks ({times}) and "
+            f"duplicates='error'. Choose a policy, or drop the extras."
+        )
+    if policy == "earliest":
+        return min(picks, key=lambda pick: pick.time)
+    if policy == "highest_weight":
+        # An absent weight loses to any stated one, and ties break on time so
+        # the choice does not depend on file order.
+        return max(
+            picks,
+            key=lambda pick: (
+                pick.weight if pick.weight is not None else float("-inf"),
+                -float(pick.time.timestamp),
+            ),
+        )
+    # prefer_reviewed: an analyst's pick beats an automatic one, then earliest.
+    return min(
+        picks,
+        key=lambda pick: (
+            0 if pick.reviewed else 1,
+            0 if pick.automatic is False else 1,
+            pick.time,
+        ),
+    )
+
+
+@runtime_checkable
+class PickReader(Protocol):
+    """One pick format.
+
+    ``suffixes`` is a hint for error messages and nothing else: a suffix does
+    not identify a format, so :func:`specmod.picks.detect_reader` selects on
+    :meth:`can_read` alone.
+
+    ``name`` and ``suffixes`` are read-only properties so that a frozen
+    dataclass satisfies the protocol; mutable attributes would not.
+    """
+
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def suffixes(self) -> tuple[str, ...]: ...
+
+    def can_read(self, source: str | PathLike[str]) -> bool:
+        """Whether this reader recognises ``source``.
+
+        Must not raise — on a missing, empty, truncated or binary file, and on
+        every other format's files, it returns ``False``. Must be cheap: read a
+        header, not the whole file.
+        """
+        ...
+
+    def read(self, source: str | PathLike[str]) -> list[PickSet]:
+        """Every event in ``source``, in file order."""
+        ...

specmod/picks/delimited.py

@@ -0,0 +1,224 @@
+"""Delimited pick tables: one row per arrival, columns named by the caller.
+
+:class:`DelimitedPickReader` is the general case, configured with a delimiter
+and a column mapping. :class:`CSVPickReader`, :class:`TSVPickReader` and
+:class:`WhitespacePickReader` are it with the delimiter and the plausible file
+suffixes already set.
+
+No vendor presets ship. PhaseNet, EQTransformer and SeisBench each write
+several column layouts across versions, and a preset written from
+documentation rather than from a real output file is a guess with a name on it.
+Supply the mapping yourself — see ``docs/pick-formats.md``.
+"""
+
+from __future__ import annotations
+
+import csv as _csv
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import obspy
+
+from .base import Pick, PickSet, SensorID
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Mapping
+    from os import PathLike
+
+__all__ = [
+    "CSVPickReader",
+    "DelimitedPickReader",
+    "TSVPickReader",
+    "WhitespacePickReader",
+]
+
+#: Fields a mapping may name. ``station``, ``phase`` and ``time`` are required;
+#: the rest populate the matching :class:`~specmod.picks.Pick` attributes.
+FIELDS = (
+    "station",
+    "phase",
+    "time",
+    "network",
+    "location",
+    "channel",
+    "weight",
+    "uncertainty",
+    "polarity",
+    "author",
+)
+REQUIRED = ("station", "phase", "time")
+
+
+@dataclass(frozen=True)
+class DelimitedPickReader:
+    """A delimited table of picks, one row per arrival.
+
+    ``columns`` maps this reader's field names to the column headings in the
+    file: ``{"station": "sta", "phase": "phase_type", "time": "arrival_time"}``.
+    ``station``, ``phase`` and ``time`` are required; :data:`FIELDS` lists what
+    else may be mapped.
+
+    ``delimiter`` is a single character, or ``None`` to split on runs of
+    whitespace — the latter takes a separate parse path, since quoting has no
+    meaning in a whitespace-aligned table.
+
+    ``reader_name`` is what :func:`specmod.picks.read` refers to it by and must
+    be unique once registered. ``file_suffixes`` is a hint for error messages
+    and nothing else; detection is by header, so a reader claims a file only
+    when every mapped column is present. Two readers configured for different
+    schemas therefore do not collide, and one whose columns are a subset of
+    another's collides visibly — the ambiguity
+    :func:`specmod.picks.detect_reader` reports.
+    """
+
+    columns: Mapping[str, str]
+    reader_name: str = "delimited"
+    delimiter: str | None = ","
+    file_suffixes: tuple[str, ...] = (".csv", ".tsv", ".txt", ".dat")
+    #: Rows whose phase does not fold to P or S are skipped rather than raising.
+    skip_unknown_phases: bool = True
+
+    def __post_init__(self) -> None:
+        unknown = sorted(set(self.columns) - set(FIELDS))
+        if unknown:
+            raise ValueError(
+                f"unknown pick fields {unknown}. Available: {list(FIELDS)}."
+            )
+        missing = [name for name in REQUIRED if name not in self.columns]
+        if missing:
+            raise ValueError(f"columns must map {missing}; got {sorted(self.columns)}.")
+        if self.delimiter is not None and len(self.delimiter) != 1:
+            raise ValueError(
+                f"delimiter must be one character or None for whitespace; "
+                f"got {self.delimiter!r}."
+            )
+
+    @property
+    def name(self) -> str:
+        return self.reader_name
+
+    @property
+    def suffixes(self) -> tuple[str, ...]:
+        return self.file_suffixes
+
+    def _rows(self, source: str | PathLike[str]) -> list[list[str]] | None:
+        """Every line as a list of cells, or ``None`` if this is not a table."""
+        try:
+            with open(source, newline="") as handle:
+                text = handle.read()
+        except (OSError, UnicodeDecodeError):
+            return None
+
+        if self.delimiter is None:
+            return [line.split() for line in text.splitlines() if line.strip()]
+        try:
+            return [
+                [cell.strip() for cell in row]
+                for row in _csv.reader(text.splitlines(), delimiter=self.delimiter)
+                if row
+            ]
+        except _csv.Error:
+            return None
+
+    def can_read(self, source: str | PathLike[str]) -> bool:
+        rows = self._rows(source)
+        if not rows:
+            return False
+        return set(self.columns.values()) <= set(rows[0])
+
+    def read(self, source: str | PathLike[str]) -> list[PickSet]:
+        rows = self._rows(source)
+        if not rows:
+            return [PickSet()]
+
+        headings, body = rows[0], rows[1:]
+        picks = []
+        for cells in body:
+            row = dict(zip(headings, cells, strict=False))
+            pick = self._pick(row)
+            if pick is not None:
+                picks.append(pick)
+        return [PickSet(picks=tuple(picks))]
+
+    def _value(self, row: Mapping[str, str], field_name: str) -> str | None:
+        heading = self.columns.get(field_name)
+        if heading is None:
+            return None
+        value = (row.get(heading) or "").strip()
+        return value or None
+
+    def _pick(self, row: Mapping[str, str]) -> Pick | None:
+        raw_phase = self._value(row, "phase")
+        phase = (raw_phase or "")[:1].upper()
+        if phase not in ("P", "S"):
+            if self.skip_unknown_phases:
+                return None
+            raise ValueError(f"phase {raw_phase!r} is neither P nor S")
+
+        station = self._value(row, "station")
+        time = self._value(row, "time")
+        if station is None or time is None:
+            return None
+
+        location = self._value(row, "location")
+        return Pick(
+            sensor=SensorID(
+                network=self._value(row, "network"),
+                station=station,
+                # A column that is present but blank states an empty location;
+                # a column that is absent states nothing.
+                location=(location or "") if "location" in self.columns else None,
+            ),
+            phase=phase,
+            time=obspy.UTCDateTime(time),
+            raw_phase=raw_phase,
+            channel=self._value(row, "channel"),
+            weight=_as_float(self._value(row, "weight")),
+            uncertainty=_as_float(self._value(row, "uncertainty")),
+            polarity=self._value(row, "polarity"),
+            author=self._value(row, "author"),
+        )
+
+
+@dataclass(frozen=True)
+class CSVPickReader(DelimitedPickReader):
+    """Comma-separated, with the quoting rules of :mod:`csv`."""
+
+    reader_name: str = "csv"
+    delimiter: str | None = ","
+    file_suffixes: tuple[str, ...] = (".csv",)
+
+
+@dataclass(frozen=True)
+class TSVPickReader(DelimitedPickReader):
+    """Tab-separated."""
+
+    reader_name: str = "tsv"
+    delimiter: str | None = "\t"
+    file_suffixes: tuple[str, ...] = (".tsv", ".tab")
+
+
+@dataclass(frozen=True)
+class WhitespacePickReader(DelimitedPickReader):
+    """Columns separated by runs of spaces or tabs.
+
+    The shape most hand-written and Fortran-era arrival tables come in. Cells
+    cannot contain spaces, and quoting is not honoured.
+
+    This **subsumes** :class:`TSVPickReader` — splitting on whitespace splits
+    on tabs — so registering both against the same column names makes every
+    tab-separated file ambiguous. Register one, or pass ``format=``.
+    """
+
+    reader_name: str = "whitespace"
+    delimiter: str | None = None
+    file_suffixes: tuple[str, ...] = (".txt", ".dat", ".lst")
+
+
+def _as_float(value: str | None) -> float | None:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except ValueError:
+        return None

specmod/picks/events.py

@@ -0,0 +1,157 @@
+"""Every event format ObsPy parses, through one reader.
+
+``obspy.read_events`` sniffs and parses nineteen formats, ten of which carry
+arrivals, so this delegate is the whole standard roster. A format registered
+with ObsPy's own ``obspy.plugin.event`` entry points is readable here without
+being registered with specmod.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+import obspy
+from obspy.core.event import Catalog
+
+from .base import Pick, PickSet, SensorID
+
+if TYPE_CHECKING:  # pragma: no cover
+    from os import PathLike
+
+    from obspy.core.event import Event as ObsPyEvent
+
+__all__ = ["ObsPyEventsReader", "from_catalog"]
+
+
+def _obspy_claims(source: str | PathLike[str]) -> bool:
+    """Whether any ObsPy event plugin recognises this file.
+
+    Uses the same per-format ``isFormat`` functions ``read_events`` uses to
+    auto-detect, so this agrees with what a subsequent read would do without
+    parsing the file.
+    """
+    from obspy.core.util.base import (  # noqa: PLC0415
+        ENTRY_POINTS,
+        buffered_load_entry_point,
+    )
+
+    for entry_point in ENTRY_POINTS["event"].values():
+        if entry_point.dist is None:
+            continue
+        try:
+            is_format = buffered_load_entry_point(
+                entry_point.dist.name,
+                f"obspy.plugin.event.{entry_point.name}",
+                "isFormat",
+            )
+            if is_format(str(source)):
+                return True
+        except Exception:
+            # A detector that raises has not claimed the file. They are
+            # third-party code reading untrusted bytes, and one of them
+            # throwing must not stop the others being asked.
+            continue
+    return False
+
+
+#: Phase hints folded to their first letter. ``Pg``/``Pn``/``Pb`` and their S
+#: counterparts are all direct-arrival branches this pipeline does not
+#: distinguish; the original is kept on the pick as ``raw_phase``.
+def _fold(hint: str | None) -> str | None:
+    if not hint:
+        return None
+    first = hint.strip()[:1].upper()
+    return first if first in ("P", "S") else None
+
+
+def _sensor_from_waveform_id(waveform_id: Any) -> SensorID | None:
+    station = (getattr(waveform_id, "station_code", None) or "").strip()
+    if not station:
+        return None
+    network = (getattr(waveform_id, "network_code", None) or "").strip()
+    location = getattr(waveform_id, "location_code", None)
+    return SensorID(
+        # An empty network code is not a valid SEED network, so it states
+        # nothing; an empty location code is the normal single-sensor case.
+        network=network or None,
+        station=station,
+        location=location if location is not None else None,
+    )
+
+
+def _pick_from_obspy(source: Any) -> Pick | None:
+    phase = _fold(getattr(source, "phase_hint", None))
+    if phase is None:
+        return None
+    if getattr(source, "evaluation_status", None) == "rejected":
+        return None
+    sensor = _sensor_from_waveform_id(getattr(source, "waveform_id", None))
+    if sensor is None:
+        return None
+
+    mode = getattr(source, "evaluation_mode", None)
+    status = getattr(source, "evaluation_status", None)
+    creation = getattr(source, "creation_info", None)
+    return Pick(
+        sensor=sensor,
+        phase=phase,
+        time=source.time,
+        raw_phase=(source.phase_hint or "").strip() or None,
+        uncertainty=getattr(source, "time_errors", None)
+        and getattr(source.time_errors, "uncertainty", None),
+        polarity=getattr(source, "polarity", None),
+        automatic=None if mode is None else mode == "automatic",
+        reviewed=None if status is None else status in ("reviewed", "confirmed"),
+        channel=getattr(getattr(source, "waveform_id", None), "channel_code", None),
+        author=getattr(creation, "author", None) if creation is not None else None,
+    )
+
+
+def from_catalog(catalog: Catalog | ObsPyEvent) -> list[PickSet]:
+    """Every event in an ObsPy catalogue, as one :class:`PickSet` each.
+
+    Phase hints are folded to ``P`` or ``S`` on their first letter, with the
+    original kept as ``raw_phase``. Picks with no ``P``/``S`` hint, with an
+    ``evaluation_status`` of ``rejected``, or with no station code are dropped.
+    """
+    events = list(catalog) if isinstance(catalog, Catalog) else [catalog]
+
+    sets = []
+    for event in events:
+        picks = tuple(
+            pick
+            for pick in (_pick_from_obspy(raw) for raw in event.picks)
+            if pick is not None
+        )
+        origin = event.preferred_origin() or (
+            event.origins[0] if event.origins else None
+        )
+        resource_id = getattr(event, "resource_id", None)
+        sets.append(
+            PickSet(
+                picks=picks,
+                event_id=str(resource_id) if resource_id is not None else None,
+                origin=origin.time if origin is not None else None,
+            )
+        )
+    return sets
+
+
+@dataclass(frozen=True)
+class ObsPyEventsReader:
+    """Anything :func:`obspy.read_events` parses."""
+
+    @property
+    def name(self) -> str:
+        return "obspy_events"
+
+    @property
+    def suffixes(self) -> tuple[str, ...]:
+        return (".xml", ".quakeml", ".scml", ".pha", ".hyp", ".nordic", ".out")
+
+    def can_read(self, source: str | PathLike[str]) -> bool:
+        return _obspy_claims(source)
+
+    def read(self, source: str | PathLike[str]) -> list[PickSet]:
+        return from_catalog(obspy.read_events(str(source)))