Skip to content

pysmo #

Pysmo types and corresponding Mini Classes.

The psymo base namespace exposes the protocol classes that are used as type hints, as well as reference implementations of a generic class for each protocol. The reference classes are subclasses of their respective protocol classes that contain exactly the same attributes (though some extra methods may be defined for convenience). They can be considered minimal implementations of a class that can be used with pysmo protocols, and are therefore named "Mini" + "name of protocol" (e.g. MiniSeismogram is an implementation of the Seismogram type).

Classes, functions and other tools that make use of pysmo types and mini need to be imported from other modules.

Modules:

  • classes –

    Classes that work with pysmo types.

  • functions –

    Simple operations using pysmo types.

  • lib –

    Pysmo library module.

  • tools –

    Extra tools or topics that use pysmo types.

Classes:

Event #

Bases: LocationWithDepth, Protocol

Protocol class to define the Event type.

Attributes:

Source code in pysmo/_types/_event.py 
11
12
13
14
15
16
17
18
19
20
21
@runtime_checkable
class Event(LocationWithDepth, Protocol):
    """Protocol class to define the `Event` type."""

    @property
    def time(self) -> datetime:
        """Event origin time."""
        ...

    @time.setter
    def time(self, value: datetime) -> None: ...

latitude property writable #

latitude: float

Latitude in degrees.

longitude property writable #

longitude: float

Longitude in degrees.

depth property writable #

depth: float

Location depth in metres.

time property writable #

time: datetime

Event origin time.

MiniEvent #

Minimal class for use with the Event type.

The MiniEvent class provides a minimal implementation of class that is compatible with the Event type.

Examples:

>>> from pysmo import MiniEvent, Event, LocationWithDepth, Location
>>> from datetime import datetime, timezone
>>> now = datetime.now(timezone.utc)
>>> my_event = MiniEvent(latitude=-24.68, longitude=-26.73,
                         depth=15234.0, time=now)
>>> isinstance(my_event, Event)
True
>>> isinstance(my_event, Location)
True
>>> isinstance(my_event, LocationWithDepth)
True

Attributes:

Source code in pysmo/_types/_event.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
@define(kw_only=True, slots=True)
class MiniEvent:
    """Minimal class for use with the [`Event`][pysmo.Event] type.

    The `MiniEvent` class provides a minimal implementation of class that is
    compatible with the [`Event`][pysmo.Event] type.

    Examples:
        >>> from pysmo import MiniEvent, Event, LocationWithDepth, Location
        >>> from datetime import datetime, timezone
        >>> now = datetime.now(timezone.utc)
        >>> my_event = MiniEvent(latitude=-24.68, longitude=-26.73,
                                 depth=15234.0, time=now)
        >>> isinstance(my_event, Event)
        True
        >>> isinstance(my_event, Location)
        True
        >>> isinstance(my_event, LocationWithDepth)
        True
    """

    _PYSMOPROTOCOL: ClassVar[Type] = Event

    time: datetime = field(validator=[type_validator(), datetime_is_utc])
    """Event origin time."""

    latitude: float | int = field(
        validator=[validators.ge(-90), validators.le(90), type_validator()],
    )
    """Event atitude from -90 to 90 degrees."""

    longitude: float | int = field(
        validator=[validators.gt(-180), validators.le(180), type_validator()],
    )
    """Event longitude from -180 to 180 degrees."""

    depth: float | int = field(validator=type_validator())
    """Event depth in metres."""

time class-attribute instance-attribute #

time: datetime = field(validator=[type_validator(), datetime_is_utc])

Event origin time.

latitude class-attribute instance-attribute #

latitude: float | int = field(validator=[ge(-90), le(90), type_validator()])

Event atitude from -90 to 90 degrees.

longitude class-attribute instance-attribute #

longitude: float | int = field(validator=[gt(-180), le(180), type_validator()])

Event longitude from -180 to 180 degrees.

depth class-attribute instance-attribute #

depth: float | int = field(validator=type_validator())

Event depth in metres.

Location #

Bases: Protocol

Protocol class to define the Location type.

Attributes:

Source code in pysmo/_types/_location.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
@runtime_checkable
class Location(Protocol):
    """Protocol class to define the `Location` type."""

    @property
    def latitude(self) -> float:
        """Latitude in degrees."""
        ...

    @latitude.setter
    def latitude(self, value: float) -> None: ...

    @property
    def longitude(self) -> float:
        """Longitude in degrees."""
        ...

    @longitude.setter
    def longitude(self, value: float) -> None: ...

