gplately.Points

class gplately.Points(plate_reconstruction, lons, lats, time: float = 0, plate_id=None, age: float | ndarray | None = inf, *, anchor_plate_id=None, remove_unreconstructable_points=False)[source]

Bases: object

Reconstruct and work with geological point data.

The locations and plate velocities of point data can be calculated at a specific geological time. The Points class depends on the PlateReconstruction class, as it provides essential components for reconstructing plate motions. Specifically, it uses the PlateReconstruction.rotation_model to compute point rotations through time, and the PlateReconstruction.static_polygons to assign points to their respective tectonic plates.

__init__(plate_reconstruction, lons, lats, time: float = 0, plate_id=None, age: float | ndarray | None = inf, *, anchor_plate_id=None, remove_unreconstructable_points=False)[source]

Parameters:

plate_reconstruction (PlateReconstruction) –
Object to provide the following essential components for reconstructing points.
- PlateReconstruction.rotation_model
- PlateReconstruction.topology_featues
- PlateReconstruction.static_polygons
lons (float or 1D array) – Longitudes of the initial points at the initial time.
lats (float or 1D array) – Latitudes of the initial points at the initial time.
time (float, default=0) – The initial time (Ma) of the points. The lons and lats are the initial coordinates of the points at this time. By default, it is set to the present day (0 Ma).
plate_id (int or 1D array or None, default=None) – Plate ID(s) of a particular tectonic plate on which point data lies, if known. If it is a single integer then all points will have the same plate ID. If it is a 1D array then length must match the number of points. If None then plate IDs are determined using the PlateReconstruction.static_polygons. By default, the plate IDs are determined using the static polygons.
age (float or 1D array or None, default=numpy.inf) – Age(s) at which each point appears, if known. If it is a single float then all points will have the same age. If it is a 1D array then length must match the number of points. If None then ages are determined using the PlateReconstruction.static_polygons. For points on oceanic crust this is when they were created at a mid-ocean ridge. By default, all points exist for all time (ie, time of appearance is infinity). This default is for backward compatibility, but you’ll typically only want this if all your points are on continental crust (not oceanic).
anchor_plate_id (int, optional) – Anchor plate ID that the specified lons and lats are relative to. Defaults to the current anchor plate ID of plate_reconstruction (its anchor_plate_id attribute).
remove_unreconstructable_points (bool or list, default=False) – Whether to remove points that cannot be reconstructed. By default, all unreconstructable points are retained. A point cannot be reconstructed if it cannot be assigned a plate ID, or cannot be assigned an age, because it did not intersect any reconstructed static polygons (note that this can only happen when plate_id and/or age is None). Also, a point cannot be reconstructed if point ages were explicitly provided (ie, age was not None) and a point’s age was less than (younger than) time, meaning it did not exist as far back as time. Additionally, if this variable is a list then the indices (into the supplied lons and lats arguments) of any removed points (ie, that are unreconstructable) are appended to that list.

Note

If time is non-zero (ie, not present day) then lons and lats are assumed to be the reconstructed point locations at time. And the reconstructed positions are assumed to be relative to the anchor plate (which is plate_reconstruction.anchor_plate_id if anchor_plate_id is None).

If plate_id and/or age is None then the plate ID and/or age of each point is determined by reconstructing the static polygons of plate_reconstruction to time and reconstructing relative to the anchor plate (regardless of whether time is present day or not). And then, for each point, assigning the plate ID and/or time-of-appearance (begin time) of the static polygon containing the point.

A point is considered unreconstructable if it does not exist at time. This can happen if its age was explicitly provided (ie, age is not None) but is younger than time. It can also happen if the point is automatically assigned a plate ID (ie, plate_id is None) or an age (ie, age is None) but does not intersect any reconstructed static polygons (at time). In either of these cases it is marked as unreconstructable and will not be available for any method outputing a reconstruction, such as reconstruct(), or any method depending on a reconstruction, such as plate_velocity(). However, all the initial locations and their associated plate IDs and ages will still be accessible as attributes, regardless of whether all the points are reconstructable or not. That is, unless remove_unreconstructable_points is True (or a list), in which case only the reconstructable points are retained.

