pygplates column - Sample code - Create features (new/query features)

Create features

This example shows how to query various types of properties.

Create new common feature types

This example shows how to create various types of attributes.
This is similar to import, except that here we are more interested in creating different types of features rather than creating the generic unclassified feature type (pygplates.FeatureType.gpml_unclassified_feature).

Create a coastline feature from current geometry

In this example we create a coastline from the existing geometry and save it to a file.

sample code

import pygplates

# 首先新建一个空的海岸线特征列表
coastline_features = []
# 创建一个折线几何图形，使用部分东巴拿马海岸线的纬度/经度坐标点
eastern_panama_present_day_coastline_geometry = pygplates.PolylineOnSphere(
    [
        (-0.635538, -80.402139),
        (-0.392500, -80.500444),
        ( 0.051750, -80.079222),
        ( 0.370111, -80.049944),
        ( 0.118972, -79.998333),
        ( 0.170306, -79.948361),
        ( 0.763083, -80.099222),
        ( 0.981833, -79.650750),
        ( 0.900000, -79.649472),
        ( 1.068417, -79.430556),
        ( 1.080250, -79.177028),
        ( 1.216111, -79.061472),
        ( 1.041000, -79.014306),
        ( 1.063750, -78.928500),
        ( 1.082389, -78.982583),
        ( 1.144583, -78.897694),
        ( 1.222414, -78.932823)
    ]
)
# 根据海岸线几何图形，名称，有效时段和板块ID新建一个coastline feature
eastern_panama_coastline_feature = pygplates.Feature.create_reconstructable_feature(
    pygplates.FeatureType.gpml_coastline,
    eastern_panama_present_day_coastline_geometry,
    name="Eastern Panama, Central America",
    valid_time=(600, pygplates.GeoTimeInstant.create_distant_future()),
    reconstruction_plate_id=201
)

coastline_features.append(eastern_panama_coastline_feature)
# 保存
coastline_feature_collection = pygplates.FeatureCollection(coastline_features)
coastline_feature_collection.write("4-output_panama_coastline.gpml")

Detailed explanation

Need to use a series (such as a list) of (latitude, longitude) tuples to construct a pygplates.PolylineOnSphere object. When the polyline constructor receives a sequence of 2-tuples, it interprets them as the (latitude, longitude) coordinates of the points that make up the polyline. This particular broken line represents the location of part of Panama's eastern coastline today (0Ma).

eastern_panama_present_day_coastline_geometry = pygplates.PolylineOnSphere(
    [
        (-0.635538, -80.402139),
        (-0.392500, -80.500444),
        ( 0.051750, -80.079222),
        ( 0.370111, -80.049944),
        ( 0.118972, -79.998333),
        ( 0.170306, -79.948361),
        ( 0.763083, -80.099222),
        ( 0.981833, -79.650750),
        ( 0.900000, -79.649472),
        ( 1.068417, -79.430556),
        ( 1.080250, -79.177028),
        ( 1.216111, -79.061472),
        ( 1.041000, -79.014306),
        ( 1.063750, -78.928500),
        ( 1.082389, -78.982583),
        ( 1.144583, -78.897694),
        ( 1.222414, -78.932823)
    ]
)

A coastline feature (pygplates.FeatureType.gpml.coastline type) is created using the pygplates.Feature.create_reconstructable_feature() function.
We also pass to the pygpaltes.Feature.create_reconstructable_feature function a current geometry, a name, a valid period and a reconstruction plate ID. Valid period ends at distant future (distant future).

eastern_panama_coastline_feature = pygplates.Feature.create_reconstructable_feature(
    pygplates.FeatureType.gpml_coastline,
    eastern_panama_present_day_coastline_geometry,
    name="Eastern Panama, Central America",
    valid_time=(600, pygplates.GeoTimeInstant.create_distant_future()),
    reconstruction_plate_id=201
)

last save

