pygplates.Feature<a class="headerlink" href="#pygplates-feature" title="Permalink to this headline">

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and seed_geometry is not a PointOnSphere or a MultiPointOnSphere.

Raises

GmlTimePeriodBeginTimeLaterThanEndTimeError if valid_time has begin time later than end time

This function calls set_geometry(). It optionally calls set_times(), set_name(), set_description(), set_valid_time(), set_left_plate(), set_right_plate(), set_reconstruction_method() and add(). The feature type is a flowline.

Create a flowline feature:

present_day_seed_geometry = pygplates.MultiPointOnSphere([...])
flowline_feature = pygplates.Feature.create_flowline(
    present_day_seed_geometry,
    [0, 10, 20, 30, 40],
    valid_time=(50, 0),
    left_plate=201,
    right_plate=701)

If seed_geometry is not present-day geometry then the created feature will need to be reverse reconstructed to present day using (using either the reverse_reconstruct parameter or reverse_reconstruct()) before the feature can be reconstructed to an arbitrary reconstruction time - this is because a feature is not complete until its geometry is present day geometry.

Create a flowline feature (note that it must also be reverse reconstructed since the specified geometry is not present day geometry):

seed_geometry_at_50Ma = pygplates.MultiPointOnSphere([...])
flowline_feature = pygplates.Feature.create_flowline(
    seed_geometry_at_50Ma,
    [0, 10, 20, 30, 40],
    valid_time=(50, 0),
    left_plate=201,
    right_plate=701,
    reverse_reconstruct=(rotation_model, 50))

The previous example is the equivalent of the following (note that the reverse reconstruction is done after the properties have been set on the feature - this is necessary because reverse reconstruction looks at these properties to determine how to reverse reconstruct):

flowline_feature = pygplates.Feature(pygplates.FeatureType.gpml_flowline)
flowline_feature.set_geometry(seed_geometry_at_50Ma)
flowline_feature.set_times([0, 10, 20, 30, 40])
flowline_feature.set_valid_time(50, 0)
flowline_feature.set_left_plate(201)
flowline_feature.set_right_plate(701)
flowline_feature.set_reconstruction_method('HalfStageRotationVersion3')
pygplates.reverse_reconstruct(flowline_feature, rotation_model, 50)

# ...or...

flowline_feature = pygplates.Feature(pygplates.FeatureType.gpml_flowline)
flowline_feature.set_times([0, 10, 20, 30, 40])
flowline_feature.set_valid_time(50, 0)
flowline_feature.set_left_plate(201)
flowline_feature.set_right_plate(701)
flowline_feature.set_reconstruction_method('HalfStageRotationVersion3')
# Set geometry and reverse reconstruct *after* other feature properties have been set.
flowline_feature.set_geometry(
    seed_geometry_at_50Ma,
    reverse_reconstruct=(rotation_model, 50))

Note

In the above example we needed to call set_reconstruction_method() to set up a half-stage rotation since that is what create_flowline() calls internally.

static create_motion_path(seed_geometry, times[, name][, description][, valid_time][, relative_plate][, reconstruction_plate_id][, other_properties][, feature_id][, reverse_reconstruct][, verify_information_model=VerifyInformationModel.yes])

[staticmethod] Create a motion path feature.

Parameters

seed_geometry (PointOnSphere or MultiPointOnSphere) – the seed point (or points) - see set_geometry() - if geometry is not present-day geometry then the created feature will need to be reverse reconstructed to present day (using either the reverse_reconstruct parameter or reverse_reconstruct()) before the feature can be reconstructed to an arbitrary reconstruction time
times (sequence (eg, list or tuple) of float or GeoTimeInstant) – the list of times
name (string, or sequence of string) –
the name or names, if not specified then no pygplates.PropertyName.gml_name properties are added
description (string) –
the description, if not specified then a pygplates.PropertyName.gml_description property is not added
valid_time (a tuple of (float or GeoTimeInstant, float or GeoTimeInstant)) –
the (begin_time, end_time) tuple, if not specified then a pygplates.PropertyName.gml_valid_time property is not added
relative_plate (int) – the relative plate id, if not specified then a pygplates.PropertyName.gpml_relative_plate property is not added
reconstruction_plate_id (int) – the reconstruction plate id, if not specified then a pygplates.PropertyName.gpml_reconstruction_plate_id property is not added
other_properties (a sequence (eg, list or tuple) of (PropertyName, PropertyValue or sequence of PropertyValue)) – any extra property name/value pairs to add, these can alternatively be added later with add()
feature_id (FeatureId) – the feature identifier, if not specified then a unique feature identifier is created
reverse_reconstruct (tuple (RotationModel, float or GeoTimeInstant [, int])) – the tuple (rotation model, seed geometry reconstruction time [, anchor plate id]) where the anchor plate is optional (defaults to default anchor plate of rotation model) - if this tuple of reverse reconstruct parameters is specified then seed_geometry is reverse reconstructed using those parameters and any specified feature properties (eg, reconstruction_plate_id) - this is only required if seed_geometry is not present day - alternatively you can subsequently call reverse_reconstruct()
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model (default) or not

Return type

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and seed_geometry is not a PointOnSphere or a MultiPointOnSphere.

Raises

GmlTimePeriodBeginTimeLaterThanEndTimeError if valid_time has begin time later than end time

This function calls set_geometry(). It optionally calls set_times(), set_name(), set_description(), set_valid_time(), set_relative_plate(), set_reconstruction_plate_id(), set_reconstruction_method() and add(). The feature type is a motion path.

Create a motion path feature:

present_day_seed_geometry = pygplates.MultiPointOnSphere([...])
motion_path_feature = pygplates.Feature.create_motion_path(
    present_day_seed_geometry,
    [0, 10, 20, 30, 40],
    valid_time=(50, 0),
    relative_plate=201,
    reconstruction_plate_id=701)

If seed_geometry is not present-day geometry then the created feature will need to be reverse reconstructed to present day using (using either the reverse_reconstruct parameter or reverse_reconstruct()) before the feature can be reconstructed to an arbitrary reconstruction time - this is because a feature is not complete until its geometry is present day geometry.

Create a motion path feature (note that it must also be reverse reconstructed since the specified geometry is not present day geometry):

seed_geometry_at_50Ma = pygplates.MultiPointOnSphere([...])
motion_path_feature = pygplates.Feature.create_motion_path(
    seed_geometry_at_50Ma,
    [0, 10, 20, 30, 40],
    valid_time=(50, 0),
    relative_plate=201,
    reconstruction_plate_id=701,
    reverse_reconstruct=(rotation_model, 50))

The previous example is the equivalent of the following (note that the reverse reconstruction is done after the properties have been set on the feature - this is necessary because reverse reconstruction looks at these properties to determine how to reverse reconstruct):

motion_path_feature = pygplates.Feature(pygplates.FeatureType.gpml_motion_path)
motion_path_feature.set_geometry(seed_geometry_at_50Ma)
motion_path_feature.set_times([0, 10, 20, 30, 40])
motion_path_feature.set_valid_time(50, 0)
motion_path_feature.set_relative_plate(201)
motion_path_feature.set_reconstruction_plate_id(701)
pygplates.reverse_reconstruct(motion_path_feature, rotation_model, 50)

# ...or...

motion_path_feature = pygplates.Feature(pygplates.FeatureType.gpml_motion_path)
motion_path_feature.set_times([0, 10, 20, 30, 40])
motion_path_feature.set_valid_time(50, 0)
motion_path_feature.set_relative_plate(201)
motion_path_feature.set_reconstruction_plate_id(701)
# Set geometry and reverse reconstruct *after* other feature properties have been set.
motion_path_feature.set_geometry(
    seed_geometry_at_50Ma,
    reverse_reconstruct=(rotation_model, 50))

static create_reconstructable_feature(feature_type, geometry[, name][, description][, valid_time][, reconstruction_plate_id][, conjugate_plate_id][, other_properties][, feature_id][, reverse_reconstruct][, verify_information_model=VerifyInformationModel.yes])

[staticmethod] Create a reconstructable feature.

Parameters

feature_type (FeatureType) – the type of feature to create
geometry (GeometryOnSphere, or sequence (eg, list or tuple) of GeometryOnSphere (or a coverage or a sequence of coverages - set_geometry())) – the geometry (or geometries, or a coverage or a sequence of coverages) - if geometry is not present-day geometry then the created feature will need to be reverse reconstructed to present day (using either the reverse_reconstruct parameter or reverse_reconstruct()) before the feature can be reconstructed to an arbitrary reconstruction time
name (string, or sequence of string) –
the name or names, if not specified then no pygplates.PropertyName.gml_name properties are added
description (string) –
the description, if not specified then a pygplates.PropertyName.gml_description property is not added
valid_time (a tuple of (float or GeoTimeInstant, float or GeoTimeInstant)) –
the (begin_time, end_time) tuple, if not specified then a pygplates.PropertyName.gml_valid_time property is not added
reconstruction_plate_id (int) –
the reconstruction plate id, if not specified then a pygplates.PropertyName.gpml_reconstruction_plate_id property is not added
conjugate_plate_id (int, or sequence of int) – the conjugate plate ID or plate IDs, if not specified then no pygplates.PropertyName.gpml_conjugate_plate_id properties are added - note that not all reconstructable features have a conjugate plate ID (conjugate_plate_id is provided to support the Isochron feature type)
other_properties (a sequence (eg, list or tuple) of (PropertyName, PropertyValue or sequence of PropertyValue)) – any extra property name/value pairs to add, these can alternatively be added later with add()
feature_id (FeatureId) – the feature identifier, if not specified then a unique feature identifier is created
reverse_reconstruct (tuple (RotationModel, float or GeoTimeInstant [, int])) – the tuple (rotation model, geometry reconstruction time [, anchor plate id]) where the anchor plate is optional (defaults to default anchor plate of rotation model) - if this tuple of reverse reconstruct parameters is specified then geometry is reverse reconstructed using those parameters and any specified feature properties (eg, reconstruction_plate_id) - this is only required if geometry is not present day - alternatively you can subsequently call reverse_reconstruct()
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model (default) or not

Return type

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and feature_type is not a reconstructable feature.

Raises

GmlTimePeriodBeginTimeLaterThanEndTimeError if valid_time has begin time later than end time

This function creates a feature of type that falls in the category of a reconstructable feature - note that there are multiple feature types that fall into this category.

Note

Advanced

This function creates a feature with a type that falls in the category of reconstructable features.
If a feature type falls in this category then we know it supports the gml:name, gml:description, gml:validTime and gpml:reconstructionPlateId properties required by this function.
There are multiple feature types that fall into this category. These can be seen by looking at the Inherited by features sub-section of gpml:ReconstructableFeature. One of the inherited feature types is gpml:TangibleFeature which in turn has a list of Inherited by features - one of which is gpml:Coastline. This means that a gpml:Coastline feature type inherits (indirectly) from a gpml:ReconstructableFeature. When a feature type inherits another feature type it essentially means it supports the same properties.
So a gpml:Coastline feature type is one of many feature types than can be used with this function.

