3.4. quakemigrate.lut

The quakemigrate.lut module handles the definition and generation of the traveltime lookup tables used in QuakeMigrate.

copyright

2020–2023, QuakeMigrate developers.

license

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

quakemigrate.lut.update_lut(old_lut_file, save_file)

Utility function to convert old-style LUTs to new-style LUTs.

Parameters

• old_lut_file (str) – Path to lookup table file to update.

• save_file (str, optional) – Output path for updated lookup table.

3.4.1. quakemigrate.lut.create_lut

Module to produce traveltime lookup tables defined on a Cartesian grid.

copyright

2020–2023, QuakeMigrate developers.

license

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

quakemigrate.lut.create_lut.compute_traveltimes(grid_spec, stations, method, phases=['P', 'S'], fraction_tt=0.1, save_file=None, log=False, **kwargs)

Top-level method for computing traveltime lookup tables.

This function takes a grid specification and is capable of computing traveltimes for an arbitrary number of phases using a variety of techniques.

Parameters

• grid_spec (dict) – Dictionary containing all of the defining parameters for the underlying 3-D grid on which the traveltimes are to be calculated. For expected keys, see Grid3D.

• stations (pandas.DataFrame) – DataFrame containing station information (lat/lon/elev).

• method (str) –

  Method to be used when computing the traveltime lookup tables.

  ”homogeneous” - straight line velocities.

  ”1dfmm” - 1-D fast-marching method using scikit-fmm.

  ”1dnlloc” - a 2-D traveltime grid is calculated from the 1-D velocity model using the Grid2Time eikonal solver in NonLinLoc, then swept over the 3-D grid using a bilinear interpolation scheme.

• phases (list of str, optional) – List of seismic phases for which to calculate traveltimes.

• fraction_tt (float, optional) – An estimate of the uncertainty in the velocity model as a function of a fraction of the traveltime. (Default 0.1 == 10%)

• save_file (str, optional) – Path to location to save pickled lookup table.

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

• kwargs (dict) – Dictionary of all keyword arguments passed to compute when called. For lists of valid arguments, please refer to the relevant method.

Returns

lut – Lookup table populated with traveltimes.

Return type

LUT object

Raises

• ValueError – If the specified method is not a valid option.

• TypeError – If the velocity model, or constant phase velocity, is not specified.

• NotImplementedError – If the 3dfmm method is specified.

quakemigrate.lut.create_lut.read_nlloc(path, stations, phases=['P', 'S'], fraction_tt=0.1, save_file=None, log=False)

Read in a traveltime lookup table that is saved in the NonLinLoc format.

Parameters

• path (str) – Path to directory containing .buf and .hdr files.

• stations (pandas.DataFrame) – DataFrame containing station information (lat/lon/elev).

• phases (list of str, optional) – List of seismic phases for which to read in traveltimes.

• fraction_tt (float, optional) – An estimate of the uncertainty in the velocity model as a function of a fraction of the traveltime. (Default 0.1 == 10%)

• save_file (str, optional) – Path to location to save pickled lookup table.

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

Returns

lut – Lookup table populated with traveltimes from the NonLinLoc lookup table files.

Return type

LUT object

Raises

NotImplementedError – If the specified projection type is not supported.

3.4.2. quakemigrate.lut.lut

Module to produce traveltime lookup tables defined on a Cartesian grid.

copyright

2020–2023, QuakeMigrate developers.

license

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

class quakemigrate.lut.lut.Grid3D(ll_corner, ur_corner, node_spacing, grid_proj, coord_proj)

Bases: object

A grid object represents a collection of points in a 3-D Cartesian space that can be used to produce regularised traveltime lookup tables that sample the continuous traveltime space for each station in a seismic network.

This class also provides the series of transformations required to move between the input projection, the grid projection and the grid index coordinate spaces.

The size and shape specifications of the grid are defined by providing the (input projection) coordinates for the lower-left and upper-right corners, a node spacing and the projections (defined using pyproj) of the input and grid spaces.

coord_proj

Input coordinate space projection.

Type

pyproj.Proj object

grid_corners

Positions of the corners of the grid in the grid coordinate space.

Type

array-like, shape (8, 3)

grid_proj

Grid space projection.

Type

pyproj.Proj object

grid_xyz

Positions of the grid nodes in the grid coordinate space. The shape of each element of the list is defined by the number of nodes in each dimension.

Type

array-like, shape (3, nx, ny, nz)

