Filters And Transformers

This page lists filter and transformer classes available in GPlately.

Feature Filters

class gplately.utils.feature_filter.FeatureFilter

Bases: object

Abstract base class for feature filters.

property filtrate_feature_collection

return the features that pass the filter as a pygplates.FeatureCollection.

property filtrate_features_as_list

return the features that pass the filter as a list. Use this property if you want to keep the order of the features.

property residue_feature_collection

return the features that do not pass the filter as a pygplates.FeatureCollection.

property residue_features_as_list

return the features that do not pass the filter as a list. Use this property if you want to keep the order of the features.

abstractmethod should_keep(feature: Feature) → bool

This abstract method must be implemented in subclass.

Parameters:

feature (pygplates.Feature)

Returns:

True if the feature should be kept; False otherwise.

Return type:

bool

class gplately.utils.feature_filter.FeatureNameFilter(names: List[str], exact_match=False, case_sensitive=False, reverse=False)

Bases: FeatureFilter

filter features by name, keep features with name matching any of the specified strings by default

Examples

Find features who name contains ‘Africa’ or ‘Asia’:

>>> FeatureNameFilter(['Africa', 'Asia'])

Find features who name doesn’t contain ‘Africa’ or ‘Asia’:

>>>  FeatureNameFilter(['Africa', 'Asia'], reverse=True)

Find features who name is exactly ‘Africa’ or ‘Asia’:

>>>  FeatureNameFilter(['Africa', 'Asia'], exact_match=True)

Find features who name is not ‘Africa’ or ‘Asia’:

>>>  FeatureNameFilter(['Africa', 'Asia'], reverse=True, exact_match=True)

Find features who name is not ‘Africa’ or ‘Asia’ (case sensitive):

>>>  FeatureNameFilter(['Africa', 'Asia'], reverse=True, exact_match=True, case_sensitive=True)

should_keep(feature: Feature) → bool

This abstract method must be implemented in subclass.

Parameters:

feature (pygplates.Feature)

Returns:

True if the feature should be kept; False otherwise.

Return type:

bool

class gplately.utils.feature_filter.PlateIDFilter(pids: List[int], reverse=False)

Bases: FeatureFilter

filter features by plate ID, keep features with plate ID in a specified list by default

Examples

Find features whose plate id is 101 or 201 or 301:

>>>  PlateIDFilter([101,201,301])

Find features whose plate id is not 101 nor 201 nor 301:

>>>  PlateIDFilter([101,201,301], reverse=True)

should_keep(feature: Feature) → bool

This abstract method must be implemented in subclass.

Parameters:

feature (pygplates.Feature)

Returns:

True if the feature should be kept; False otherwise.

Return type:

bool

class gplately.utils.feature_filter.BirthAgeFilter(age: float, reverse=False)

Bases: FeatureFilter

filter features by the time of appearance, keep older features by default

Examples

Find features which appreared before 500 Ma:

>>>  BirthAgeFilter(500)

Find features which appreared after 500 Ma:

>>> BirthAgeFilter(500, reverse=False)

should_keep(feature: Feature) → bool

This abstract method must be implemented in subclass.

Parameters:

feature (pygplates.Feature)

Returns:

True if the feature should be kept; False otherwise.

Return type:

bool

class gplately.utils.feature_filter.EndTimeFilter(end_time: float, reverse=False)

Bases: FeatureFilter

filter features by the time of disappearance, keep features that disappeared before a certain time by default

Examples

Find features which disappeared before 100 Ma:

>>> EndTimeFilter(100)

Find features which disappeared after 100 Ma, including features that have not disappeared yet:

>>> EndTimeFilter(100, reverse=False)

should_keep(feature: Feature) → bool

This abstract method must be implemented in subclass.

Parameters:

feature (pygplates.Feature)

Returns:

True if the feature should be kept; False otherwise.

Return type:

bool

class gplately.utils.feature_filter.FeatureTypeFilter(feature_types: str | List[str], reverse=False)

Bases: FeatureFilter

filter features by the feature type, keep features with feature type matching a specified regular expression by default. A list of feature types can also be provided, and the regular expression will be the combination of these feature types.

