pygplates.PlatePartitioner

class pygplates.PlatePartitioner

Bases: Boost.Python.instance

Partition features or geometries into plates.

__init__(...)

A PlatePartitioner object can be constructed in more than one way. The following applies to both ways…

This table maps the values of the sort_partitioning_plates parameter to the sorting criteria used for the partitioning plates:

Value

Description

SortPartitioningPlates.by_partition_type

Group in order of resolved topological networks then resolved topological boundaries then reconstructed static polygons, but with no sorting within each group (ordering within each group is unchanged).

SortPartitioningPlates.by_partition_type_then_plate_id

Same as by_partition_type, but also sort by plate ID (from highest to lowest) within each partition type group.

SortPartitioningPlates.by_partition_type_then_plate_area

Same as by_partition_type, but also sort by plate area (from highest to lowest) within each partition type group.

SortPartitioningPlates.by_plate_id

Sort by plate ID (from highest to lowest), but no grouping by partition type.

SortPartitioningPlates.by_plate_area

Sort by plate area (from highest to lowest), but no grouping by partition type.

Note

If you don’t want to sort the partitioning plates (for example, if you have already sorted them) then you’ll need to explicitly specify None for the sort_partitioning_plates parameter (eg, pygplates.PlatePartitioner(..., sort_partitioning_plates=None)). This is because not specifying anything defaults to SortPartitioningPlates.by_partition_type_then_plate_id (since this always gives deterministic partitioning results).

If the partitioning plates overlap each other then their final ordering determines the partitioning results. Resolved topologies do not tend to overlap, but reconstructed static polygons do overlap (for non-zero reconstruction times) and hence the sorting order becomes relevant.

Partitioning of points is more efficient if you sort by plate area because an arbitrary point is likely to be found sooner when testing against larger partitioning polygons first (and hence more remaining partitioning polygons can be skipped). Since resolved topologies don’t tend to overlap you don’t need to sort them by plate ID to get deterministic partitioning results. So we are free to sort by plate area (well, plate area is also deterministic but not as deterministic as sorting by plate ID since modifications to the plate geometries change their areas but not their plate IDs). Note that we also group by partition type in case the topological networks happen to overlay the topological plate boundaries (usually this isn’t the case though):
plate_partitioner = pygplates.PlatePartitioner(..., sort_partitioning_plates=pygplates.SortPartitioningPlates.by_partition_type_then_plate_area)
Note

Only those reconstructed/resolved geometries that contain a polygon boundary are actually used for partitioning. For resolved topologies this includes ResolvedTopologicalBoundary and ResolvedTopologicalNetwork. For reconstructed geometries, a ReconstructedFeatureGeometry is only included if its reconstructed geometry is a PolygonOnSphere.

A PlatePartitioner object can be constructed in the following ways…

__init__(partitioning_plates, rotation_model, [sort_partitioning_plates=SortPartitioningPlates.by_partition_type_then_plate_id])

Create a partitioner from a sequence of reconstructed/resolved plates.

param partitioning_plates: A sequence of reconstructed/resolved plates to partition with.
type partitioning_plates: Any sequence of ReconstructionGeometry
param rotation_model: A rotation model or a rotation feature collection or a rotation filename or a sequence of rotation feature collections and/or rotation filenames
type rotation_model: RotationModel or FeatureCollection or string or sequence of FeatureCollection instances and/or strings
param sort_partitioning_plates: optional sort order of partitioning plates (defaults to SortPartitioningPlates.by_partition_type_then_plate_id)
type sort_partitioning_plates: One of the values in the SortPartitioningPlates table above, or None
raises: DifferentTimesInPartitioningPlatesError if all partitioning plates do not have the same reconstruction times

The partitioning_plates sequence can be generated by reconstructing regular geological features and/or resolving topological features.

rotation_model = pygplates.RotationModel('rotations.rot')

resolved_topologies = []
pygplates.resolve_topologies('topologies.gpml', rotation_model, resolved_topologies, reconstruction_time=0)

plate_partitioner = pygplates.PlatePartitioner(resolved_topologies, rotation_model)

Note

All partitioning plates should have been generated for the same reconstruction time otherwise DifferentTimesInPartitioningPlatesError is raised.

Note

rotation_model should be the same rotation model used to reconstruct/resolve the partitioning plates. This enables partitioned feature geometries to be reverse-reconstructed correctly in partition_features() for non-zero reconstruction times.

