Module `gplately.tools`

A module that offers tools for executing common geological calculations, mathematical conversions and numpy conversions.

Functions

def My2s(my)

convert million year(my) to seconds. Roughly, 1 Million Years = 31,536,000,000,000 Seconds

def calculate_spreading_rates(time, lons, lats, left_plates, right_plates, rotation_model, delta_time=1.0, units=pygplates.pygplates.VelocityUnits.kms_per_my, earth_radius=6371.009)

def correct_longitudes_for_dateline(lons)

def extract_feature_lonlat(features)

Extracts the latitudes and longitudes of topological feature points.

Parameters

features : list: A list of topological point features to extract lat-lon coordinates from.

Returns

rlon, rlat : lists: Extracted longitudes and latitudes of feature points. Each index corresponds to different points. Same length as the input feature array.

def find_distance_to_nearest_ridge(resolved_topologies, shared_boundary_sections, point_features, fill_value=5000.0)

def geocentric_area(latitude_one, latitude_two, longitude_resolution)

Calculates the point area of an evenly gridded lat/lon mesh Longitude resolution is lon2 - lon1

def griddata_sphere(points, values, xi, method='nearest', **kwargs)

Interpolate unstructured D-D data on the sphere.

Parameters

points : 2-D ndarray of floats with shape (n, D), or length D tuple of 1-D ndarrays with shape (n,).

Data point coordinates in longitudes / latitudes.

values : ndarray of float or complex, shape (n,)

Data values.

xi : 2-D ndarray of floats with shape (m, D), or length D tuple of ndarrays broadcastable to the same shape.

Points at which to interpolate data in logitudes / latitudes.

method : {'linear', 'nearest', 'cubic'}, optional

Method of interpolation. One of

nearest return the value at the data point closest to the point of interpolation. See NearestNDInterpolator for more details.

rbf return the value determined from a radial basis function. See RBFInterpolator for more details.

kwargs : dict of keyword-arguments

Pass optional arguments to interpolation objects specified in "method". A default value of neighors=12 is automatically applied to rbf.

Returns

ndarray: Array of interpolated values.

def lat_area_function(latitude_one, latitude_two, longitude_resolution)

Calculates the point area of an evenly gridded lat/lon mesh Longitude resolution is lon2 - lon1

def plate_isotherm_depth(age, temp=1150.0, plate_thickness=125000.0, maxiter=50, tol=0.001, require_convergence=False, **kwargs)

Computes the depth to the temp - isotherm in a cooling plate mode. Solution by iteration.

By default the plate thickness is 125 km as in Parsons/Sclater.

Parameters

age : array_like: Geological ages (Ma) at which to compute depths.
temp : float, default: 1150.0: The temperature of a temp-isotherm for which to calculate depth, in degrees Celsius.
plate_thickness : float, default: 125.0e3: Thickness of the plate, in metres.
maxiter : int, default: 50: Maximum number of iterations.
tol : float, default: 0.001: Tolerance for convergence of plate_temp().
require_convergence : bool, default: False: If True, raise a RuntimeError if convergence is not reached within maxiter iterations; if False, a RuntimeWarning is issued instead.
**kwargs: Any further keyword arguments are passed on to plate_temp().

Returns

z : ndarray: Array of depths to the chosen temperature isotherm at the given ages. This is a scalar if age is a scalar.

Raises

RuntimeError: If require_convergence is True and convergence is not reached within maxiter iterations.

def plate_partitioner_for_point(lat_lon_tuple, topology_features, rotation_model)

Determine the present-day plate ID of a (lat, lon) coordinate pair if it is not specified.

def plate_surface_depth(age, model='Richards2020')

Computes the depth to the surface of a cooling plate.

Essentially converts the ocean basin age to basement depth using a specified age/depth model.

Parameters

age : float: The age in Ma.
model : str: The model to use when converting ocean age to basement depth. - 'Richards2020': Richards et al. (2020), Structure and dynamics of the oceanic lithosphere-asthenosphere system - 'Stein1992': Stein and Stein (1992), Model for the global variation in oceanic depth and heat flow with lithospheric age - 'Parsons1977': Parsons and Sclater (1972), An analysis of the variation of ocean floor bathymetry and heat flow with age