should_keep(feature: Feature) → bool

This abstract method must be implemented in subclass.

Parameters:

feature (pygplates.Feature)

Returns:

True if the feature should be kept; False otherwise.

Return type:

bool

class gplately.utils.feature_filter.PropertyExistsFilter(property_name: str, reverse=False)

Bases: FeatureFilter

filter features by the existence of a property, keep features that have a specific property by default

Depending on the value of reverse, this filter can be used to either keep features that have a specific property, or keep features that do not have that property.

Examples

Keep features that do not have the property gpml:subductionPolarity:

>>> PropertyExistsFilter("gpml:subductionPolarity", reverse=True)

should_keep(feature: Feature) → bool

This abstract method must be implemented in subclass.

Parameters:

feature (pygplates.Feature)

Returns:

True if the feature should be kept; False otherwise.

Return type:

bool

class gplately.utils.feature_filter.PropertyValueFilter(property_name: str, property_value, reverse=False)

Bases: FeatureFilter

filter features by the value of a property, keep features that have a specific property with a specific value by default

Depending on the value of “reverse” parameter, this filter can be used to either keep features that have the specific property and its value matches the specified value, or keep features that either do not have that property or its value does not match the specified value.

Examples

Keep features whose gpml:subductionPolarity property value is not Unknown:

>>> PropertyValueFilter("gpml:subductionPolarity", "Unknown", reverse=True)

should_keep(feature: Feature) → bool

This abstract method must be implemented in subclass.

Parameters:

feature (pygplates.Feature)

Returns:

True if the feature should be kept; False otherwise.

Return type:

bool

class gplately.utils.feature_filter.RegionOfInterestFilter(region_of_interest: Tuple[float, float, float, float] | PolygonOnSphere, reverse=False)

Bases: FeatureFilter

filter features by whether they are inside a region of interest, which can be defined by a bounding box or a polygon. By default, features that are inside the region of interest will pass the filter.

Examples

Keep features that are in the polygon:

>>> RegionOfInterestFilter(polygon)

Keep features that are not in the polygon:

>>> RegionOfInterestFilter(polygon, reverse=True)

should_keep(feature: Feature) → bool

This abstract method must be implemented in subclass.

Parameters:

feature (pygplates.Feature)

Returns:

True if the feature should be kept; False otherwise.

Return type:

bool

class gplately.utils.feature_filter.TopologicalFeaturesWithDuplicateSectionsFilter

Bases: FeatureFilter

find features whose topological geometries have duplicated section features.

No parameter is needed to create this filter. For the given feature, if any of its topological geometries has duplicated section features, the feature will pass the filter.

should_keep(feature: Feature) → bool

This abstract method must be implemented in subclass.

Parameters:

feature (pygplates.Feature)

Returns:

True if the feature should be kept; False otherwise.

Return type:

bool

class gplately.utils.feature_filter.TopologicalReferenceFilter(topological_feature_collection=<pygplates.pygplates.FeatureCollection object>)

Bases: FeatureFilter

find reference section features for given topological features

Given a collection of topological features, this filter will find section features that are used in the topological geometries of these topological features from another feature collection containing the real geometries.

A map of topological feature ID to the list of section feature IDs used in the topological geometries of that topological feature will also be created and stored in the filter, which can be accessed by the property “topological_reference_map”. The keys of this map are the string representation of the feature IDs of the topological features, and the values are lists of string representation of the feature IDs of the section features used in the topological geometries of that topological feature.

should_keep(feature: Feature) → bool

This abstract method must be implemented in subclass.

Parameters:

feature (pygplates.Feature)

Returns:

True if the feature should be kept; False otherwise.

Return type:

bool

property topological_reference_map

return the map of topological feature ID to the list of section feature IDs used in the topological geometries of that topological feature

class gplately.utils.feature_filter.FeatureIDFilter(fids: List[str], reverse=False)

Bases: FeatureFilter

Filter features by feature ID.

By default, this filter keeps features whose feature ID is present in fids. Set reverse=True to keep features whose feature ID is not present in fids.