__init__(partitioning_features, rotation_model, [reconstruction_time=0], [sort_partitioning_plates=SortPartitioningPlates.by_partition_type_then_plate_id])

Create a partitioner by reconstructing/resolving plates from a sequence of plate features.

param partitioning_features: A sequence of plate features to partition with.
type partitioning_features: FeatureCollection, or string, or Feature, or sequence of Feature, or sequence of any combination of those four types
param rotation_model: A rotation model or a rotation feature collection or a rotation filename or a sequence of rotation feature collections and/or rotation filenames
type rotation_model: RotationModel or FeatureCollection or string or sequence of FeatureCollection instances and/or strings
param reconstruction_time: the specific geological time to reconstruct/resolve the partitioning_features to (defaults to zero)
type reconstruction_time: float or GeoTimeInstant
param sort_partitioning_plates: optional sort order of partitioning plates (defaults to SortPartitioningPlates.by_partition_type_then_plate_id)
type sort_partitioning_plates: One of the values in the SortPartitioningPlates table above, or None
raises: ValueError if reconstruction_time is distant past or distant future

The partitioning plates are generated internally by reconstructing the regular geological features and resolving the topological features in partitioning_features using the rotation model and optional reconstruction time.

To create a plate partitioner suitable for partitioning present day geometries/features (ie, reconstruction_time is zero):.

plate_partitioner = pygplates.PlatePartitioner('static_polygons.gpml', 'rotations.rot')

Methods

`__init__`(...)	A PlatePartitioner object can be constructed in more than one way.
`partition_features`(features, ...)	Partitions features into partitioning plates.
`partition_geometry`(geometry, ...)	Partitions one or more geometries into partitioning plates.
`partition_point`(point)	A convenient alternative to `partition_geometry()`, for a point, that finds the first partitioning plate (if any) containing the point.

partition_features(features, [properties_to_copy=[PartitionProperty.reconstruction_plate_id]], [partition_method=PartitionMethod.split_into_plates], [partition_return=PartitionReturn.combined_partitioned_and_unpartitioned])

Partitions features into partitioning plates.

Parameters

features (FeatureCollection, or string, or Feature, or sequence of Feature, or sequence of any combination of those four types) – the features to partition
properties_to_copy (a sequence of any combination of PropertyName and the PartitionProperty enumeration values (see table below)) – the properties to copy from partitioning plate features to the partitioned features (defaults to just the reconstruction plate ID)
partition_method (a PartitionMethod enumeration value (see table below)) – how the features are to be partitioned by the partitioning plates (defaults to PartitionMethod.split_into_plates)
partition_return (a PartitionReturn enumeration value (see table below)) – how to return the partitioned and unpartitioned features and whether to include the partitioning plates (defaults to PartitionReturn.combined_partitioned_and_unpartitioned)

Returns

the partitioned and unpartitioned features (note: new features are always returned, never the originals passed in via features)

Return type

depends on partition_return (see table below)

The features in features are tested for overlap/intersection with the partitioning plates using the partition method specified by partition_method. Properties are copied from the partitioning plate features to the features partitioned by them as specified by properties_to_copy (by default this is only the reconstruction plate ID).

Note

New features are always returned. The original features (passed into the features argument) are never modified or returned.

So while the partitioning polygons are reconstructed/resolved to the reconstruction time before testing for overlap/intersection, the geometries in the features to be partitioned (features) are not since they effectively represent a snapshot of the features at the reconstruction time. In other words the features to be partitioned effectively contain geometry at the reconstruction time (rather than present day) and hence they are not reconstructed to the reconstruction time before testing for overlap/intersection with the partitioning plates (even if they already happen to have a reconstruction plate ID property).

To partition features at present day (and assign reconstruction plate IDs) and write them to a new file:

plate_partitioner = pygplates.PlatePartitioner('static_polygons.gpml', 'rotations.rot')
features = plate_partitioner.partition_features('features_to_partition.gpml')

feature_collection = pygplates.FeatureCollection(features)
feature_collection.write('partitioned_and_unpartitioned_features.gpml')

partition_method specifies how the features are to be partitioned by the partitioning plates.

partition_method supports the following enumeration values:

Value

Description

PartitionMethod.split_into_plates