ll_corner

Location of the lower-left corner of the grid in the grid projection. Should also contain the minimum depth in the grid.

Type

array-like, [float, float, float]

node_count

Number of nodes in each dimension of the grid. This is calculated by finding the number of nodes with a given node spacing that fit between the lower-left and upper-right corners. This value is rounded up if the number of nodes returned is non-integer, to ensure the requested area is included in the grid.

Type

array-like, [int, int, int]

node_spacing

Distance between nodes in each dimension of the grid.

Type

array-like, [float, float, float]

precision

An appropriate number of decimal places for distances as a function of the node spacing and coordinate projection.

Type

list of float

unit_conversion_factor

A conversion factor based on the grid projection, used to convert between units of metres and kilometres.

Type

float

unit_name

Shorthand string for the units of the grid projection.

Type

str

ur_corner

Location of the upper-right corner of the grid in the grid projection. Should also contain the maximum depth in the grid.

Type

array-like, [float, float, float]

coord2grid(value, inverse=False, clip=False)

Provides a transformation between the input projection and grid coordinate spaces.

decimate(df, inplace=False)

Downsamples the traveltime lookup tables by some decimation factor.

index2coord(value, inverse=False, unravel=False, clip=False)

Provides a transformation between grid indices (can be a flattened index or an [i, j, k] position) and the input projection coordinate space.

index2grid(value, inverse=False, unravel=False)

Provides a transformation between grid indices (can be a flattened index or an [i, j, k] position) and the grid coordinate space.

property cell_count

Handler for deprecated attribute name ‘cell_count’

property cell_size

Handler for deprecated attribute name ‘cell_size’

coord2grid(value, inverse=False)

Convert between input coordinate space and grid coordinate space.

Parameters

• value (array-like) – Array (of arrays) containing the coordinate locations to be transformed. Each sub-array should describe a single point in the 3-D input space.

• inverse (bool, optional) – Reverses the direction of the transform. Default input coordinates -> grid coordinates

Returns

out – Returns an array of arrays of the transformed values.

Return type

array-like

decimate(df, inplace=False)

Resample the traveltime lookup tables by decimation by some factor.

Parameters

• df (array-like [int, int, int]) – Decimation factor in each dimension.

• inplace (bool, optional) – Perform the operation on the lookup table object or a copy.

Returns

grid – Returns a Grid3D object with decimated traveltime lookup tables.

Return type

Grid3D object (optional)

get_grid_extent(cells=False)

Get the minimum/maximum extent of each dimension of the grid.

The default returns the grid extent as the convex hull of the grid nodes. It is useful, for visualisation purposes, to also be able to determine the grid extent as the convex hull of a grid of cells centred on the grid nodes.

Parameters

cells (bool, optional) – Specifies the grid mode (nodes / cells) for which to calculate the extent.

Returns

extent – Pair of arrays representing two corners for the grid.

Return type

array-like

property grid_corners

Get the xyz positions of the nodes on the corners of the grid.

property grid_extent

Get the minimum/maximum extent of each dimension of the grid.

The default returns the grid extent as the convex hull of the grid nodes. It is useful, for visualisation purposes, to also be able to determine the grid extent as the convex hull of a grid of cells centred on the grid nodes.

Parameters

cells (bool, optional) – Specifies the grid mode (nodes / cells) for which to calculate the extent.

Returns

extent – Pair of arrays representing two corners for the grid.

Return type

array-like

property grid_xyz

Get the xyz positions of all of the nodes in the grid.

index2coord(value, inverse=False, unravel=False)

Convert between grid indices and input coordinate space.

This is a utility function that wraps the other two defined transforms.

Parameters

• value (array-like) – Array (of arrays) containing the grid indices (grid coordinates) to be transformed. Can be an array of flattened indices.

• inverse (bool, optional) – Reverses the direction of the transform. Default indices -> input projection coordinates.

• unravel (bool, optional) – Convert a flat index or array of flat indices into a tuple of coordinate arrays.

Returns

out – Returns an array of arrays of the transformed values.

Return type

array-like

index2grid(value, inverse=False, unravel=False)

Convert between grid indices and grid coordinate space.

Parameters

• value (array-like) – Array (of arrays) containing the grid indices (grid coordinates) to be transformed. Can be an array of flattened indices.

• inverse (bool, optionale) – Reverses the direction of the transform. Default indices -> grid coordinates.

• unravel (bool, optional) – Convert a flat index or array of flat indices into a tuple of coordinate arrays.

