Skip to content

pysmo.functions #

Simple operations using pysmo types.

This module provides functions that perform common operations using pysmo types (mostly Seismogram). They are meant to be building blocks that can be used to construct more complex processing algorithms.

Many functions have a clone argument that controls whether the function should operate on the input directly, or first create a clone of it (using deepcopy) and return the clone after using it for the the function. For example:

>>> from pysmo.function import resample
>>> from pysmo.classes import SAC
>>> sac_seis = SAC.from_file('testfile.sac').seismogram
>>> new_delta = sac_seis.delta * 2
>>>
>>> # create a clone and modify data in clone instead of sac_seis:
>>> new_sac_seis = resample(sac_seis, new_delta, clone=True)
>>>
>>> # modify data in sac_seis directly:
>>> resample(sac_seis, new_delta)
>>>
>>> # because the deepcopy operation can be computationaly expensive,
>>> # you should NOT use the following pattern:
>>> sac_seis = resample(sac_seis, new_delta, clone=True)
Hint

Additional functions may be found in pysmo.tools.

Functions:

  • clone_to_mini –

    Create a new instance of a Mini class from a matching other one.

  • copy_from_mini –

    Copy attributes from a Mini instance to matching other one.

  • crop –

    Shorten a seismogram by providing a start and end time.

  • detrend –

    Remove linear and/or constant trends from a seismogram.

  • normalize –

    Normalize a seismogram with its absolute max value.

  • resample –

    Resample Seismogram object data using the Fourier method.

  • time2index –

    Retuns data index corresponding to a given time.

clone_to_mini #

clone_to_mini(mini_cls: type[TMini], source: _AnyProto) -> TMini

Create a new instance of a Mini class from a matching other one.

This function is creates a clone of an exising class by copying the attributes defined in mini_cls from the source to the target. Attributes only present in the source object are ignored, potentially resulting in a smaller and more performant object.

Parameters:

  • mini_cls (type[TMini]) –

    The type of Mini class to create.

  • source (_AnyProto) –

    The instance to clone (must contain all attributes present in mini_cls).

Returns:

  • TMini –

    A new Mini instance type mini_cls.

Raises:

  • AttributeError –

    If the source instance does not contain all attributes in mini_cls.

Examples:

Create a MiniSeismogram from a SacSeismogram instance.

>>> from pysmo.funtions import clone_to_mini
>>> from pysmo import MiniSeismogram
>>> from pysmo.classes import SAC
>>> sac_seismogram = SAC.from_file("testfile.sac").seismogram
>>> mini_seismogram = clone_to_mini(MiniSeismogram, sac_seismogram)
See Also

copy_from_mini: Copy attributes from a Mini instance to matching other one.

Source code in pysmo/functions/_utils.py 
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
78
79
80
81
82
83
84
85
86
87
def clone_to_mini[TMini: _AnyMini](mini_cls: type[TMini], source: _AnyProto) -> TMini:
    """Create a new instance of a Mini class from a matching other one.

    This function is creates a clone of an exising class by
    [copying][copy.copy] the attributes defined in `mini_cls` from the source
    to the target. Attributes only present in the source object are ignored,
    potentially resulting in a smaller and more performant object.

    Parameters:
        mini_cls: The type of Mini class to create.
        source: The instance to clone (must contain all attributes present
            in `mini_cls`).

    Returns:
        A new Mini instance type mini_cls.

    Raises:
        AttributeError: If the source instance does not contain all attributes
            in mini_cls.

    Examples:
        Create a [`MiniSeismogram`][pysmo.MiniSeismogram] from a
        [`SacSeismogram`][pysmo.classes.SacSeismogram] instance.

        >>> from pysmo.funtions import clone_to_mini
        >>> from pysmo import MiniSeismogram
        >>> from pysmo.classes import SAC
        >>> sac_seismogram = SAC.from_file("testfile.sac").seismogram
        >>> mini_seismogram = clone_to_mini(MiniSeismogram, sac_seismogram)

    See Also:
        [`copy_from_mini`][pysmo.functions.copy_from_mini]: Copy attributes
        from a Mini instance to matching other one.
    """

    if all(map(lambda x: hasattr(source, x.name), fields(mini_cls))):
        clone_dict = {
            attr.name: copy(getattr(source, attr.name)) for attr in fields(mini_cls)
        }
        # TODO: why do we need cast here for mypy?
        return cast(TMini, mini_cls(**clone_dict))

    raise AttributeError(
        f"Unable to create clone: {source} not compatible with {mini_cls}."
    )