A gpml:conjugatePlateId is not supported by all reconstructable features. It is provided (via the conjugate_plate_id argument) to support the gpml:Isochron feature type which is commonly encountered. Reconstructable features not supporting gpml:conjugatePlateId should not specify the conjugate_plate_id argument.

This function calls set_geometry(). It optionally calls set_name(), set_description(), set_valid_time(), set_reconstruction_plate_id(), set_conjugate_plate_id() and add().

Create a coastline feature:

present_day_coastline_geometry = pygplates.PolylineOnSphere([...])
east_antarctica_coastline_feature = pygplates.Feature.create_reconstructable_feature(
    pygplates.FeatureType.gpml_coastline,
    present_day_coastline_geometry,
    name='East Antarctica',
    valid_time=(600, pygplates.GeoTimeInstant.create_distant_future()),
    reconstruction_plate_id=802)

If geometry is not present-day geometry (see isochron example below) then the created feature will need to be reverse reconstructed to present day (using either the reverse_reconstruct parameter or reverse_reconstruct()) before the feature can be reconstructed to an arbitrary reconstruction time - this is because a feature is not complete until its geometry is present day geometry.

Create an isochron feature (note that it must also be reverse reconstructed since the specified geometry is not present day geometry but instead the geometry of the mid-ocean ridge that the isochron came from at the isochron’s time of appearance):

time_of_appearance = 600
geometry_at_time_of_appearance = pygplates.PolylineOnSphere([...])
isochron_feature = pygplates.Feature.create_reconstructable_feature(
    pygplates.FeatureType.gpml_isochron,
    geometry_at_time_of_appearance,
    name='SOUTH ATLANTIC, SOUTH AMERICA-AFRICA ANOMALY 13 ISOCHRON',
    valid_time=(time_of_appearance, pygplates.GeoTimeInstant.create_distant_future()),
    reconstruction_plate_id=201,
    conjugate_plate_id=701,
    reverse_reconstruct=(rotation_model, time_of_appearance))

# ...or...

isochron_feature = pygplates.Feature.create_reconstructable_feature(
    pygplates.FeatureType.gpml_isochron,
    geometry_at_time_of_appearance,
    name='SOUTH ATLANTIC, SOUTH AMERICA-AFRICA ANOMALY 13 ISOCHRON',
    valid_time=(time_of_appearance, pygplates.GeoTimeInstant.create_distant_future()),
    reconstruction_plate_id=201,
    conjugate_plate_id=701)
pygplates.reverse_reconstruct(isochron_feature, rotation_model, time_of_appearance)

The previous example is the equivalent of the following (note that the reverse reconstruction is done after the properties have been set on the feature - this is necessary because reverse reconstruction looks at these properties to determine how to reverse reconstruct):

isochron_feature = pygplates.Feature(pygplates.FeatureType.gpml_isochron)
isochron_feature.set_geometry(geometry_at_time_of_appearance)
isochron_feature.set_name('SOUTH ATLANTIC, SOUTH AMERICA-AFRICA ANOMALY 13 ISOCHRON')
isochron_feature.set_valid_time(time_of_appearance, pygplates.GeoTimeInstant.create_distant_future())
isochron_feature.set_reconstruction_plate_id(201)
isochron_feature.set_conjugate_plate_id(701)
pygplates.reverse_reconstruct(isochron_feature, rotation_model, time_of_appearance)

# ...or...

isochron_feature = pygplates.Feature(pygplates.FeatureType.gpml_isochron)
isochron_feature.set_name('SOUTH ATLANTIC, SOUTH AMERICA-AFRICA ANOMALY 13 ISOCHRON')
isochron_feature.set_valid_time(time_of_appearance, pygplates.GeoTimeInstant.create_distant_future())
isochron_feature.set_reconstruction_plate_id(201)
isochron_feature.set_conjugate_plate_id(701)
# Set geometry and reverse reconstruct *after* other feature properties have been set.
isochron_feature.set_geometry(
    geometry_at_time_of_appearance,
    reverse_reconstruct=(rotation_model, time_of_appearance))

Changed in version 0.29: The geometry import time is set to the geometry reconstruction time when reverse reconstructing.

static create_tectonic_section(feature_type, geometry[, name][, description][, valid_time][, reconstruction_plate_id][, conjugate_plate_id][, left_plate][, right_plate][, reconstruction_method][, other_properties][, feature_id][, reverse_reconstruct][, verify_information_model=VerifyInformationModel.yes])

[staticmethod] Create a tectonic section feature.

Parameters

feature_type (FeatureType) – the type of feature to create
geometry (GeometryOnSphere, or sequence (eg, list or tuple) of GeometryOnSphere (or a coverage or a sequence of coverages - set_geometry())) – the geometry (or geometries, or a coverage or a sequence of coverages) - if geometry is not present-day geometry then the created feature will need to be reverse reconstructed to present day (using either the reverse_reconstruct parameter or reverse_reconstruct()) before the feature can be reconstructed to an arbitrary reconstruction time
name (string, or sequence of string) –
the name or names, if not specified then no pygplates.PropertyName.gml_name properties are added
description (string) –
the description, if not specified then a pygplates.PropertyName.gml_description property is not added
valid_time (a tuple of (float or GeoTimeInstant, float or GeoTimeInstant)) –
the (begin_time, end_time) tuple, if not specified then a pygplates.PropertyName.gml_valid_time property is not added
reconstruction_plate_id (int) –
the reconstruction plate id, if not specified then a pygplates.PropertyName.gpml_reconstruction_plate_id property is not added
conjugate_plate_id (int, or sequence of int) –
the conjugate plate ID or plate IDs, if not specified then no pygplates.PropertyName.gpml_conjugate_plate_id properties are added
left_plate (int) –
the left plate id, if not specified then a pygplates.PropertyName.gpml_left_plate property is not added
right_plate (int) –
the right plate id, if not specified then a pygplates.PropertyName.gpml_right_plate property is not added
reconstruction_method (string (see supported values)) – the reconstruction method, if not specified then a pygplates.PropertyName.gpml_reconstruction_method property is not added (note that a missing property essentially defaults to ‘ByPlateId’ behaviour) - note that ‘HalfStageRotationVersion3’ is the latest and most accurate half-stage method and should generally be used unless backward compatibility with old GPlates versions is required
other_properties (a sequence (eg, list or tuple) of (PropertyName, PropertyValue or sequence of PropertyValue)) – any extra property name/value pairs to add, these can alternatively be added later with add()
feature_id (FeatureId) – the feature identifier, if not specified then a unique feature identifier is created
reverse_reconstruct (tuple (RotationModel, float or GeoTimeInstant [, int])) – the tuple (rotation model, geometry reconstruction time [, anchor plate id]) where the anchor plate is optional (defaults to default anchor plate of rotation model) - if this tuple of reverse reconstruct parameters is specified then geometry is reverse reconstructed using those parameters and any specified feature properties (eg, reconstruction_plate_id) - this is only required if geometry is not present day - alternatively you can subsequently call reverse_reconstruct()
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model (default) or not

Return type

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and feature_type is not a tectonic section.

Raises

GmlTimePeriodBeginTimeLaterThanEndTimeError if valid_time has begin time later than end time

This function creates a feature of type that falls in the category of a tectonic section - note that there are multiple feature types that fall into this category.

This function calls set_geometry(). It optionally calls set_name(), set_description(), set_valid_time(), set_reconstruction_plate_id(), set_conjugate_plate_id(), set_left_plate(), set_right_plate() and add().

If geometry is not present-day geometry then the created feature will need to be reverse reconstructed to present day using (using either the reverse_reconstruct parameter or reverse_reconstruct()) before the feature can be reconstructed to an arbitrary reconstruction time - this is because a feature is not complete until its geometry is present day geometry. This is usually the case for features that are reconstructed using half-stage rotations (see reconstruction_method) since it is typically much easier to specify the geometry at the time of appearance (as opposed to present-day). The mid-ocean ridge example below demonstrates this.

Create a mid-ocean ridge feature (note that it must also be reverse reconstructed since the specified geometry is not present day geometry but instead the geometry of the mid-ocean ridge at its time of appearance):

time_of_appearance = 55.9
time_of_disappearance = 48
geometry_at_time_of_appearance = pygplates.PolylineOnSphere([...])
mid_ocean_ridge_feature = pygplates.Feature.create_tectonic_section(
    pygplates.FeatureType.gpml_mid_ocean_ridge,
    geometry_at_time_of_appearance,
    name='SOUTH ATLANTIC, SOUTH AMERICA-AFRICA',
    valid_time=(time_of_appearance, time_of_disappearance),
    left_plate=201,
    right_plate=701,
    reconstruction_method='HalfStageRotationVersion3',
    reverse_reconstruct=(rotation_model, time_of_appearance))

The previous example is the equivalent of the following (note that the reverse reconstruction is done after the properties have been set on the feature - this is necessary because reverse reconstruction looks at these properties to determine how to reverse reconstruct):

mid_ocean_ridge_feature = pygplates.Feature(pygplates.FeatureType.gpml_mid_ocean_ridge)
mid_ocean_ridge_feature.set_geometry(geometry_at_time_of_appearance)
mid_ocean_ridge_feature.set_name('SOUTH ATLANTIC, SOUTH AMERICA-AFRICA')
mid_ocean_ridge_feature.set_valid_time(time_of_appearance, time_of_disappearance)
mid_ocean_ridge_feature.set_left_plate(201)
mid_ocean_ridge_feature.set_right_plate(701)
mid_ocean_ridge_feature.set_reconstruction_method('HalfStageRotationVersion3')
pygplates.reverse_reconstruct(mid_ocean_ridge_feature, rotation_model, time_of_appearance)

# ...or...

mid_ocean_ridge_feature = pygplates.Feature(pygplates.FeatureType.gpml_mid_ocean_ridge)
mid_ocean_ridge_feature.set_name('SOUTH ATLANTIC, SOUTH AMERICA-AFRICA')
mid_ocean_ridge_feature.set_valid_time(time_of_appearance, time_of_disappearance)
mid_ocean_ridge_feature.set_left_plate(201)
mid_ocean_ridge_feature.set_right_plate(701)
mid_ocean_ridge_feature.set_reconstruction_method('HalfStageRotationVersion3')
# Set geometry and reverse reconstruct *after* other feature properties have been set.
mid_ocean_ridge_feature.set_geometry(
    geometry_at_time_of_appearance,
    reverse_reconstruct=(rotation_model, time_of_appearance))

In the examples above the geometry import time is internally set to time_of_appearance (either due to the reverse_reconstruct arguments or the reverse_reconstruct() function). This is so the ridge geometry at the time of appearance is correctly reverse-reconstructed (which is especially important for mid-ocean ridges with version 3 half-stage rotations where the spreading start time is the geometry import time).

