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)

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)

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, *[, time, ...])	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)

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()

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, *, time=None, anchor_plate_id=None, return_times=False, return_rate_of_motion=False)

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

One flowline is created for each point that is reconstructable (see Notes). Each flowline is reconstructed to time.

Parameters:

• time_array (float or 1D array) –

  An array of reconstruction times at which to track spreading of the points. 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)
  

  Note that the time array will be sorted in ascending order (if it is not already).

• left_plate_id (int) – The plate ID of the plate to the left of the spreading ridge.

• right_plate_id (int) – The plate ID of the plate to the right of the spreading ridge.

• time (float, optional) – The reconstruction time (Ma) to reconstruct the flowline to. Defaults to the current time (time attribute).

• anchor_plate_id (int, optional) – Anchor plate ID. Defaults to the current anchor plate ID (anchor_plate_id attribute).

• return_times (bool, default=False) – Choose whether to return the times in time_array that are older than the reconstruction time (ie, where time_array[i] > time). This includes the reconstruction time (to_time) unless it is outside the time range of time_array.

• return_rate_of_motion (bool, default=False) – Choose whether to return the rate of spreading through time for each time step between the times in time_array that are older than the reconstruction time (ie, where time_array[i] > time). This includes the reconstruction time (to_time) unless it is outside the time range of time_array.

Returns:

• left_rlons (2D array) – A 2D array with each row containing the left plate spreading history of longitudes of a reconstructable point at each time in time_array that is older than the reconstruction time (ie, where time_array[i] >= to_time). There are n rows for n reconstructable points.

• left_rlats (2D array) – A 2D array with each row containing the left plate spreading history of latitudes of a reconstructable point at each time in time_array that is older than the reconstruction time (ie, where time_array[i] >= to_time). There are n rows for n reconstructable points.

• right_rlons (2D array) – A 2D array with each row containing the right plate spreading history of longitudes of a reconstructable point at each time in time_array that is older than the reconstruction time (ie, where time_array[i] >= to_time). There are n rows for n reconstructable points.

• right_rlats (2D array) – A 2D array with each row containing the right plate spreading history of latitudes of a reconstructable point at each time in time_array that is older than the reconstruction time (ie, where time_array[i] >= to_time). There are n rows for n reconstructable points.

• rtimes (1D array) – Only provided if return_times is True. A 1D array with the times in time_array that are older than the reconstruction time (ie, where time_array[i] >= to_time). The size of this array is the same as the number of columns in left_rlons`, ``left_rlats, right_rlons` and ``right_rlats.

• rate_of_motion (2D array) – Only provided if return_rate_of_motion is True. The rate of plate motion (in cm/yr) for each time step between the times in time_array that are older than the reconstruction time (ie, where time_array[i] >= to_time). The number of columns is one less than the number of columns in left_rlons`, ``left_rlats, right_rlons` and ``right_rlats. There are n rows for n reconstructable points.

Note

If max(time_array) <= time then there will be no history in the returned arrays (ie, the number of columns will be zero for each returned array, including rtimes and rate_of_motion if requested).

Examples

To access the latitudes and longitudes of each point’s flowline:

lons = [...]
lats = [...]
gpts = gplately.Points(model, lons, lats)

time_array = [0, 10, 20, 30, 40, 50]
left_plate_ID=201
right_plate_ID=701
left_rlons, left_rlats, right_rlons, right_rlats = gpts.flowline(time_array, left_plate_ID, right_plate_ID)

# Left flowline.
for i in range(len(left_rlons)):
    current_left_lons = left_rlons[i]
    current_left_lats = left_rlats[i]

# Right flowline.
for i in range(len(right_rlons)):
    current_right_lons = right_rlons[i]
    current_right_lats = right_rlats[i]

get_geodataframe()

The same as get_geopandas_dataframe().

get_geopandas_dataframe()

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
0  10  2  30  POINT (140.00000 -30.00000)
1   2  3   0  POINT (150.00000 -40.00000)
2   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, *, time=None, relative_plate_id=None, anchor_plate_id=None, return_times=False, return_rate_of_motion=False)

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

One motion path is created for each point that is reconstructable (see Notes) using its plate ID. Each motion path is reconstructed to time.

Parameters:

• time_array (float or 1D array) –

  An array of reconstruction times at which to determine the trajectory of the points. 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)
  

  Note that the time array will be sorted in ascending order (if it is not already).

• time (float, optional) – The reconstruction time (Ma) to reconstruct the motion path to. Defaults to the current time (time attribute).

• relative_plate_id (int, optional) – The ID of the plate that the motion path is relative to. Defaults to anchor_plate_id which itself defaults to the current anchor plate ID (anchor_plate_id attribute).

• anchor_plate_id (int, optional) – Anchor plate ID. Defaults to the current anchor plate ID (anchor_plate_id attribute).

• return_times (bool, default=False) – Choose whether to return the times in time_array that are older than the reconstruction time (ie, where time_array[i] > time). This includes the reconstruction time (to_time) unless it is outside the time range of time_array.

• return_rate_of_motion (bool, default=False) – Choose whether to return the rate of plate motion through time for each time step between the times in time_array that are older than the reconstruction time (ie, where time_array[i] > time). This includes the reconstruction time (to_time) unless it is outside the time range of time_array.

Returns:

• rlons (2D array) – A 2D array with each row containing the history of longitudes of a reconstructable point at each time in time_array that is older than the reconstruction time (ie, where time_array[i] >= to_time). There are n rows for n reconstructable points.

• rlats (2D array) – A 2D array with each row containing the history of latitudes of a reconstructable point at each time in time_array that is older than the reconstruction time (ie, where time_array[i] >= to_time). There are n rows for n reconstructable points.

• rtimes (1D array) – Only provided if return_times is True. A 1D array with the times in time_array that are older than the reconstruction time (ie, where time_array[i] >= to_time). The size of this array is the same as the number of columns in rlons and rlats.

• rate_of_motion (2D array) – Only provided if return_rate_of_motion is True. The rate of plate motion (in cm/yr) for each time step between the times in time_array that are older than the reconstruction time (ie, where time_array[i] >= to_time). The number of columns is one less than the number of columns in rlons and rlats. There are n rows for n reconstructable points.

Note

If max(time_array) <= time then there will be no history in the returned arrays (ie, the number of columns will be zero for each returned array, including rtimes and rate_of_motion if requested).

Examples

To access the latitudes and longitudes of each point’s motion path:

lons = [...]
lats = [...]
gpts = gplately.Points(model, lons, lats)

time_array = [0, 10, 20, 30, 40, 50]
rlons, rlats = gpts.motion_path(time_array)

for i in range(len(rlons)):
    current_lons = rlons[i]
    current_lats = rlats[i]

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.

• PlateReconstruction.rotation_model

• PlateReconstruction.topology_featues

• PlateReconstruction.static_polygons

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)

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)

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 return_array is False, return the reconstructed points in a Points object.

• rlons, rlats (ndarray) – If return_array is True, return the longitude and latitude coordinate arrays of the reconstructed points.

• point_indices (ndarray) – If 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)

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)

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)

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