copy_from_mini #

copy_from_mini(source: _AnyMini, target: _AnyProto) -> None

Copy attributes from a Mini instance to matching other one.

This function copies all attributes in the source Mini class instance to a compatible target instance.

Parameters:

  • source (_AnyMini) –

    The Mini instance to copy attributes from.

  • target (_AnyProto) –

    Compatible target instance.

Raises:

  • AttributeError –

    If the target instance does not contain all attributes in the source instance.

See Also

clone_to_mini: Create a new instance of a Mini class from a matching other one.

Source code in pysmo/functions/_utils.py 
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
def copy_from_mini(source: _AnyMini, target: _AnyProto) -> None:
    """Copy attributes from a Mini instance to matching other one.

    This function [copies][copy.copy] all attributes in the `source` Mini class
    instance to a compatible `target` instance.

    Parameters:
        source: The Mini instance to copy attributes from.
        target: Compatible target instance.

    Raises:
        AttributeError: If the `target` instance does not contain all
            attributes in the `source` instance.

    See Also:
        [`clone_to_mini`][pysmo.functions.clone_to_mini]: Create a new
        instance of a Mini class from a matching other one.
    """

    if all(map(lambda x: hasattr(target, x.name), fields(type(source)))):
        for attr in fields(type(source)):
            setattr(target, attr.name, copy(getattr(source, attr.name)))
    else:
        raise AttributeError(
            f"Unable to copy to target: {type(target)} not compatible with {type(source)}."
        )

crop #

crop(seismogram: T, begin_time: datetime, end_time: datetime, clone: bool = False) -> None | T

Shorten a seismogram by providing a start and end time.

Parameters:

  • seismogram (T) –

    Seismogram object.

  • begin_time (datetime) –

    New start time.

  • end_time (datetime) –

    New end time.

  • clone (bool, default: False ) –

    Operate on a clone of the input seismogram.

Returns:

  • None | T –

    Cropped Seismogram object if called with clone=True.

Examples:

>>> from pysmo.functions import crop
>>> from pysmo.classes import SAC
>>> from datetime import timedelta
>>> sac_seis = SAC.from_file('testfile.sac').seismogram
>>> new_begin_time = sac_seis.begin_time + timedelta(seconds=10)
>>> new_end_time = sac_seis.end_time - timedelta(seconds=10)
>>> crop(sac_seis, new_begin_time, new_end_time)
Note

The returned seismogram may not have the exact new begin and end times that are specified as input, as no resampling is performed. Instead the nearest earlier sample is used as new begin time, and the nearest later sample as new end time.

Source code in pysmo/functions/_seismogram.py 
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
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def crop[T: Seismogram](
    seismogram: T, begin_time: datetime, end_time: datetime, clone: bool = False
) -> None | T:
    """Shorten a seismogram by providing a start and end time.

    Parameters:
        seismogram: [`Seismogram`][pysmo.Seismogram] object.
        begin_time: New start time.
        end_time: New end time.
        clone: Operate on a clone of the input seismogram.

    Returns:
        Cropped [`Seismogram`][pysmo.Seismogram] object if called with `clone=True`.

    Examples:
        >>> from pysmo.functions import crop
        >>> from pysmo.classes import SAC
        >>> from datetime import timedelta
        >>> sac_seis = SAC.from_file('testfile.sac').seismogram
        >>> new_begin_time = sac_seis.begin_time + timedelta(seconds=10)
        >>> new_end_time = sac_seis.end_time - timedelta(seconds=10)
        >>> crop(sac_seis, new_begin_time, new_end_time)

    Note:
        The returned seismogram may not have the exact new begin and end
        times that are specified as input, as no resampling is performed.
        Instead the nearest earlier sample is used as new begin time, and the
        nearest later sample as new end time.
    """

    if seismogram.begin_time > begin_time:
        raise ValueError("new begin_time cannot be before seismogram.begin_time")

    if seismogram.end_time < end_time:
        raise ValueError("new end_time cannot be after seismogram.end_time")

    if begin_time > end_time:
        raise ValueError("new begin_time cannot be after end_time")

    if clone is True:
        seismogram = deepcopy(seismogram)

    start_index = time2index(seismogram, begin_time, "floor")
    end_index = time2index(seismogram, end_time, "ceil")

    seismogram.data = seismogram.data[start_index : end_index + 1]
    seismogram.begin_time = seismogram.begin_time + seismogram.delta * start_index

    if clone is True:
        return seismogram

    return None

