pygplates.FeatureCollection

class pygplates.FeatureCollection

Bases: instance

A feature collection aggregates a set of features into a collection. This is traditionally so that a group of features can be loaded, saved or unloaded in a single operation.

For example, to read coastline features from a file:

coastline_feature_collection = pygplates.FeatureCollection('coastlines.gpml')

And to write coastline features to a file:

coastline_feature_collection = pygplates.FeatureCollection(coastline_features)
coastline_feature_collection.write('coastlines.gpml')

The following feature collection file formats are currently supported:

File Format	Filename Extension	Supports Read	Supports Write
GPlates Markup Language	‘.gpml’	Yes	Yes
Compressed GPML	‘.gpmlz’ or ‘.gpml.gz’	Yes	Yes
PLATES4 line	‘.dat’ or ‘.pla’	Yes	Yes
PLATES4 rotation	‘.rot’	Yes	Yes
GPlates rotation	‘.grot’	Yes	Yes
ESRI Shapefile	‘.shp’	Yes	Yes
GeoJSON	‘.geojson’ or ‘.json’	Yes	Yes
GeoPackage	‘.gpkg’	Yes	Yes
OGR GMT	‘.gmt’	Yes	Yes
GMT xy	‘.xy’	No	Yes
GMAP Virtual Geomagnetic Poles	‘.vgp’	Yes	No

In the future, support will be added to enable users to implement and register readers/writers for other file formats (or their own non-standard file formats).

The following operations for accessing the features are supported:

Operation	Result
`len(fc)`	number of features in feature collection fc
`for f in fc`	iterates over the features f in feature collection fc
`fc[i]`	the feature of fc at index i

For example:

num_features = len(feature_collection)
features_in_collection = [feature for feature in feature_collection]
# assert(num_features == len(features_in_collection))

Note

A feature collection can be deep copied using clone().

A FeatureCollection can also be pickled.

Changed in version 0.31: Can index a feature in feature collection fc with fc[i].

Changed in version 0.42: Added pickle support.

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

__init__([features])

Create a new feature collection instance.

Parameters:: features (string/os.PathLike, or a sequence (eg, list or tuple) of Feature, or a single Feature) – an optional filename, or sequence of features, or a single feature
Raises:: OpenFileForReadingError if file is not readable (if filename specified)
Raises:: FileFormatNotSupportedError if file format (identified by the filename extension) does not support reading (when filename specified)

To create a new feature collection from a file:

coastline_feature_collection = pygplates.FeatureCollection('coastlines.gpml')

To create a new feature collection from a sequence of features:

feature_collection = pygplates.FeatureCollection([feature1, feature2])

# ...is the equivalent of...

feature_collection = pygplates.FeatureCollection()
feature_collection.add(feature1)
feature_collection.add(feature2)

Note

Since a FeatureCollection is an iterable sequence of features it can be used in the features argument.

This creates a shallow copy much in the same way as with a Python list (for example shallow_copy_list = list(original_list)):

shallow_copy_feature_collection = pygplates.FeatureCollection(original_feature_collection)

# Modifying the collection/list of features in the shallow copy will not affect the original...
shallow_copy_feature_collection.add(...)
# assert(len(shallow_copy_feature_collection) != len(original_feature_collection))

# Modifying the actual feature data in the collection will affect both feature collections
# since the feature data is shared by both collections...
for feature in original_feature_collection:
    # Changing the reconstruction plate ID affects both original and shallow copy collections.
    feature.set_reconstruction_plate_id(...)

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

Methods

`__init__`([features])	Create a new feature collection instance.
`add`(feature)	Adds one or more features to this collection.
`clone`()	Create a duplicate of this feature collection instance.
`get`(feature_query, ...)	Returns one or more features matching a feature type, feature id or predicate.
`read`(filename)	[staticmethod] Reads one or more feature collections (from one or more files).
`remove`(feature_query)	Removes features from this collection.
`write`(filename)	Writes this feature collection to the file with name filename.

add(feature)

Adds one or more features to this collection.

Parameters:: feature (Feature or sequence (eg, list or tuple) of Feature) – one or more features to add

A feature collection is an unordered collection of features so there is no concept of where a feature is inserted in the sequence of features.

feature_collection.add(feature)
feature_collection.add([feature1, feature2])

clone()

Create a duplicate of this feature collection instance.

Return type:: FeatureCollection

This creates a new FeatureCollection instance with cloned versions of this collection’s features. And the cloned features (in the cloned collection) are each created with a unique FeatureId.

get(feature_query[, feature_return=FeatureReturn.exactly_one])

Returns one or more features matching a feature type, feature id or predicate.