Changed in version 0.29: The geometry import time is set to the geometry reconstruction time when reverse reconstructing.

static create_topological_feature(feature_type, topological_geometry[, name][, description][, valid_time][, other_properties][, feature_id][, verify_information_model=VerifyInformationModel.yes])

[staticmethod] Create a topological feature.

Parameters

feature_type (FeatureType) – the type of feature to create
topological_geometry (GpmlTopologicalLine or GpmlTopologicalPolygon or GpmlTopologicalNetwork, or a sequence (eg, list or tuple) of them) – the topological geometry or geometries
name (string, or sequence of string) –
the name or names, if not specified then no pygplates.PropertyName.gml_name properties are added
description (string) –
the description, if not specified then a pygplates.PropertyName.gml_description property is not added
valid_time (a tuple of (float or GeoTimeInstant, float or GeoTimeInstant)) –
the (begin_time, end_time) tuple, if not specified then a pygplates.PropertyName.gml_valid_time property is not added
other_properties (a sequence (eg, list or tuple) of (PropertyName, PropertyValue or sequence of PropertyValue)) – any extra property name/value pairs to add, these can alternatively be added later with add()
feature_id (FeatureId) – the feature identifier, if not specified then a unique feature identifier is created
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model (default) or not

Return type

create_reconstructable_feature()

Raises

GmlTimePeriodBeginTimeLaterThanEndTimeError if valid_time has begin time later than end time

Note

A topological feature really only differs from a reconstructable feature in that it has a topological geometry instead of a regular geometry (ie, internally it calls set_topological_geometry() instead of set_geometry().

This function calls set_topological_geometry(). It optionally calls set_name(), set_description(), set_valid_time() and add().

Create a subduction zone line feature:

topological_line = pygplates.GpmlTopologicalLine([...])
subduction_zone_feature = pygplates.Feature.create_topological_feature(
    pygplates.FeatureType.gpml_subduction_zone,
    topological_line,
    name='Andes Subduction Zone',
    valid_time=(10, pygplates.GeoTimeInstant.create_distant_future()))

Note

We did not set a reconstruction plate ID on the subduction zone because it is a line that is reconstructed by its constituent topological sections (and not using a plate ID).

Create a topological closed plate boundary feature:

topological_boundary = pygplates.GpmlTopologicalPolygon([...])
SAM_plate_feature = pygplates.Feature.create_topological_feature(
    pygplates.FeatureType.gpml_topological_closed_plate_boundary,
    topological_boundary,
    name='SAM',
    valid_time=(10, pygplates.GeoTimeInstant.create_distant_future()))

SAM_plate_feature.set_reconstruction_plate_id(201)

Note

Unlike the subduction zone we set a plate ID on the topological boundary because it represents a rigid plate and the plate ID can be used when assigning plate IDs to other feature geometries.

See also

New in version 0.24.

static create_total_reconstruction_sequence(fixed_plate_id, moving_plate_id, total_reconstruction_pole[, name][, description][, other_properties][, feature_id][, verify_information_model=VerifyInformationModel.yes])

[staticmethod] Create a rotation feature for a fixed/moving plate pair.

Parameters

fixed_plate_id (int) – the fixed plate id
moving_plate_id (int) – the moving plate id
total_reconstruction_pole (GpmlIrregularSampling of GpmlFiniteRotation) – the time-sequence of rotations
name (string, or sequence of string) –
the name or names, if not specified then no pygplates.PropertyName.gml_name properties are added
description (string) –
the description, if not specified then a pygplates.PropertyName.gml_description property is not added
other_properties (a sequence (eg, list or tuple) of (PropertyName, PropertyValue or sequence of PropertyValue)) – any extra property name/value pairs to add, these can alternatively be added later with add()
feature_id (FeatureId) – the feature identifier, if not specified then a unique feature identifier is created
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model (default) or not

Return type

This function creates a rotation feature containing a total reconstruction pole (a time sequence of finite rotations) for a fixed/moving plate pair. The feature type is a total reconstruction sequence.

This function calls set_total_reconstruction_pole(). It optionally calls set_name(), set_description(), and add().

Create a rotation feature:

rotation_feature = pygplates.Feature.create_total_reconstruction_sequence(
    550,
    801,
    total_reconstruction_pole_801_rel_550,
    name='INA-AUS Muller et.al 2000')

The previous example is the equivalent of the following:

rotation_feature = pygplates.Feature(pygplates.FeatureType.gpml_total_reconstruction_sequence)
rotation_feature.set_name('INA-AUS Muller et.al 2000')
rotation_feature.set_total_reconstruction_pole(550, 801, total_reconstruction_pole_801_rel_550)

get(property_query[, property_return=PropertyReturn.exactly_one])

Returns one or more properties matching a property name or predicate.

Parameters

property_query (PropertyName, or callable (accepting single Property argument)) – the property name (or predicate function) that matches the property (or properties) to get
property_return (PropertyReturn.exactly_one, PropertyReturn.first or PropertyReturn.all) – whether to return exactly one property, the first property or all matching properties

Return type

Property, or list of Property, or None

This method is similar to get_value() except it returns properties instead of property values.

The following table maps property_return values to return values:

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

property_name = pygplates.PropertyName.gml_valid_time
exactly_one_property = feature.get(property_name)
first_property = feature.get(property_name, pygplates.PropertyReturn.first)
all_properties = feature.get(property_name, pygplates.PropertyReturn.all)

# A predicate function that returns true if property is `pygplates.PropertyName.gpml_reconstruction_plate_id <http://www.gplates.org/docs/gpgim/#gpml:reconstructionPlateId>`_ with value less than 700.
def recon_plate_id_less_700(property):
  return property.get_name() == pygplates.PropertyName.gpml_reconstruction_plate_id and \
         property.get_value().get_plate_id() < 700

recon_plate_id_less_700_property = feature.get(recon_plate_id_less_700)
# assert(recon_plate_id_less_700_property.get_value().get_plate_id() < 700)

See also

get_value()

See also

set()

get_all_geometries([coverage_return=CoverageReturn.geometry_only])

Return a list of all present day geometries of this feature (regardless of their property names).

Parameters: coverage_return (CoverageReturn.geometry_only or CoverageReturn.geometry_and_scalars) – whether to return geometries only (the default), or coverages (where a coverage is a geometry and associated per-point scalar values)
Return type: list of GeometryOnSphere (or list of 2-tuple of GeometryOnSphere and dict of scalar values if CoverageReturn.geometry_and_scalars specified)

This is a convenient alternative to get_geometries() that returns a list of all geometries regardless of their property names.

This method is equivalent to:

def get_all_geometries(feature, coverage_return):
    return feature.get_geometries(
        lambda property: True,
        coverage_return)

See get_geometries() for more details.

See also

set_topological_geometry()

get_all_topological_geometries()

Return a list of all topological geometries of this feature (regardless of their property names).

Return type: list of GpmlTopologicalLine or GpmlTopologicalPolygon or GpmlTopologicalNetwork

This is a convenient alternative to get_topological_geometries() that returns a list of all topological geometries regardless of their property names.

This method is equivalent to:

def get_all_topological_geometries(feature):
    return feature.get_topological_geometries(lambda property: True)

See get_topological_geometries() for more details.

See also

New in version 0.24.

get_boolean(property_name[, default=False][, property_return=PropertyReturn.exactly_one])

Returns the boolean property value associated with property_name.

Parameters

property_name (PropertyName) – the property name of the boolean property (or properties)
default (bool or list or None) – the default boolean value (defaults to False), or default boolean values
property_return (PropertyReturn.exactly_one, PropertyReturn.first or PropertyReturn.all) – whether to return exactly one boolean, the first boolean or all matching booleans

Return type

bool, or list of bools, or type(default)

This is a convenience method that wraps get_value() for XsBoolean properties.

The following table maps property_return values to return values:

PropertyReturn Value	Description
exactly_one	Returns a `bool` if exactly one property_name property is found, otherwise default is returned.
first	Returns the `bool` of the first property_name property - however note that a feature is an unordered collection of properties. Returns default if there are no property_name properties.
all	Returns a `list` of `bool` of property_name properties. Returns default if there are no property_name properties.

Return the active state (defaulting to False if not exactly one found):

is_active = feature.get_boolean(
    pygplates.PropertyName.create_gpml('isActive'))

See also

set_boolean()

get_conjugate_plate_id([default=0][, property_return=PropertyReturn.exactly_one])

Return the conjugate plate ID (or IDs) of this feature.

Parameters

default (int or list or None) – the default plate ID (defaults to zero), or default plate IDs
property_return (PropertyReturn.exactly_one, PropertyReturn.first or PropertyReturn.all) – whether to return exactly one ID, the first ID or all IDs

Return type

int, or list of int, or type(default)

This is a convenience method that wraps get_value() for the common property pygplates.PropertyName.gpml_conjugate_plate_id.

There can be more than one conjugate plate ID for a feature but typically there will be only one.

The following table maps property_return values to return values:

PropertyReturn Value	Description
exactly_one	Returns the integer plate ID if exactly one ‘gpml:conjugatePlateId’ property is found, otherwise default is returned.
first	Returns the integer plate ID of the first ‘gpml:conjugatePlateId’ property - however note that a feature is an unordered collection of properties. Returns default if there are no ‘gpml:conjugatePlateId’ properties.
all	Returns a `list` of integer plate IDs of ‘gpml:conjugatePlateId’ properties. Returns default if there are no ‘gpml:conjugatePlateId’ properties. Note that any ‘gpml:conjugatePlateId’ property with a zero plate ID will be added to the list.

Return the conjugate plate ID as an integer (defaults to zero if not exactly one found):

conjugate_plate_id = feature.get_conjugate_plate_id()

Test that there is exactly one ‘gpml:conjugatePlateId’ property:

conjugate_plate_id = feature.get_conjugate_plate_id(None)
# Compare with None since a plate id of zero evaluates to False.
if conjugate_plate_id is not None:
  ...

Test that there is exactly one ‘gpml:conjugatePlateId’ property and that it is not zero:

conjugate_plate_id = feature.get_conjugate_plate_id()
if conjugate_plate_id:
  ...

Return the list of conjugate plate IDs as integers (defaults to an empty list if no conjugate plate IDs are found):

conjugate_plate_ids = feature.get_conjugate_plate_id([], pygplates.PropertyReturn.all)

Test if there are any ‘gpml:conjugatePlateId’ properties:

conjugate_plate_ids = feature.get_conjugate_plate_id(None, pygplates.PropertyReturn.all)
if conjugate_plate_ids:
  ...

Test if there are any ‘gpml:conjugatePlateId’ properties with a non-zero plate ID:

conjugate_plate_ids = feature.get_conjugate_plate_id(None, pygplates.PropertyReturn.all)
if conjugate_plate_ids and any(conjugate_plate_ids):
  ...

See also

set_conjugate_plate_id()

get_description([default=''])

Return the description of this feature.

Parameters

default (string or None) – the default description (defaults to an empty string)

Returns

the description (if exactly one pygplates.PropertyName.gml_description property found), otherwise default is returned

Return type

string, or type(default)

This is a convenience method that wraps get_value() for the common property pygplates.PropertyName.gml_description.

Return the description as a string (defaults to an empty string if not exactly one found):

description = feature.get_description()

Set default to None to test that there is exactly one ‘gml:description’ property:

description = feature.get_description(None)
# Compare with None since an empty string evaluates to False.
if description is not None:
  ...

Test that there is exactly one ‘gml:description’ property and that it is not the empty string:

description = feature.get_description()
if description:
  ...

See also

set_description()

get_double(property_name[, default=0.0][, property_return=PropertyReturn.exactly_one])

Returns the floating-point (double) property value associated with property_name.

Parameters

property_name (PropertyName) – the property name of the float property (or properties)
default (float or list or None) – the default float value (defaults to 0.0), or default float values
property_return (PropertyReturn.exactly_one, PropertyReturn.first or PropertyReturn.all) – whether to return exactly one float, the first float or all matching floats

Return type

float, or list of floats, or type(default)

This is a convenience method that wraps get_value() for XsDouble properties.

The following table maps property_return values to return values:

PropertyReturn Value	Description
exactly_one	Returns a `float` if exactly one property_name property is found, otherwise default is returned.
first	Returns the `float` of the first property_name property - however note that a feature is an unordered collection of properties. Returns default if there are no property_name properties.
all	Returns a `list` of `float` of property_name properties. Returns default if there are no property_name properties.

Return the subduction zone depth (defaulting to 0.0 if not exactly one found):

subduction_zone_depth = feature.get_double(
    pygplates.PropertyName.create_gpml('subductionZoneDepth'))

See also

set_double()

get_enumeration(property_name[, default])

Returns the enumeration content associated with property_name.

Parameters

property_name (PropertyName) – the property name of the enumeration property
default (string or None) – the default enumeration content value (defaults to None)

Returns

the enumeration content value if exactly one enumeration property named property_name is found with the expected enumeration type associated with property_name, otherwise default is returned

Return type

string, or type(default)

This is a convenience method that wraps get_value() for Enumeration properties.

Return the subduction polarity (defaulting to ‘Unknown’):

subduction_polarity = subduction_zone_feature.get_enumeration(
    pygplates.PropertyName.gpml_subduction_polarity,
    'Unknown')

See also

set_enumeration()

get_feature_id()

Returns the feature identifier.

Return type: FeatureId

get_feature_type()

Returns the feature type.

Return type: FeatureType

get_geometries([property_query][, coverage_return=CoverageReturn.geometry_only])

Return a list of the present day geometries of this feature.

Parameters

property_query (PropertyName, or callable (accepting single Property argument)) – the optional property name or predicate function used to find the geometry properties, if not specified then the default geometry property name associated with this feature’s type is used instead
coverage_return (CoverageReturn.geometry_only or CoverageReturn.geometry_and_scalars) – whether to return geometries only (the default), or coverages (where a coverage is a geometry and associated per-point scalar values)

Return type

list of GeometryOnSphere (or list of 2-tuple of GeometryOnSphere and dict of scalar values if CoverageReturn.geometry_and_scalars specified)

This is a convenient alternative to get_geometry() that returns a list of matching geometries without having to specify pygplates.PropertyReturn.all.

This method is essentially equivalent to:

def get_geometries(feature, property_query, coverage_return):
    return feature.get_geometry(property_query, pygplates.PropertyReturn.all, coverage_return)

See get_geometry() for more details.

See also

get_all_geometries()

See also

get_geometry([property_query][, property_return=PropertyReturn.exactly_one][, coverage_return=CoverageReturn.geometry_only])

Return the present day geometry (or geometries) of this feature.

Parameters

property_query (PropertyName, or callable (accepting single Property argument)) – the optional property name or predicate function used to find the geometry property or properties, if not specified then the default geometry property name associated with this feature’s type is used instead
property_return (PropertyReturn.exactly_one, PropertyReturn.first or PropertyReturn.all) – whether to return exactly one geometry, the first geometry or all geometries
coverage_return (CoverageReturn.geometry_only or CoverageReturn.geometry_and_scalars) – whether to return geometry(s) only (the default), or coverage(s) (where a coverage is a geometry and associated per-point scalar values)

Return type

GeometryOnSphere or list of GeometryOnSphere (or 2-tuple of GeometryOnSphere and dict of scalar values, or list of those, if CoverageReturn.geometry_and_scalars specified) or None

This is a convenience method to make geometry retrieval easier.

Usually a feature type supports geometry properties with more than one property name. For example, a coastline feature supports both a pygplates.PropertyName.gpml_center_line_of geometry and a pygplates.PropertyName.gpml_unclassified_geometry) geometry. But only one of them is the default (the default property that geometry data is imported into). You can see which is the default by reading the Default Geometry Property label in the coastline feature model.

