pygplates.FeatureCollection

class pygplates.FeatureCollection([features])

Bases: Boost.Python.instance

The 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.

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

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 read from a file and written to a file.

Note

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

__init__([features])

Create a new feature collection instance.

Parameters:features (string, 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_features = pygplates.FeatureCollection('coastlines.gpml')

Note

If a filename is specified then FeatureCollectionFileFormatRegistry is used internally to read the file.

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(...)

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)
read(filename)

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

Parameters:filename (string, or sequence of strings) – 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]):
    ...

Note

This function is equivalent to:

registry = pygplates.FeatureCollectionFileFormatRegistry()
feature_collection = registry.read(filename)

See also

For the list of supported file formats see FeatureCollectionFileFormatRegistry.

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) – 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)

Note

This function is equivalent to:

registry = pygplates.FeatureCollectionFileFormatRegistry()
registry.write(feature_collection, filename)

See also

For the list of supported file formats see FeatureCollectionFileFormatRegistry.

Previous topic

pygplates.Feature

Next topic

pygplates.Property

This Page