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:

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()
...
>>> sac = SAC.from_file("example.sac")
>>> seismogram = sac.seismogram
>>> example_function(seismogram)
'2005-03-01T07:23:02.160000+00:00'
>>>

Methods:

  • __len__ –

    The length of the Seismogram.

Attributes:

Source code in pysmo/_types/_seismogram.py 
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
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
68
69
@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:

        ```python
        >>> 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()
        ...
        >>> sac = SAC.from_file("example.sac")
        >>> seismogram = sac.seismogram
        >>> example_function(seismogram)
        '2005-03-01T07:23:02.160000+00:00'
        >>>
        ```
    """

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

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

    @property
    def data(self) -> np.ndarray:
        """Seismogram data."""
        ...

    @data.setter
    def data(self, value: np.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 
34
35
36
37
38
39
40
def __len__(self) -> int:
    """The length of the Seismogram.

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

Station #

Bases: Location, Protocol

Protocol class to define the Station type.

Attributes:

Source code in pysmo/_types/_station.py 
 8
 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
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 Station(Location, Protocol):
    """Protocol class to define the `Station` type."""

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

        A 1-5 character identifier for the station recording the data.
        """
        ...

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

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

        A 1-2 character code identifying the network/owner of the data.
        """
        ...

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

    @property
    def location(self) -> str:
        """Location ID.

        A two character code used to uniquely identify different data streams
        at a single stationa.
        """
        ...

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

    @property
    def channel(self) -> str:
        """Channel code.

        A three character combination used to identify:

        1. Band and general sample rate.
        2. Instrument type.
        3. Orientation of the sensor.
        """
        ...

    @channel.setter
    def channel(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.

A 1-5 character identifier for the station recording the data.

network property writable #

network: str

Network name or identifier.

A 1-2 character code identifying the network/owner of the data.

location property writable #

location: str

Location ID.

A two character code used to uniquely identify different data streams at a single stationa.

channel property writable #

channel: str

Channel code.

A three character combination used to identify:

  1. Band and general sample rate.
  2. Instrument type.
  3. Orientation of the sensor.

elevation property writable #

elevation: float | None

Station elevation in metres.

Event #

Bases: LocationWithDepth, Protocol

Protocol class to define the Event type.

Attributes:

Source code in pysmo/_types/_event.py 
10
11
12
13
14
15
16
17
18
19
20
@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.

Location #

Bases: Protocol

Protocol class to define the Location type.

Attributes:

Source code in pysmo/_types/_location.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
@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.

LocationWithDepth #

Bases: Location, Protocol

Protocol class to define the LocationWithDepth type.

Attributes:

Source code in pysmo/_types/_location_with_depth.py 
 8
 9
10
11
12
13
14
15
16
17
18
@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.

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)
>>> delta = timedelta(seconds=0.1)
>>> seismogram = MiniSeismogram(begin_time=now, delta=delta, data=np.random.rand(100))
>>> isinstance(seismogram, Seismogram)
True
>>>

Methods:

  • __len__ –

    The length of the Seismogram.

Attributes:

Source code in pysmo/_types/_seismogram.py 
 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:
        ```python
        >>> from pysmo import MiniSeismogram, Seismogram
        >>> from datetime import datetime, timedelta, timezone
        >>> import numpy as np
        >>> now = datetime.now(timezone.utc)
        >>> delta = timedelta(seconds=0.1)
        >>> seismogram = MiniSeismogram(begin_time=now, delta=delta, data=np.random.rand(100))
        >>> isinstance(seismogram, Seismogram)
        True
        >>>
        ```
    """

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

    delta: timedelta = SEISMOGRAM_DEFAULTS.delta.value
    """Seismogram sampling interval."""

    data: np.ndarray = field(factory=lambda: np.array([]))
    """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=datetime_is_utc
)

Seismogram begin time.

delta class-attribute instance-attribute #

delta: timedelta = delta.value

Seismogram sampling interval.

data class-attribute instance-attribute #

data: ndarray = field(factory=lambda: array([]))

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)

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
>>> station = MiniStation(latitude=-21.680301, longitude=-46.732601, name="CACB", network="BL", channel="BHZ", location="00")
>>> isinstance(station, Station)
True
>>> isinstance(station, Location)
True
>>>

Attributes:

Source code in pysmo/_types/_station.py 
 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