If property_query is not specified then the default property name is determined from this feature’s type and the geometry is retrieved from one or more properties of that PropertyName.

The question of how many distinct geometries are allowed per feature is a little more tricky. Some geometry properties, such as pygplates.PropertyName.gpml_center_line_of, support multiple properties per feature and support any geometry type. Other geometry properties, such as pygplates.PropertyName.gpml_boundary, tend to support only one property per feature and only some geometry types (eg, only PolylineOnSphere and PolygonOnSphere). However the geometry type is usually apparent given the feature type. For example a pygplates.FeatureType.gpml_isochron feature typically contains a polyline whereas a pygplates.FeatureType.gpml_hot_spot feature contains a point.

The following table maps property_return values to return values:

PropertyReturn Value	Description
exactly_one	Returns the geometry if exactly one matching geometry property is found, otherwise `None` is returned.
first	Returns the geometry of the first matching geometry property - however note that a feature is an unordered collection of properties. Returns `none` if there are no matching geometry properties.
all	Returns a `list` of geometries of matching geometry properties. Returns an empty list if there are no matching geometry properties.

Return the default geometry (returns None if not exactly one default geometry property found):

default_geometry = feature.get_geometry()
if default_geometry:
    ...

Return the list of default geometries (defaults to an empty list if no default geometry properties are found):

default_geometries = feature.get_geometry(property_return=pygplates.PropertyReturn.all)

# ...or more conveniently...

default_geometries = feature.get_geometries()

Return the geometry associated with the property named ‘gpml:averageSampleSitePosition’:

average_sample_site_position = feature.get_geometry(
    pygplates.PropertyName.gpml_average_sample_site_position)

Return the list of all geometries (regardless of which properties they came from):

all_geometries = feature.get_geometry(
    lambda property: True,
    pygplates.PropertyReturn.all)

# ...or more conveniently...

all_geometries = feature.get_all_geometries()

Return the geometry (regardless of which property it came from) - returns None if not exactly one geometry property found:

geometry = feature.get_geometry(lambda property: True)
if geometry:
    ...

Note

If CoverageReturn.geometry_and_scalars is specified for coverage_return then a coverage (or sequence of coverages) is returned - where a coverage essentially maps each point in a geometry to one or more scalar values. A coverage is returned as a (GeometryOnSphere, scalar-values-dictionary) tuple where scalar-values-dictionary is a dict that maps scalar types to lists of scalar values. This is the same as the sole argument to GmlDataBlock.__init__(). The number of scalar values, associated with each ScalarType should be equal to the number of points in the geometry.

Get the velocity coverage on the default geometry:

default_coverage = feature.get_geometry(coverage_return=pygplates.CoverageReturn.geometry_and_scalars)
if default_coverage:
    coverage_geometry, coverage_scalars = default_coverage
    coverage_points = coverage_geometry.get_points()
    velocity_colat_scalars = coverage_scalars.get(
        pygplates.ScalarType.create_gpml('VelocityColat'))
    velocity_lon_scalars = coverage_scalars.get(
        pygplates.ScalarType.create_gpml('VelocityLon'))

See also

set_geometry_import_time()

get_geometry_import_time([default=0.0])

Returns the geometry import time of this feature.

Parameters: default (float or None) – the default geometry import time (defaults to present day)
Returns: geometry import time (if exactly one pygplates.PropertyName.gpml_geometry_import_time property found), otherwise default is returned
Return type: float, or type(default)

This is a convenience method that wraps get_value() for the common property pygplates.PropertyName.gpml_geometry_import_time.

Return the geometry import time as a float (defaults to present day if not exactly one found):

geometry_import_time = feature.get_geometry_import_time()

Set default to None to test that there is exactly one ‘gpml:geometryImportTime’ property:

geometry_import_time = feature.get_geometry_import_time(None)
# Compare with None since a geometry import time of zero evaluates to False.
if geometry_import_time:
  ...

See also

get_integer(property_name[, default=0][, property_return=PropertyReturn.exactly_one])

Returns the integer property value associated with property_name.

Parameters

property_name (PropertyName) – the property name of the integer property (or properties)
default (integer or list or None) – the default integer value (defaults to zero), or default integer values
property_return (PropertyReturn.exactly_one, PropertyReturn.first or PropertyReturn.all) – whether to return exactly one integer, the first integer or all matching integers

Return type

integer, or list of integers, or type(default)

This is a convenience method that wraps get_value() for XsInteger properties.

The following table maps property_return values to return values:

PropertyReturn Value	Description
exactly_one	Returns a `int` if exactly one property_name property is found, otherwise default is returned.
first	Returns the `int` of the first property_name property - however note that a feature is an unordered collection of properties. Returns default if there are no property_name properties.
all	Returns a `list` of `int` of property_name properties. Returns default if there are no property_name properties.

Return the subduction zone system order (defaulting to zero if not exactly one found):

subduction_zone_system_order = feature.get_integer(
    pygplates.PropertyName.create_gpml('subductionZoneSystemOrder'))

See also

set_integer()

get_left_plate([default=0])

Returns the left plate ID of this feature.

Parameters

default (int or None) – the default left plate id (defaults zero)

Returns

the left plate id (if exactly one pygplates.PropertyName.gpml_left_plate property found), otherwise default is returned

Return type

int, or type(default)

This is a convenience method that wraps get_value() for the common property pygplates.PropertyName.gpml_left_plate.

Return the left plate ID as an integer (defaults to zero if not exactly one found):

left_plate = feature.get_left_plate()

Set default to None to test that there is exactly one ‘gpml:leftPlate’ property:

left_plate = feature.get_left_plate(None)
# Compare with None since a plate id of zero evaluates to False.
if left_plate is not None:
  ...

See also

set_left_plate()

get_name([default=''][, property_return=PropertyReturn.exactly_one])