latitude property writable #

latitude: float

Latitude in degrees.

longitude property writable #

longitude: float

Longitude in degrees.

MiniLocation #

Minimal class for use with the Location type.

The MiniLocation class provides a minimal implementation of class that is compatible with the Location type.

Examples:

>>> from pysmo import MiniLocation, Location
>>> my_location = MiniLocation(latitude=41.8781, longitude=-87.6298)
>>> isinstance(my_location, Location)
True

Attributes:

Source code in pysmo/_types/_location.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
@define(kw_only=True, slots=True)
class MiniLocation:
    """Minimal class for use with the [`Location`][pysmo.Location] type.

    The `MiniLocation` class provides a minimal implementation of class that
    is compatible with the [`Location`][pysmo.Location] type.

    Examples:
        >>> from pysmo import MiniLocation, Location
        >>> my_location = MiniLocation(latitude=41.8781, longitude=-87.6298)
        >>> isinstance(my_location, Location)
        True
    """

    latitude: float | int = field(
        validator=[validators.ge(-90), validators.le(90), type_validator()],
    )
    """Latitude from -90 to 90 degrees."""

    longitude: float | int = field(
        validator=[validators.gt(-180), validators.le(180), type_validator()],
    )
    """Longitude from -180 to 180 degrees."""

latitude class-attribute instance-attribute #

latitude: float | int = field(validator=[ge(-90), le(90), type_validator()])

Latitude from -90 to 90 degrees.

longitude class-attribute instance-attribute #

longitude: float | int = field(validator=[gt(-180), le(180), type_validator()])

Longitude from -180 to 180 degrees.

LocationWithDepth #

Bases: Location, Protocol

Protocol class to define the LocationWithDepth type.

Attributes:

Source code in pysmo/_types/_location_with_depth.py 
 9
10
11
12
13
14
15
16
17
18
19
@runtime_checkable
class LocationWithDepth(Location, Protocol):
    """Protocol class to define the `LocationWithDepth` type."""

    @property
    def depth(self) -> float:
        """Location depth in metres."""
        ...

    @depth.setter
    def depth(self, value: float) -> None: ...

latitude property writable #

latitude: float

Latitude in degrees.

longitude property writable #

longitude: float

Longitude in degrees.

depth property writable #

depth: float

Location depth in metres.

MiniLocationWithDepth #

Minimal class for use with the MiniLocationWithDepth type.

The MiniLocationWithDepth class provides a minimal implementation of class that is compatible with the MiniLocationWithDepth type.

Examples:

>>> from pysmo import MiniLocationWithDepth, LocationWithDepth, Location
>>> my_hypo = MiniLocationWithDepth(latitude=-24.68, longitude=-26.73, depth=15234.0)
>>> isinstance(my_hypo, LocationWithDepth)
True
>>> isinstance(my_hypo, Location)
True

Attributes:

Source code in pysmo/_types/_location_with_depth.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
@define(kw_only=True, slots=True)
class MiniLocationWithDepth:
    """Minimal class for use with the [`MiniLocationWithDepth`][pysmo.MiniLocationWithDepth] type.

    The `MiniLocationWithDepth` class provides a minimal implementation of class that
    is compatible with the [`MiniLocationWithDepth`][pysmo.MiniLocationWithDepth] type.

    Examples:
        >>> from pysmo import MiniLocationWithDepth, LocationWithDepth, Location
        >>> my_hypo = MiniLocationWithDepth(latitude=-24.68, longitude=-26.73, depth=15234.0)
        >>> isinstance(my_hypo, LocationWithDepth)
        True
        >>> isinstance(my_hypo, Location)
        True
    """

    latitude: float | int = field(
        validator=[validators.ge(-90), validators.le(90), type_validator()],
    )
    """Location latitude from -90 to 90 degrees."""

    longitude: float | int = field(
        validator=[validators.gt(-180), validators.le(180), type_validator()],
    )
    """Location longitude from -180 to 180 degrees."""

    depth: float | int = field(validator=type_validator())
    """Location depth in metres."""

latitude class-attribute instance-attribute #

latitude: float | int = field(validator=[ge(-90), le(90), type_validator()])

Location latitude from -90 to 90 degrees.

longitude class-attribute instance-attribute #

longitude: float | int = field(validator=[gt(-180), le(180), type_validator()])

Location longitude from -180 to 180 degrees.

depth class-attribute instance-attribute #

depth: float | int = field(validator=type_validator())

Location depth in metres.

Seismogram #

Bases: Protocol

Protocol class to define the Seismogram type.

