Utility Functions (seislib.utils)

This module provides support for several useful functions for processing and analysing seismic data. These mainly build on ObsPy, and include:

  • Vectorized calculation of great-circle distances, azimuths, and back azimuths

  • Slicing / resampling of pairs of seismograms so as to adapt them to a common time window / sampling rate

  • Pre-processing operations such as zero-padding and bandpass filtering

  • Rotation of horizontal-component recordings to an arbitrary amount of degrees. SeisLib’s implementation also takes into account not uncommon ValueErrors raised by ObsPy due to the presence of slightly (sub-sample) differences in the time spanned by the two traces

  • Interpolation of scattered data on equal-area grids

  • Calculation of the Pearson correlation coefficient between physical parameters defined on equal-area grids

seislib.utils.utils.adapt_sampling_rate(st1, st2)

If the input streams (or traces) have different sampling rates, the one characterized by the largest sampling rate is downsampled to the sampling rate of the other stream (or trace).

The downsampling is carried out via the resample(), which modifies the input streams in place.

Parameters
st1, st2obspy.Stream, obspy.Trace
Returns
st1, st2obspy.Stream, obspy.Trace

Obspy stream or trace depending on the input. The input is permanently modified

seislib.utils.utils.adapt_timespan(st1, st2)

Slices all traces from the two input streams to the overlapping timerange. Then returns a copy of the sliced streams.

Parameters
st1, st2obspy.Stream, obspy.Trace
Returns
st1, st2obspy.Stream, obspy.Trace

Obspy stream or trace depending on the input. The original input is not permanently modified (a copy is returned)

Raises
TimeSpanException

If no overlap is available

Notes

The maximum precision achieved by this function is governed by the samling rate. If sub-sample precision is required, consider using adapt_timespan_interpolate()

seislib.utils.utils.adapt_timespan_interpolate(st1, st2, min_overlap=0)

Slices all traces from the two input streams to the overlapping timerange. Then returns a copy of the sliced streams. If the starttime of the sliced traces do not fit exactly (because of sub-sample time shifts), the traces are interpolated to remove the time shift.

Parameters
st1, st2obspy.Stream, obspy.Trace
Returns
st1_out, st2_outobspy.Stream, obspy.Trace

Obspy stream or trace depending on the input. The original input is not permanently modified (a copy is returned)

Raises
TimeSpanException

If no overlap is available

Notes

Interpolation can require a relatively long time depending on the size of the sliced stream. If speed is preferred to (sub-sample) precision, consider using adapt_timespan()

seislib.utils.utils.azimuth_backazimuth(lat1, lon1, lat2, lon2)

Calculates the azimuth and backazimuth (in degrees) between coordinate points (in degrees). This function calls directly the obspy gps2dist_azimuth, it only extends its functionality through the numpy.vectorize decorator

Parameters
lat1, lon1, lat2, lon2float or array-like of shape (n,)

Coordinates of the points on the Earth’s surface, in degrees.

Returns
tuple of shape (2,) or ndarray of shape (n, 2)

The columns consist of azimuth azimuth and backazimuth

seislib.utils.utils.bandpass_gaussian(data, dt, period, alpha)

Gaussian filter of real-valued data carried out in the frequency domain

The bandpass filter is carried out with a Gaussian filter centered at period, whose width is controlled by alpha:

exp(-alpha * ((f-f0)/f0)**2)

where f is frequency and f0 = 1 / period.

Parameters
datandarray of shape (n,)

Real-valued data to be filtered

dtfloat

Time sampling interval of the data

periodfloat

Central period, around which the (tight) bandapass filter is carried out

alphafloat

Parameter that controls the width of the Gaussian filter

Returns
numpy.ndarray of shape (n,)

Filtered data

seislib.utils.utils.gc_distance(lat1, lon1, lat2, lon2)

Calculates the great circle distance (in m) between coordinate points (in degrees). This function calls directly the obspy gps2dist_azimuth, it only extends its functionality through the numpy.vectorize decorator.

Parameters
lat1, lon1, lat2, lon2float or array-like of shape (n,)

