Load and save feature collections

This example shows how to load feature data that is already in a file format that pyGPlates can load. If this is not the case then the feature data first needs to be imported.

See also

Import geometries and assign plate IDs

This example also shows how to save feature data.

Create a file containing a subset of features from another file

In this example we make a new GPML file containing only the coastlines that have a plate ID of 801 (Australia).

Sample code

import pygplates


# Load the global coastline features.
input_feature_collection = pygplates.FeatureCollection('coastlines.gpml')

# Start with an empty list of coastline features on plate 801.
features_in_plate_801 = []

# Iterate over all coastline features and add those on plate 801 to 'features_in_plate_801'.
for feature in input_feature_collection:
    if feature.get_reconstruction_plate_id() == 801:
        features_in_plate_801.append(feature)

# Write the coastline features for plate 801 to a new file.
output_feature_collection = pygplates.FeatureCollection(features_in_plate_801)
output_feature_collection.write('coastlines_801.gpml')

Details

The general idea is to use pygplates.FeatureCollection to both load and save features from/to files.

First we load a file containing GPlates coastline features into a pygplates.FeatureCollection from a file called 'coastlines.gpml'.

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

Alternatively we could have used the pygplates.FeatureCollection.read() function as follows:

features = pygplates.FeatureCollection.read('coastlines.gpml')

…or we could have used pygplates.FeatureCollectionFileFormatRegistry as follows:

registry = pygplates.FeatureCollectionFileFormatRegistry()
features = registry.read('coastlines.gpml')

…however the last two examples are more complicated than necessary.

Next we use a Python list to contain the subset of coastline features that are on plate 801.

It’s easier to use a Python list to contain the subset of features we will write to the new file.

We could have used a pygplates.FeatureCollection instead, but it doesn’t really matter since we can easily create a pygplates.FeatureCollection from the Python list when we need to save to a file.

features_in_plate_801 = []

Iterate over all the coastline features and only add those with plate ID 801 to the new list.

Note that a pygplates.FeatureCollection behaves like any sequence (eg, a Python list) and so we can iterate over it like we would any sequence using the syntax for item in sequence:.

for feature in features:
    if feature.get_reconstruction_plate_id() == 801:
        features_in_plate_801.append(feature)

As mentioned above, when we want to save features to a file we need to create a pygplates.FeatureCollection (it accepts any Python sequence containing features). In our case the Python sequence is our features_in_plate_801 list.

output_feature_collection = pygplates.FeatureCollection(features_in_plate_801)

Now we can write the output feature collection to a new file.

Here we’re saving the coastline features for plate 801 to a file called 'coastlines_801.gpml'.

output_feature_collection.write('coastlines_801.gpml')

Create a file containing features from multiple files

In this example we make a new GPML file containing ridges from one file and isochrons from another.

Sample code

import pygplates


# The list of files to merge.
filenames = ['ridges.gpml', 'isochrons.gpml']

# The list of features from all input files.
merged_features = []

# Iterate over the input files and add their features to the merged list.
for filename in filenames:
    features = pygplates.FeatureCollection(filename)
    merged_features.extend(features)

# Write the merged features to a file.
merged_feature_collection = pygplates.FeatureCollection(merged_features)
merged_feature_collection.write('ridges_and_isochrons.gpml')

Details

The general idea is to use pygplates.FeatureCollection to both load and save features from/to files.

Iterate over all the input files, read features from each file and add to a list of merged features.

Note that a pygplates.FeatureCollection behaves like any sequence (eg, a Python list) and so we can pass it to the list.extend() method of our merged_features Python list and it will iterate over our pygplates.FeatureCollection sequence to retrieve features and extend the merged_features list.

merged_features = []
for filename in filenames:
    features = pygplates.FeatureCollection(filename)
    merged_features.extend(features)

Write the merged feature collection to a new file using pygplates.FeatureCollection.

merged_feature_collection = pygplates.FeatureCollection(merged_features)
merged_feature_collection.write('ridges_and_isochrons.gpml')