Skip to content

Functions#

Pysmo provides functions that perform common operations on the types of data that match pysmo's types.

azimuth(point1, point2, ellps=DEFAULT_ELLPS) #

Calculate azimuth between two points.

info

For more information see: https://pyproj4.github.io/pyproj/stable

Parameters:

Name Type Description Default
point1 Location

Name of the event object providing coordinates of the origin point.

 required
point2 Location

Name of the station object providing coordinates of the target point.

 required
ellps str

Ellipsoid to use for azimuth calculation

 DEFAULT_ELLPS

Returns:

Type Description
float

Azimuth in degrees from point 1 to point 2.

Examples:

>>> from pysmo import SAC, azimuth
>>> sacobj = SAC.from_file('testfile.sac')
>>> # the SAC class provides both event and station
>>> azimuth(sacobj.event, sacobj.station)
181.9199258637492
>>> # Use Clarke 1966 instead of default
>>> azimuth(sacobj.event, sacobj.station, ellps='clrk66')
181.92001941872516
Source code in pysmo/functions.py 
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def azimuth(point1: Location, point2: Location, ellps: str = DEFAULT_ELLPS) -> float:
    """Calculate azimuth between two points.

    info:
        For more information see: <https://pyproj4.github.io/pyproj/stable>

    Parameters:
        point1: Name of the event object providing coordinates of the origin point.
        point2: Name of the station object providing coordinates of the target point.
        ellps: Ellipsoid to use for azimuth calculation

    Returns:
        Azimuth in degrees from point 1 to point 2.

    Examples:
        >>> from pysmo import SAC, azimuth
        >>> sacobj = SAC.from_file('testfile.sac')
        >>> # the SAC class provides both event and station
        >>> azimuth(sacobj.event, sacobj.station)
        181.9199258637492
        >>> # Use Clarke 1966 instead of default
        >>> azimuth(sacobj.event, sacobj.station, ellps='clrk66')
        181.92001941872516
    """
    return _azdist(
        lat1=point1.latitude,
        lon1=point1.longitude,
        lat2=point2.latitude,
        lon2=point2.longitude,
        ellps=ellps,
    )[0]

backazimuth(point1, point2, ellps=DEFAULT_ELLPS) #

Calculate backazimuth (in DEG) between two points.

info

For more information see: https://pyproj4.github.io/pyproj/stable

Parameters:

Name Type Description Default
point1 Location

Name of the event object providing coordinates of the origin point.

 required
point2 Location

Name of the station object providing coordinates of the target point.

 required
ellps str

Ellipsoid to use for azimuth calculation

 DEFAULT_ELLPS

Returns:

Type Description
float

Backzimuth in degrees from point 2 to point 1

Examples:

>>> from pysmo import SAC, backazimuth
>>> sacobj = SAC.from_file('testfile.sac')
>>> # the SAC class provides both event and station
>>> backazimuth(sacobj.event, sacobj.station)
2.4677533885335947
>>> # Use Clarke 1966 instead of default
>>> backazimuth(sacobj.event, sacobj.station, ellps='clrk66')
2.467847115319614
Source code in pysmo/functions.py 
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
241
242
243
244
245
246
247
def backazimuth(
    point1: Location, point2: Location, ellps: str = DEFAULT_ELLPS
) -> float:
    """Calculate backazimuth (in DEG) between two points.

    info:
        For more information see: <https://pyproj4.github.io/pyproj/stable>

    Parameters:
        point1: Name of the event object providing coordinates of the origin point.
        point2: Name of the station object providing coordinates of the target point.
        ellps: Ellipsoid to use for azimuth calculation

    Returns:
        Backzimuth in degrees from point 2 to point 1

    Examples:
        >>> from pysmo import SAC, backazimuth
        >>> sacobj = SAC.from_file('testfile.sac')
        >>> # the SAC class provides both event and station
        >>> backazimuth(sacobj.event, sacobj.station)
        2.4677533885335947
        >>> # Use Clarke 1966 instead of default
        >>> backazimuth(sacobj.event, sacobj.station, ellps='clrk66')
        2.467847115319614
    """
    return _azdist(
        lat1=point1.latitude,
        lon1=point1.longitude,
        lat2=point2.latitude,
        lon2=point2.longitude,
        ellps=ellps,
    )[1]

detrend(seismogram) #

Remove linear and/or constant trends from a seismogram.

Parameters:

Name Type Description Default
seismogram Seismogram

Seismogram object.

 required

Returns:

Type Description
MiniSeismogram

Detrended seismogram.
Note

This function is also available as a method in the MiniSeismogram class. Thus, if you intend detrending data of a MiniSeismogram object in-place, instead of writing:

my_seis.data = detrend(my_seis)

you should instead use:

my_seis.detrend()

Examples:

