pygplates.TopologicalSnapshot

class pygplates.TopologicalSnapshot

Bases: instance

A snapshot of resolved topological features (lines, boundaries and networks) at a specific geological time.

See also

Topological snapshot in the Primer documentation.

Changed in version 0.31: Added default_resolve_topology_parameters argument.

Changed in version 0.44: Filenames can be os.PathLike (such as pathlib.Path) in addition to strings.

Methods

`__init__`(topological_features, ...)	Create from topological features and a rotation model at a specific reconstruction time.
`calculate_plate_boundary_statistics`(...)	Calculate statistics at uniformly spaced points along plate boundaries.
`export_resolved_topological_sections`(...)	Exports the resolved topological sections of the requested type(s) to a file.
`export_resolved_topologies`(export_filename, ...)	Exports the resolved topologies of the requested type(s) to a file.
`get_anchor_plate_id`()	Return the anchor plate ID (see `constructor`).
`get_point_locations`(points, ...)	Returns the resolved topological boundaries/networks that contain the specified points.
`get_point_strain_rates`(points, ...)	Returns the strain rates of the specified points (as determined by the resolved topological boundaries/networks that contain them).
`get_point_velocities`(points, ...)	Returns the velocities of the specified points (as determined by the resolved topological boundaries/networks that contain them).
`get_reconstruction_time`()	Return the reconstruction time of this snapshot.
`get_resolved_topological_sections`(...)	Returns the resolved topological sections of the requested type(s).
`get_resolved_topologies`(...)	Returns the resolved topologies of the requested type(s).
`get_rotation_model`()	Return the rotation model used internally.

calculate_plate_boundary_statistics(uniform_point_spacing_radians[, first_uniform_point_spacing_radians][, velocity_delta_time=1.0][, velocity_delta_time_type=pygplates.VelocityDeltaTimeType.t_plus_delta_t_to_t][, velocity_units=pygplates.VelocityUnits.kms_per_my][, earth_radius_in_kms=pygplates.Earth.mean_radius_in_kms][, include_network_boundaries=False][, boundary_section_filter][, return_shared_sub_segment_dict=False])

Calculate statistics at uniformly spaced points along plate boundaries.

Parameters:

uniform_point_spacing_radians (float) – Spacing between uniform points along plate boundaries (in radians). See PolylineOnSphere.to_uniform_points().
first_uniform_point_spacing_radians (float) – Spacing of first uniform point in each resolved topological section (in radians). Each resolved topological section represents a specific boundary Feature and has a list of shared sub-segments that are the parts of it that actually contribute to plate boundaries. So, this parameter is the distance from the first vertex of the first shared sub-segment (along the sub-segment). And note that the uniform spacing is continuous across adjacent shared sub-segments, unless there’s a gap between them (eg, that no plate uses as part of its boundary), in which case the spacing is reset to first_uniform_point_spacing_radians for the next shared sub-segment (after the gap). See PolylineOnSphere.to_uniform_points(). Defaults to half of uniform_point_spacing_radians.
velocity_delta_time (float) – The time delta used to calculate velocities (defaults to 1 Myr).
velocity_delta_time_type (VelocityDeltaTimeType.t_plus_delta_t_to_t, VelocityDeltaTimeType.t_to_t_minus_delta_t or VelocityDeltaTimeType.t_plus_minus_half_delta_t) – How the two velocity times are calculated relative to the reconstruction time. This includes [t+dt, t], [t, t-dt] and [t+dt/2, t-dt/2]. Defaults to [t+dt, t].
velocity_units (VelocityUnits.kms_per_my or VelocityUnits.cms_per_yr) – whether to return velocities as kilometres per million years or centimetres per year (defaults to kilometres per million years)
earth_radius_in_kms (float) – The radius of the Earth in kilometres (defaults to pygplates.Earth.mean_radius_in_kms). This is only used to calculate velocities (strain rates always use pygplates.Earth.equatorial_radius_in_kms).
include_network_boundaries (bool) – Whether to calculate statistics along network boundaries that are not also plate boundaries (defaults to False). If a deforming network shares a boundary with a plate then it’ll get included regardless of this option.
boundary_section_filter (FeatureType, or list of FeatureType, or callable (accepting a single ResolvedTopologicalSection)) – Optionally restrict boundary sections to those that match a feature type, or match one of several feature types, or match a filter function. Defaults to None (meaning accept all boundary sections).
return_shared_sub_segment_dict (bool) – Whether to return a dict mapping each shared sub-segment (ie, a boundary section shared by one or more plates) to a list of PlateBoundaryStatistic associated with it. If False then just returns one large list of PlateBoundaryStatistic for all plate boundaries. Defaults to False.