detrend #

detrend(seismogram: T, clone: bool = False) -> None | T

Remove linear and/or constant trends from a seismogram.

Parameters:

  • seismogram (T) –

    Seismogram object.

  • clone (bool, default: False ) –

    Operate on a clone of the input seismogram.

Returns:

  • None | T –

    Detrended Seismogram object if called with clone=True.

Examples:

>>> import numpy as np
>>> import pytest
>>> from pysmo.functions detrend
>>> from pysmo.classes import SAC
>>> sac_seis = SAC.from_file('testfile.sac').seismogram
>>> assert 0 == pytest.approx(np.mean(sac_seis.data), abs=1e-11)
False
>>> detrend(sac_seis)
>>> assert 0 == pytest.approx(np.mean(sac_seis.data), abs=1e-11)
True
Source code in pysmo/functions/_seismogram.py 
 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
def detrend[T: Seismogram](seismogram: T, clone: bool = False) -> None | T:
    """Remove linear and/or constant trends from a seismogram.

    Parameters:
        seismogram: Seismogram object.
        clone: Operate on a clone of the input seismogram.

    Returns:
        Detrended [`Seismogram`][pysmo.Seismogram] object if called with `clone=True`.

    Examples:
        >>> import numpy as np
        >>> import pytest
        >>> from pysmo.functions detrend
        >>> from pysmo.classes import SAC
        >>> sac_seis = SAC.from_file('testfile.sac').seismogram
        >>> assert 0 == pytest.approx(np.mean(sac_seis.data), abs=1e-11)
        False
        >>> detrend(sac_seis)
        >>> assert 0 == pytest.approx(np.mean(sac_seis.data), abs=1e-11)
        True
    """
    if clone is True:
        seismogram = deepcopy(seismogram)

    seismogram.data = scipy.signal.detrend(seismogram.data)

    if clone is True:
        return seismogram

    return None

normalize #

normalize(seismogram: T, clone: bool = False, t1: datetime | None = None, t2: datetime | None = None) -> None | T

Normalize a seismogram with its absolute max value.

Parameters:

  • seismogram (T) –

    Seismogram object.

  • clone (bool, default: False ) –

    Operate on a clone of the input seismogram.

  • t1 (datetime | None, default: None ) –

    Optionally restrict searching of maximum to time after this time.

  • t2 (datetime | None, default: None ) –

    Optionally restrict searching of maximum to time before this time.

Returns:

  • None | T –

    Normalized Seismogram object if clone=True.

Examples:

>>> import numpy as np
>>> from pysmo.functions import normalize
>>> from pysmo.classes import SAC
>>> sac_seis = SAC.from_file('testfile.sac').seismogram
>>> normalize(sac_seis)
>>> assert np.max(sac_seis.data) <= 1
True
Source code in pysmo/functions/_seismogram.py 
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def normalize[T: Seismogram](
    seismogram: T,
    clone: bool = False,
    t1: datetime | None = None,
    t2: datetime | None = None,
) -> None | T:
    """Normalize a seismogram with its absolute max value.

    Parameters:
        seismogram: Seismogram object.
        clone: Operate on a clone of the input seismogram.
        t1: Optionally restrict searching of maximum to time after this time.
        t2: Optionally restrict searching of maximum to time before this time.

    Returns:
        Normalized [`Seismogram`][pysmo.Seismogram] object if `clone=True`.

    Examples:
        >>> import numpy as np
        >>> from pysmo.functions import normalize
        >>> from pysmo.classes import SAC
        >>> sac_seis = SAC.from_file('testfile.sac').seismogram
        >>> normalize(sac_seis)
        >>> assert np.max(sac_seis.data) <= 1
        True
    """

    if clone is True:
        seismogram = deepcopy(seismogram)

    start_index = None
    if t1 is not None:
        start_index = time2index(seismogram, t1, "floor")

    end_index = None
    if t2 is not None:
        end_index = time2index(seismogram, t2, "ceil")

    seismogram.data /= np.max(np.abs(seismogram.data[start_index:end_index]))

    if clone is True:
        return seismogram

    return None