>>> import numpy as np
>>> import pytest
>>> from pysmo import SAC, detrend
>>> original_seis = SAC.from_file('testfile.sac').seismogram
>>> assert 0 == pytest.approx(np.mean(original_seis.data), abs=1e-11)
False
>>> detrended_seis = detrend(original_seis)
>>> assert 0 == pytest.approx(np.mean(detrended_seis.data), abs=1e-11)
True
Source code in pysmo/functions.py 
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
88
89
90
91
92
def detrend(seismogram: Seismogram) -> MiniSeismogram:
    """Remove linear and/or constant trends from a seismogram.

    Parameters:
        seismogram: Seismogram object.

    Returns:
        Detrended seismogram.

    Note:
        This function is also available as a method in the
        [MiniSeismogram][pysmo.classes.mini.MiniSeismogram]
        class. Thus, if you intend detrending data of a
        MiniSeismogram object **in-place**, instead of
        writing:

        ```python
        my_seis.data = detrend(my_seis)
        ```

        you should instead use:

        ```python
        my_seis.detrend()
        ```

    Examples:
        >>> import numpy as np
        >>> import pytest
        >>> from pysmo import SAC, detrend
        >>> original_seis = SAC.from_file('testfile.sac').seismogram
        >>> assert 0 == pytest.approx(np.mean(original_seis.data), abs=1e-11)
        False
        >>> detrended_seis = detrend(original_seis)
        >>> assert 0 == pytest.approx(np.mean(detrended_seis.data), abs=1e-11)
        True
    """
    clone = MiniSeismogram.clone(seismogram, skip_data=True)
    clone.data = _detrend(seismogram)
    return clone

distance(point1, point2, ellps=DEFAULT_ELLPS) #

Calculate the great circle distance (in metres) between two points.

info

For more information see: https://pyproj4.github.io/pyproj/stable

Parameters:

Name Type Description Default
point1 Location

Name of the event object providing coordinates of the origin point.

 required
point2 Location

Name of the station object providing coordinates of the target point.

 required
ellps str

Ellipsoid to use for distance calculation

 DEFAULT_ELLPS

Returns:

Type Description
float

Great Circle Distance in metres.

Examples:

>>> from pysmo import SAC, distance
>>> sacobj = SAC.from_file('testfile.sac')
>>> # the SAC class provides both event and station
>>> distance(sacobj.event, sacobj.station)
1889154.9940066522
>>> # Use Clarke 1966 instead of default
>>> distance(sacobj.event, sacobj.station, ellps='clrk66')
1889121.778136402
Source code in pysmo/functions.py 
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 distance(point1: Location, point2: Location, ellps: str = DEFAULT_ELLPS) -> float:
    """Calculate the great circle distance (in metres) between two points.

    info:
        For more information see: <https://pyproj4.github.io/pyproj/stable>

    Parameters:
        point1: Name of the event object providing coordinates of the origin point.
        point2: Name of the station object providing coordinates of the target point.
        ellps: Ellipsoid to use for distance calculation

    Returns:
        Great Circle Distance in metres.

    Examples:
        >>> from pysmo import SAC, distance
        >>> sacobj = SAC.from_file('testfile.sac')
        >>> # the SAC class provides both event and station
        >>> distance(sacobj.event, sacobj.station)
        1889154.9940066522
        >>> # Use Clarke 1966 instead of default
        >>> distance(sacobj.event, sacobj.station, ellps='clrk66')
        1889121.778136402
    """
    return _azdist(
        lat1=point1.latitude,
        lon1=point1.longitude,
        lat2=point2.latitude,
        lon2=point2.longitude,
        ellps=ellps,
    )[2]

normalize(seismogram) #

Normalize a seismogram with its absolute max value

Parameters:

Name Type Description Default
seismogram Seismogram

Seismogram object.

 required

Returns:

Type Description
MiniSeismogram

Normalized seismogram.
Note

This function is also available as a method in the MiniSeismogram class. Thus, if you intend normalizing data of a MiniSeismogram object in-place, instead of writing:

my_seis.data = normalize(my_seis)

you should instead use:

my_seis.normalize()

Examples:

>>> import numpy as np
>>> from pysmo import SAC, normalize
>>> original_seis = SAC.from_file('testfile.sac').seismogram
>>> normalized_seis = normalize(original_seis)
>>> assert np.max(normalized_seis.data) <= 1
True
Source code in pysmo/functions.py 
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
def normalize(seismogram: Seismogram) -> MiniSeismogram:
    """Normalize a seismogram with its absolute max value

    Parameters:
        seismogram: Seismogram object.

    Returns:
        Normalized seismogram.

    Note:
        This function is also available as a method in the
        [MiniSeismogram][pysmo.classes.mini.MiniSeismogram]
        class. Thus, if you intend normalizing data of a
        MiniSeismogram object **in-place**, instead of
        writing:

        ```python
        my_seis.data = normalize(my_seis)
        ```

        you should instead use:

        ```python
        my_seis.normalize()
        ```

    Examples:
        >>> import numpy as np
        >>> from pysmo import SAC, normalize
        >>> original_seis = SAC.from_file('testfile.sac').seismogram
        >>> normalized_seis = normalize(original_seis)
        >>> assert np.max(normalized_seis.data) <= 1
        True
    """
    clone = MiniSeismogram.clone(seismogram, skip_data=True)
    clone.data = _normalize(seismogram)
    return clone