118
119
120
121
122
123
124
125
126
127
128
129
130
@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:
        ```python
        >>> from pysmo import MiniStation, Station, Location
        >>> station = MiniStation(latitude=-21.680301, longitude=-46.732601, name="CACB", network="BL", channel="BHZ", location="00")
        >>> isinstance(station, Station)
        True
        >>> isinstance(station, Location)
        True
        >>>
        ```
    """

    name: str = field(validator=[validators.min_len(1), validators.max_len(5)])
    """Station name.

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

    network: str = field(validator=[validators.min_len(1), validators.max_len(2)])
    """Network name.

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

    location: str = field(
        default="  ",
        validator=[validators.min_len(2), validators.max_len(2)],
        converter=pad_string,
    )
    """Location ID.

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

    channel: str = field(validator=[validators.min_len(3), validators.max_len(3)])
    """Channel code.

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

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

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

    elevation: float | None = field(
        default=None, validator=validators.optional(validators.instance_of(float | int))
    )
    """Station elevation."""

name class-attribute instance-attribute #

name: str = field(validator=[min_len(1), max_len(5)])

Station name.

See Station.name for more details.

network class-attribute instance-attribute #

network: str = field(validator=[min_len(1), max_len(2)])

Network name.

See Station.network for more details.

location class-attribute instance-attribute #

location: str = field(
    default="  ",
    validator=[min_len(2), max_len(2)],
    converter=pad_string,
)

Location ID.

See Station.location for more details.

channel class-attribute instance-attribute #

channel: str = field(validator=[min_len(3), max_len(3)])

Channel code.

See Station.channel for more details.

latitude class-attribute instance-attribute #

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

Station latitude from -90 to 90 degrees.

longitude class-attribute instance-attribute #

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

Station longitude from -180 to 180 degrees.

elevation class-attribute instance-attribute #

elevation: float | None = field(
    default=None,
    validator=optional(instance_of(float | int)),
)

Station elevation.

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)
>>> event = MiniEvent(latitude=-24.68, longitude=-26.73, depth=15234.0, time=now)
>>> isinstance(event, Event)
True
>>> isinstance(event, Location)
True
>>> isinstance(event, LocationWithDepth)
True
>>>

Attributes:

Source code in pysmo/_types/_event.py 
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
@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:
        ```python
        >>> from pysmo import MiniEvent, Event, LocationWithDepth, Location
        >>> from datetime import datetime, timezone
        >>> now = datetime.now(timezone.utc)
        >>> event = MiniEvent(latitude=-24.68, longitude=-26.73, depth=15234.0, time=now)
        >>> isinstance(event, Event)
        True
        >>> isinstance(event, Location)
        True
        >>> isinstance(event, LocationWithDepth)
        True
        >>>
        ```
    """

    time: datetime = field(validator=datetime_is_utc)
    """Event origin time."""

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

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

    depth: float
    """Event depth in metres."""

time class-attribute instance-attribute #

time: datetime = field(validator=datetime_is_utc)

Event origin time.

latitude class-attribute instance-attribute #

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

Event atitude from -90 to 90 degrees.

longitude class-attribute instance-attribute #

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

Event longitude from -180 to 180 degrees.

depth instance-attribute #

depth: float

Event depth in metres.

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
>>> location = MiniLocation(latitude=41.8781, longitude=-87.6298)
>>> isinstance(location, Location)
True
>>>

Attributes:

Source code in pysmo/_types/_location.py 
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 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:
        ```python
        >>> from pysmo import MiniLocation, Location
        >>> location = MiniLocation(latitude=41.8781, longitude=-87.6298)
        >>> isinstance(location, Location)
        True
        >>>
        ```
    """

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

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

latitude class-attribute instance-attribute #

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

Latitude from -90 to 90 degrees.

longitude class-attribute instance-attribute #

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

Longitude from -180 to 180 degrees.

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
>>> hypo = MiniLocationWithDepth(latitude=-24.68, longitude=-26.73, depth=15234.0)
>>> isinstance(hypo, LocationWithDepth)
True
>>> isinstance(hypo, Location)
True
>>>

Attributes:

Source code in pysmo/_types/_location_with_depth.py 
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
@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:
        ```python
        >>> from pysmo import MiniLocationWithDepth, LocationWithDepth, Location
        >>> hypo = MiniLocationWithDepth(latitude=-24.68, longitude=-26.73, depth=15234.0)
        >>> isinstance(hypo, LocationWithDepth)
        True
        >>> isinstance(hypo, Location)
        True
        >>>
        ```
    """

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

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

    depth: float
    """Location depth in metres."""

latitude class-attribute instance-attribute #

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

Location latitude from -90 to 90 degrees.

longitude class-attribute instance-attribute #

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

Location longitude from -180 to 180 degrees.

depth instance-attribute #

depth: float

Location depth in metres.