Returns:

list of PlateBoundaryStatistic for all uniform points, or (if return_shared_sub_segment_dict is True) a dict mapping each ResolvedTopologicalSharedSubSegment to a list of PlateBoundaryStatistic

Return type:

list or dict

Raises:

ValueError if uniform_point_spacing_radians is negative or zero

Raises:

ValueError if velocity_delta_time is negative or zero.

See also

Plate boundary statistics in the Primer documentation.

Note

If return_shared_sub_segment_dict is True then any shared sub-segments that are not long enough to contain any uniform points will be missing from the returned dict.

Uniform points are not generated along network boundaries by default (unless they happen to also be a plate boundary) since not all parts of a network’s boundary are necessarily along plate boundaries. But you can optionally generate points along them by setting include_network_boundaries to True. Note that, regardless of this option, networks are always used when calculating plate statistics. This is because networks typically overlay rigid plates, and so need to be queried (at uniform points along plate boundaries) with a higher priority than the underlying rigid plate.

Note

The plate boundaries, along which uniform points are generated, can be further restricted using boundary_section_filter.

Added in version 0.47.

export_resolved_topological_sections(export_filename[, resolve_topological_section_types=(pygplates.ResolveTopologyType.boundary|pygplates.ResolveTopologyType.network)][, export_topological_line_sub_segments=True][, wrap_to_dateline=True])

Exports the resolved topological sections of the requested type(s) to a file.

Parameters:

export_filename (string/os.PathLike) – the name of the export file
resolve_topological_section_types (a bitwise combination of any of pygplates.ResolveTopologyType.boundary or pygplates.ResolveTopologyType.network) – Determines whether ResolvedTopologicalBoundary or ResolvedTopologicalNetwork (or both types) are listed in the exported resolved topological sections. Note that pygplates.ResolveTopologyType.line cannot be specified since only topologies with boundaries are considered. Defaults to resolved topological boundaries and resolved topological networks.
export_topological_line_sub_segments (bool) – Whether to export the individual sub-segments of each boundary segment that came from a resolved topological line (True) or export a single geometry per boundary segment (False). Defaults to True.
wrap_to_dateline (bool) – Whether to wrap/clip resolved topological sections to the dateline (currently ignored unless exporting to an ESRI Shapefile format file). Defaults to True.

Raises:

ValueError if resolve_topological_section_types (if specified) contains a flag that is not one of pygplates.ResolveTopologyType.boundary or pygplates.ResolveTopologyType.network

The following export file formats are currently supported:

Export File Format	Filename Extension
ESRI Shapefile	‘.shp’
GeoJSON	‘.geojson’ or ‘.json’
OGR GMT	‘.gmt’
GMT xy	‘.xy’

The argument export_topological_line_sub_segments only applies to topological lines. It determines whether to export the section of the resolved topological line (contributing to boundaries) or its sub-segments. Note that this also determines whether the feature properties (such as plate ID and feature type) of the topological line feature or its individual sub-segment features are exported.

Note

Resolved topological sections are exported in the same order as that of their respective topological features (see constructor) and the order across topological feature collections (if any) is also retained.

Changed in version 0.33: Added export_topological_line_sub_segments argument.

Changed in version 0.44: Filenames can be os.PathLike (such as pathlib.Path) in addition to strings.

export_resolved_topologies(export_filename[, resolve_topology_types=(pygplates.ResolveTopologyType.boundary|pygplates.ResolveTopologyType.network)][, wrap_to_dateline=True][, force_boundary_orientation])

