3.7. quakemigrate.util

Module that supplies various utility functions and classes.

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

exception quakemigrate.util.ArchiveEmptyException

Bases: Exception

Custom exception to handle empty archive

exception quakemigrate.util.ArchiveFormatException

Bases: Exception

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

exception quakemigrate.util.ArchivePathStructureError(archive_format)

Bases: Exception

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

exception quakemigrate.util.BadUpfactorException(trace)

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 quakemigrate.util.ChannelNameException(trace)

Bases: Exception

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

exception quakemigrate.util.DataGapException

Bases: Exception

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

class quakemigrate.util.DateFormatter(fmt, precision=3)

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 quakemigrate.util.InvalidThresholdMethodException

Bases: Exception

Custom exception to handle case when the user has not selected a valid threshold method.

exception quakemigrate.util.InvalidVelocityModelHeader(key)

Bases: Exception

Custom exception to handle incorrect header columns in station file

exception quakemigrate.util.MagsTypeError

Bases: Exception

Custom exception to handle case when an object has been provided to calculate magnitudes during locate, but it isn’t supported.

exception quakemigrate.util.NoScanMseedDataException

Bases: Exception

Custom exception to handle case when no .scanmseed files can be found by read_coastream()

exception quakemigrate.util.NoStationAvailabilityDataException

Bases: Exception

Custom exception to handle case when no .StationAvailability files can be found by read_availability()

exception quakemigrate.util.NoTriggerFilesFound

Bases: Exception

Custom exception to handle case when no trigger files are found during locate. This can occur for one of two reasons - an entirely invalid time period was used (i.e. one that does not overlap at all with a period of time for which there exists TriggeredEvents.csv files) or an invalid run name was provided.

exception quakemigrate.util.NyquistException(freqmax, f_nyquist, tr_id)

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 quakemigrate.util.OnsetTypeError

Bases: Exception

Custom exception to handle case when the onset object passed to QuakeScan is not of the default type defined in QuakeMigrate.

exception quakemigrate.util.PeakToTroughError(err)

Bases: Exception

Custom exception to handle case when amplitude._peak_to_trough_amplitude encounters an anomalous set of peaks and troughs, so can’t calculate an amplitude.

exception quakemigrate.util.PickOrderException(event_uid, station, p_pick, s_pick)

Bases: Exception

Custom exception to handle the case when the pick for the P phase is later than the pick for the S phase.

exception quakemigrate.util.PickerTypeError

Bases: Exception

Custom exception to handle case when the phase picker object passed to QuakeScan is not of the default type defined in QuakeMigrate.

exception quakemigrate.util.ResponseNotFoundError(e, tr_id)

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 quakemigrate.util.ResponseRemovalError(e, tr_id)

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 quakemigrate.util.StationFileHeaderException

Bases: Exception

Custom exception to handle incorrect header columns in station file

exception quakemigrate.util.TimeSpanException

Bases: Exception

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

quakemigrate.util.decimate(trace, sr)

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.

trace : obspy.Trace object

Trace to be decimated.

sr : int

Output sampling rate.

trace : obspy.Trace object

Decimated trace.

quakemigrate.util.gaussian_1d(x, a, b, c)

Create a 1-dimensional Gaussian function.

Parameters:

• x (array-like) – Array of x values
• a (float / int) – Amplitude (height of Gaussian)
• b (float / int) – Mean (centre of Gaussian)
• c (float / int) – Sigma (width of Gaussian)

Returns:

f – 1-dimensional Gaussian function

Return type:

function

quakemigrate.util.gaussian_3d(nx, ny, nz, sgm)

Create a 3-dimensional Gaussian function.

Parameters:

• nx (array-like) – Array of x values
• ny (array-like) – Array of y values
• nz (array-like) – Array of z values
• sgm (float / int) – Sigma (width of gaussian in all directions)

Returns:

f – 3-dimensional Gaussian function

Return type:

function

quakemigrate.util.logger(logstem, log, loglevel='info')

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”.

quakemigrate.util.make_directories(run, subdir=None)

Make run directory, and optionally make subdirectories within it.

Parameters:

• run (pathlib Path object) – Location of parent output directory, named by run name.
• subdir (string, optional) – subdir to make beneath the run level.

quakemigrate.util.time2sample(time, sampling_rate)

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

quakemigrate.util.timeit(*args_, **kwargs_)

Function wrapper that measures the time elapsed during its execution.

quakemigrate.util.trim2sample(time, sampling_rate)

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 correpsonds to an integer number of samples at a specific sampling rate.

Return type:

int

quakemigrate.util.upsample(trace, upfactor)

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

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

quakemigrate.util.wa_response(convert='DIS2DIS', obspy_def=True)

Generate a Wood Anderson response dictionary.

Parameters:

• convert ({'DIS2DIS', 'VEL2VEL', ‘VEL2DIS'}) – Type of output to convert between; determines the number of complex zeros used.
• obspy_def (bool, optional) – Use the ObsPy definition of the Wood Anderson response (Default). Otherwise, use the IRIS/SAC definition.

Returns:

WOODANDERSON – Poles, zeros, sensitivity and gain of the Wood-Anderson torsion seismograph.

Return type:

dict