Examples:

Usage for a function that takes a Seismogram compatible class instance as argument and returns the begin time in isoformat:

>>> from pysmo import Seismogram
>>> from pysmo.classes import SAC  # SAC is a class that "speaks" Seismogram
>>> def example_function(seis_in: Seismogram) -> str:
...     return seis_in.begin_time.isoformat()
...
>>> my_sac = SAC.from_file('testfile.sac')
>>> my_seismogram = my_sac.seismogram
>>> example_function(my_seismogram)
'2005-03-02T07:23:02.160000'

Methods:

  • __len__ –

    The length of the Seismogram.

Attributes:

Source code in pysmo/_types/_seismogram.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
@runtime_checkable
class Seismogram(Protocol):
    """Protocol class to define the `Seismogram` type.

    Examples:
        Usage for a function that takes a Seismogram compatible class instance as
        argument and returns the begin time in isoformat:

        >>> from pysmo import Seismogram
        >>> from pysmo.classes import SAC  # SAC is a class that "speaks" Seismogram
        >>> def example_function(seis_in: Seismogram) -> str:
        ...     return seis_in.begin_time.isoformat()
        ...
        >>> my_sac = SAC.from_file('testfile.sac')
        >>> my_seismogram = my_sac.seismogram
        >>> example_function(my_seismogram)
        '2005-03-02T07:23:02.160000'
    """

    def __len__(self) -> int:
        """The length of the Seismogram.

        Returns:
            Number of samples in the data array.
        """
        ...

    @property
    def data(self) -> npt.NDArray:
        """Seismogram data."""
        ...

    @data.setter
    def data(self, value: npt.NDArray) -> None: ...

    @property
    def begin_time(self) -> datetime:
        """Seismogram begin time."""
        ...

    @begin_time.setter
    def begin_time(self, value: datetime) -> None: ...

    @property
    def end_time(self) -> datetime:
        """Seismogram end time."""
        ...

    @property
    def delta(self) -> timedelta:
        """The sampling interval."""
        ...

    @delta.setter
    def delta(self, value: timedelta) -> None: ...

data property writable #

data: NDArray

Seismogram data.

begin_time property writable #

begin_time: datetime

Seismogram begin time.

end_time property #

end_time: datetime

Seismogram end time.

delta property writable #

delta: timedelta

The sampling interval.

__len__ #

__len__() -> int

The length of the Seismogram.

Returns:

  • int –

    Number of samples in the data array.

Source code in pysmo/_types/_seismogram.py 
32
33
34
35
36
37
38
def __len__(self) -> int:
    """The length of the Seismogram.

    Returns:
        Number of samples in the data array.
    """
    ...

MiniSeismogram #

Minimal class for use with the Seismogram type.

The MiniSeismogram class provides a minimal implementation of class that is compatible with the Seismogram type.

Examples:

>>> from pysmo import MiniSeismogram, Seismogram
>>> from datetime import datetime, timedelta, timezone
>>> import numpy as np
>>> now = datetime.now(timezone.utc)
>>> delta0 = timedelta(seconds=0.1)
>>> my_seismogram = MiniSeismogram(begin_time=now, delta=delta,
                                   data=np.random.rand(100))
>>> isinstance(my_seismogram, Seismogram)
True

Methods:

  • __len__ –

    The length of the Seismogram.

Attributes:

Source code in pysmo/_types/_seismogram.py 
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
@define(kw_only=True, slots=True)
class MiniSeismogram:
    """Minimal class for use with the [`Seismogram`][pysmo.Seismogram] type.

    The `MiniSeismogram` class provides a minimal implementation of class that
    is compatible with the [`Seismogram`][pysmo.Seismogram] type.

    Examples:
        >>> from pysmo import MiniSeismogram, Seismogram
        >>> from datetime import datetime, timedelta, timezone
        >>> import numpy as np
        >>> now = datetime.now(timezone.utc)
        >>> delta0 = timedelta(seconds=0.1)
        >>> my_seismogram = MiniSeismogram(begin_time=now, delta=delta,
                                           data=np.random.rand(100))
        >>> isinstance(my_seismogram, Seismogram)
        True
    """

    begin_time: datetime = field(
        default=SEISMOGRAM_DEFAULTS.begin_time.value,
        validator=[type_validator(), datetime_is_utc],
    )
    """Seismogram begin time."""

    delta: timedelta = field(
        default=SEISMOGRAM_DEFAULTS.delta.value,
        validator=type_validator(),
    )
    """Seismogram sampling interval."""

    data: npt.NDArray = field(factory=lambda: np.array([]), validator=type_validator())
    """Seismogram data."""

    def __len__(self) -> int:
        """The length of the Seismogram.

        Returns:
            Number of samples in the data array.
        """
        return np.size(self.data)

    @property
    def end_time(self) -> datetime:
        """Seismogram end time."""
        if len(self) == 0:
            return self.begin_time
        return self.begin_time + self.delta * (len(self) - 1)