Returns

out – Returns an array of arrays of the transformed values.

Return type

array-like

property node_count

Get and set the number of nodes in each dimension of the grid.

property node_spacing

Get and set the spacing of nodes in each dimension of the grid.

property precision

Get appropriate number of decimal places as a function of the node spacing and coordinate projection.

property unit_conversion_factor

Expose unit_conversion_factor of the grid projection.

property unit_name

Expose unit_name of the grid_projection and return shorthand.

class quakemigrate.lut.lut.LUT(fraction_tt=0.1, lut_file=None, **grid_spec)

Bases: Grid3D

A lookup table (LUT) object is a simple data structure that is used to store a series of regularised tables that, for each seismic station in a network, store the traveltimes to every point in the 3-D volume. These lookup tables are pre-computed to efficiently carry out the migration.

This class provides utility functions that can be used to serve up or query these pre-computed lookup tables.

This object is-a Grid3D.

fraction_tt

An estimate of the uncertainty in the velocity model as a function of a fraction of the traveltime. (Default 0.1 == 10%)

Type

float

max_traveltime

The maximum traveltime between any station and a point in the grid.

Type

float

phases

Seismic phases for which there are traveltime lookup tables available.

Type

list of str

stations_xyz

Positions of the stations in the grid coordinate space.

Type

array-like, shape (n, 3)

traveltimes

A dictionary containing the traveltime lookup tables. The structure of this dictionary is:

traveltimes

• “<Station1-ID>”

  • “<PHASE>”

  • “<PHASE>”

• “<Station2-ID”

  • “<PHASE>”

  • “<PHASE>”

etc

Type

dict

velocity_model

Contains the input velocity model specification.

Type

pandas.DataFrame object

serve_traveltimes(sampling_rate)

Serve up the traveltime lookup tables.

traveltime_to(phase, ijk)

Query traveltimes to a grid location (in terms of indices) for a particular phase.

save(filename)

Dumps the current state of the lookup table object to a pickle file.

load(filename)

Restore the state of the saved LUT object from a pickle file.

plot(fig, gs, slices=None, hypocentre=None, station_clr='k')

Plot cross-sections of the LUT with station locations. Optionally plot slices through a coalescence image.

load(filename)

Read the contents of a pickle file and restore state of the lookup table object.

Parameters

filename (str) – Path to pickle file to load.

property max_extent

Get the minimum/maximum geographical extent of the stations/grid.

property max_traveltime

Get the maximum traveltime from any station across the grid.

plot(fig, gs, slices=None, hypocentre=None, station_clr='k', station_list=None)

Plot the lookup table for a particular station.

Parameters

• fig (matplotlib.Figure object) – Canvas on which LUT is plotted.

• gs (tuple(int, int)) – Grid specification for the plot.

• slices (array of arrays, optional) – Slices through a coalescence image to plot.

• hypocentre (array of floats) – Event hypocentre - will add cross-hair to plot.

• station_clr (str, optional) – Plot the stations with a particular colour.

• station_list (list-like of str, optional) – List of stations from the LUT to plot - useful if only a subset have been selected to be used in e.g. locate.

save(filename)

Dump the current state of the lookup table object to a pickle file.

Parameters

filename (str) – Path to location to save pickled lookup table.

serve_traveltimes(sampling_rate, availability=None)

Serve up the traveltime lookup tables.

The traveltimes are multiplied by the scan sampling rate and converted to integers.

Parameters

• sampling_rate (int) – Samples per second used in the scan run.

• availability (dict, optional) – Dict of stations and phases for which to serve traveltime lookup tables: keys “station_phase”.

Returns

traveltimes – Stacked traveltime lookup tables for all seismic phases, stacked along the station axis, with shape(nx, ny, nz, nstations)

Return type

numpy.ndarray of numpy.int

property station_extent

Get the minimum/maximum extent of the seismic network.

property stations_xyz

Get station locations in the grid space [X, Y, Z].

traveltime_to(phase, ijk, station=None)

Serve up the traveltimes to a grid location for a particular phase.

Parameters

• phase (str) – The seismic phase to lookup.

• ijk (array-like) – Grid indices for which to serve traveltime.

• station (str or list-like (of str), optional) – Station or stations for which to serve traveltimes. Can be str (for a single station) or list / pandas.Series object for multiple.

Returns

traveltimes – Array of interpolated traveltimes to the requested grid position.

Return type

array-like