Exports the resolved topologies of the requested type(s) to a file.

Parameters:

export_filename (string/os.PathLike) – the name of the export file
resolve_topology_types (a bitwise combination of any of pygplates.ResolveTopologyType.line, pygplates.ResolveTopologyType.boundary or pygplates.ResolveTopologyType.network) – specifies the resolved topology types to export - defaults to resolved topological boundaries and resolved topological networks (excludes resolved topological lines)
wrap_to_dateline (bool) – Whether to wrap/clip resolved topologies to the dateline (currently ignored unless exporting to an ESRI Shapefile format file). Defaults to True.
force_boundary_orientation (int) – Optionally force boundary orientation to clockwise (PolygonOnSphere.Orientation.clockwise) or counter-clockwise (PolygonOnSphere.Orientation.counter_clockwise). Only applies to resolved topological boundaries and networks (excludes lines). Note that ESRI Shapefiles always use clockwise orientation (and so ignore this parameter).

Raises:

ValueError if resolve_topology_types (if specified) contains a flag that is not one of pygplates.ResolveTopologyType.line, pygplates.ResolveTopologyType.boundary or pygplates.ResolveTopologyType.network

The following export file formats are currently supported:

Export File Format	Filename Extension
ESRI Shapefile	‘.shp’
GeoJSON	‘.geojson’ or ‘.json’
OGR GMT	‘.gmt’
GMT xy	‘.xy’

Note

Resolved topologies are exported in the same order as that of their respective topological features (see constructor) and the order across topological feature collections (if any) is also retained.

Changed in version 0.44: Filenames can be os.PathLike (such as pathlib.Path) in addition to strings.

get_anchor_plate_id()

Return the anchor plate ID (see constructor).

Return type:: int

Note

This is the same as the default anchor plate ID of get_rotation_model().

get_point_locations(points[, resolve_topology_types=(pygplates.ResolveTopologyType.boundary|pygplates.ResolveTopologyType.network)])

Returns the resolved topological boundaries/networks that contain the specified points.

Parameters:

points (any sequence of PointOnSphere or LatLonPoint or tuple (latitude,longitude), in degrees, or tuple (x,y,z)) – sequence of points at which to find containing topologies
resolve_topology_types (a bitwise combination of any of pygplates.ResolveTopologyType.boundary or pygplates.ResolveTopologyType.network) – specifies the resolved topology types to search - defaults to resolved topological boundaries and resolved topological networks (excludes resolved topological lines since lines cannot contain points)

Return type:

list of TopologyPointLocation

Raises:

ValueError if resolve_topology_types (if specified) contains a flag that is not one of pygplates.ResolveTopologyType.boundary or pygplates.ResolveTopologyType.network

Resolved topological networks have a higher priority than resolved topological boundaries since networks typically overlay rigid plates. So if a point is inside both a boundary and a network then the network location is returned.

Note

Each point that is outside all resolved topologies searched will have TopologyPointLocation.not_located_in_resolved_topology() returning True.

To associate each point with the resolved topological boundary/network containing it:

topology_point_locations = reconstruct_snapshot.get_point_locations(points)

for point_index in range(len(points)):
    point = points[point_index]
    topology_point_location = topology_point_locations[point_index]

    if topology_point_location.located_in_resolved_boundary():  # if point is inside a resolved boundary
        resolved_topological_boundary = topology_point_location.located_in_resolved_boundary()
    elif topology_point_location.located_in_resolved_network():  # if point is inside a resolved network
        resolved_topological_network = topology_point_location.located_in_resolved_network()
    else:  # point is not in any resolved topologies
        ...

Added in version 0.50.

get_point_strain_rates(points[, resolve_topology_types=(pygplates.ResolveTopologyType.boundary|pygplates.ResolveTopologyType.network)][, return_point_locations=False])

Returns the strain rates of the specified points (as determined by the resolved topological boundaries/networks that contain them).

Parameters:

