Geographical and spatial functions

Geographical and spatial functions#

Module to deal with spatial and geographical data.

class covseisnet.spatial.Regular3DGrid(extent: tuple[float, float, float, float, float, float], shape: tuple[int, int, int], fill_value: float | str = nan)[source]#

Bases: ndarray

Base class for regular three-dimensional grid of values such as velocity models, travel times, and differential travel times.

The grid is a placeholder for any mathematic object \(f\) that depends on three variables \((\varphi, \lambda, z) \in \mathbb{R}^3\) such as \(f(\varphi, \lambda, z)\). The grid is defined by its geographical extent \((\varphi_0, \varphi_1, \lambda_0, \lambda_1, z_0, z_1)\) and the number of points in each direction \((n_{\varphi}, n_{\lambda}, n_{z})\).

At any coordinate \((\varphi, \lambda, z)\) of the grid we can assign a value \(f(\varphi, \lambda, z)\). The assignment of the values is done by either filling the grid with a constant value, a random value, or a user-defined value.

Attributes

  • lon (numpy.ndarray): The longitudes of the grid in decimal degrees.

  • lat (numpy.ndarray): The latitudes of the grid in decimal degrees.

  • depth (numpy.ndarray): The depths of the grid in kilometers.

  • mesh (list of numpy.ndarray): The meshgrid of the grid in the form (lon, lat, depth).

Methods

  • flatten(): Flatten the grid to allow for faster calculations.

Example

Create a 3D regular grid of values with random values, and plot it.

import numpy as np

import covseisnet as csn

np.random.seed(42)

grid = csn.spatial.Regular3DGrid(
    extent=(40, 41, 50, 51, 0, 20), shape=(10, 10, 10),
    fill_value="random",
)

csn.plot.grid3d(grid, cmap="cividis")
_images/spatial-1.svg
Parameters:

  • extent (tuple) -- The geographical extent of the grid in the form (lon_min, lon_max, lat_min, lat_max, depth_min, depth_max). The longitudes and latitudes are in decimal degrees, and the depths in kilometers.

  • shape (tuple) -- The number of points in the grid in the form (n_lon, n_lat, n_depth).

  • fill_value (float or str, optional) -- The fill value of the grid. By default, it is set to np.nan.

property extent#

Geographical extent of the grid in the form (lon_min, lon_max, lat_min, lat_max, depth_min, depth_max).

property resolution#

Resolution of the grid in the form (lon_res, lat_res, depth_res).

flatten()[source]#

Flatten the grid.

This method flattens the grid to allow for faster calculations. The flattened grid is a 2D array with the shape (n_points, 3) where the columns are the longitudes, latitudes, and depths of the grid. The method internally uses the mesh attribute to flatten the grid with the numpy.ndarray.flat attribute.

covseisnet.spatial.geographical_to_cartesian(lon: float, lat: float, depth: float, earth_radius: float = 6371) → tuple[source]#

Convert geographical to Cartesian coordinates.

Given a point of longitude \(\varphi\), latitude \(\lambda\), and depth \(d\), the Cartesian coordinates \((x, y, z)\) are calculated as follows:

\[\begin{split}\begin{cases} x = (R - d) \cos(\lambda) \cos(\varphi) \\ y = (R - d) \cos(\lambda) \sin(\varphi) \\ z = (R - d) \sin(\lambda) \end{cases}\end{split}\]

where \(R\) is the mean radius of the Earth. The depth is given in kilometers. And the latitude and longitude are given in radians (turned into radians by the function internally). Note that this transformation is only valid for small distances, and that no reference coordinate is provided. This is to calculate the relative distances between points in the same region.

Parameters:

  • lon, lat, depth (float) -- Longitude, latitude, and depth of the point, with depth in kilometers, and latitude and longitude in degrees.

  • earth_radius (float, optional) -- Mean radius of the Earth in kilometers.

Returns:

x, y, z (float) -- Cartesian coordinates of the point.

covseisnet.spatial.straight_ray_distance(lon1: float, lat1: float, depth1: float, lon2: float, lat2: float, depth2: float, earth_radius: float = 6371)[source]#

Straight-ray distance between two geographical coordinates.

The straight-ray distance between two points is calculated using the Euclidean distance between the Cartesian coordinates of the points. The Cartesian coordinates are calculated using the geographical coordinates and the mean radius of the Earth, with the geographical_to_cartesian() function. The units of the longitudes and latitudes are in degrees, and the depths in kilometers.

Parameters:

  • lon1, lat1, depth1 (float) -- Longitude, latitude, and depth of the first point.

  • lon2, lat2, depth2 (float) -- Longitude, latitude, and depth of the second point.

  • earth_radius (float, optional) -- Mean radius of the Earth in kilometers.

Returns:

distance (float) -- Straight-ray distance between the two points in kilometers.

covseisnet.spatial.pairwise_great_circle_distances_from_stats(stats: list[Stats] | None = None, output_units: str = 'km', include_diagonal: bool = True) → list[float][source]#

Get the pairwise great-circle distances between stats coordinates.

Calculate the pairwise great-circle distances between the coordinates of the different stations listed by a list of Stats objects. The distances are calculated using the obspy.geodetics.base.locations2degrees(), if the stats contain a coordinates attribute. The output units can be in degrees or kilometers.

Parameters:

  • stats (list of Stats, optional) -- The list of stats objects containing the coordinates of the stations.

  • output_units (str, optional) -- The output units of the pairwise distances. The units can be 'degrees', 'kilometers', or 'miles'.

  • include_diagonal (bool, optional) -- Whether to include the diagonal of the pairwise distances.

Returns:

numpy.ndarray -- The pairwise distances between the stations.