3.3. anisotropy.util

Module that supplies various utility functions and classes.

copyright

2021–2022, AnisotroPy developers.

license

GNU General Public License, Version 3 (https://www.gnu.org/licenses/gpl-3.0.html)

exception anisotropy.util.ArchiveEmptyException[source]

Bases: Exception

Custom exception to handle empty archive

exception anisotropy.util.ArchiveFormatException[source]

Bases: Exception

Custom exception to handle case where Archive.format is not set.

exception anisotropy.util.ArchivePathStructureError(archive_format)[source]

Bases: Exception

Custom exception to handle case where an invalid Archive path structure is selected.

exception anisotropy.util.BadUpfactorException(trace)[source]

Bases: Exception

Custom exception to handle case when the chosen upfactor does not create a trace with a sampling rate that can be decimated to the target sampling rate

exception anisotropy.util.ChannelNameException(trace)[source]

Bases: Exception

Custom exception to handle case when waveform data header has channel names which do not conform to the IRIS SEED standard.

exception anisotropy.util.DataGapException[source]

Bases: Exception

Custom exception to handle case when all data has gaps for a given timestep

class anisotropy.util.DateFormatter(fmt, precision=3)[source]

Bases: matplotlib.ticker.Formatter

Extend the matplotlib.ticker.Formatter class to allow for millisecond precision when formatting a tick (in days since the epoch) with a datetime.datetime.strftime format string.

exception anisotropy.util.NyquistException(freqmax, f_nyquist, tr_id)[source]

Bases: Exception

Custom exception to handle the case where the specified filter has a lowpass corner above the signal Nyquist frequency.

Parameters

  • freqmax (float) – Specified lowpass frequency for filter

  • f_nyquist (float) – Nyquist frequency for the relevant waveform data

  • tr_id (str) – ID string for the Trace

exception anisotropy.util.ResponseNotFoundError(e, tr_id)[source]

Bases: Exception

Custom exception to handle the case where the provided response inventory doesn’t contain the response information for a trace.

Parameters

  • e (str) – Error message from ObsPy Inventory.get_response()

  • tr_id (str) – ID string for the Trace for which the response cannot be found

exception anisotropy.util.ResponseRemovalError(e, tr_id)[source]

Bases: Exception

Custom exception to handle the case where the response removal was not successful.

Parameters

  • e (str) – Error message from ObsPy Trace.remove_response() or Trace.simulate()

  • tr_id (str) – ID string for the Trace for which the response cannot be removed

exception anisotropy.util.TimeSpanException[source]

Bases: Exception

Custom exception to handle case when the user has submitted a start time that is after the end time.

anisotropy.util.azinc2vec(ψ, θ)[source]

Return a 3-vector with the direction defined by (ψ, θ)

Parameters

  • ψ (float) – Azimuth from x1 towards x2. Units of degrees.

  • θ (float) – Inclination from the x1-x2 plane towards x3. Units of degrees.

Returns

x – Vector pointing along (ψ, θ).

Return type

array

anisotropy.util.decimate(trace, sampling_rate)[source]

Decimate a trace to achieve the desired sampling rate, sr.

NOTE: data will be detrended and a cosine taper applied before decimation, in order to avoid edge effects when applying the lowpass filter before decimating.

traceobspy.Trace object

Trace to be decimated.

sampling_rateint

Output sampling rate.

traceobspy.Trace object

Decimated trace.

anisotropy.util.logger(logstem, log, loglevel='info')[source]

Simple logger that will output to both a log file and stdout.

Parameters

  • logstem (str) – Filestem for log file.

  • log (bool) – Toggle for logging - default is to only print information to stdout. If True, will also create a log file.

  • loglevel (str, optional) – Toggle for logging level - default is to print only “info” messages to log. To print more detailed “debug” messages, set to “debug”.

anisotropy.util.make_directories(run, subdir=None)[source]

Make run directory, and optionally make subdirectories within it.

Parameters

  • run (pathlib.Path object) – Location of parent output directory, named by run name.

  • subdir (str, optional) – subdir to make beneath the run level.

anisotropy.util.pairwise(iterable)[source]

Utility to iterate over an iterable pairwise.

anisotropy.util.resample(stream, sampling_rate, resample, upfactor, starttime, endtime)[source]

Resample data in an obspy.Stream object to the specified sampling rate.

By default, this function will only perform decimation of the data. If necessary, and if the user specifies resample = True and an upfactor to upsample by upfactor = int, data can also be upsampled and then, if necessary, subsequently decimated to achieve the desired sampling rate.

For example, for raw input data sampled at a mix of 40, 50 and 100 Hz, to achieve a unified sampling rate of 50 Hz, the user would have to specify an upfactor of 5; 40 Hz x 5 = 200 Hz, which can then be decimated to 50 Hz.

NOTE: assumes any data with off-sample timing has been corrected with shift_to_sample(). If not, the resulting traces may not all contain the correct number of samples.

NOTE: data will be detrended and a cosine taper applied before decimation, in order to avoid edge effects when applying the lowpass filter.

Parameters

  • stream (obspy.Stream object) – Contains list of obspy.Trace objects to be decimated / resampled.

  • resample (bool) – If true, perform resampling of data which cannot be decimated directly to the desired sampling rate.

  • upfactor (int or None) – Factor by which to upsample the data to enable it to be decimated to the desired sampling rate, e.g. 40Hz -> 50Hz requires upfactor = 5.

Returns

stream – Contains list of resampled obspy.Trace objects at the chosen sampling rate sr.

Return type

obspy.Stream object

anisotropy.util.rotate2xy(vector, azimuth, inclination)[source]

Rotate a 3-vector into the x-y plane.

Parameters

  • azimuth (list of float or float) – Azimuth, ψ, from x1 towards x2, in degrees.

  • inclination (list of float or float) – Inclination, θ, from the x1-x2 plane towards x3, in degrees.

Returns

x – Vector within the x-y plane.

Return type

array

anisotropy.util.shift_to_sample(stream, interpolate=False)[source]

Check whether any data in an obspy.Stream object is “off-sample” - i.e. the data timestamps are not an integer number of samples after midnight. If so, shift data to be “on-sample”.

This can either be done by shifting the timestamps by a sub-sample time interval, or interpolating the trace to the “on-sample” timestamps. The latter has the benefit that it will not affect the timing of the data, but will require additional computation time and some inevitable edge effects - though for onset calculation these should be contained within the pad windows. If you are using a sampling rate < 10 Hz, contact the AnisotroPy developers.

Parameters

  • stream (obspy.Stream object) – Contains list of obspy.Trace objects for which to check the timing.

  • interpolate (bool, optional) – Whether to interpolate the data to correct the “off-sample” timing. Otherwise, the metadata will simply be altered to shift the timestamps “on-sample”; this will lead to a sub-sample timing offset.

Returns

stream – Waveform data with all timestamps “on-sample”.

Return type

obspy.Stream object

anisotropy.util.time2sample(time, sampling_rate)[source]

Utility function to convert from seconds and sampling rate to number of samples.

Parameters

  • time (float) – Time to convert

  • sampling_rate (int) – Sampling rate of input data/sampling rate at which to compute the coalescence function.

Returns

out – Time that correpsonds to an integer number of samples at a specific sampling rate.

Return type

int

anisotropy.util.timeit(*args_, **kwargs_)[source]

Function wrapper that measures the time elapsed during its execution.

anisotropy.util.trim2sample(time, sampling_rate)[source]

Utility function to ensure time padding results in a time that is an integer number of samples.

Parameters

  • time (float) – Time to trim.

  • sampling_rate (int) – Sampling rate of input data/sampling rate at which to compute the coalescence function.

Returns

out – Time that corresponds to an integer number of samples at a specific sampling rate.

Return type

int

anisotropy.util.upsample(trace, upfactor, starttime, endtime)[source]

Upsample a data stream by a given factor, prior to decimation. The upsampling is carried out by linear interpolation.

NOTE: assumes any data with off-sample timing has been corrected with shift_to_sample(). If not, the resulting traces may not all contain the correct number of samples (and desired start and end times).

Parameters

  • trace (obspy.Trace object) – Trace to be upsampled.

  • upfactor (int) – Factor by which to upsample the data in trace.

Returns

out – Upsampled trace.

Return type

obpsy.Trace object

3.3.1. anisotropy.util.util