pygplates.partition_into_plates

pygplates.partition_into_plates(partitioning_features, rotation_model, features_to_partition, [properties_to_copy=[PartitionProperty.reconstruction_plate_id]], [reconstruction_time=0], [partition_method=PartitionMethod.split_into_plates], [partition_return=PartitionReturn.combined_partitioned_and_unpartitioned], [sort_partitioning_plates=SortPartitioningPlates.by_partition_type_then_plate_id])

Partition features into plates.

Parameters

partitioning_features (FeatureCollection, or string, or Feature, or sequence of Feature, or sequence of any combination of those four types) – the partitioning features
rotation_model (RotationModel or FeatureCollection or string or sequence of FeatureCollection instances and/or strings) – A rotation model or a rotation feature collection or a rotation filename or a sequence of rotation feature collections and/or rotation filenames
features_to_partition (FeatureCollection, or string, or Feature, or sequence of Feature, or sequence of any combination of those four types) – the features to be partitioned
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)
reconstruction_time (float or GeoTimeInstant) – the specific geological time to reconstruct/resolve the partitioning_features to (defaults to zero)
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)
sort_partitioning_plates (a SortPartitioningPlates enumeration value (see table below), or None) – optional sort order of partitioning plates (defaults to SortPartitioningPlates.by_partition_type_then_plate_id)

Returns

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

Return type

depends on partition_return (see table below)

The features in features_to_partition 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_to_partition argument) are never modified or returned.

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

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.

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_to_partition) 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:

features = pygplates.partition_into_plates(
        'static_polygons.gpml',
        'rotations.rot',
        '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:

features = pygplates.partition_into_plates(
        'static_polygons.gpml',
        'rotations.rot',
        '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:

features = pygplates.partition_into_plates(
        'static_polygons.gpml',
        'rotations.rot',
        '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


features = pygplates.partition_into_plates(
        'static_polygons.gpml',
        'rotations.rot',
        '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):

partitioned_features, unpartitioned_features = pygplates.partition_into_plates(
        'static_polygons.gpml',
        'rotations.rot',
        '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.

sort_partitioning_plates determines the sorting criteria used to order 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.partition_into_plates(..., 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):

features = pygplates.partition_into_plates(...,
    sort_partitioning_plates=pygplates.SortPartitioningPlates.by_partition_type_then_plate_area)