coastline_feature_collection = pygplates.FeatureCollection(coastline_features)
coastline_feature_collection.write('coastlines.gpml')`

backup method

First create a pygplates.FeatureType.gpml_coastline empty object, and then set the properties one by one

eastern_panama_coastline_feature = pygplates.Feature(pygplates.FeatureType.gpml_coastline)
eastern_panama_coastline_feature.set_geometry(eastern_panama_present_day_coastline_geometry)
eastern_panama_coastline_feature.set_name("Eastern Panama, Central America")
eastern_panama_coastline_feature.set_valid_time(600, pygplates.GeoTimeInstant.create_distant_future())
eastern_panama_coastline_feature.set_reconstruction_plate_id(201)

Advanced

The pygplates.Feature.create_reconstructable_feature() function will create a feature, and the parameter type specifies any type in reconstructable features .
If any type of feature in the reconstructable features is used, then the object will support gml:name , gml:description , gml:validTime and gml:reconstructionPlatedId .
There are many feature types in reconstructable features. See the Inherited by features section of gpml:ReconstructableFeature . For example, one of them is gpml:TangibleFeature , and one of its Inherited by features includes gpml:Coastline . This means that gpml:Coastline inherits from gpml:ReconsructableFeature. That means they support the same base properties

Create an isochrone feature from geometry from past geological periods

In this example, we create an isochrone from geometry representing its position in geological time in the past (rather than the present).

sample code

import pygplates

# 加载板块运动模型
rotation_model = pygplates.RotationModel("Muller2019-Young2019-Cao2020_CombinedRotations.rot")
# 为40.1Ma的等时线坐标点创建一个折线几何图形
isochron_time_of_appearance = 40.1
isochron_geometry_at_time_of_appearance = pygplates.PolylineOnSphere(
    [
        (-57.635356,  0.765764),
        (-57.162269, -1.953176),
        (-57.916700, -2.522021),
        (-57.658576, -3.936703),
        (-58.639846, -4.849338),
        (-58.404889, -6.060713),
        (-59.390700, -6.877544),
        (-59.048499, -8.573530)
    ]
)
# 新建一个等时线feature
isochron_feature = pygplates.Feature.create_reconstructable_feature(
    pygplates.FeatureType.gpml_isochron,
    isochron_geometry_at_time_of_appearance,
    name="SOUTH AMERICAN ANTARCTIC RIDGE, SOUTH AMERICA-ANTARCTICA ANOMALY 18 IS",
    valid_time=(isochron_time_of_appearance, pygplates.GeoTimeInstant.create_distant_future()),
    reconstruction_plate_id = 201,
    conjugate_plate_id = 802,
    # 指定的几何形状不是现在的，所以它需要反向重构到现在
    reverse_reconstruct = (rotation_model, isochron_time_of_appearance)
)
# 保存
isochron_feature_collection = pygplates.FeatureCollection([isochron_feature])
isochron_feature_collection.write("4-output_isochron_40.1.gpml")

Detailed explanation

pygplates.PolylineOnSphere geometries are created from a sequence (in our case a list) of (latitude, longitude) tuples. This is possible because when the polyline constructor receives a sequence of 2-tuples, it interprets them as the (latitude, longitude) coordinates of the points that make up the polyline.

isochron_geometry_at_time_of_appearance = pygplates.PolylineOnSphere(
    [
        (-57.635356,  0.765764),
        (-57.162269, -1.953176),
        (-57.916700, -2.522021),
        (-57.658576, -3.936703),
        (-58.639846, -4.849338),
        (-58.404889, -6.060713),
        (-59.390700, -6.877544),
        (-59.048499, -8.573530)
    ])

The isochron geometry is not the geometry of today, so it is necessary to reverse reconstruct the created isochron feature to today (using the reverse_reconstruct parameter or the pygplates.reverse_reconstruct() function), and then the feature can be reconstructed to any reconstruction construction time. This is because a feature is not complete until its geometry is what it is now.
Use the pygplates.Feature.create_reconstructable_feature() function to create an isochron feature (pygplates.FeatureType.gpml_isochron type).
The reverse_reconstruct argument takes a tuple including a plate motion model and the current time of the isochrone.
We pass to the pygplates.Feature.create_reconstructable_feature function a geometry at that time, age at that time (plate motion model), name, valid period and reconstructed plate ID.

isochron_feature = pygplates.Feature.create_reconstructable_feature(
    pygplates.FeatureType.gpml_isochron,
    isochron_geometry_at_time_of_appearance,
    name="SOUTH AMERICAN ANTARCTIC RIDGE, SOUTH AMERICA-ANTARCTICA ANOMALY 18 IS",
    valid_time=(isochron_time_of_appearance, pygplates.GeoTimeInstant.create_distant_future()),
    reconstruction_plate_id = 201,
    conjugate_plate_id = 802,
    # 指定的几何形状不是现在的，所以它需要反向重构到现在
    reverse_reconstruct = (rotation_model, isochron_time_of_appearance)
)

Replace the reverse_reconstruct parameter with the pygplates.reverse_reconstruct() function

isochron_feature = pygplates.Feature.create_reconstructable_feature(
	pygplates.FeatureType.gpml_isochron,
	isochron_geometry_at_time_of_appearance,
	name="SOUTH AMERICAN ANTARCTIC RIDGE, SOUTH AMERICA-ANTARCTICA ANOMALY 18 IS"，
	valid_time=(isochron_time_of_appearance, pygplates.GeoTimeInstant.create_distant_future()),
	reconstruction_plate_id = 201,
	conjugate_plate_id=802)
pygplates.reverse_reconstruct(isochron_feature, rotation_model, isochron_time_of_appearance)

warn

pygplates.reverse_reconstruct() should be performed after the attributes of the features are determined. This is necessary because reverse refactoring needs to look at these properties to determine how to reverse refactor.

An alternate method is to reverse the refactoring when setting the geometry:

isochron_feature = pygplates.Feature(pygplates.FeatureType.gpml.isochron)
isochron_feature.set_name("SOUTH AMERICAN ANTARCTIC RIDGE, SOUTH AMERICA-ANTARCTIC ANOMALY 18 IS")
isochron_feature.set_valid_time(isochron_time_of_appearance, pygplates.GeoTimeInstant.create_distant_future())
isochron_feature.set_reconstruction_plate_id(201)
isochron_feature.set_conjugate_plate_id(802)

isochron_feature.set_geometry(
	isochron_geometry_at_time_of_appearance)
	reverse_reconstruct=(rotation_model, isochron_time_of_appearance)))

Create a mid-ocean ridge feature from geometry from past geological periods

sample code

import pygplates

# 加载板块运动模型
rotation_model = pygplates.RotationModel("Muller2019-Young2019-Cao2020_CombinedRotations.rot")
# 使用过去地质时期的几何图形创建大洋中脊特征
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="HalfStageRotationVersion2",
    reverse_reconstruct=(rotation_model, time_of_appearance)
)

Create a subduction zone from today's geometry

sample code

import pygplates

present_day_geometry = pygplates.PolylineOnSphere([...])
subduction_zone_feature = pygplates.Feature.create_reconstructable_feature(
    pygplates.FeatureType.gpml_subduction_zone,
    present_day_geometry,
    name="South America trench",
    valid_time = (200, pygplates.GeoTimeInstant.create_distant_future()),
    reconstruction_plate_id=201
)
subduction_zone_feature.set_enumeration(pygplates.PropertyName.gpml_subduction_polarity, 'Right')

We set the swoop polarity to 'Right' using pygplates.Feature.set_enumeration().

Create a virtual geomagnetic pole feature

sample code

import pygplates

# 极点位置和平均样本位置。
pole_position = pygplates.PointOnSphere(86.3, 168.02)
average_sample_position = pygplates.PointOnSphere(-2.91, -9.59)
# 新建虚拟地磁极特征
virtual_geomagnetic_pole_feature = pygplates.Feature.create_reconstructable_feature(
    pygplates.FeatureType.gpml_virtual_geomagnetic_pole,
    pole_position,
    name="RM: -10 -  10Ma N=10 (Dp col) Lat Range: 29.2 to -78.17 (Dm col.)",
    reconstruction_plate_id = 701
)
# 设置平均样本位置，我们需要指定它的属性名，否则它默认为极点位置并覆盖它。
virtual_geomagnetic_pole_feature.set_geometry(
    average_sample_position,
    pygplates.PropertyName.gpml_average_sample_site_position
)
# 设置平均倾角/赤纬。
virtual_geomagnetic_pole_feature.set_double(
    pygplates.PropertyName.gpml_average_inclination, 180.16
)
virtual_geomagnetic_pole_feature.set_double(
    pygplates.PropertyName.gpml_average_declination, 13.04
)
# 设置杆位不确定度和平均年龄。
virtual_geomagnetic_pole_feature.set_double(
    pygplates.PropertyName.gpml_pole_a95, 3.05
)
virtual_geomagnetic_pole_feature.set_double(
    pygplates.PropertyName.gpml_average_age, 0
)
# 保存
virtual_geomagnetic_pole_feature_collection = pygplates.FeatureCollection(virtual_geomagnetic_pole_feature)
virtual_geomagnetic_pole_feature_collection.write("4-output_virtual_geomagnetic_pole.gpml")

Detailed explanation

A virtual geomagnetic pole feature consists of two geometries, the virtual geomagnetic pole location and the mean sample location

pole_position = pygplates.PointOnSphere(86.3, 168.02)
average_sample_site_position = pygplates.PointOnSphere(-2.91, -9.59)

First create a virtual geomagnetic pole feature through the pygplates.Feature.create_reconstructable_feature() function. The
geometric feature specified here is the pole position (not the average sample position). Because the default geometric element of the virtual geomagnetic pole feature is gpml:polePosition

virtual_geomagnetic_pole_feature = pygplates.Feature.create_reconstructable_feature(
    pygplates.FeatureType.gpml_virtual_geomagnetic_pole,
    pole_position,
    name='RM:-10 -  10Ma N= 10 (Dp col.) Lat Range: 29.2 to -78.17 (Dm col.)',
    reconstruction_plate_id=701)

We need to set the average sample position separately, because it is not the default geometry feature
We also need to specify the correct name, otherwise pygplates.Feature.set_geometry() will set the pole position by default and override the geometry we set.

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

Then set some floating point numbers through pygplates.Feature.set_double()

virtual_geomagnetic_pole_feature.set_double(
    pygplates.PropertyName.gpml_average_inclination,
    180.16)
virtual_geomagnetic_pole_feature.set_double(
    pygplates.PropertyName.gpml_average_declination,
    13.04)
virtual_geomagnetic_pole_feature.set_double(
    pygplates.PropertyName.gpml_pole_a95,
    3.05)
virtual_geomagnetic_pole_feature.set_double(
    pygplates.PropertyName.gpml_average_age,
    0)

Create a motion path

In this example, we created a Motion Path feature to track the movement of plates over time.

sample code

import pygplates

# 指定今时今日非洲海岸线上的两个点（纬度/经度）
seed_points = pygplates.MultiPointOnSphere(
    [
        (-19, 12.5),
        (-28, 15.7)
    ]
)
# 重建运动轨迹的时间序列-从0-90Ma，间隔1Ma
times = range(0, 91, 1)
# 创建运动轨迹特征
motion_path_feature = pygplates.Feature.create_motion_path(
    seed_points,
    times,
    valid_time = (max(times), min(times)),
    relative_plate=201,
    reconstruction_plate_id=701
)

motion_path_feature_collection = pygplates.FeatureCollection([motion_path_feature])
motion_path_feature_collection.write("4-output_motion_path.gpml")

Detailed explanation

We specify the location of two points on the African coastline (701).
These are trajectories of points over time.

seed_points = pygplates.MultiPointOnSphere(
    [
        (-19, 12.5),
        (-28, 15.7)
    ])

The sequence of time samples determines how precise the motion path is—how intensively it is sampled.
Here we sample from 0 to 90Ma at 1My intervals.

times = range(0, 91, 1)

We can create motion trajectories through point coordinates, time series, effective period and related/reconstruction plate ID.
Here, the effective period is set to the entire time series.
The trajectory movement of points is based on the gpml:reconstructionPlateId plate and the related gpml:relatiePlate plate

motion_path_feature = pygplates.Feature.create_motion_path(
        seed_points,
        times,
        valid_time=(max(times), min(times)),
        relative_plate=201,
        reconstruction_plate_id=701)

Create a pipeline feature

sample code

import pygplates

# 指定两个位于现今板块201和701之间的大洋中脊上的点
seed_points = pygplates.MultiPointOnSphere(
    [
        (-35.547600, -17.873000),
        (-46.208000, -13.623000)
    ]
)
# 取样时间序列
times = range(0, 91, 1)
# 创建流水线
flowline_feature = pygplates.Feature.create_flowline(
    seed_points,
    times,
    valid_time=(max(times),min(times)),
    left_plate=201,
    right_plate=701
)
# 保存
flowline_feature_collection = pygplates.FeatureCollection([flowline_feature])
flowline_feature_collection.write("4-output_flowline.gpml")

Create a fully reconstructed sequence (plate motion model) feature

In this example, we create a total reconstructed series feature representing the time series of the total pole of rotation of a moving plate relative to a stationary plate.

sample code

import pygplates
import math

# 移动板块550相对于固定板块801的有限旋转极数据。
# #数据顺序为(pole_time, pole_lat, pole_lan, pole_angle, pole_description)。
pole_data_550_rel_801 = [
    (99.0, 0.72, -179.98, 50.78, 'INA-AUS Muller et.al 2000'),
    (120.4, 10.32, -177.4, 61.12, 'INA-AUS M0 Muller et.al 2000'),
    (124.0, 11.36, -177.07, 62.54, 'INA-AUS M2 Muller et.al 2000'),
    (124.7, 11.69, -176.97, 62.99, 'INA-AUS M3 Muller et.al 2000'),
    (126.7, 12.34, -176.76, 63.95, 'INA-AUS M4 Muller et.al 2000'),
    (127.7, 12.65, -176.66, 64.42, 'INA-AUS M5 Muller et.al 2000'),
    (128.2, 12.74, -176.65, 64.63, 'INA-AUS M6 Muller et.al 2000'),
    (128.4, 12.85, -176.63, 64.89, 'INA-AUS M7 Muller et.al 2000'),
    (129.0, 13.0, -176.61, 65.23, 'INA-AUS M8 Muller et.al 2000'),
    (129.5, 13.2, -176.59, 65.67, 'INA-AUS M9 Muller et.al 2000'),
    (130.2, 13.39, -176.56, 66.1, 'INA-AUS M10 Muller et.al 2000'),
    (130.9, 13.63, -176.53, 66.66, 'INA-AUS M10N Muller et.al 2000'),
    (132.1, 13.93, -176.48, 67.4, 'INA-AUS M11 Muller et.al 2000'),
    (133.4, 14.31, -176.43, 68.33, 'INA-AUS M11A Muller et.al 2000'),
    (134.0, 14.61, -176.39, 69.09, 'INA-AUS M12 Muller et.al 2000'),
    (135.0, 14.86, -176.36, 69.73, 'INA-AUS M12A Muller et.al 2000'),
    (135.3, 15.03, -176.33, 70.19, 'INA-AUS M13 Muller et.al 2000'),
    (135.9, 15.29, -176.3, 70.89, 'INA-AUS M14 Muller et.al 2000'),
    (136.2, 15.5, -176.27, 71.44, 'INA-AUS based on closure IND-ANT Muller et.al 2000'),
    (600.0, 15.5, -176.27, 71.44, 'INA-AUS')
]
# 从极点数据创建一个有限旋转时间样本列表
pole_time_samples_550_rel_801 = [
    pygplates.GpmlTimeSample(
        pygplates.GpmlFiniteRotation(
            pygplates.FiniteRotation(pygplates.PointOnSphere(lat, lon), math.radians(angle))
        ),
        time,
        description
    ) for time, lat, lon, angle, description in pole_data_550_rel_801
]
# 时间样本需要包裹成不规则的采样属性值。
total_reconstruction_pole_550_rel_801 = pygplates.GpmlIrregularSampling(pole_time_samples_550_rel_801)
# Create the total reconstruction sequence (rotation) feature.
rotation_feature_550_rel_801 = pygplates.Feature.create_total_reconstruction_sequence(
    801,
    550,
    total_reconstruction_pole_550_rel_801,
    name="INA-AUS Muller et.al 2000"
)
# 保存
rotation_feature_550_rel_801_collectioin = pygplates.FeatureCollection([rotation_feature_550_rel_801])
rotation_feature_550_rel_801_collectioin.write("4-output_rotation_feature_550_rel_801.gpml")