Split each feature into partitioning plates and into unpartitioned parts that are outside all partitioning plates (if plates don’t have global coverage).

For example, if a feature overlaps two plates then it will get cloned twice. Each clone will have its geometry set to the part of the original feature geometry contained within the respective partitioning plate. Any part (or parts) of the original feature geometry outside all the plates will result in a third cloned feature containing the unpartitioned geometry(s).

The two partitioned cloned features will have properties copied from the respective partitioned plate feature (as determined by properties_to_copy). The unpartitioned cloned feature will not have any properties copied to it.

PartitionMethod.most_overlapping_plate

Don’t split each feature into partitioning plates, instead use the partitioning plate that most overlaps the feature’s geometry.

For example, if a feature overlaps two plates then it will still only get cloned once (and its geometry unmodified). Only the most overlapping partitioning plate (if any) is selected. The overlap is measured based on the length of the polyline or polygon geometry contained within each partitioning plate (or number of points if geometry is a multipoint or point).

The cloned feature will have properties copied from the most overlapping partitioned plate feature (as determined by properties_to_copy) if it overlaps any, otherwise it will not have any properties copied to it.

Note that if a feature contains multiple geometries then they are treated as one composite geometry in the overlap calculation.

Note

VirtualGeomagneticPole features (of type FeatureType.gpml_virtual_geomagnetic_pole) ignore partition_method since these features are always partitioned using the average sample site position (PropertyName.gpml_average_sample_site_position). The pole position (PropertyName.gpml_pole_position) is not used during the partitioning.

To assign reconstruction plate IDs to features using the most overlapping partitioning plate:

plate_partitioner = pygplates.PlatePartitioner('static_polygons.gpml', 'rotations.rot')
features = plate_partitioner.partition_features(
        'features_to_partition.gpml',
        partition_method = pygplates.PartitionMethod.most_overlapping_plate)

properties_to_copy specifies the properties to copy from the partitioning features to the features that are being partitioned.

properties_to_copy supports a sequence of any of the following arguments:

Type	Description
PartitionProperty.reconstruction_plate_id	The reconstruction plate ID. This is an alternative to specifying the property name `PropertyName.gpml_reconstruction_plate_id`.
PartitionProperty.valid_time_period	The valid time period. This is an alternative to specifying the property name `PropertyName.gml_valid_time`.
PartitionProperty.valid_time_begin	Only the begin time of the valid time period of the partitioning feature is copied (the end time remains unchanged). If the begin time is later than (has a smaller value than) the end time then it is set to the end time. Note that there is no equivalent way to specify this using a PropertyName.
PartitionProperty.valid_time_end	Only the end time of the valid time period of the partitioning feature is copied (the begin time remains unchanged). If the end time is earlier than (has a larger value) the begin time then it is set to the begin time. Note that there is no equivalent way to specify this using a PropertyName.
`PropertyName`	Any property name. If the partitioning feature has one or more properties with this name then they will be copied/cloned to the feature being partitioned provided its `feature type` supports the property name.

Note

If a property cannot copied into a feature (eg, because the property is not supported the feature’s type) then that copy is silently ignored.

To copy/assign reconstruction plate ID, valid time period and name from the partitioning features to their associated partitioned features:

plate_partitioner = pygplates.PlatePartitioner('static_polygons.gpml', 'rotations.rot')
features = plate_partitioner.partition_features(
        'features_to_partition.gpml',
        properties_to_copy = [
            pygplates.PartitionProperty.reconstruction_plate_id,
            pygplates.PartitionProperty.valid_time_period,
            pygplates.PropertyName.gml_name])

properties_to_copy can also be a single callable (function):

Type

Description

Arbitrary callable (function)

A callable accepting the following arguments:

the partitioning feature
the feature being partitioned

This can be used to write your own implementation for copying properties.

An alternative way to copy/assign reconstruction plate ID, valid time period and name from the partitioning features to their associated partitioned features:

def properties_to_copy_func(partitioning_feature, feature):
    # If a property cannot be set on the feature (eg, because not supported by feature type)
    # then don't copy that property (ie, do nothing if pygplates.InformationModelError is raised).
    try:
        feature.set_reconstruction_plate_id(partitioning_feature.get_reconstruction_plate_id())
    except pygplates.InformationModelError:
        pass

    begin, end = partitioning_feature.get_valid_time()
    try:
        feature.set_valid_time(begin, end)
    except pygplates.InformationModelError:
        pass

    try:
        feature.set_name(partitioning_feature.get_name())
    except pygplates.InformationModelError:
        pass

    except pygplates.InformationModelError:
        pass