Methods

`__init__`(plate_reconstruction, lons, lats[, ...])
`add_attributes`(**kwargs)	Adds the value of a feature attribute associated with a key.
`copy`()	Returns a copy of the `Points` object
`flowline`(time_array, left_plate_ID, ...[, ...])	Create a path of points to track plate motion away from spreading ridges over time using half-stage rotations.
`get_geodataframe`()	The same as `get_geopandas_dataframe()`.
`get_geopandas_dataframe`()	Return a `geopandas.GeoDataFrame` object for the points.
`motion_path`(time_array[, anchor_plate_id, ...])	Create a path of points to mark the trajectory of a plate's motion through geological time.
`plate_velocity`(time[, delta_time, ...])	Calculates the east and north components of the tectonic plate velocities of the internal points at a particular geological time.
`reconstruct`(time[, anchor_plate_id, ...])	Reconstruct points from the initial time (`self.time`) to the specified time (`time`).
`reconstruct_to_birth_age`(ages[, ...])	Reconstruct points from the initial time (`self.time`) to a range of times.
`rotate_reference_frames`(reconstruction_time)	Rotate a grid defined in one plate model reference frame within a `Raster` object to another plate reconstruction model reference frame.
`save`(filename)	Saves the feature collection used in the Points object under a given filename to the current directory.

Attributes

`age`	A 1D array containing the ages (time of appearance) of the points.
`anchor_plate_id`	Anchor plate that the initial `lons` and `lats` are relative to, at the initial `time`.
`lats`	Latitudes of the initial points at the initial `time`.
`lons`	Longitudes of the initial points at the initial `time`.
`plate_id`	A 1D array containing the plate IDs of the points.
`plate_reconstruction`	Object to provide the following essential components for reconstructing points.
`size`	Number of points.
`time`	The initial time (Ma) of the points.

add_attributes(**kwargs)[source]

Adds the value of a feature attribute associated with a key.

Parameters:: **kwargs (sequence of key=item/s) – A single key=value pair, or a sequence of key=value pairs denoting the name and value of an attribute.

Example

# Define latitudes and longitudes to set up a Points object
pt_lons = np.array([140., 150., 160.])
pt_lats = np.array([-30., -40., -50.])

gpts = gplately.Points(model, pt_lons, pt_lats)

# Add the attributes a, b and c to the points in the Points object
gpts.add_attributes(
    a=[10,2,2],
    b=[2,3,3],
    c=[30,0,0],
)

print(gpts.attributes)

The output would be:

{'a': [10, 2, 2], 'b': [2, 3, 3], 'c': [30, 0, 0]}

Note

An assertion is raised if the number of points in the Points object is not equal to the number of values associated with an attribute key. For example, consider an instance of the Points object with 3 points. If the points are ascribed an attribute temperature, there must be one temperature value per point, i.e. temperature = [20, 15, 17.5].

property age

A 1D array containing the ages (time of appearance) of the points. The length must match that of lons and lats. For points on oceanic crust this is when they were created at a mid-ocean ridge. Any points existing for all time will have a value of numpy.inf (equivalent to float('inf')).

Type:: float 1D array

property anchor_plate_id

Anchor plate that the initial lons and lats are relative to, at the initial time. This is also used as the default anchor plate when reconstructing the points. It does not change, even if the anchor plate of plate_reconstruction subsequently changes.

Type:: int

copy()[source]

Returns a copy of the Points object

Returns:: A copy of the current Points object
Return type:: Points

flowline(time_array, left_plate_ID, right_plate_ID, return_rate_of_motion=False)[source]

Create a path of points to track plate motion away from spreading ridges over time using half-stage rotations.

Parameters:

lons (arr) – An array of longitudes of points along spreading ridges.
lats (arr) – An array of latitudes of points along spreading ridges.
time_array (arr) – A list of times to obtain seed point locations at.
left_plate_ID (int) – The plate ID of the polygon to the left of the spreading ridge.
right_plate_ID (int) – The plate ID of the polygon to the right of the spreading ridge.
return_rate_of_motion (bool, default False) – Choose whether to return a step time and step rate array for a step-plot of flowline motion.