points (any sequence of PointOnSphere or LatLonPoint or tuple (latitude,longitude), in degrees, or tuple (x,y,z)) – sequence of points at which to calculate strain rates
resolve_topology_types (a bitwise combination of any of pygplates.ResolveTopologyType.boundary or pygplates.ResolveTopologyType.network) – specifies the resolved topology types to use for strain rates - defaults to resolved topological boundaries and resolved topological networks (excludes resolved topological lines since lines cannot contain points)
return_point_locations – whether to also return the resolved topological boundary/network that contains each point - defaults to False

Return type:

list of StrainRate, or 2-tuple (list of StrainRate, list of TopologyPointLocation) if return_point_locations is True

Raises:

ValueError if resolve_topology_types (if specified) contains a flag that is not one of pygplates.ResolveTopologyType.boundary or pygplates.ResolveTopologyType.network

Resolved topological networks have a higher priority than resolved topological boundaries since networks typically overlay rigid plates. So a point that is inside a resolved topological network can generate a non-zero strain rate. However, a point that is inside a resolved topological boundary (but is outside all resolved topological networks searched) will generate a zero strain rate (pygplates.StrainRate.zero) since it is inside a non-deforming plate.

Note

Each point that is outside all resolved topologies searched (boundaries and networks) will have a strain rate of None, and optionally (if return_point_locations is True) have a TopologyPointLocation.not_located_in_resolved_topology() returning True.

To associate each point with its strain rate and the resolved topological boundary/network containing it:

strain_rates, topology_point_locations = topological_snapshot.get_point_strain_rates(
        points,
        return_point_locations=True)

for point_index in range(len(points)):
    point = points[point_index]
    strain_rate = strain_rates[point_index]
    topology_point_location = topology_point_locations[point_index]

    if strain_rate:  # if point is inside a resolved boundary or network
        ...

Note

It is more efficient to call topological_snapshot.get_point_strain_rates(points, return_point_locations=True) to get both strain rates and point locations than it is to call both topological_snapshot.get_point_strain_rates(points) and topological_snapshot.get_point_locations(points).

Note

Strain rates in deforming networks are calculated from the spatial gradients of velocity where the velocities are calculated over a 1 Myr time interval and using the equatorial Earth radius pygplates.Earth.equatorial_radius_in_kms.

Added in version 0.50.

get_point_velocities(points[, resolve_topology_types=(pygplates.ResolveTopologyType.boundary|pygplates.ResolveTopologyType.network)][, velocity_delta_time=1.0][, velocity_delta_time_type=pygplates.VelocityDeltaTimeType.t_plus_delta_t_to_t][, velocity_units=pygplates.VelocityUnits.kms_per_my][, earth_radius_in_kms=pygplates.Earth.mean_radius_in_kms][, return_point_locations=False])

Returns the velocities of the specified points (as determined by the resolved topological boundaries/networks that contain them).

Parameters:

points (any sequence of PointOnSphere or LatLonPoint or tuple (latitude,longitude), in degrees, or tuple (x,y,z)) – sequence of points at which to calculate velocities
resolve_topology_types (a bitwise combination of any of pygplates.ResolveTopologyType.boundary or pygplates.ResolveTopologyType.network) – specifies the resolved topology types to use for calculating velocities - defaults to resolved topological boundaries and resolved topological networks (excludes resolved topological lines since lines cannot contain points)
velocity_delta_time (float) – The time delta used to calculate velocities (defaults to 1 Myr).
velocity_delta_time_type (VelocityDeltaTimeType.t_plus_delta_t_to_t, VelocityDeltaTimeType.t_to_t_minus_delta_t or VelocityDeltaTimeType.t_plus_minus_half_delta_t) – How the two velocity times are calculated relative to the reconstruction time. This includes [t+dt, t], [t, t-dt] and [t+dt/2, t-dt/2]. Defaults to [t+dt, t].
velocity_units (VelocityUnits.kms_per_my or VelocityUnits.cms_per_yr) – whether to return velocities as kilometres per million years or centimetres per year (defaults to kilometres per million years)
earth_radius_in_kms (float) – the radius of the Earth in kilometres (defaults to pygplates.Earth.mean_radius_in_kms)
return_point_locations – whether to also return the resolved topological boundary/network that contains each point - defaults to False