resample #

resample(seismogram: T, delta: timedelta, clone: bool = False) -> None | T

Resample Seismogram object data using the Fourier method.

Parameters:

  • seismogram (T) –

    Seismogram object.

  • delta (timedelta) –

    New sampling interval.

  • clone (bool, default: False ) –

    Operate on a clone of the input seismogram.

Returns:

  • None | T –

    Resampled Seismogram object if called with clone=True.

Examples:

>>> from pysmo.functions import resample
>>> from pysmo.classes import SAC
>>> sac_seis = SAC.from_file('testfile.sac').seismogram
>>> len(sac_seis)
180000
>>> original_delta = sac_seis.delta
>>> new_delta = original_delta * 2
>>> resample(sac_seis, new_delta)
>>> len(sac_seis)
90000
Source code in pysmo/functions/_seismogram.py 
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
def resample[T: Seismogram](
    seismogram: T, delta: timedelta, clone: bool = False
) -> None | T:
    """Resample Seismogram object data using the Fourier method.

    Parameters:
        seismogram: Seismogram object.
        delta: New sampling interval.
        clone: Operate on a clone of the input seismogram.

    Returns:
        Resampled [`Seismogram`][pysmo.Seismogram] object if called with `clone=True`.

    Examples:
        >>> from pysmo.functions import resample
        >>> from pysmo.classes import SAC
        >>> sac_seis = SAC.from_file('testfile.sac').seismogram
        >>> len(sac_seis)
        180000
        >>> original_delta = sac_seis.delta
        >>> new_delta = original_delta * 2
        >>> resample(sac_seis, new_delta)
        >>> len(sac_seis)
        90000
    """

    if clone is True:
        seismogram = deepcopy(seismogram)

    npts = int(len(seismogram) * seismogram.delta / delta)
    seismogram.data = scipy.signal.resample(seismogram.data, npts)
    seismogram.delta = delta

    if clone is True:
        return seismogram

    return None

time2index #

time2index(seismogram: Seismogram, time: datetime, method: Literal['round', 'ceil', 'floor'] = 'round') -> int

Retuns data index corresponding to a given time.

This function converts time to index of a seismogram's data array. In most cases the time will not have an exact match in the data array. This function allows choosing how to select the index to return when that is the case with the method parameter:

  • round: round to nearest index.
  • ceil: always round up to next higher index.
  • floor: always round down to next lower index.

Parameters:

  • seismogram (Seismogram) –

    Seismogram object.

  • time (datetime) –

    Time to convert to index.

  • method (Literal['round', 'ceil', 'floor'], default: 'round' ) –

    Method to use for selecting the index to return.

Returns:

  • int –

    Index of the sample corresponding to the given time.

Source code in pysmo/functions/_seismogram.py 
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
def time2index(
    seismogram: Seismogram,
    time: datetime,
    method: Literal["round", "ceil", "floor"] = "round",
) -> int:
    """Retuns data index corresponding to a given time.

    This function converts time to index of a seismogram's data array. In most
    cases the time will not have an exact match in the data array. This
    function allows choosing how to select the index to return when that is
    the case with the method parameter:

    - round: round to nearest index.
    - ceil: always round up to next higher index.
    - floor: always round down to next lower index.

    Parameters:
        seismogram: Seismogram object.
        time: Time to convert to index.
        method: Method to use for selecting the index to return.

    Returns:
        Index of the sample corresponding to the given time.
    """

    if not seismogram.begin_time <= time <= seismogram.end_time:
        raise ValueError("time must be between begin_time and end_time")

    if method not in ["round", "ceil", "floor"]:
        raise ValueError("method must be 'round', 'ceil' or 'floor'")

    if method == "ceil":
        return ceil((time - seismogram.begin_time) / seismogram.delta)

    if method == "floor":
        return floor((time - seismogram.begin_time) / seismogram.delta)

    return round((time - seismogram.begin_time) / seismogram.delta)