Coordinates of the points on the Earth’s surface, in degrees.

Returns
Great-circle distance (in m)

If the input is an array (or list) of coordinates, an array of distances is returned

seislib.utils.utils.load_pickle(path)

Loads a .pickle file

Parameters
pathstr

Absolute path to the file

Returns
Object contained in the .pickle file
seislib.utils.utils.next_power_of_2(x)

Closest power of two larger or equal to x

Parameters
xint
Returns
int
seislib.utils.utils.pearson_corrcoef(v1, v2)

Pearson coerrelation coefficient between two vectors

Parameters
v1, v2lists or ndarrays (n,)
Returns
corrcoefffloat

Pearson correlation coefficient

pvaluefloat
Raises
ValueError

If v1 and v2 have different shapes

Notes

This function calls scipy.stats.pearsonr, bu handles the presence of nan values.

seislib.utils.utils.remove_file(file)

Removes a file from disk, handling eventual exceptions

Parameters
filestr

Absolute path to the file to be removed

seislib.utils.utils.resample(x, fs)

If the input streams (or traces) have different sampling rates, the one characterized by the largest sampling rate is downsampled to the sampling rate of the other stream (or trace).

Parameters
st1, st2obspy.Stream, obspy.Trace
Returns
st1, st2obspy.Stream, obspy.Trace

Obspy stream or trace depending on the input. The input is permanently modified

seislib.utils.utils.rotate(r, t, dphi)

Rotation of radial and transverse component of the seismogram by a specified angle, following the obspy signs convention.

Parameters
r, tnumpy.ndarray

Radial (r) and transverse (t) components

dphifloat

Angle in degrees

Returns
rnew, tnewnumpy.ndarray

Rotated components

seislib.utils.utils.rotate_stream(st, **kwargs)

The method calls the obspy.Stream.rotate method, which sometimes runs into errors if differences are present among the starttimes and/or endtimes of the traces constituting the stream. These are prevented by slicing the stream to a common time window and (if necessary) interpolating it so as to avoid sub-sample differences.

Parameters
stobspy.Stream
**kwargs

Optional arguments passed to obspy.Stream.rotate

Returns
stobspy.Stream

Rotated copy of the input Stream

seislib.utils.utils.running_mean(x, N)

Moving average

Parameters
xndarray of shape (m,)

Data vector

Nint

Controls the extent of the smoothing (larger values correspond to larger smoothing)

Returns
runmeanndarray of shape (m,)

Smoothed input

Notes

This is a simple implementation of a moving average. More sofisticated functions can be found, e.g., in scipy.signal.savgol_filter or scipy.ndimage.filters.uniform_filter1d

seislib.utils.utils.save_pickle(file, obj)

Saves an object to a .pickle file

Parameters
filestr

Absolute path to the resulting file

objpython object

Object to be saved (see documentation on the pickle module to know more on which Python objects can be stored into .pickle files)

seislib.utils.utils.scatter_to_mesh(lats, lons, c, mesh, method='linear')

Translates scattered data into a seislib mesh

Parameters
lats, lonsndarray (n,)

Coordinates of the scattered data

cndarray (n,)

Values of the scattered data

meshndarray (m, 4)

mesh in SeisLib’s format, where the four columns correspond to the boundaries of each pixel, i.e., lat1, lat2, lon1, lon2

method{‘linear’, ‘nearest’, ‘cubic’}

Interpolation method. Supported: ‘linear’ (default), ‘nearest’, and ‘cubic’. The three methods call LinearNDInterpolator, NearestNDInterpolator, and CloughTocher2DInterpolator of the scipy.interpolate module, respectively.

Returns
1-D ndarray containing the c values interpolated on mesh
Raises
NotImplementedError

If method is not supported

seislib.utils.utils.zeropad(tr, starttime, endtime)

Zeropads an obspy.Trace so as to cover the time window specified by starttime’and endtime

Parameters
trobspy.Trace
starttime, endtimeobspy.UTCDateTime
Returns
traceobspy.Trace

Zeropadded copy of the input trace.