plotseis(*seismograms, outfile='', showfig=True, title='', **kwargs) #

Plot Seismogram objects.

Parameters:

Name Type Description Default
seismograms Seismogram

One or more seismogram objects. If a 'label' attribute is found it will be used to label the trace in the plot.

 ()
outfile str

Optionally save figure to this filename.

 ''
showfig bool

Display figure.

 True
title str

Optionally set figure title.

 ''
kwargs dict

Optionally add kwargs to pass to the plot command

 {}

Examples:

>>> from pysmo import SAC, plotseis
>>> seis = SAC.from_file('testfile.sac').seismogram
>>> plotseis(seis)
Source code in pysmo/functions.py 
139
140
141
142
143
144
145
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
def plotseis(
    *seismograms: Seismogram,
    outfile: str = "",
    showfig: bool = True,
    title: str = "",
    **kwargs: dict,
) -> matplotlib.figure.Figure:
    """Plot Seismogram objects.

    Parameters:
        seismograms: One or more seismogram objects. If a 'label' attribute is found
                     it will be used to label the trace in the plot.
        outfile: Optionally save figure to this filename.
        showfig: Display figure.
        title: Optionally set figure title.
        kwargs: Optionally add kwargs to pass to the plot command

    Examples:
        >>> from pysmo import SAC, plotseis
        >>> seis = SAC.from_file('testfile.sac').seismogram
        >>> plotseis(seis)
    """
    fig = plt.figure()
    for seis in seismograms:
        start = mdates.date2num(seis.begin_time)
        end = mdates.date2num(seis.end_time)
        time = np.linspace(start, end, len(seis))
        plt.plot(time, seis.data, scalex=True, scaley=True, **kwargs)
    plt.xlabel("Time")
    plt.gcf().autofmt_xdate()
    fmt = mdates.DateFormatter("%H:%M:%S")
    plt.gca().xaxis.set_major_formatter(fmt)
    if not title:
        left, _ = plt.xlim()
        title = mdates.num2date(left).strftime("%Y-%m-%d %H:%M:%S")
    plt.title(title)
    if outfile:
        plt.savefig(outfile)
    if showfig:
        plt.show()
    return fig

resample(seismogram, delta) #

Resample Seismogram object data using the Fourier method.

Parameters:

Name Type Description Default
seismogram Seismogram

Seismogram object.

 required
delta float

New sampling interval.

 required

Returns:

Type Description
MiniSeismogram

Resampled seismogram.
Note

This function is also available as a method in the MiniSeismogram class. Thus, if you intend resampling data of a MiniSeismogram object in-place, instead of writing:

my_seis.data = resample(my_seis)

you should instead use:

my_seis.resample()

Examples:

>>> from pysmo import SAC, resample
>>> original_seis = SAC.from_file('testfile.sac').seismogram
>>> len(original_seis)
180000
>>> original_delta = original_seis.delta
>>> new_delta = original_delta * 2
>>> resampled_seis = resample(original_seis, new_delta)
>>> len(resampled_seis)
90000
Source code in pysmo/functions.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
126
127
128
129
130
131
132
133
134
135
136
def resample(seismogram: Seismogram, delta: float) -> MiniSeismogram:
    """Resample Seismogram object data using the Fourier method.

    Parameters:
        seismogram: Seismogram object.
        delta: New sampling interval.

    Returns:
        Resampled seismogram.

    Note:
        This function is also available as a method in the
        [MiniSeismogram][pysmo.classes.mini.MiniSeismogram]
        class. Thus, if you intend resampling data of a
        MiniSeismogram object **in-place**, instead of
        writing:

        ```python
        my_seis.data = resample(my_seis)
        ```

        you should instead use:

        ```python
        my_seis.resample()
        ```

    Examples:
        >>> from pysmo import SAC, resample
        >>> original_seis = SAC.from_file('testfile.sac').seismogram
        >>> len(original_seis)
        180000
        >>> original_delta = original_seis.delta
        >>> new_delta = original_delta * 2
        >>> resampled_seis = resample(original_seis, new_delta)
        >>> len(resampled_seis)
        90000
    """
    clone = MiniSeismogram.clone(seismogram, skip_data=True)
    clone.data = _resample(seismogram, delta)
    clone.delta = delta
    return clone