begin_time class-attribute instance-attribute #

begin_time: datetime = field(default=begin_time.value, validator=[type_validator(), datetime_is_utc])

Seismogram begin time.

delta class-attribute instance-attribute #

delta: timedelta = field(default=delta.value, validator=type_validator())

Seismogram sampling interval.

data class-attribute instance-attribute #

data: NDArray = field(factory=lambda: array([]), validator=type_validator())

Seismogram data.

end_time property #

end_time: datetime

Seismogram end time.

__len__ #

__len__() -> int

The length of the Seismogram.

Returns:

  • int –

    Number of samples in the data array.

Source code in pysmo/_types/_seismogram.py 
104
105
106
107
108
109
110
def __len__(self) -> int:
    """The length of the Seismogram.

    Returns:
        Number of samples in the data array.
    """
    return np.size(self.data)

Station #

Bases: Location, Protocol

Protocol class to define the Station type.

Attributes:

Source code in pysmo/_types/_station.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
@runtime_checkable
class Station(Location, Protocol):
    """Protocol class to define the Station type."""

    @property
    def name(self) -> str:
        """Station name or identifier."""
        ...

    @name.setter
    def name(self, value: str) -> None: ...

    @property
    def network(self) -> str | None:
        """Network name or identifier."""
        ...

    @network.setter
    def network(self, value: str) -> None: ...

    @property
    def elevation(self) -> float | None:
        """Station elevation in metres."""
        ...

    @elevation.setter
    def elevation(self, value: float) -> None: ...

latitude property writable #

latitude: float

Latitude in degrees.

longitude property writable #

longitude: float

Longitude in degrees.

name property writable #

name: str

Station name or identifier.

network property writable #

network: str | None

Network name or identifier.

elevation property writable #

elevation: float | None

Station elevation in metres.

MiniStation #

Minimal class for use with the Station type.

The MiniStation class provides a minimal implementation of class that is compatible with the Station type.

Examples:

>>> from pysmo import MiniStation, Station, Location
>>> my_station = MiniStation(latitude=-21.680301, longitude=-46.732601,
                             name="CACB", network="BL")
>>> isinstance(my_station, Station)
True
>>> isinstance(my_station, Location)
True

Attributes:

Source code in pysmo/_types/_station.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
@define(kw_only=True, slots=True)
class MiniStation:
    """Minimal class for use with the Station type.

    The `MiniStation` class provides a minimal implementation of class that
    is compatible with the `Station` type.

    Examples:
        >>> from pysmo import MiniStation, Station, Location
        >>> my_station = MiniStation(latitude=-21.680301, longitude=-46.732601,
                                     name="CACB", network="BL")
        >>> isinstance(my_station, Station)
        True
        >>> isinstance(my_station, Location)
        True
    """

    name: str = field(validator=type_validator())
    """Station name."""

    network: str | None = field(default=None, validator=type_validator())
    """Network name."""

    latitude: float | int = field(
        validator=[validators.ge(-90), validators.le(90), type_validator()],
    )
    """Station latitude from -90 to 90 degrees."""

    longitude: float | int = field(
        validator=[validators.gt(-180), validators.le(180), type_validator()],
    )
    """Station longitude from -180 to 180 degrees."""

    elevation: float | int | None = field(
        default=None,
        validator=validators.optional(
            [validators.gt(-180), validators.le(180), type_validator()]
        ),
    )
    """Station elevation."""

name class-attribute instance-attribute #

name: str = field(validator=type_validator())

Station name.

network class-attribute instance-attribute #

network: str | None = field(default=None, validator=type_validator())

Network name.

latitude class-attribute instance-attribute #

latitude: float | int = field(validator=[ge(-90), le(90), type_validator()])

Station latitude from -90 to 90 degrees.

longitude class-attribute instance-attribute #

longitude: float | int = field(validator=[gt(-180), le(180), type_validator()])

Station longitude from -180 to 180 degrees.

elevation class-attribute instance-attribute #

elevation: float | int | None = field(default=None, validator=optional([gt(-180), le(180), type_validator()]))

Station elevation.