3.4. quakemigrate.lut package

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

copyright:2020, 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, 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 “1dsweep” - a 2-D traveltime grid for a 1-D velocity model is 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%)
• filename (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 from the NonLinLoc files.

Return type:

LUT object

quakemigrate.lut.create_lut.read_nlloc(path, stations, phases=['P', 'S'], fraction_tt=0.1, 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 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%)
• 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 files.

Return type:

LUT object

3.4.2. quakemigrate.lut.lut

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

copyright:2020, 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.

cell_count

Handler for deprecated attribute name ‘cell_count’

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

grid_corners

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

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

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

node_count

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

node_spacing

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

precision

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

unit_conversion_factor

Expose unit_conversion_factor of the grid projection.

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: quakemigrate.lut.lut.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 reduce the computational cost of the back-projection method.

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

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.

max_extent

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

max_traveltime

Get the maximum traveltime from any station across the grid.

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

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

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)

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

station_extent

Get the minimum/maximum extent of the seismic network.

stations_xyz

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

traveltime_to(phase, ijk)

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.

Returns:

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

Return type:

array-like