Returns:

left_lon (ndarray) – The longitudes of the left flowline for n seed points. There are n columns for n seed points, and m rows for m time steps in time_array.
left_lat (ndarray) – The latitudes of the left flowline of n seed points. There are n columns for n seed points, and m rows for m time steps in time_array.
right_lon (ndarray) – The longitudes of the right flowline of n seed points. There are n columns for n seed points, and m rows for m time steps in time_array.
right_lat (ndarray) – The latitudes of the right flowline of n seed points. There are n columns for n seed points, and m rows for m time steps in time_array.

Examples

To access the i^th seed point’s left and right latitudes and longitudes:

for i in np.arange(0,len(seed_points)):
    left_flowline_longitudes = left_lon[:,i]
    left_flowline_latitudes = left_lat[:,i]
    right_flowline_longitudes = right_lon[:,i]
    right_flowline_latitudes = right_lat[:,i]

get_geodataframe()[source]: The same as get_geopandas_dataframe().

get_geopandas_dataframe()[source]

Return a geopandas.GeoDataFrame object for the points.

Returns:: GeoDataFrame – A geopandas.GeoDataFrame object with rows equal to the number of points in the Points object, and an additional column containing a shapely geometry attribute.
Return type:: geopandas.GeoDataFrame

Example

pt_lons = np.array([140., 150., 160.])
pt_lats = np.array([-30., -40., -50.])

gpts = gplately.Points(model, pt_lons, pt_lats)

# Add sample attributes a, b and c to the points in the Points object
gpts.add_attributes(
    a=[10,2,2],
    b=[2,3,3],
    c=[30,0,0],
)

gpts.get_geopandas_dataframe()

has the output:

    a  b   c                     geometry
10  2  30  POINT (140.00000 -30.00000)
 2  3   0  POINT (150.00000 -40.00000)
 2  3   0  POINT (160.00000 -50.00000)

property lats

Latitudes of the initial points at the initial time.

Type:: float 1D array

property lons

Longitudes of the initial points at the initial time.

Type:: float 1D array

motion_path(time_array, anchor_plate_id=None, return_rate_of_motion=False)[source]

Create a path of points to mark the trajectory of a plate’s motion through geological time.

Parameters:

time_array (arr) –

An array of reconstruction times at which to determine the trajectory of a point on a plate.

For example,

import numpy as np
min_time = 30
max_time = 100
time_step = 2.5
time_array = np.arange(min_time, max_time + time_step, time_step)

anchor_plate_id (int, optional) – Reconstruct features with respect to a certain anchor plate. By default, reconstructions are made with respect to the anchor plate ID specified in the PlateReconstruction object.
return_rate_of_motion (bool, default=False) – Choose whether to return the rate of plate motion through time for each

Returns:

rlons (ndarray) – An n-dimensional array with columns containing the longitudes of the seed points at each timestep in time_array. There are n columns for n seed points.
rlats (ndarray) – An n-dimensional array with columns containing the latitudes of the seed points at each timestep in time_array. There are n columns for n seed points.

property plate_id

A 1D array containing the plate IDs of the points. The length must match that of lons and lats.

Type:: int 1D array

property plate_reconstruction

Object to provide the following essential components for reconstructing points.

Type:: PlateReconstruction

plate_velocity(time, delta_time=1.0, *, velocity_delta_time_type=pygplates.pygplates.VelocityDeltaTimeType.t_plus_delta_t_to_t, velocity_units=pygplates.pygplates.VelocityUnits.cms_per_yr, earth_radius_in_kms=6371.009, anchor_plate_id=None, return_reconstructed_points=False, return_point_indices=False)[source]

Calculates the east and north components of the tectonic plate velocities of the internal points at a particular geological time.

The point velocities are calculated using the plate IDs of the internal points and the rotation model of the internal PlateReconstruction object. If the requested time differs from the initial time (self.time) then the internal points are first reconstructed to time before calculating velocities. Velocities are only calculated at points that are reconstructable (See Notes) and that have ages greater than or equal to time (ie, at points that exist at time).