Return type:

list of Vector3D, or 2-tuple (list of Vector3D, list of TopologyPointLocation) if return_point_locations is True

Raises:

ValueError if resolve_topology_types (if specified) contains a flag that is not one of pygplates.ResolveTopologyType.boundary or pygplates.ResolveTopologyType.network

Resolved topological networks have a higher priority than resolved topological boundaries since networks typically overlay rigid plates. So if a point is inside both a boundary and a network then the velocity of the network is returned.

Note

Each point that is outside all resolved topologies searched will have a velocity of None, and optionally (if return_point_locations is True) have a TopologyPointLocation.not_located_in_resolved_topology() returning True.

To associate each point with its velocity and the resolved topological boundary/network containing it:

velocities, topology_point_locations = topological_snapshot.get_point_velocities(
        points,
        return_point_locations=True)

for point_index in range(len(points)):
    point = points[point_index]
    velocity = velocities[point_index]
    topology_point_location = topology_point_locations[point_index]

    if velocity:  # if point is inside a resolved boundary or network
        ...

Note

It is more efficient to call topological_snapshot.get_point_velocities(points, return_point_locations=True) to get both velocities and point locations than it is to call both topological_snapshot.get_point_velocities(points) and topological_snapshot.get_point_locations(points).

Added in version 0.50.

get_reconstruction_time()

Return the reconstruction time of this snapshot.

Return type:: float

Added in version 0.43.

get_resolved_topological_sections([resolve_topological_section_types=(pygplates.ResolveTopologyType.boundary|pygplates.ResolveTopologyType.network)][, same_order_as_topological_features=False])

Returns the resolved topological sections of the requested type(s).

Parameters:

resolve_topological_section_types (a bitwise combination of any of pygplates.ResolveTopologyType.boundary or pygplates.ResolveTopologyType.network) – Determines whether ResolvedTopologicalBoundary or ResolvedTopologicalNetwork (or both types) are listed in the returned resolved topological sections. Note that pygplates.ResolveTopologyType.line cannot be specified since only topologies with boundaries are considered. Defaults to resolved topological boundaries and resolved topological networks.
same_order_as_topological_features (bool) – whether the returned resolved topological sections are sorted in the order of the topological features (including order across topological files, if there were any) - defaults to False

Return type:

list of ResolvedTopologicalSection

Raises:

ValueError if resolve_topological_section_types (if specified) contains a flag that is not one of pygplates.ResolveTopologyType.boundary or pygplates.ResolveTopologyType.network

Note

If same_order_as_topological_features is True then the returned resolved topological sections are sorted in the order of their respective topological features (see constructor). This includes the order across any topological feature collections/files.

get_resolved_topologies([resolve_topology_types=(pygplates.ResolveTopologyType.boundary|pygplates.ResolveTopologyType.network)][, same_order_as_topological_features=False])

Returns the resolved topologies of the requested type(s).

Parameters:

resolve_topology_types (a bitwise combination of any of pygplates.ResolveTopologyType.line, pygplates.ResolveTopologyType.boundary or pygplates.ResolveTopologyType.network) – specifies the resolved topology types to return - defaults to resolved topological boundaries and resolved topological networks
same_order_as_topological_features (bool) – whether the returned resolved topologies are sorted in the order of the topological features (including order across topological files, if there were any) - defaults to False

Returns:

the resolved topological lines, resolved topological boundaries and resolved topological networks (depending on the optional argument resolve_topology_types) - by default resolved topological lines are excluded

Return type:

list

Raises:

ValueError if resolve_topology_types (if specified) contains a flag that is not one of pygplates.ResolveTopologyType.line, pygplates.ResolveTopologyType.boundary or pygplates.ResolveTopologyType.network

Note

If same_order_as_topological_features is True then the returned resolved topologies are sorted in the order of their respective topological features (see constructor). This includes the order across any topological feature collections/files.

get_rotation_model()

Return the rotation model used internally.

Return type:: RotationModel

Note

The default anchor plate ID of the returned rotation model may be different to that of the rotation model passed into the constructor if an anchor plate ID was specified in the constructor.