pygplates.Feature

class pygplates.Feature

Bases: Boost.Python.instance

The feature is an abstract model of some geological or plate-tectonic object or concept of interest defined by the GPlates Geological Information Model (GPGIM). A feature consists of a collection of properties, a feature type and a feature id.

The following operations for iterating over the properties in a feature are supported:

Operation Result
len(f) number of properties in feature f
for p in f iterates over the properties p in feature f

For example:

num_properties = len(feature)
properties_in_feature = [property for property in feature]
# assert(num_properties == len(properties_in_feature))

The following methods provide convenient ways to create features:

The following methods return the feature type and feature id:

The following methods provide generic support for adding, removing, setting and getting properties:

The following methods provide a convenient way to set and get feature geometry:

The following methods provide a convenient way to set and get feature topological geometry (which can be topological a line, polygon or network):

The following methods provide a convenient way to set and get attributes imported from a Shapefile:

The following methods provide a convenient way to set and get enumeration properties:

The following methods provide a convenient way to set and get string, floating-point, integer and boolean properties:

The following methods provide a convenient way to set and get some of the properties that are common to many feature types:

For other properties the generic set(), get() and get_value() methods will still need to be used.

A feature can be deep copied using clone().

__init__([feature_type][, feature_id][, verify_information_model=VerifyInformationModel.yes])

Create a new feature instance that is (initially) empty (has no properties).

Parameters:
  • feature_type (FeatureType) – the type of feature
  • feature_id (FeatureId) – the feature identifier
  • verify_information_model (VerifyInformationModel.yes or VerifyInformationModel.no) – whether to check feature_type with the information model (default) or not
Raises:

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

See FeatureType for a list of available feature types.

feature_type defaults to gpml:UnclassifiedFeature if not specified. There are no restrictions on the types and number of properties that can be added to features of type gpml:UnclassifiedFeature provided their property names are recognised by the GPlates Geological Information Model (GPGIM). However all other feature types are restricted to a subset of recognised properties. The restriction is apparent when the features are created explicitly (see add()) and when features are read from a GPML format file (there are no restrictions when the features are written to a GPML format file).

If feature_id is not specified then a unique feature identifier is created. In most cases a specific feature_id should not be specified because it avoids the possibility of accidentally having two feature instances with the same identifier which can cause problems with topological geometries.

unclassified_feature = pygplates.Feature()

# This does the same thing as the code above.
unclassified_feature = pygplates.Feature(
    pygplates.FeatureType.gpml_unclassified_feature)

Methods

__init__([feature_type], [feature_id], …) Create a new feature instance that is (initially) empty (has no properties).
add(property_name, property_value, …) Adds a property (or properties) to this feature.
clone() Create a duplicate of this feature instance.
create_flowline(seed_geometry, times, …) [staticmethod] Create a flowline feature.
create_motion_path(seed_geometry, times, …) [staticmethod] Create a motion path feature.
create_reconstructable_feature(feature_type, …) [staticmethod] Create a reconstructable feature.
create_tectonic_section(feature_type, …) [staticmethod] Create a tectonic section feature.
create_topological_feature(feature_type, …) [staticmethod] Create a topological feature.
create_total_reconstruction_sequence(…) [staticmethod] Create a rotation feature for a fixed/moving plate pair.
get(property_query, …) Returns one or more properties matching a property name or predicate.
get_all_geometries(…) Return a list of all present day geometries of this feature (regardless of their property names).
get_all_topological_geometries() Return a list of all topological geometries of this feature (regardless of their property names).
get_boolean(property_name, [default=False], …) Returns the boolean property value associated with property_name.
get_conjugate_plate_id([default=0], …) Return the conjugate plate ID (or IDs) of this feature.
get_description([default=]) Return the description of this feature.
get_double(property_name, [default=0.0], …) Returns the floating-point (double) property value associated with property_name.
get_enumeration(property_name, [default]) Returns the enumeration content associated with property_name.
get_feature_id() Returns the feature identifier.
get_feature_type() Returns the feature type.
get_geometries([property_query], …) Return a list of the present day geometries of this feature.
get_geometry([property_query], …) Return the present day geometry (or geometries) of this feature.
get_geometry_import_time([default=0.0]) Returns the geometry import time of this feature.
get_integer(property_name, [default=0], …) Returns the integer property value associated with property_name.
get_left_plate([default=0]) Returns the left plate ID of this feature.
get_name([default=], …) Return the name (or names) of this feature.
get_reconstruction_method([default=]) Returns the reconstruction method of this feature.
get_reconstruction_plate_id([default=0]) Returns the reconstruction plate ID of this feature.
get_relative_plate([default=0]) Returns the relative plate ID of this feature.
get_right_plate([default=0]) Returns the right plate ID of this feature.
get_shapefile_attribute(key, [default_value]) Returns the value of a shapefile attribute associated with a key.
get_shapefile_attributes([default]) Returns all shapefile attributes as a dict of key/value pairs.
get_string(property_name, [default=], …) Returns the string property value associated with property_name.
get_times() Returns the list of times of this flowline or motion path feature.
get_topological_geometries([property_query]) Return a list of topological geometries of this feature.
get_topological_geometry([property_query], …) Return the topological geometry (or geometries) of this feature.
get_total_reconstruction_pole() Returns the time-dependent total reconstruction pole of this feature.
get_valid_time([default=(float(), float())]) Returns the valid time range of this feature.
get_value(property_query, [time=0], …) Returns one or more values of properties matching a property name or predicate.
is_valid_at_time(time) Determine if this feature is valid at the specified time.
remove(property_query) Removes properties from this feature.
set(property_name, property_value, …) Sets a property (or properties) to this feature.
set_boolean(property_name, boolean, …) Sets the boolean property value associated with property_name.
set_conjugate_plate_id(conjugate_plate_id, …) Set the conjugate plate ID (or IDs) of this feature.
set_description(description, …) Sets the description of this feature.
set_double(property_name, double, …) Sets the floating-point (double) property value associated with property_name.
set_enumeration(property_name, …) Sets the enumeration content associated with property_name.
set_geometry(geometry, [property_name], …) Set the geometry (or geometries) of this feature.
set_geometry_import_time(…) Sets the geometry import time of this feature.
set_integer(property_name, integer, …) Sets the integer property value associated with property_name.
set_left_plate(left_plate, …) Sets the left plate ID of this feature.
set_name(name, …) Set the name (or names) of this feature.
set_reconstruction_method(…) Sets the reconstruction method of this feature.
set_reconstruction_plate_id(…) Sets the reconstruction plate ID of this feature.
set_relative_plate(relative_plate, …) Sets the relative plate ID of this feature.
set_right_plate(right_plate, …) Sets the right plate ID of this feature.
set_shapefile_attribute(key, value, …) Sets the value of a shapefile attribute associated with a key.
set_shapefile_attributes(…) Sets the shapefile attributes of this feature.
set_string(property_name, string, …) Sets the string property value associated with property_name.
set_times(times, …) Sets the list of times of this flowline or motion path feature.
set_topological_geometry(…) Set the topological geometry (or geometries) of this feature.
set_total_reconstruction_pole(…) Sets the time-dependent total reconstruction pole of this feature.
set_valid_time(begin_time, end_time, …) Sets the valid time range of this feature.
add(property_name, property_value[, verify_information_model=VerifyInformationModel.yes])

