pysmo

class Event(LocationWithDepth, Protocol):
    """Protocol class to define the `Event` type.

    A seismic event: a hypocentre from
    [`LocationWithDepth`][pysmo.LocationWithDepth] together with an origin
    time.
    """

    time: pd.Timestamp
    """Event origin time."""

class Location(Protocol):
    """Protocol class to define the `Location` type.

    A geographic point, given as latitude and longitude in degrees.
    """

    latitude: float
    """Latitude in degrees."""

    longitude: float
    """Longitude in degrees."""

class LocationWithDepth(Location, Protocol):
    """Protocol class to define the `LocationWithDepth` type.

    A [`Location`][pysmo.Location] that also carries a depth, such as an
    earthquake hypocentre.
    """

    depth: float
    """Location depth in metres, positive downwards."""

@define(kw_only=True)
class MiniEvent:
    """Minimal implementation of the `Event` type.

    See [`Event`][pysmo.Event].

    Examples:
        ```python
        >>> from pysmo import MiniEvent
        >>> import pandas as pd
        >>> from datetime import timezone
        >>> now = pd.Timestamp.now(timezone.utc)
        >>> event = MiniEvent(latitude=-24.68, longitude=-26.73, depth=15234.0, time=now)
        >>>
        ```
    """

    time: UtcTimestamp = field(
        converter=to_utc_timestamp,
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Event origin time."""

    latitude: float = field(
        converter=float,
        validator=is_latitude,
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Event latitude from -90 to 90 degrees."""

    longitude: float = field(
        converter=to_longitude,
        validator=is_longitude,
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Event longitude from -180 to 180 degrees (-180 is stored as +180)."""

    depth: float = field(
        converter=float, on_setattr=setters.pipe(setters.convert, setters.validate)
    )
    """Event depth in metres, positive downwards."""

@define(kw_only=True)
class MiniLocation:
    """Minimal implementation of the `Location` type.

    See [`Location`][pysmo.Location].

    Examples:
        ```python
        >>> from pysmo import MiniLocation
        >>> location = MiniLocation(latitude=41.8781, longitude=-87.6298)
        >>>
        ```
    """

    latitude: float = field(
        converter=float,
        validator=is_latitude,
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Latitude from -90 to 90 degrees."""

    longitude: float = field(
        converter=to_longitude,
        validator=is_longitude,
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Longitude from -180 to 180 degrees (-180 is stored as +180)."""

@define(kw_only=True)
class MiniLocationWithDepth:
    """Minimal implementation of the `LocationWithDepth` type.

    See [`LocationWithDepth`][pysmo.LocationWithDepth].

    Examples:
        ```python
        >>> from pysmo import MiniLocationWithDepth
        >>> hypo = MiniLocationWithDepth(latitude=-24.68, longitude=-26.73, depth=15234.0)
        >>>
        ```
    """

    latitude: float = field(
        converter=float,
        validator=is_latitude,
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Location latitude from -90 to 90 degrees."""

    longitude: float = field(
        converter=to_longitude,
        validator=is_longitude,
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Location longitude from -180 to 180 degrees (-180 is stored as +180)."""

    depth: float = field(
        converter=float, on_setattr=setters.pipe(setters.convert, setters.validate)
    )
    """Location depth in metres, positive downwards."""

@define(kw_only=True)
class MiniResponse:
    """Minimal implementation of the `Response` type.

    See [`Response`][pysmo.Response].

    Examples:
        ```python
        >>> from pysmo import MiniResponse
        >>> response = MiniResponse(
        ...     poles=[-0.037 + 0.037j, -0.037 - 0.037j],
        ...     zeros=[0j, 0j],
        ...     overall_sensitivity=3.4e9,
        ...     input_units="M/S",
        ... )
        >>>
        ```
    """

    poles: list[complex] = field(
        converter=to_complex_list,
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Response poles.

    See [`Response.poles`][pysmo.Response.poles] for more details.
    """

    zeros: list[complex] = field(
        converter=to_complex_list,
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Response zeros.

    See [`Response.zeros`][pysmo.Response.zeros] for more details.
    """

    overall_sensitivity: NonZeroNumber = field(
        converter=float,
        validator=is_nonzero,
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Scale factor combined with `poles`/`zeros` to reconstruct `H(f)`.

    See [`Response.overall_sensitivity`][pysmo.Response.overall_sensitivity]
    for more details.
    """

    reference_sensitivity: NonZeroNumber | None = field(
        default=None,
        converter=converters.optional(float),
        validator=validators.optional(is_nonzero),
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Total system sensitivity at the reference frequency, `A0` excluded.

    See
    [`Response.reference_sensitivity`][pysmo.Response.reference_sensitivity]
    for more details.
    """

    input_units: str = field(
        validator=validators.instance_of(str),
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Physical units produced by removing this response.

    See [`Response.input_units`][pysmo.Response.input_units] for more details.
    """

@define(kw_only=True)
class MiniResponseStage:
    """Minimal implementation of the `ResponseStage` type.

    See [`ResponseStage`][pysmo.ResponseStage].

    Examples:
        ```python
        >>> from pysmo import MiniResponseStage
        >>> stage = MiniResponseStage(
        ...     input_sample_rate=40.0,
        ...     decimation_factor=1,
        ...     numerator=[0.5, 0.5],
        ... )
        >>> stage.denominator
        [1.0]
        >>>
        ```
    """

    input_sample_rate: PositiveNumber = field(
        converter=float,
        validator=validators.gt(0),
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Sample rate this stage's filter coefficients operate at.

    See [`ResponseStage.input_sample_rate`][pysmo.ResponseStage.input_sample_rate]
    for more details.
    """

    decimation_factor: int = field(
        converter=to_strict_int,
        validator=validators.gt(0),
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Integer decimation factor applied by this stage.

    See [`ResponseStage.decimation_factor`][pysmo.ResponseStage.decimation_factor]
    for more details.
    """

    numerator: list[float] = field(
        converter=to_float_list,
        validator=validators.min_len(1),
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Feedforward ("b") filter coefficients.

    See [`ResponseStage.numerator`][pysmo.ResponseStage.numerator] for more details.
    """

    denominator: list[float] = field(
        factory=lambda: [1.0],
        converter=to_float_list,
        validator=validators.min_len(1),
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Feedback ("a") filter coefficients.

    See [`ResponseStage.denominator`][pysmo.ResponseStage.denominator] for more details.
    """

    correction: float = field(
        default=0.0,
        converter=float,
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Time correction (seconds) already applied to cancel this stage's own
    filter delay.

    See [`ResponseStage.correction`][pysmo.ResponseStage.correction] for
    more details.
    """

@define(kw_only=True)
class MiniSeismogram(SeismogramEndtimeMixin):
    """Minimal implementation of the `Seismogram` type.

    See [`Seismogram`][pysmo.Seismogram].

    Examples:
        ```python
        >>> from pysmo import MiniSeismogram
        >>> import pandas as pd
        >>> from datetime import timezone
        >>> import numpy as np
        >>> now = pd.Timestamp.now(timezone.utc)
        >>> delta = pd.Timedelta(seconds=0.1)
        >>> seismogram = MiniSeismogram(
        ...     begin_time=now, delta=delta, data=np.random.rand(100)
        ... )
        >>>
        ```
    """

    begin_time: UtcTimestamp = field(
        default=SeismogramDefaults.begin_time,
        converter=to_utc_timestamp,
        on_setattr=setters.convert,
    )
    """Seismogram begin time."""

    delta: PositiveTimedelta = field(
        default=SeismogramDefaults.delta,
        converter=to_timedelta,
        validator=is_positive_timedelta,
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Seismogram sampling interval."""

    data: npt.NDArray[np.floating] = field(
        factory=lambda: np.array([]),
        converter=to_ndarray,
        validator=validators.instance_of(np.ndarray),
        on_setattr=setters.pipe(setters.convert, setters.validate),
        eq=cmp_using(eq=np.array_equal),
    )
    """Seismogram data."""

@define(kw_only=True)
class MiniStagedResponse(MiniResponse):
    """Minimal implementation of the `StagedResponse` type.

    See [`StagedResponse`][pysmo.StagedResponse].

    Examples:
        ```python
        >>> from pysmo import MiniStagedResponse
        >>> response = MiniStagedResponse(
        ...     poles=[-0.037 + 0.037j, -0.037 - 0.037j],
        ...     zeros=[0j, 0j],
        ...     overall_sensitivity=3.4e9,
        ...     input_units="M/S",
        ... )
        >>>
        ```
    """

    stages: list[ResponseStage] = field(
        factory=list,
        validator=validators.deep_iterable(
            member_validator=satisfies_protocol(ResponseStage),
            iterable_validator=validators.instance_of(list),
        ),
        on_setattr=setters.validate,
    )
    """Digital decimation stages, in signal order.

    See [`StagedResponse.stages`][pysmo.StagedResponse.stages] for more details.
    """

@define(kw_only=True)
class MiniStation:
    """Minimal implementation of the `Station` type.

    See [`Station`][pysmo.Station].

    Examples:
        ```python
        >>> from pysmo import MiniStation
        >>> station = MiniStation(
        ...     latitude=-21.680301,
        ...     longitude=-46.732601,
        ...     name="CACB",
        ...     network="BL",
        ...     channel="BHZ",
        ...     location="00",
        ... )
        >>>
        ```
    """

    name: str = field(
        validator=_name_code,
        on_setattr=setters.validate,
    )
    """Station name.

    See [`Station.name`][pysmo.Station.name] for more details.
    """

    network: str = field(
        validator=_network_code,
        on_setattr=setters.validate,
    )
    """Network name.

    See [`Station.network`][pysmo.Station.network] for more details.
    """

    location: str = field(
        default="  ",
        validator=_location_code,
        converter=_pad_string,
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Location ID.

    See [`Station.location`][pysmo.Station.location] for more details.
    """

    channel: str = field(
        validator=_channel_code,
        on_setattr=setters.validate,
    )
    """Channel code.

    See [`Station.channel`][pysmo.Station.channel] for more details.
    """

    latitude: float = field(
        converter=float,
        validator=is_latitude,
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Station latitude from -90 to 90 degrees."""

    longitude: float = field(
        converter=to_longitude,
        validator=is_longitude,
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Station longitude from -180 to 180 degrees (-180 is stored as +180)."""

    elevation: float | None = field(
        default=None,
        converter=converters.optional(float),
        validator=validators.optional(validators.instance_of(float)),
        on_setattr=setters.pipe(setters.convert, setters.validate),
    )
    """Station elevation."""