pygplates.FeatureCollection¶

class pygplates.FeatureCollection¶

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)

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

pygplates.FeatureCollection¶

Previous topic

Next topic

This Page