Adds a property (or properties) to this feature.

param property_name:
 the name of the property (or properties) to add
type property_name:
 PropertyName
param property_value:
 the value (or values) of the property (or properties) to add
type property_value:
 PropertyValue, or sequence (eg, list or tuple) of PropertyValue
param verify_information_model:
 whether to check the information model before adding (default) or not
type verify_information_model:
 VerifyInformationModel.yes or VerifyInformationModel.no
returns:the property (or properties) added to the feature
rtype: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_value does not have a property value type supported by property_name 
property_added = feature.add(property_name, property_value)
properties_added = feature.add(property_name, [property_value1, property_value2])
# assert(len(properties_added) == 2)

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

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

remove()

add(properties, [verify_information_model=VerifyInformationModel.yes])

Adds properties to this feature.

param properties:
 the property name/value pairs to add
type properties:
 a sequence (eg, list or tuple) of (PropertyName, PropertyValue or sequence of PropertyValue)
param verify_information_model:
 whether to check the information model before adding (default) or not
type verify_information_model:
 VerifyInformationModel.yes or VerifyInformationModel.no
returns:the list of properties added to the feature
rtype:list of Property
raises:InformationModelError if verify_information_model is VerifyInformationModel.yes and any of the property names are not recognised property names or not supported by the feature type, or if any property value type is not supported by its associated property name 
properties_added = feature.add([
    (property_name1, property_value1),
    (property_name2, property_value2)])
# assert(len(properties_added) == 2)

properties_added = feature.add([
    (property_name3, (property_value3a, property_value3b, property_value3c)),
    (property_name4, [property_value4a, property_value4b])
    (property_name5, property_value5)
    ])
# assert(len(properties_added) == 6)

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

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

remove()

clone()

Create a duplicate of this feature instance.

Return type:Feature

This creates a new Feature instance with cloned versions of this feature’s properties. And the cloned feature is created with its own unique FeatureId.

static create_flowline(seed_geometry, times[, name][, description][, valid_time][, left_plate][, right_plate][, other_properties][, feature_id][, reverse_reconstruct][, verify_information_model=VerifyInformationModel.yes])

[staticmethod] Create a flowline 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
  • 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
  • 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 - if this tuple of reverse reconstruct parameters is specified then seed_geometry is reverse reconstructed using those parameters and any specified feature properties (eg, left_plate) - 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:

Feature
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 - 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:

Feature
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 - 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:

Feature
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))
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 - 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:

Feature
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))
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:
Return type:

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

create_reconstructable_feature()

New in version 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:

Feature

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
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_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

set_topological_geometry()

New in version 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
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

set_geometry()

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

get_geometries() and get_all_geometries()

See also

set_geometry()

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

set_geometry_import_time()

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

get_topological_geometries() and get_all_topological_geometries()

See also

set_topological_geometry()

New in version 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

See also

set_valid_time() and is_valid_at_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):
    ...

See also

get_valid_time() and set_valid_time()

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:

Property
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:

Property
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 - 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
Return type:

Property, or list of Property depending on whether geometry is a GeometryOnSphere or sequence of GeometryOnSphere
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)

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.

See also

get_geometry(), get_geometries() and get_all_geometries()

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:

Property
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

get_geometry_import_time()

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:

Property
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:

Property
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

get_reconstruction_method()

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:

Property
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

get_reconstruction_plate_id()

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:

Property
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:

Property
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

set_shapefile_attributes()

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:

Property
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_topological_geometry(), get_topological_geometries() and get_all_topological_geometries()

See also

set_geometry()

New in version 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

get_total_reconstruction_pole()

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:

Property
Raises:

GmlTimePeriodBeginTimeLaterThanEndTimeError if begin time is later than end time
Raises:

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

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

Set the valid time range to include all geological time up until present day:

feature.set_valid_time(pygplates.GeoTimeInstant.create_distant_past(), 0)

See also

get_valid_time() and is_valid_at_time()