Parameters:

feature_query (FeatureType, or FeatureId, or callable (accepting single Feature argument)) – the feature type, feature id or predicate function that matches the feature (or features) to get
feature_return (FeatureReturn.exactly_one, FeatureReturn.first or FeatureReturn.all) – whether to return exactly one feature, the first feature or all matching features

Return type:

Feature, or list of Feature, or None

The following table maps feature_return values to return values:

FeatureReturn Value	Description
exactly_one	Returns a `Feature` only if feature_query matches exactly one feature, otherwise `None` is returned.
first	Returns the first `Feature` that matches feature_query - however note that a feature collection is an unordered collection of features. If no features match then `None` is returned.
all	Returns a `list` of `features` matching feature_query. If no features match then the returned list will be empty.

isochron_feature_type = pygplates.FeatureType.gpml_isochron
exactly_one_isochron = feature_collection.get(isochron_feature_type)
first_isochron = feature_collection.get(isochron_feature_type, pygplates.FeatureReturn.first)
all_isochrons = feature_collection.get(isochron_feature_type, pygplates.FeatureReturn.all)

feature_matching_id = feature_collection.get(feature_id)

# Using a predicate function that returns true if feature's type is 'gpml:Isochron' and 
# reconstruction plate ID is less than 700.
recon_plate_id_less_700_isochrons = feature_collection.get(
    lambda feature: feature.get_feature_type() == pygplates.FeatureType.gpml_isochron and
                    feature.get_reconstruction_plate_id() < 700,
    pygplates.FeatureReturn.all)

static read(filename)

[staticmethod] Reads one or more feature collections (from one or more files).

Parameters:: filename (string/os.PathLike, or sequence of string/os.PathLike) – the name of the file (or files) to read
Return type:: FeatureCollection, list of FeatureCollection
Raises:: OpenFileForReadingError if any file is not readable
Raises:: FileFormatNotSupportedError if any file format (identified by a filename extension) does not support reading

feature_collection = pygplates.FeatureCollection.read(filename)

…although for a single file the following is even easier:

feature_collection = pygplates.FeatureCollection(filename)

Multiple files can also be read:

for feature_collection in pygplates.FeatureCollection.read([filename1, filename2]):
    ...

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

remove(feature_query)

Removes features from this collection.

Parameters:: feature_query (FeatureType, or FeatureId, or Feature, or callable (accepting single Feature argument), or a sequence (eg, list or tuple) of any combination of them) – one or more feature types, feature IDs, feature instances or predicate functions that determine which features to remove
Raises:: ValueError if any specified Feature is not currently a feature in this collection

All features matching any FeatureType, FeatureId or predicate callable (if any specified) will be removed. Any specified FeatureType, FeatureId or predicate callable that does not match a feature in this collection is ignored. However if any specified Feature is not currently a feature in this collection then the ValueError exception is raised - note that the same Feature instance must have previously been added (in other words the feature values are not compared - it actually looks for the same feature instance).

feature_collection.remove(feature_id)
feature_collection.remove(pygplates.FeatureType.gpml_volcano)
feature_collection.remove([
    pygplates.FeatureType.gpml_volcano,
    pygplates.FeatureType.gpml_isochron])

for feature in feature_collection:
    if predicate(feature):
        feature_collection.remove(feature)
feature_collection.remove([feature for feature in feature_collection if predicate(feature)])
feature_collection.remove(predicate)

# Mix different query types.
# Remove a specific 'feature' instance and any features of type 'gpml:Isochron'...
feature_collection.remove([feature, pygplates.FeatureType.gpml_isochron])

# Remove features of type 'gpml:Isochron' with reconstruction plate IDs less than 700...
feature_collection.remove(
    lambda feature: feature.get_feature_type() == pygplates.FeatureType.gpml_isochron and
                     feature.get_reconstruction_plate_id() < 700)

# Remove features of type 'gpml:Volcano' and 'gpml:Isochron'...
feature_collection.remove([
    lambda feature: feature.get_feature_type() == pygplates.FeatureType.gpml_volcano,
    pygplates.FeatureType.gpml_isochron])
feature_collection.remove(
    lambda feature: feature.get_feature_type() == pygplates.FeatureType.gpml_volcano or
                     feature.get_feature_type() == pygplates.FeatureType.gpml_isochron)

write(filename)

Writes this feature collection to the file with name filename.

Parameters:: filename (string/os.PathLike) – the name of the file to write
Raises:: OpenFileForWritingError if the file is not writable
Raises:: FileFormatNotSupportedError if the file format (identified by the filename extension) does not support writing

feature_collection.write(filename)

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