Returns

depth : array: Depth (in metres) as a positive number.

Raises

ValueError: If model is not a recognised model.

Notes

The Richards2020 curve is approximate. A polynomial was fitted to the age-depth data

def plate_temp(age, z, plate_thickness=125000.0, kappa=8.04e-07, t_mantle=1350.0, t_surface=0.0)

Compute the temperature in a cooling plate for a given age, plate thickness, and depth.

By default, assumes a mantle temperature of 1350 degrees, and a 0 degree surface temperature. Kappa defaults to 0.804e-6.

Parameters

age : float: The geological time (Ma) at which to calculate plate temperature.
z : array_like: The plate depth(s) (m) at which to calculate temperature.
plate_thickness : float, default: 125.0e3: The thickness (m) of the plate in consideration.
kappa : float, default: 0.804e-6
t_mantle : float, default: 1350.0: Mantle temperature at the Moho, in degrees Celsius.
t_surface : float, default: 0.0: Temperature at the surface, in degrees Celsius.

Returns

ndarray: The plate temperature at the given age and depth. This is a scalar if z is a scalar.

def points_to_features(lons, lats, plate_ID=None, *, return_points=False)

Creates point features represented on a unit length sphere in 3D cartesian coordinates from a latitude and longitude list.

Parameters

lons : int or list: The longitudes of needed point features.
lats : int or list: The latitudes of needed point features.
plate_ID : int or list, default=None: The reconstruction plate ID(s) to assign to the needed point features.
return_points : bool, default=False: Whether to also return the points (converted from latitude/longitude to pygplates.PointOnSphere).

Returns

point_features : pygplates.Feature, or list of pygplates.Feature: Point features (of type pygplates.Feature) created from the given lists of lat-lon point coordinates.
points : pygplates.PointOnSphere, or list of pygplates.PointOnSphere: Points (of type pygplates.PointOnSphere) created from the given lists of lat-lon point coordinates. Points are only returned if return_points is True.

def read_csv(filename, readcols)

read csv and reorder from 0 - 250 Ma

def read_rotation_file_pandas(rotation_file_paths)

Written by Nicky M Wright. Extract data from one rotation file, and write it to a pandas dataframe.

def smooth_1D(array, sigma=3.0, axis=0)

Gaussian filter with standard deviation

def smooth_1D_gaussian(input_data, time_window, axis=-1, output=None, mode='reflect', truncate=4.0)

Smooth every data element in the 1D input_data array over a specified time_window, using a one-dimensional, zeroth order Gaussian filter.

The time_window, or Gaussian kernel diameter, is used to calculate a sigma for the Gaussian kernel.

For example, if a time_window of 20 Myr is supplied, an array with 21 elements (10 Myr on each side of a central point, including the central point) is produced. Each element is filled with the Gaussian evaluated at that point.

This Gaussian is correlated to each data point in the input_array to smooth the data.

Parameters

input_data : 1d array: A one-dimensional array of input data to smooth using a Gaussian filter.
time_window : float, default = 5 (Myr): A float or integer to specify the full width of the Gaussian filter with which to smooth each data point in input_data. 1 pixel : 1 Myr.
axis : int, default = -1: The axis of input_data along which to smooth. Default is -1.
output : array or dtype, optional: The array in which to place the output, or the dtype of the returned array. By default an array of the same dtype as input will be created.
mode : str, default "reflect": The way the input_array is extended beyond its bounds to ensure all data points can be convolved with the created Gaussian. See scipy's docs to see the full list of extension methods. By default, "reflect" extends input_array such that [a b c d] becomes (d c b a | a b c d | d c b a), reflecting about the edge of the last pixel.
truncate : float or int, default = 4.0: A multiplicative factor that truncates the number of standard deviations, or sigmas, that the Gaussian distribution spans in either direction from the centre. This impacts the number of pixels that the Gaussian kernel spans. By default, this is set to 4 standard deviations.

def surface_area_oblate_spheroid(r1, r2)

def update_progress(progress)