Parameters:

time (float) – The specific geological time (Ma) at which to calculate plate velocities.
delta_time (float, default=1.0) – The time interval used for velocity calculations. 1.0Ma by default.
velocity_delta_time_type (pygplates.VelocityDeltaTimeType, default=pygplates.VelocityDeltaTimeType.t_plus_delta_t_to_t) – How the two velocity times are calculated relative to time (defaults to [time + velocity_delta_time, time]).
velocity_units (pygplates.VelocityUnits, default=pygplates.VelocityUnits.cms_per_yr) – Whether to return velocities in centimetres per year or kilometres per million years (defaults to centimetres per year).
earth_radius_in_kms (float, default=pygplates.Earth.mean_radius_in_kms) – Radius of the Earth in kilometres. This is only used to calculate velocities (strain rates always use pygplates.Earth.equatorial_radius_in_kms).
anchor_plate_id (int, optional) – Anchor plate used to reconstruct the points and calculate velocities at their locations. By default, reconstructions are made with respect to self.anchor_plate_id (which is the anchor plate that the initial points at the initial time are relative to).
return_reconstructed_points (bool, default=False) – Return the reconstructed points (as longitude and latitude arrays) in addition to the velocities.
return_point_indices (bool, default=False) – Return the indices of those internal points at which velocities are calculated. These are indices into self.lons, self.lats, self.plate_id and self.age. Those points with an age less than time have not yet appeared at time, and therefore will not have velocities returned.

Returns:

velocity_lons, velocity_lats (ndarray) – The velocity arrays containing the east (longitude) and north (latitude) components of the velocity of each internal point that exists at time (ie, whose age greater than or equal to time).
rlons, rlats (ndarray) – Only provided if return_reconstructed_points is True. The longitude and latitude coordinate arrays of the reconstructed points (at which velocities are calculated). These arrays are the same size as velocity_lons and velocity_lats.
point_indices (ndarray) – Only provided if return_point_indices is True. The indices of the returned points (at which velocities are calculated). These are indices into self.lons, self.lats, self.plate_id and self.age. This array is the same size as velocity_lons and velocity_lats.

Note

The velocities are in centimetres per year by default (not kilometres per million years, the default in PlateReconstruction.get_point_velocities()). This difference is maintained for backward compatibility.

For each velocity, the east* component is first followed by the north component. This is different to PlateReconstruction.get_point_velocities() where the north component is first. This difference is maintained for backward compatibility.

See also

PlateReconstruction.get_point_velocities() : Velocities of points calculated using topologies instead of plate IDs (assigned from static polygons).

reconstruct(time, anchor_plate_id=None, return_array=False, return_point_indices=False)[source]

Reconstruct points from the initial time (self.time) to the specified time (time).

Only those points that are reconstructable (See Notes) and that have ages greater than or equal to time (ie, at points that exist at time) are reconstructed.

Parameters:

time (float) – The specific geological time (Ma) to reconstruct features to.
anchor_plate_id (int, optional) – Reconstruct features with respect to a certain anchor plate. By default, reconstructions are made with respect to self.anchor_plate_id (which is the anchor plate that the initial points at the initial time are relative to).
return_array (bool, default=False) – Return a 2-tuple of numpy.ndarray, rather than a Points object.
return_point_indices (bool, default=False) – Return the indices of the points that are reconstructed. Those points with an age less than time have not yet appeared at time, and therefore are not reconstructed. These are indices into self.lons, self.lats, self.plate_id and self.age.

Returns:

reconstructed_points (Points) – If the return_array is False, return the reconstructed points in a Points object.
rlons, rlats (ndarray) – If the return_array is True, return the longitude and latitude coordinate arrays of the reconstructed points.
point_indices (ndarray) – If the return_point_indices is True, return the indices of the returned points (that are reconstructed). This array is the same size as rlons and rlats (or size of reconstructed_points). These are indices into self.lons, self.lats, self.plate_id and self.age.