Ordering behavior

When reverse=False, the output list in filtrate_features_as_list is arranged to follow the order of IDs in fids (with None placeholders for IDs that are not found).

When reverse=True, the output list in residue_features_as_list follows the order of IDs in fids (again with None placeholders for IDs that are not found).

Notes

• IDs in fids must be unique.

• If multiple features share the same feature ID in the input collection, only the

  first occurrence is kept in the ordered output list and a warning is logged.

Examples

Find features with IDs id1, id2, or id3:

>>> FeatureIDFilter(['id1', 'id2', 'id3'])

Find features whose IDs are not id1, id2, or id3:

>>> FeatureIDFilter(['id1', 'id2', 'id3'], reverse=True)

should_keep(feature: Feature) → bool

This abstract method must be implemented in subclass.

Parameters:

feature (pygplates.Feature)

Returns:

True if the feature should be kept; False otherwise.

Return type:

bool

class gplately.utils.feature_filter.ValidTimeFilter(begin_time: float = inf, end_time: float = -inf)

Bases: FeatureFilter

filter features by their valid time, keep features with valid time within a specified time range.

should_keep(feature: Feature) → bool

This abstract method must be implemented in subclass.

Parameters:

feature (pygplates.Feature)

Returns:

True if the feature should be kept; False otherwise.

Return type:

bool

Feature Transformers

class gplately.utils.feature_transformer.FeatureTransformer

Bases: object

Abstract base class for feature transformers.

abstractmethod transform(feature: Feature) → Feature

Transform a single feature.

This abstract method must be implemented by all subclasses. Implementations may modify the feature in place and/or return a new feature object.

Parameters:

feature (pygplates.Feature) – The feature to transform.

Returns:

The transformed feature (may be the same object or a new instance).

Return type:

pygplates.Feature

class gplately.utils.feature_transformer.SetReconstructionPlateIDTransformer(plate_id: int)

Bases: FeatureTransformer

Set the reconstruction plate ID of a feature to a specified value.

This transformer updates the reconstruction plate ID property of features, which is essential for plate kinematic reconstructions.

Parameters:

plate_id (int) – The reconstruction plate ID to assign to features. Typically a positive integer (0 is valid but represents an unspecified plate).

Examples

Create a transformer that sets plate ID to 801:

>>> transformer = SetReconstructionPlateIDTransformer(plate_id=801)

See also

SetValidTimeTransformer

Transformer for setting valid time intervals

transform(feature: Feature) → Feature

Transform a single feature.

This abstract method must be implemented by all subclasses. Implementations may modify the feature in place and/or return a new feature object.

Parameters:

feature (pygplates.Feature) – The feature to transform.

Returns:

The transformed feature (may be the same object or a new instance).

Return type:

pygplates.Feature

class gplately.utils.feature_transformer.SetValidTimeTransformer(begin_time: float | None = None, end_time: float | None = None)

Bases: FeatureTransformer

Set the valid time of a feature to specified begin and end times.

This transformer allows partial updates to feature valid time intervals. If only one time bound is specified, the existing bound is preserved.

Parameters:

• begin_time (float or None, optional) – The begin time (valid from) for the feature in Ma (millions of years ago). If None, the existing begin time is preserved. Default is None.

• end_time (float or None, optional) – The end time (valid until) for the feature in Ma (millions of years ago). If None, the existing end time is preserved. Default is None.

Examples

Set both begin and end times:

>>> transformer = SetValidTimeTransformer(begin_time=100.0, end_time=50.0)

Set only the begin time, preserving the existing end time:

>>> transformer = SetValidTimeTransformer(begin_time=100.0)

See also

SetReconstructionPlateIDTransformer

Transformer for setting reconstruction plate ID

transform(feature: Feature) → Feature

Transform a single feature.

This abstract method must be implemented by all subclasses. Implementations may modify the feature in place and/or return a new feature object.

Parameters:

feature (pygplates.Feature) – The feature to transform.

Returns:

The transformed feature (may be the same object or a new instance).

Return type:

pygplates.Feature