Module `gplately.gpml`

This sub-module contains functions for manipulating GPML (.gpml, .gpmlz) files, as well as pygplates.Feature and pygplates.FeatureCollection objects.

Functions

def create_feature_dict(features, id_type=pygplates.pygplates.FeatureId)

Create a dictionary mapping feature IDs to features.

Feature IDs can be either str or pygplates.FeatureId, according to id_type.

Parameters

features : valid argument for pygplates.FeaturesFunctionArgument: features may be a single pygplates.Feature, a pygplates.FeatureCollection, a str filename, or a (potentially nested) sequence of any combination of the above.
id_type : {pygplates.FeatureId, str}, optional: By default, dictionary keys will be of type pygplates.FeatureId; pass id_type=str to use string representations instead.

Returns

dict: Dictionary for looking up features by their feature ID. N.B. the result will be an empty dictonary if features is empty.

Raises

TypeError: If id_type is not one of {pygplates.FeatureId, str}, or if features is of an invalid type.
OSError (including FileNotFoundError, IsADirectoryError): If features points to a non-existent or unrecognised file.

def extract_feature(id, features)

Return the feature with the given feature ID.

Searches through features and returns the feature with a feature ID matching id. The order of features is not preserved, so multiple features sharing the same feature ID should be avoided.

Parameters

id : pygplates.FeatureId or str: The feature ID (or string representation) to search for.
features : valid argument for pygplates.FeaturesFunctionArgument: features may be a single pygplates.Feature, a pygplates.FeatureCollection, a str filename, or a (potentially nested) sequence of any combination of the above.

Returns

pygplates.Feature or None: The matching feature if found, otherwise None.

Raises

TypeError: If id is not one of {pygplates.FeatureId, str}, or if features is of an invalid type.
OSError (including FileNotFoundError, IsADirectoryError): If features points to a non-existent or unrecognised file.

def get_topological_references(features, id_type=pygplates.pygplates.FeatureId)

Create a dictionary mapping topological feature IDs to referenced features.

The resulting dictionary maps each topological pygplates.FeatureId in features to the set of pygplates.FeatureId referenced by its topological geometry or geometries.

Parameters

features : valid argument for pygplates.FeaturesFunctionArgument: features may be a single pygplates.Feature, a pygplates.FeatureCollection, a str filename, or a (potentially nested) sequence of any combination of the above.
id_type : {pygplates.FeatureId, str}, optional: By default, feature IDs will be of type pygplates.FeatureId; pass id_type=str to use string representations instead.

Returns

dict: N.B. Dictionary keys include all topological features in features, and only topological features.

Raises

TypeError: If id_type is not one of {pygplates.FeatureId, str}, or if features is of an invalid type.
OSError (including FileNotFoundError, IsADirectoryError): If features points to a non-existent or unrecognised file.

def is_topological(feature)

Determine whether a feature contains a topological geometry.

Parameters

feature : pygplates.Feature

Returns

bool: True if feature contains a topological geometry, else False.

Raises

TypeError: If feature is a type other than pygplates.Feature (more precisely, if its type does not implement get_all_topological_geometries).