reconstruct_to_birth_age(ages, anchor_plate_id=None, return_point_indices=False)[source]

Reconstruct points from the initial time (self.time) to a range of times.

The number of supplied times must equal the number of points supplied to this Points object (ie, self.size attribute). Only those points that are reconstructable (See Notes) and that have ages greater than or equal to the respective supplied ages (ie, at points that exist at the supplied ages) are reconstructed.

Parameters:

ages (array) – Geological times to reconstruct points to. Must have the same length as the number of points (self.size attribute).
anchor_plate_id (int, optional) – Reconstruct points with respect to a certain anchor plate. By default, reconstructions are made with respect to self.anchor_plate_id (which is the anchor plate that the initial points at the initial time are relative to).
return_point_indices (bool, default=False) – Return the indices of the points that are reconstructed. Those points with an age less than their respective supplied age have not yet appeared, and therefore are not reconstructed. These are indices into self.lons, self.lats, self.plate_id and self.age.

Raises:

ValueError – If the number of ages is not equal to the number of points supplied to this Points object.

Returns:

rlons, rlats (ndarray) – The longitude and latitude coordinate arrays of points reconstructed to the specified ages.
point_indices (ndarray) – Only provided if return_point_indices is True. The indices of the returned points (that are reconstructed). This array is the same size as rlons and rlats. These are indices into self.lons, self.lats, self.plate_id and self.age.

Examples

To reconstruct n seed points to B Ma (for this example n=2, with (lon,lat) = (78,30) and (56,22) at time=0 Ma, and we reconstruct to B=10 Ma):

# Longitude and latitude of n=2 seed points
pt_lon = np.array([78., 56])
pt_lat = np.array([30., 22])

# Call the Points object!
gpts = gplately.Points(model, pt_lon, pt_lat)
print(gpts.features[0].get_all_geometries())   # Confirms we have features represented as points on a sphere

ages = numpy.linspace(10,10, len(pt_lon))
rlons, rlats = gpts.reconstruct_to_birth_age(ages)

rotate_reference_frames(reconstruction_time, from_rotation_features_or_model=None, to_rotation_features_or_model=None, from_rotation_reference_plate=0, to_rotation_reference_plate=0, non_reference_plate=701, output_name=None, return_array=False)[source]

Rotate a grid defined in one plate model reference frame within a Raster object to another plate reconstruction model reference frame.

Parameters:

reconstruction_time (float) – The time at which to rotate the reconstructed points.
from_rotation_features_or_model (str/os.PathLike, list of str/os.PathLike, or instance of pygplates.RotationModel) – A filename, or a list of filenames, or a pyGPlates RotationModel object that defines the rotation model that the input grid is currently associated with. self.plate_reconstruction.rotation_model is default.
to_rotation_features_or_model (str/os.PathLike, list of str/os.PathLike, or instance of pygplates.RotationModel) – A filename, or a list of filenames, or a pyGPlates RotationModel object that defines the rotation model that the input grid shall be rotated with. self.plate_reconstruction.rotation_model is default.
from_rotation_reference_plate (int, default = 0) – The current reference plate for the plate model the points are defined in. Defaults to the anchor plate 0.
to_rotation_reference_plate (int, default = 0) – The desired reference plate for the plate model the points to be rotated to. Defaults to the anchor plate 0.
non_reference_plate (int, default = 701) – An arbitrary placeholder reference frame with which to define the “from” and “to” reference frames.
output_name (str, default None) – If passed, the rotated points are saved as a gpml to this filename.

Returns:

An instance of the Points object containing the rotated points.

Return type:

Points

save(filename)[source]

Saves the feature collection used in the Points object under a given filename to the current directory.

The file format is determined from the filename extension.

Parameters:: filename (str) – Can be provided as a string including the filename and the file format needed.
Return type:: Feature collection saved under given filename to current directory.

property size

Number of points. This is the size of lons, lats, plate_id and age.

Type:: int

property time

The initial time (Ma) of the points. The initial lons and lats are the coordinates of the points at this time.

Type:: float