Return the name (or names) of this feature.

Parameters

default (string or list or None) – the default name (defaults to an empty string), or default names
property_return (PropertyReturn.exactly_one, PropertyReturn.first or PropertyReturn.all) – whether to return exactly one name, the first name or all names

Return type

string, or list of strings, or type(default)

This is a convenience method that wraps get_value() for the common property pygplates.PropertyName.gml_name.

There can be more than one name for a feature but typically there will be only one.

The following table maps property_return values to return values:

PropertyReturn Value	Description
exactly_one	Returns the name `str` if exactly one ‘gml:name’ property is found, otherwise default is returned.
first	Returns the name `str` of the first ‘gml:name’ property - however note that a feature is an unordered collection of properties. Returns default if there are no ‘gml:name’ properties.
all	Returns a `list` of names (`str`) of ‘gml:name’ properties. Returns default if there are no ‘gml:name’ properties. Note that any ‘gml:name’ property with an empty name string will be added to the list.

Return the name as a string (defaults to an empty string if not exactly one found):

name = feature.get_name()

Test that there is exactly one ‘gml:name’ property:

name = feature.get_name(None)
# Compare with None since an empty string evaluates to False.
if name is not None:
  ...

Test that there is exactly one ‘gml:name’ property and that it is not the empty string:

name = feature.get_name()
if name:
  ...

Return the list of names as strings (defaults to an empty list if no names are found):

names = feature.get_name([], pygplates.PropertyReturn.all)

Test if there are any ‘gml:name’ properties:

names = feature.get_name(None, pygplates.PropertyReturn.all)
if names:
  ...

Test if there are any ‘gml:name’ properties with a non-empty string:

names = feature.get_name(None, pygplates.PropertyReturn.all)
if names and any(names):
  ...

See also

set_name()

get_reconstruction_method([default='ByPlateId'])

Returns the reconstruction method of this feature.

Parameters

default (string or None) – the default reconstruction method (defaults to ‘ByPlateId’)

Returns

the reconstruction method (see supported values) if exactly one pygplates.PropertyName.gpml_reconstruction_method property found containing an enumeration type of ‘gpml:ReconstructionMethodEnumeration’, otherwise default is returned

Return type

string, or type(default)

This is a convenience method that wraps get_value() for the common property pygplates.PropertyName.gpml_reconstruction_method.

Return the reconstruction method as a string (defaults to ‘ByPlateId’ if not exactly one found):

reconstruction_method = feature.get_reconstruction_method()

Set default to None to test that there is exactly one pygplates.PropertyName.gpml_reconstruction_method property:

reconstruction_method = feature.get_reconstruction_method(None)
if reconstruction_method:
  ...

See also

set_reconstruction_method()

get_reconstruction_plate_id([default=0])

Returns the reconstruction plate ID of this feature.

Parameters

default (int or None) – the default reconstruction plate id (defaults zero)

Returns

the reconstruction plate id (if exactly one pygplates.PropertyName.gpml_reconstruction_plate_id property found), otherwise default is returned

Return type

int, or type(default)

This is a convenience method that wraps get_value() for the common property pygplates.PropertyName.gpml_reconstruction_plate_id.

Return the reconstruction plate ID as an integer (defaults to zero if not exactly one found):

reconstruction_plate_id = feature.get_reconstruction_plate_id()

Set default to None to test that there is exactly one ‘gpml:reconstructionPlateId’ property:

reconstruction_plate_id = feature.get_reconstruction_plate_id(None)
# Compare with None since a plate id of zero evaluates to False.
if reconstruction_plate_id is not None:
  ...

See also

set_reconstruction_plate_id()

get_relative_plate([default=0])

Returns the relative plate ID of this feature.

Parameters

default (int or None) – the default relative plate id (defaults zero)

Returns

the relative plate id (if exactly one pygplates.PropertyName.gpml_relative_plate property found), otherwise default is returned

Return type

int, or type(default)

This is a convenience method that wraps get_value() for the common property pygplates.PropertyName.gpml_relative_plate.

Return the relative plate ID as an integer (defaults to zero if not exactly one found):

relative_plate_id = feature.get_relative_plate()

Set default to None to test that there is exactly one ‘gpml:relativePlate’ property:

relative_plate_id = feature.get_relative_plate(None)
# Compare with None since a plate id of zero evaluates to False.
if relative_plate_id is not None:
  ...

See also

set_relative_plate()

get_right_plate([default=0])

Returns the right plate ID of this feature.

Parameters

default (int or None) – the default right plate id (defaults zero)

Returns

the right plate id (if exactly one pygplates.PropertyName.gpml_right_plate property found), otherwise default is returned

Return type

int, or type(default)

This is a convenience method that wraps get_value() for the common property pygplates.PropertyName.gpml_right_plate.

Return the right plate ID as an integer (defaults to zero if not exactly one found):

right_plate = feature.get_right_plate()

Set default to None to test that there is exactly one ‘gpml:rightPlate’ property:

right_plate = feature.get_right_plate(None)
# Compare with None since a plate id of zero evaluates to False.
if right_plate is not None:
  ...

See also

set_right_plate()

get_shapefile_attribute(key[, default_value])

Returns the value of a shapefile attribute associated with a key.

Parameters

key (string) – the key of the shapefile attribute
default_value (int or float or string or None) – the default value to return if key does not exist (if not specified then it defaults to None)

Returns

the value of the shapefile attribute associated with key, otherwise default_value if key does not exist

Return type

integer or float or string or type(default_value) or None

Shapefile attributes are stored in a GpmlKeyValueDictionary property named pygplates.PropertyName.gpml_shapefile_attributes and contain attributes imported from a Shapefile.

This is a convenience method that wraps get_value() for the common property pygplates.PropertyName.gpml_shapefile_attributes and accesses the attribute value associated with key within that property using GpmlKeyValueDictionary.get().

Note

default_value is returned if either a ‘gpml:shapefileAttributes’ property does not exist in this feature, or one does exist but does not contain a shapefile attribute associated with key.

To test if a key is present and retrieve its value:

value = feature.get_shapefile_attribute('key')
# Compare with None since an integer (or float) value of zero, or an empty string, evaluates to False.
if value is not None:
  ...

Return the integer value of the attribute associated with ‘key’ (default to zero if not present):

integer_value = feature.get_shapefile_attribute('key', 0))

See also

get_shapefile_attributes()

See also

set_shapefile_attribute()

get_shapefile_attributes([default])

Returns all shapefile attributes as a dict of key/value pairs.

Parameters: default (dict or None) – the default to return if there are no shapefile attributes (if not specified then it default defaults to None)
Returns: all shapefile attributes, otherwise default if no shapefile attributes exist
Return type: dict or type(default) or None

Shapefile attributes are stored in a GpmlKeyValueDictionary property named pygplates.PropertyName.gpml_shapefile_attributes and contain attributes imported from a Shapefile.

This is a convenience method that wraps get_value() for the common property pygplates.PropertyName.gpml_shapefile_attributes.

Note

default is returned if a ‘gpml:shapefileAttributes’ property does not exist in this feature.

To get the shapefile attributes dict, or None if a ‘gpml:shapefileAttributes’ property is not present:

shapefile_attributes = feature.get_shapefile_attributes()
if shapefile_attributes:
  attribute_value = shapefile_attributes.get(attribute_key, default_value)

To get the shapefile attributes dict, or an empty dict if a ‘gpml:shapefileAttributes’ property is not present:

shapefile_attributes = feature.get_shapefile_attributes(dict())
attribute_value = shapefile_attributes.get(attribute_key, default_value)

See also

get_shapefile_attribute()

See also

set_shapefile_attributes()

get_string(property_name[, default=''][, property_return=PropertyReturn.exactly_one])

Returns the string property value associated with property_name.

Parameters

property_name (PropertyName) – the property name of the string property (or properties)
default (string or list or None) – the default string value (defaults to an empty string), or default string values
property_return (PropertyReturn.exactly_one, PropertyReturn.first or PropertyReturn.all) – whether to return exactly one string, the first string or all matching strings

Return type

string, or list of strings, or type(default)

This is a convenience method that wraps get_value() for XsString properties.

The following table maps property_return values to return values:

PropertyReturn Value	Description
exactly_one	Returns a `str` if exactly one property_name property is found, otherwise default is returned.
first	Returns the `str` of the first property_name property - however note that a feature is an unordered collection of properties. Returns default if there are no property_name properties.
all	Returns a `list` of `str` of property_name properties. Returns default if there are no property_name properties. Note that any property_name property with an empty name string will be added to the list.

Return the ship track name (defaulting to empty string if not exactly one found):

ship_track_name = feature.get_string(
    pygplates.PropertyName.create_gpml('shipTrackName'))

See also

set_string()

get_times()

Returns the list of times of this flowline or motion path feature.

Returns: the list of times (if exactly one pygplates.PropertyName.gpml_times property found), otherwise None is returned
Return type: list of float, or None

This is a convenience method that wraps get_value() for the common property pygplates.PropertyName.gpml_times used in flowlines and motion paths.

The list is from most recent (closest to present day) to least recent (furthest in the geological past).

Return the list of times (returns None if not exactly one ‘gpml:times’ property found):

times = feature.get_times()
if times:
  for time in times:
    ...

Note

The ‘gpml:times’ property actually contains a list of time periods (not time instants). So this method converts the time periods to a list of time instants (by assuming the time periods do not overlap each other and do not have gaps between them).

See also

set_times()

get_topological_geometries([property_query])

Return a list of topological geometries of this feature.

Parameters: property_query (PropertyName, or callable (accepting single Property argument)) – the optional property name or predicate function used to find the topological geometry properties, if not specified then the default geometry property name associated with this feature’s type is used instead
Return type: list of GpmlTopologicalLine or GpmlTopologicalPolygon or GpmlTopologicalNetwork

This is a convenient alternative to get_topological_geometry() that returns a list of matching topological geometries without having to specify pygplates.PropertyReturn.all.

This method is essentially equivalent to:

def get_topological_geometries(feature, property_query):
    return feature.get_topological_geometry(property_query, pygplates.PropertyReturn.all)

See get_topological_geometry() for more details.

See also

get_all_topological_geometries()

See also

set_topological_geometry()

New in version 0.24.

get_topological_geometry([property_query][, property_return=PropertyReturn.exactly_one])

Return the topological geometry (or geometries) of this feature.

Parameters

property_query (PropertyName, or callable (accepting single Property argument)) – the optional property name or predicate function used to find the topological geometry property or properties, if not specified then the default geometry property name associated with this feature’s type is used instead
property_return (PropertyReturn.exactly_one, PropertyReturn.first or PropertyReturn.all) – whether to return exactly one topological geometry, the first geometry or all topological geometries

Return type

GpmlTopologicalLine or GpmlTopologicalPolygon or GpmlTopologicalNetwork, or list of them, or None