plate_partitioner = pygplates.PlatePartitioner('static_polygons.gpml', 'rotations.rot')
features = plate_partitioner.partition_features(
        'features_to_partition.gpml',
        properties_to_copy = properties_to_copy_func)

partition_return specifies how the features are to be partitioned by the partitioning plates. This applies regardless of the value of partition_method.

partition_return supports the following enumeration values:

Value

Return Type

Description

PartitionReturn.combined_partitioned_and_unpartitioned

list of Feature

Return a single combined list of partitioned and unpartitioned features.

PartitionReturn.separate_partitioned_and_unpartitioned

2-tuple ( list of partitioned features, list of unpartitioned features)

Return a 2-tuple whose first element is a list of partitioned features and whose second element is a list of unpartitioned features.

PartitionReturn.partitioned_groups_and_unpartitioned

2-tuple ( list of 2-tuple ( partitioning plate, list of partitioned features), list of unpartitioned features)

Return a 2-tuple whose first element is a list of partitioned groups and whose second element is a list of unpartitioned features.

Each partitioned group associates a partitioning plate with its partitioned features and consists of a 2-tuple whose first element is the partitioning plate and whose second element is a list of features partitioned by that plate.

To reset the reconstruction plate ID (to zero) for all unpartitioned features (features that did not intersect any partitioning plates):

plate_partitioner = pygplates.PlatePartitioner('static_polygons.gpml', 'rotations.rot')
partitioned_features, unpartitioned_features = plate_partitioner.partition_features(
        'features_to_partition.gpml',
        partition_return = pygplates.PartitionReturn.separate_partitioned_and_unpartitioned)

for unpartitioned_feature in unpartitioned_features:
    unpartitioned_feature.set_reconstruction_plate_id(0)

…this is useful when the features to be partitioned already have reconstruction plate IDs but they are deemed to be incorrect. By resetting them to zero we ensure the unpartitioned features remain stationary and do not reconstruct incorrectly over geological time. Any partitioned features will get a new plate ID.

partition_geometry(geometry[, partitioned_inside_geometries][, partitioned_outside_geometries])

Partitions one or more geometries into partitioning plates.

Parameters

geometry (GeometryOnSphere, or sequence (eg, list or tuple) of GeometryOnSphere) – the geometry, or geometries, to partition
partitioned_inside_geometries (list of 2-tuple (ReconstructionGeometry, list of GeometryOnSphere), or None) – optional list of geometries partitioned inside the partitioning plates (note that the list is not cleared first)
partitioned_outside_geometries (list of GeometryOnSphere, or None) – optional list of geometries partitioned outside all partitioning plates (note that the list is not cleared first)

Return type

bool

If geometry is inside any partitioning plates (even partially) then True is returned and the inside parts of geometry are appended to partitioned_inside_geometries (if specified) and the outside parts appended to partitioned_outside_geometries (if specified). Otherwise False is returned and geometry is appended to partitioned_outside_geometries (if specified).

Note

Each element in partitioned_inside_geometries is a 2-tuple consisting of a partitioning ReconstructionGeometry and a list of the geometry pieces partitioned into it (note that these pieces can come from multiple input geometries if geometry is a sequence). In contrast, partitioned_outside_geometries is simply a list of geometries outside all partitioning plates.

Warning

Support for partitioning a polygon geometry is partial. See PolygonOnSphere.partition() for more details.

To find the length of a polyline partitioned inside all reconstructed static polygons:

polyline_to_partition = pygplates.PolylineOnSphere(...)
polyline_inside_length = 0

plate_partitioner = pygplates.PlatePartitioner('static_polygons.gpml', 'rotations.rot')
partitioned_inside_geometries = []
if plate_partitioner.partition(polyline_to_partition, partitioned_inside_geometries):
    for partitioning_recon_geom, inside_geometries in partitioned_inside_geometries:
        for inside_geometry in inside_geometries:
            polyline_inside_length += inside_geometry.get_arc_length()

polyline_inside_length_in_kms = polyline_inside_length * pygplates.Earth.mean_radius_in_kms