This is a convenience method to make topological geometry retrieval easier.

Usually a feature type supports geometry properties with more than one property name - see get_geometry(). Those geometry properties can also be topological geometry properties - the same principle applies here - see get_geometry() for more details.

If property_query is not specified then the default property name is determined from this feature’s type and the topological geometry is retrieved from one or more properties of that PropertyName. See get_geometry() for details on how many distinct geometries (topological or non-topological) are allowed per feature.

The following table maps property_return values to return values:

PropertyReturn Value	Description
exactly_one	Returns the topological geometry if exactly one matching topological geometry property is found, otherwise `None` is returned.
first	Returns the topological geometry of the first matching topological geometry property - however note that a feature is an unordered collection of properties. Returns `none` if there are no matching topological geometry properties.
all	Returns a `list` of topological geometries of matching topological geometry properties. Returns an empty list if there are no matching topological geometry properties.

Return the default topological geometry, in this case a GpmlTopologicalPolygon from a ‘gpml:TopologicalClosedPlateBoundary’ feature. Returns None if not exactly one default topological geometry property found:

topological_polygon = topological_closed_plate_boundary_feature.get_topological_geometry()
if topological_polygon:
    topological_boundary_sections = topological_polygon.get_boundary_sections()
    ...

Return the GpmlTopologicalNetwork from a ‘gpml:TopologicalNetwork’ feature:

topological_network = topological_network_feature.get_topological_geometry()
if topological_network:
    topological_boundary_sections = topological_network.get_boundary_sections()
    topological_interiors = topological_network.get_interiors()
    ...

See also

set_topological_geometry()

New in version 0.24.

get_total_reconstruction_pole()

Returns the time-dependent total reconstruction pole of this feature.

Return type: tuple(int, int, GpmlIrregularSampling) or None
Returns: A tuple containing (fixed plate id, moving plate id, time sequence of finite rotations) or None

This is a convenience method that wraps get_value() for the common properties pygplates.PropertyName.gpml_fixed_reference_frame, pygplates.PropertyName.gpml_moving_reference_frame and pygplates.PropertyName.gpml_total_reconstruction_pole.

Returns None if the feature does not contain a pygplates.PropertyName.gpml_fixed_reference_frame plate id, a pygplates.PropertyName.gpml_moving_reference_frame plate id and a pygplates.PropertyName.gpml_total_reconstruction_pole GpmlIrregularSampling (with time samples containing GpmlFiniteRotation instances).

A feature with type pygplates.FeatureType.gpml_total_reconstruction_sequence should have these properties if it conforms to the GPlates Geological Information Model (GPGIM). These feature types are usually read from a GPML rotation file or a PLATES4 rotation (‘.rot’) file.

Calculate the interpolated finite rotation that represents the rotation of a moving plate relative to a fixed plate from present day to a specific reconstruction time:

fixed_plate_id, moving_plate_id, total_reconstruction_pole = rotation_feature.get_total_reconstruction_pole()
interpolated_finite_rotation_property_value = total_reconstruction_pole.get_value(reconstruction_time)
if interpolated_finite_rotation_property_value:
    interpolated_finite_rotation = interpolated_finite_rotation_property_value.get_finite_rotation()

…although it is much easier to use RotationModel.

See also

set_total_reconstruction_pole()

get_valid_time([default=(float('inf'), float('-inf'))])

Returns the valid time range of this feature.

Parameters

default (tuple (float,float) or None) – the default time range (defaults to all time)

Returns

begin and end times (if exactly one pygplates.PropertyName.gml_valid_time property found), otherwise default is returned

Return type

tuple (float,float), or type(default)

This is a convenience method that wraps get_value() for the common property pygplates.PropertyName.gml_valid_time.

Return the valid time range as a tuple of begin and end times (defaults to all time if not exactly one found):

begin_time, end_time = feature.get_valid_time()

# Valid time for an empty feature defaults to all time.
empty_feature = pygplates.Feature()
begin_time, end_time = empty_feature.get_valid_time()
# assert(begin_time == pygplates.GeoTimeInstant.create_distant_past())
# assert(end_time == pygplates.GeoTimeInstant.create_distant_future())

Set default to None to test that there is exactly one ‘gml:validTime’ property:

valid_time = feature.get_valid_time(None)
if valid_time:
  begin_time, end_time = valid_time

get_value(property_query[, time=0][, property_return=PropertyReturn.exactly_one])

Returns one or more values of properties matching a property name or predicate.

Parameters

property_query (PropertyName, or callable (accepting single Property argument)) – the property name (or predicate function) that matches the property (or properties) to get
time (float or GeoTimeInstant) – the time to extract value (defaults to present day)
property_return (PropertyReturn.exactly_one, PropertyReturn.first or PropertyReturn.all) – whether to return exactly one property, the first property or all matching properties

Return type

PropertyValue, or list of PropertyValue, or None

This method is essentially the same as get() except it also calls Property.get_value() on each property.

The following table maps property_return values to return values:

PropertyReturn Value	Description
exactly_one	Returns a `value` only if property_query matches exactly one property, otherwise `None` is returned. Note that `None` can still be returned, even if exactly one property matches, due to `Property.get_value()` returning `None`.
first	Returns the `value` of the first property matching property_query - however note that a feature is an unordered collection of properties. If no properties match then `None` is returned. Note that `None` can still be returned for the first matching property due to `Property.get_value()` returning `None`.
all	Returns a `list` of `values` of properties matching property_query. If no properties match then the returned list will be empty. Any matching properties where `Property.get_value()` returns `None` will not be added to the list.

property_name = pygplates.PropertyName.gml_valid_time
exactly_one_property_value = feature.get_value(property_name)
first_property_value = feature.get_value(property_name, property_return=pygplates.PropertyReturn.first)
all_property_values = feature.get_value(property_name, property_return=pygplates.PropertyReturn.all)

# Using a predicate function that returns true if property is `pygplates.PropertyName.gpml_reconstruction_plate_id <http://www.gplates.org/docs/gpgim/#gpml:reconstructionPlateId>`_ with value less than 700.
recon_plate_id_less_700_property_value = feature.get_value(
    lambda property: property.get_name() == pygplates.PropertyName.gpml_reconstruction_plate_id and
                     property.get_value().get_plate_id() < 700)
# assert(recon_plate_id_less_700_property_value.get_plate_id() < 700)

See also

get()

is_valid_at_time(time)

Determine if this feature is valid at the specified time.

Parameters: time (float or GeoTimeInstant) – the time
Return type: bool

A feature is valid at time if time lies within the time period returned by get_valid_time() (includes coinciding with begin or end time of time period). Otherwise the feature does not exist at the geological time.

Note

A feature that does not have a valid time (property) will be valid for all time (since get_valid_time() defaults to all time).

To test if a feature exists at present day (0Ma):

if feature.is_valid_at_time(0):
    ...

remove(property_query)

Removes properties from this feature.

Parameters: property_query (PropertyName, or Property, or callable (accepting single Property argument), or a sequence (eg, list or tuple) of any combination of them) – one or more property names, property instances or predicate functions that determine which properties to remove
Raises: ValueError if any specified Property is not currently a property in this feature

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

feature.remove(pygplates.PropertyName.gpml_left_plate)
feature.remove([
    pygplates.PropertyName.gpml_left_plate,
    pygplates.PropertyName.gpml_right_plate])

for property in feature:
    if predicate(property):
        feature.remove(property)
feature.remove(predicate)
feature.remove([property for property in feature if predicate(property)])
# Specifying just an iterator also works...
feature.remove(property for property in feature if predicate(property))

# Mix different query types.
# Remove a specific 'property' instance and any 'gpml:leftPlate' properties...
feature.remove([property, pygplates.PropertyName.gpml_left_plate])

# Remove 'gpml:leftPlate' properties with plate IDs less than 700...
feature.remove(
    lambda property: property.get_name() == pygplates.PropertyName.gpml_left_plate and
                     property.get_value().get_plate_id() < 700)

# Remove 'gpml:leftPlate' and 'gpml:rightPlate' properties...
feature.remove([
    lambda property: property.get_name() == pygplates.PropertyName.gpml_left_plate,
    pygplates.PropertyName.gpml_right_plate])
feature.remove(
    lambda property: property.get_name() == pygplates.PropertyName.gpml_left_plate or
                     property.get_name() == pygplates.PropertyName.gpml_right_plate)

See also

add()

set(property_name, property_value[, verify_information_model=VerifyInformationModel.yes])

Sets a property (or properties) to this feature.

Parameters

property_name (PropertyName) – the name of the property (or properties) to set
property_value (PropertyValue, or sequence (eg, list or tuple) of PropertyValue) – the value (or values) of the property (or properties) to set
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property (or properties) set in the feature

Return type

Property, or list of Property depending on whether property_value is a PropertyValue or sequence of PropertyValue

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and property_name is not a recognised property name or is not supported by the feature type, or if property_name does not support the number of property values in property_value, or if property_value does not have a property value type supported by property_name

property = feature.set(property_name, property_value)
properties = feature.set(property_name, [property_value1, property_value2])
# assert(len(properties) == 2)

This method essentially has the same effect as calling remove() followed by add():

def set(feature, property_name, property_value, verify_information_model):
    feature.remove(property_name)
    return feature.add(property_name, property_value, verify_information_model)

Note that even a feature of type gpml:UnclassifiedFeature will raise InformationModelError if verify_information_model is VerifyInformationModel.yes and property_name is not recognised by the GPlates Geological Information Model (GPGIM).

See also

get()

set_boolean(property_name, boolean[, verify_information_model=VerifyInformationModel.yes])

Sets the boolean property value associated with property_name.

Parameters

property_name (PropertyName) – the property name of the boolean property
boolean (bool, or sequence of bools) – the boolean or booleans
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property containing the boolean, or properties containing the booleans

Return type

Property, or list of Property

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and property_name is not a recognised property name or is not supported by the feature type, or if property_name does not support a boolean property value type.

This is a convenience method that wraps set() for XsBoolean properties.

Set the active state on a feature:

feature.set_boolean(
    pygplates.PropertyName.create_gpml('isActive'),
    True)

See also

get_boolean()

set_conjugate_plate_id(conjugate_plate_id[, verify_information_model=VerifyInformationModel.yes])

Set the conjugate plate ID (or IDs) of this feature.

Parameters

conjugate_plate_id (int, or sequence of int) – the conjugate plate ID or plate IDs
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property containing the conjugate plate ID, or properties containing the conjugate plate IDs

Return type

Property, or list of Property

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and the feature type does not support the pygplates.PropertyName.gpml_conjugate_plate_id property.

This is a convenience method that wraps set() for the common property pygplates.PropertyName.gpml_conjugate_plate_id.

There can be more than one conjugate plate ID for a feature but typically there will be only one.

Set the conjugate plate ID to an integer:

feature.set_conjugate_plate_id(201)

Set the conjugate plate IDs to integers:

feature.set_conjugate_plate_id([903, 904])

See also

get_conjugate_plate_id()

set_description(description[, verify_information_model=VerifyInformationModel.yes])

Sets the description of this feature.

Parameters

description (string) – the description
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property containing the description

Return type

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and the feature type does not support the pygplates.PropertyName.gml_description property.

This is a convenience method that wraps set() for the common property pygplates.PropertyName.gml_description.

Set the description to a string:

feature.set_description('description')

See also

get_description()

set_double(property_name, double[, verify_information_model=VerifyInformationModel.yes])

Sets the floating-point (double) property value associated with property_name.

Parameters

property_name (PropertyName) – the property name of the float property
double (float, or sequence of floats) – the float or floats
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property containing the float, or properties containing the floats

Return type

Property, or list of Property

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and property_name is not a recognised property name or is not supported by the feature type, or if property_name does not support a double property value type.

This is a convenience method that wraps set() for XsDouble properties.

Set the subduction zone depth on a feature:

feature.set_double(
    pygplates.PropertyName.create_gpml('subductionZoneDepth'),
    85.5)

See also

get_double()

set_enumeration(property_name, enumeration_content[, verify_information_model=VerifyInformationModel.yes])

Sets the enumeration content associated with property_name.

Parameters

property_name (PropertyName) – the property name of the enumeration property
enumeration_content (string) – the enumeration content (value of enumeration)
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property containing the enumeration

Return type

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and the feature type does not support an enumeration property named property_name, or enumeration_content is not a recognised enumeration content value for the enumeration type associated with property_name.

This is a convenience method that wraps set() for Enumeration properties.

Set the subduction polarity on a subduction zone feature to Left:

subduction_zone_feature.set_enumeration(
    pygplates.PropertyName.gpml_subduction_polarity,
    'Left')

See also

get_enumeration()

set_geometry(geometry[, property_name][, reverse_reconstruct][, verify_information_model=VerifyInformationModel.yes])

Set the geometry (or geometries) of this feature.

Parameters

geometry (GeometryOnSphere, or sequence (eg, list or tuple) of GeometryOnSphere (or a coverage or a sequence of coverages - see below)) – the geometry or geometries (or coverage or coverages - see below) to set - if the geometry(s) is not present-day geometry then this feature will need to be reverse reconstructed to present day using (using either the reverse_reconstruct parameter or reverse_reconstruct()) before this feature can be reconstructed to an arbitrary reconstruction time
property_name (PropertyName) – the optional property name of the geometry property or properties to set, if not specified then the default geometry property name associated with this feature’s type is used instead
reverse_reconstruct (tuple (RotationModel, float or GeoTimeInstant [, int])) – the tuple (rotation model, geometry reconstruction time [, anchor plate id]) where the anchor plate is optional (defaults to default anchor plate of rotation model) - if this tuple of reverse reconstruct parameters is specified then geometry is reverse reconstructed using those parameters and this feature’s existing properties (eg, reconstruction plate id) - this is only required if geometry is not present day - alternatively you can subsequently call reverse_reconstruct()
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the geometry property or properties set in the feature (or 2-tuple of geometry property and scalars property, or list of those, if a coverage or coverages was specified for geometry)

Return type

Property or list of Property depending on whether geometry is a GeometryOnSphere or sequence of GeometryOnSphere (or 2-tuple of Property or list of 2-tuple of Property if geometry is a coverage or list of coverage - see below)

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and property_name is specified but is not a recognised property name or is not supported by this feature’s type

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and multiple geometries (if specified in geometry) are not supported by property_name (or the default geometry property name if property_name not specified)

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and any geometry type in geometry is not supported for property_name (or the default geometry property name if property_name not specified)

Raises

InformationModelError if property_name is not specified and a default geometry property is not associated with this feature’s type (this normally should not happen)

Raises

AmbiguousGeometryCoverageError if multiple coverages are specified (in geometry) and more than one has the same number of points (or scalar values) - the ambiguity is due to not being able to subsequently determine which coverage range property is associated with which coverage domain property

Raises

ValueError if geometry is one or more coverages where the number of points in a coverage geometry is not equal to the number of scalar values associated with it

Raises

ValueError if geometry is one or more coverages where the scalar values are incorrectly specified - see GmlDataBlock.__init__() for details

This is a convenience method to make setting geometry easier.

Usually a feature type supports geometry properties with more than one property name. For example, a coastline feature supports both a pygplates.PropertyName.gpml_center_line_of geometry and a pygplates.PropertyName.gpml_unclassified_geometry) geometry. But only one of them is the default (the default property that geometry data is imported into). You can see which is the default by reading the Default Geometry Property label in the coastline feature model.

If property_name is not specified then the default property name is determined from this feature’s type and the geometry is set in one or more properties of that PropertyName.

The question of how many distinct geometries are allowed per feature is a little more tricky. Some geometry properties, such as pygplates.PropertyName.gpml_center_line_of, support multiple properties per feature and support any geometry type. Other geometry properties, such as pygplates.PropertyName.gpml_boundary, tend to support only one property per feature and only some geometry types (eg, only PolylineOnSphere and PolygonOnSphere). However the geometry type is usually apparent given the feature type. For example a pygplates.FeatureType.gpml_isochron feature typically contains a polyline whereas a pygplates.FeatureType.gpml_hot_spot feature contains a point.

Set the default geometry:

feature.set_geometry(default_geometry)

Set the list of default geometries:

default_geometries = []
...
feature.set_geometry(default_geometries)

Set the geometry associated with a property named ‘gpml:averageSampleSitePosition’:

feature.set_geometry(
    average_sample_site_position,
    pygplates.PropertyName.gpml_average_sample_site_position)

Set the list of geometries associated with the property name ‘gpml:unclassifiedGeometry’:

unclassified_geometries = []
...
feature.set_geometry(
    unclassified_geometries,
    pygplates.PropertyName.gpml_unclassified_geometry)

If geometry is not present-day geometry then the created feature will need to be reverse reconstructed to present day using (using either the reverse_reconstruct parameter or reverse_reconstruct()) before the feature can be reconstructed to an arbitrary reconstruction time - this is because a feature is not complete until its geometry is present day geometry. This is usually the case for features that are reconstructed using half-stage rotations since it is typically much easier to specify the geometry at the geological time at which the feature is digitised (as opposed to present-day) as the following example demonstrates:

time_of_digitisation = 50
ridge_geometry_at_digitisation_time = pygplates.PolylineOnSphere([...])
mid_ocean_ridge_feature.set_geometry(
    ridge_geometry_at_digitisation_time,
    reverse_reconstruct=(rotation_model, time_of_digitisation))

The previous example is the equivalent of the following:

time_of_digitisation = 50
ridge_geometry_at_digitisation_time = pygplates.PolylineOnSphere([...])
mid_ocean_ridge_feature.set_geometry(ridge_geometry_at_digitisation_time)
pygplates.reverse_reconstruct(mid_ocean_ridge_feature, rotation_model, time_of_digitisation)

In the examples above the geometry import time is internally set to time_of_digitisation (either due to the reverse_reconstruct argument or the reverse_reconstruct() function). This is so the ridge geometry at digitisation time is correctly reverse-reconstructed (which is especially important for mid-ocean ridges with version 3 half-stage rotations where the spreading start time is the geometry import time).

Note

geometry can also be a coverage or sequence of coverages - where a coverage essentially maps each point in a geometry to one or more scalar values. A coverage is specified in geometry as a (GeometryOnSphere, scalar-values-dictionary) tuple (or a sequence of tuples) where scalar-values-dictionary is a dict that maps scalar types to lists of scalar values. This is the same as the sole argument to GmlDataBlock.__init__(). The number of scalar values, associated with each ScalarType should be equal to the number of points in the geometry.

Set the velocity coverage on the default geometry:

coverage_geometry = pygplates.MultiPointOnSphere([(0,0), (0,10), (0,20)])
coverage_scalars = {
    pygplates.ScalarType.create_gpml('VelocityColat') : [-1.5, -1.6, -1.55],
    pygplates.ScalarType.create_gpml('VelocityLon') : [0.36, 0.37, 0.376]}
feature.set_geometry((coverage_geometry, coverage_scalars))

Warning

If more than one coverage geometry is specified in geometry then the number of points in each coverage geometry should be different otherwise AmbiguousGeometryCoverageError will be raised. Due to this restriction it’s better to set only a single coverage (per geometry property name) - but that single coverage can still have more than one list of scalars.

Changed in version 0.29: The geometry import time is set to the geometry reconstruction time when reverse reconstructing.

set_geometry_import_time(geometry_import_time[, verify_information_model=VerifyInformationModel.yes])

Sets the geometry import time of this feature.

Parameters

geometry_import_time (float or GeoTimeInstant) – the reconstruction time that geometry was imported
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property containing the geometry import time

Return type

get_geometry_import_time()

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and the feature type does not support the pygplates.PropertyName.gpml_geometry_import_time property.

This is a convenience method that wraps set() for the common property pygplates.PropertyName.gpml_geometry_import_time.

Set the geometry import time to 100Ma:

feature.set_geometry_import_time(100)

See also

set_integer(property_name, integer[, verify_information_model=VerifyInformationModel.yes])

Sets the integer property value associated with property_name.

Parameters

property_name (PropertyName) – the property name of the integer property
integer (integer, or sequence of integers) – the integer or integers
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property containing the integer, or properties containing the integers

Return type

Property, or list of Property

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and property_name is not a recognised property name or is not supported by the feature type, or if property_name does not support an integer property value type.

This is a convenience method that wraps set() for XsInteger properties.

Set the subduction zone system order on a feature:

feature.set_integer(
    pygplates.PropertyName.create_gpml('subductionZoneSystemOrder'),
    1)

See also

get_integer()

set_left_plate(left_plate[, verify_information_model=VerifyInformationModel.yes])

Sets the left plate ID of this feature.

Parameters

left_plate (int) – the left plate id
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property containing the left plate id

Return type

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and the feature type does not support the pygplates.PropertyName.gpml_left_plate property.

This is a convenience method that wraps set() for the common property pygplates.PropertyName.gpml_left_plate.

Set the left plate ID to an integer:

feature.set_left_plate(201)

See also

get_left_plate()

set_name(name[, verify_information_model=VerifyInformationModel.yes])

Set the name (or names) of this feature.

Parameters

name (string, or sequence of string) – the name or names
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property containing the name, or properties containing the names

Return type

Property, or list of Property

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and the feature type does not support the pygplates.PropertyName.gml_name property.

This is a convenience method that wraps set() for the common property pygplates.PropertyName.gml_name.

There can be more than one name for a feature but typically there will be only one.

Set the name to a string:

feature.set_name('name')

Set the names to strings:

feature.set_name(['name1', 'name2'])

See also

get_name()

set_reconstruction_method(reconstruction_method[, verify_information_model=VerifyInformationModel.yes])

Sets the reconstruction method of this feature.

Parameters

reconstruction_method (string) –
the reconstruction method (see supported values)
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property containing the reconstruction method

Return type

get_reconstruction_method()

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and the feature type does not support the pygplates.PropertyName.gpml_reconstruction_method property, or reconstruction_method is not a recognised reconstruction method.

This is a convenience method that wraps set() for the common property pygplates.PropertyName.gpml_reconstruction_method.

Set the reconstruction method such that reconstructions of the feature will be done using half-stage rotations:

feature.set_reconstruction_method('HalfStageRotationVersion2')

See also

set_reconstruction_plate_id(reconstruction_plate_id[, verify_information_model=VerifyInformationModel.yes])

Sets the reconstruction plate ID of this feature.

Parameters

reconstruction_plate_id (int) – the reconstruction plate id
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property containing the reconstruction plate id

Return type

get_reconstruction_plate_id()

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and the feature type does not support the pygplates.PropertyName.gpml_reconstruction_plate_id property.

This is a convenience method that wraps set() for the common property pygplates.PropertyName.gpml_reconstruction_plate_id.

Set the reconstruction plate ID to an integer:

feature.set_reconstruction_plate_id(701)

See also

set_relative_plate(relative_plate[, verify_information_model=VerifyInformationModel.yes])

Sets the relative plate ID of this feature.

Parameters

relative_plate (int) – the relative plate id
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property containing the relative plate id

Return type

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and the feature type does not support the pygplates.PropertyName.gpml_relative_plate property.

This is a convenience method that wraps set() for the common property pygplates.PropertyName.gpml_relative_plate.

Set the relative plate ID to an integer:

feature.set_relative_plate(701)

See also

get_relative_plate()

set_right_plate(right_plate[, verify_information_model=VerifyInformationModel.yes])

Sets the right plate ID of this feature.

Parameters

right_plate (int) – the right plate id
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property containing the right plate id

Return type

set_shapefile_attributes()

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and the feature type does not support the pygplates.PropertyName.gpml_right_plate property.

This is a convenience method that wraps set() for the common property pygplates.PropertyName.gpml_right_plate.

Set the right plate ID to an integer:

feature.set_right_plate(701)

See also

get_right_plate()

set_shapefile_attribute(key, value[, verify_information_model=VerifyInformationModel.yes])

Sets the value of a shapefile attribute associated with a key.

Parameters

key (string) – the key of the shapefile attribute
value (integer, float or string) – the value of the shapefile attribute
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property containing all the shapefile attributes

Return type

Property containing a GpmlKeyValueDictionary property value

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and the feature type does not support the pygplates.PropertyName.gpml_shapefile_attributes property (although all feature types do support it).

Raises

InformationModelError if a pygplates.PropertyName.gpml_shapefile_attributes property name is found in this feature but the property value is not a GpmlKeyValueDictionary (this should not normally happen).

Shapefile attributes are stored in a GpmlKeyValueDictionary property named pygplates.PropertyName.gpml_shapefile_attributes and contain attributes imported from a Shapefile.

This is a convenience method that wraps set() for the common property pygplates.PropertyName.gpml_shapefile_attributes and sets the attribute value associated with key within that property using GpmlKeyValueDictionary.set().

If a ‘gpml:shapefileAttributes’ property does not exist in this feature then one is first created and added to this feature before setting the shapefile attribute in it.

Set an integer attribute value associated with ‘key’:

feature.set_shapefile_attribute('key', 100)

See also

See also

get_shapefile_attribute()

set_shapefile_attributes([attribute_mapping][, verify_information_model=VerifyInformationModel.yes])

Sets the shapefile attributes of this feature.

Parameters

attribute_mapping (dict mapping each key (string) to a value (integer, float or string), or a sequence of (key, value) tuples, or None) – optional mapping of keys to values
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property containing all the shapefile attributes

Return type

Property containing a GpmlKeyValueDictionary property value

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and the feature type does not support the pygplates.PropertyName.gpml_shapefile_attributes property (although all feature types do support it).

Raises

InformationModelError if a pygplates.PropertyName.gpml_shapefile_attributes property name is found in this feature but the property value is not a GpmlKeyValueDictionary (this should not normally happen).

Shapefile attributes are stored in a GpmlKeyValueDictionary property named pygplates.PropertyName.gpml_shapefile_attributes and contain attributes imported from a Shapefile.

This is a convenience method that wraps set() for the common property pygplates.PropertyName.gpml_shapefile_attributes.

Note

This replaces any existing shapefile attributes.

To set all shapefile attributes on a feature in one go:

feature.set_shapefile_attributes(
    {'NAME' : 'South America Craton', 'PLATEID1' : 201})

# ...or...

feature.set_shapefile_attributes(
    [('NAME', 'South America Craton'), ('PLATEID1', 201)])

To clear all shapefile attributes on a feature in one go:

feature.set_shapefile_attributes()

Note

Clearing all attributes, as in the above example, will result in the feature containing a single property named ‘gpml:shapefileAttributes’ with an empty attribute dictionary.

See also

set_shapefile_attribute()

See also

get_shapefile_attributes()

set_string(property_name, string[, verify_information_model=VerifyInformationModel.yes])

Sets the string property value associated with property_name.

Parameters

property_name (PropertyName) – the property name of the string property
string (string, or sequence of string) – the string or strings
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property containing the string, or properties containing the strings

Return type

Property, or list of Property

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and property_name is not a recognised property name or is not supported by the feature type, or if property_name does not support a string property value type.

This is a convenience method that wraps set() for XsString properties.

Set the ship track name on a feature:

feature.set_string(
    pygplates.PropertyName.create_gpml('shipTrackName'),
    '...')

See also

get_string()

set_times(times[, verify_information_model=VerifyInformationModel.yes])

Sets the list of times of this flowline or motion path feature.

Parameters

times (sequence (eg, list or tuple) of float or GeoTimeInstant) – the list of times
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property containing the list of times

Return type

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and the feature type does not support the pygplates.PropertyName.gpml_times property.

Raises

ValueError if the time values in times are not in monotonically increasing order, or there are fewer than two time values.

This is a convenience method that wraps set() for the common property pygplates.PropertyName.gpml_times used in flowlines and motion paths.

The list of times must progressively be from most recent (closest to present day) to least recent (furthest in the geological past) otherwise ValueError will be raised.

Set the list of times:

feature.set_times([0, 10, 20, 30, 40])

Note

The ‘gpml:times’ property actually contains a list of time periods (not time instants). So this method converts the time instants (in times) to adjoining time periods when creating the property.

See also

get_times()

set_topological_geometry(topological_geometry[, property_name][, verify_information_model=VerifyInformationModel.yes])

Set the topological geometry (or geometries) of this feature.

Parameters

topological_geometry (GpmlTopologicalLine or GpmlTopologicalPolygon or GpmlTopologicalNetwork, or a sequence (eg, list or tuple) of them) – the topological geometry or geometries to set
property_name (PropertyName) – the optional property name of the topological geometry property or properties to set, if not specified then the default geometry property name associated with this feature’s type is used instead
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the topological geometry property (or properties) set in the feature

Return type

Property, or list of Property depending on whether topological_geometry is a single topological geometry or sequence of them

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and property_name is specified but is not a recognised property name or is not supported by this feature’s type

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and multiple topological geometries (if specified in topological_geometry) are not supported by property_name (or the default geometry property name if property_name not specified)

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and any topological geometry type in topological_geometry is not supported for property_name (or the default geometry property name if property_name not specified)

Raises

InformationModelError if property_name is not specified and a default geometry property is not associated with this feature’s type (this normally should not happen)

This is a convenience method to make setting topological geometry easier.

If property_name is not specified then the default property name is determined from this feature’s type and the geometry is set in one or more properties of that PropertyName.

Set a topological line as the default geometry on a feature:

topological_line = pygplates.GpmlTopologicalLine(...)
feature.set_topological_geometry(topological_line)

Set a topological boundary as the default (‘gpml:boundary’) geometry property of a ‘gpml:TopologicalClosedPlateBoundary’ feature:

topological_boundary_feature = pygplates.Feature(pygplates.FeatureType.gpml_topological_closed_plate_boundary)
topological_boundary_feature.set_topological_geometry(
    pygplates.GpmlTopologicalPolygon(...))

Set the topological boundary as the default (‘gpml:outlineOf’) geometry property of a ‘gpml:ExtendedContinentalCrust’ feature:

extended_continental_crust_feature = pygplates.Feature(pygplates.FeatureType.gpml_extended_continental_crust)
extended_continental_crust_feature.set_topological_geometry(
    pygplates.GpmlTopologicalPolygon(...))

Set a topological network as the default (‘gpml:network’) geometry property of a ‘gpml:TopologicalNetwork’ feature:

topological_network_feature = pygplates.Feature(pygplates.FeatureType.gpml_topological_network)
topological_network_feature.set_topological_geometry(
    pygplates.GpmlTopologicalNetwork(...))

See also

get_total_reconstruction_pole()

New in version 0.24.

set_total_reconstruction_pole(fixed_plate_id, moving_plate_id, total_reconstruction_pole[, verify_information_model=VerifyInformationModel.yes])

Sets the time-dependent total reconstruction pole of this feature.

Parameters

fixed_plate_id (int) – the fixed plate id
moving_plate_id (int) – the moving plate id
total_reconstruction_pole (GpmlIrregularSampling of GpmlFiniteRotation) – the time-sequence of rotations
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the fixed plate id property, the moving plate id property and the total reconstruction pole property

Return type

tuple of three Property

Raises

InformationModelError if verify_information_model is VerifyInformationModel.yes and the feature type does not support pygplates.PropertyName.gpml_fixed_reference_frame, pygplates.PropertyName.gpml_moving_reference_frame and pygplates.PropertyName.gpml_total_reconstruction_pole properties.

This is a convenience method that wraps set() for the common properties pygplates.PropertyName.gpml_fixed_reference_frame, pygplates.PropertyName.gpml_moving_reference_frame and pygplates.PropertyName.gpml_total_reconstruction_pole.

A feature with type pygplates.FeatureType.gpml_total_reconstruction_sequence should support these properties if it conforms to the GPlates Geological Information Model (GPGIM). These feature types are usually read from a GPML rotation file or a PLATES4 rotation (‘.rot’) file.

Set the total reconstruction pole with two integer plate IDs:

feature.set_total_reconstruction_pole(550, 801, total_reconstruction_pole)

See also

set_valid_time(begin_time, end_time[, verify_information_model=VerifyInformationModel.yes])

Sets the valid time range of this feature.

Parameters

begin_time (float or GeoTimeInstant) – the begin time (time of appearance)
end_time (float or GeoTimeInstant) – the end time (time of disappearance)
verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check the information model before setting (default) or not

Returns

the property containing the valid time range

Return type