pygplates.ReconstructionTree

class pygplates.ReconstructionTree(rotation_features, reconstruction_time[, anchor_plate_id=0])

Bases: Boost.Python.instance

Represents the plate-reconstruction hierarchy of total reconstruction poles at an instant in geological time.

See Plate reconstruction hierarchy.

Total rotations are handled by the methods get_equivalent_total_rotation() and get_relative_total_rotation().

Stage rotations are handled by the functions get_equivalent_stage_rotation() and get_relative_stage_rotation().

Note

All four combinations of total/stage and equivalent/relative rotations can be obtained more easily from class RotationModel using its method RotationModel.get_rotation().

__init__(rotation_features, reconstruction_time[, anchor_plate_id=0])

Create a plate-reconstruction hierarchy at the specified reconstruction time with equivalent rotations relative to the specified anchored plate.

Parameters:
  • rotation_features (FeatureCollection, or string, or Feature, or sequence of Feature, or sequence of any combination of those four types) – A rotation feature collection, or rotation filename, or rotation feature, or sequence of rotation features, or a sequence (eg, list or tuple) of any combination of those four types
  • reconstruction_time (float or GeoTimeInstant) – the time at which to generate the reconstruction tree
  • anchor_plate_id (int) – the id of the anchored plate that equivalent rotations are calculated with respect to
Raises:

InterpolationError if reconstruction_time is distant past or distant future

Note that rotation_features can be a rotation FeatureCollection or a rotation filename or a rotation Feature or a sequence of rotation features, or a sequence (eg, list or tuple) of any combination of those four types.

If any rotation filenames are specified then this method uses FeatureCollectionFileFormatRegistry internally to read the rotation files.

Note

The anchored plate id can be any plate id (does not have to be zero). All equivalent rotations are calculated relative to the anchored plate id.

This method essentially does the following:

def create_reconstruction_tree(rotation_features, reconstruction_time, anchor_plate_id):
    builder = pygplates.ReconstructionTreeBuilder()
    for rotation_feature in rotation_features:
        trp = rotation_feature.get_total_reconstruction_pole()
        if trp:
            fixed_plate_id, moving_plate_id, total_reconstruction_pole = trp
            interpolated_rotation = total_reconstruction_pole.get_value(reconstruction_time)
            if interpolated_rotation:
                builder.insert_total_reconstruction_pole(fixed_plate_id, moving_plate_id, interpolated_rotation)
    return builder.build_reconstruction_tree(anchor_plate_id, reconstruction_time)

Note that the above example uses ReconstructionTreeBuilder and Feature.get_total_reconstruction_pole()

Methods

__init__(rotation_features, ...) Create a plate-reconstruction hierarchy at the specified reconstruction time with equivalent rotations relative to the specified anchored plate.
get_anchor_plate_edges() Returns a view, of the edges at the top (or root) of this reconstruction tree, that supports iteration over the edges as well as indexing into the edges.
get_anchor_plate_id() Return the anchor plate id for which this ReconstructionTree was generated.
get_edge(moving_plate_id) Return the edge in the hierarchy (graph) of the reconstruction tree associated with the specified moving plate id, or None if moving_plate_id is not in the reconstruction tree.
get_edges() Returns a view, of all edges of this reconstruction tree, that supports iteration over the edges as well as indexing into the edges.
get_equivalent_stage_rotation(...) [staticmethod] Return the finite rotation that rotates from the anchored plate to plate plate_id and from the time of from_reconstruction_tree to the time of to_reconstruction_tree.
get_equivalent_total_rotation(plate_id, ...) Return the equivalent finite rotation of the plate_id plate relative to the anchored plate.
get_reconstruction_time() Return the reconstruction time for which this ReconstructionTree was generated.
get_relative_stage_rotation(...) [staticmethod] Return the finite rotation that rotates from the fixed_plate_id plate to the moving_plate_id plate and from the time of from_reconstruction_tree to the time of to_reconstruction_tree.
get_relative_total_rotation(moving_plate_id, ...) Return the finite rotation of the moving_plate_id plate relative to the fixed_plate_id plate.
get_anchor_plate_edges()

Returns a view, of the edges at the top (or root) of this reconstruction tree, that supports iteration over the edges as well as indexing into the edges.

The fixed plate id of each anchor plate edge matches the anchor plate id.

Note that the view object returned by this method is not a list or an iterator but, like dictionary views in Python 3, a list or iterator can be obtained from the view as in list(reconstruction_tree.get_anchor_plate_edges()) or iter(reconstruction_tree.get_anchor_plate_edges()).

The returned view provides the following operations for accessing the anchor plate edges:

Operation Result
len(anchor_plate_edges) number of anchor plate edges
for e in anchor_plate_edges iterates over the anchor plate edges e
anchor_plate_edges[i] the anchor plate edge at index i

The following example demonstrates top-down (starting at the anchored plate) traversal of the reconstruction tree:

def traverse_sub_tree(edge):
    print 'Parent plate: %d, child plate:%d' % (edge.get_fixed_plate_id(), edge.get_moving_plate_id())
    # Recurse into the children sub-trees.
    for child_edge in edge.get_child_edges():
        traverse_sub_tree(child_edge)

for anchor_plate_edge in reconstruction_tree.get_anchor_plate_edges():
    traverse_sub_tree(anchor_plate_edge)
get_anchor_plate_id()

Return the anchor plate id for which this ReconstructionTree was generated.

Return type:int
get_edge(moving_plate_id)

Return the edge in the hierarchy (graph) of the reconstruction tree associated with the specified moving plate id, or None if moving_plate_id is not in the reconstruction tree.

Parameters:moving_plate_id (int) – the moving plate id of the edge in the reconstruction tree (graph)
Return type:ReconstructionTreeEdge or None

Returns None if moving_plate_id is the anchored plate, or is not found (because a total reconstruction pole with that moving plate id was not inserted into the ReconstructionTreeBuilder used to build this reconstruction tree). If moving_plate_id matches more than one edge then the first match is returned.

get_edges()

Returns a view, of all edges of this reconstruction tree, that supports iteration over the edges as well as indexing into the edges.

Note that the view object returned by this method is not a list or an iterator but, like dictionary views in Python 3, a list or iterator can be obtained from the view as in list(reconstruction_tree.get_edges()) or iter(reconstruction_tree.get_edges()).

The returned view provides the following operations for accessing the edges:

Operation Result
len(edges) number of edges
for e in edges iterates over the edges e
edges[i] the edge at index i

The following example demonstrates iteration over all edges in the reconstruction tree to export relative rotations:

with open('export.txt', 'w') as file: 
    for edge in reconstruction_tree.get_edges():
        relative_rotation = edge.get_relative_total_rotation()
        relative_pole_latitude, relative_pole_longitude, relative_angle_degrees = (
            relative_rotation.get_lat_lon_euler_pole_and_angle_degrees())
        file.write('%f %f %f %f %f\n' % (
            edge.get_moving_plate_id(),
            relative_pole_latitude,
            relative_pole_longitude,
            relative_angle_degrees,
            edge.get_fixed_plate_id()))
get_equivalent_stage_rotation(from_reconstruction_tree, to_reconstruction_tree, plate_id[, use_identity_for_missing_plate_ids=True])

[staticmethod] Return the finite rotation that rotates from the anchored plate to plate plate_id and from the time of from_reconstruction_tree to the time of to_reconstruction_tree.

Parameters:
  • from_reconstruction_tree (ReconstructionTree) – the reconstruction tree created for the from time
  • to_reconstruction_tree (ReconstructionTree) – the reconstruction tree created for the to time
  • plate_id (int) – the plate id of the plate
  • use_identity_for_missing_plate_ids (bool) – whether to return an identity rotation or return None for missing plate ids (default is to use identity rotation)
Return type:

FiniteRotation, or None (if use_identity_for_missing_plate_ids is False)

Raises:

DifferentAnchoredPlatesInReconstructionTreesError if the anchor plate of both reconstruction trees is not the same plate

Get the stage rotation of plate 802 (relative to anchor plate) from 20Ma to 15Ma:

reconstruction_tree_at_20Ma = pygplates.ReconstructionTree(rotation_features, 20)
reconstruction_tree_at_15Ma = pygplates.ReconstructionTree(rotation_features, 15)
stage_rotation = pygplates.ReconstructionTree.get_equivalent_stage_rotation(
    reconstruction_tree_at_20Ma,
    reconstruction_tree_at_15Ma,
    802)

#...or even better...

rotation_model = pygplates.RotationModel(rotation_features)
stage_rotation = rotation_model.get_rotation(15, 802, 20)

If the anchored plate of both reconstruction trees differs then DifferentAnchoredPlatesInReconstructionTreesError is raised. In this situation you can instead use get_relative_stage_rotation() and set its fixed_plate_id parameter to the anchored plate that you want.

If there is no plate circuit path from plate_id to the anchor plate (in either reconstruction tree) then an identity rotation is returned if use_identity_for_missing_plate_ids is True, otherwise None is returned. See Plate reconstruction hierarchy for details on how a plate id can go missing and how to work around it.

The only real advantage of this function over get_relative_stage_rotation() is it is a bit faster when the fixed plate is the anchored plate.

This function essentially does the following:

def get_equivalent_stage_rotation(from_reconstruction_tree, to_reconstruction_tree, plate_id):
    if from_reconstruction_tree.get_anchor_plate_id() != to_reconstruction_tree.get_anchor_plate_id():
        raise pygplates.DifferentAnchoredPlatesInReconstructionTreesError
    from_plate_rotation = from_reconstruction_tree.get_equivalent_total_rotation(plate_id)
    to_plate_rotation = to_reconstruction_tree.get_equivalent_total_rotation(plate_id)
    if from_plate_rotation and to_plate_rotation:
        return to_plate_rotation * from_plate_rotation.get_inverse()

Note

See Equivalent stage rotation for the derivation of the stage rotation.

get_equivalent_total_rotation(plate_id[, bool use_identity_for_missing_plate_ids=True])

Return the equivalent finite rotation of the plate_id plate relative to the anchored plate.

Parameters:
  • plate_id (int) – the plate id of plate to calculate the equivalent rotation
  • use_identity_for_missing_plate_ids (bool) – whether to return an identity rotation or return None for missing plate ids (default is to use identity rotation)
Return type:

FiniteRotation, or None (if use_identity_for_missing_plate_ids is False)

Get the rotation of plate 802 (relative to the anchor plate) at 10Ma (relative to present-day):

reconstruction_tree = pygplates.ReconstructionTree(rotation_features, 10)
finite_rotation = reconstruction_tree.get_equivalent_total_rotation(802)

#...or even better...

rotation_model = pygplates.RotationModel(rotation_features)
stage_rotation = rotation_model.get_rotation(10, 802)

The total in the method name indicates that the rotation is also relative to present day.

If there is no plate circuit path from plate_id to the anchor plate then an identity rotation is returned if use_identity_for_missing_plate_ids is True, otherwise None is returned. See Plate reconstruction hierarchy for details on how a plate id can go missing and how to work around it. If plate_id matches more than one plate id in this ReconstructionTree then the first match is returned.

This method essentially does the following:

def get_equivalent_total_rotation(reconstruction_tree, plate_id):
    edge = reconstruction_tree.get_edge(plate_id)
    if edge:
        return edge.get_equivalent_total_rotation()
    elif plate_id == reconstruction_tree.get_anchor_plate_id():
        return pygplates.FiniteRotation.create_identity_rotation()
    elif use_identity_for_missing_plate_ids:
        return pygplates.FiniteRotation.create_identity_rotation()
    # else returns None

Note

See Equivalent total rotation for the derivation of the rotation.

get_reconstruction_time()

Return the reconstruction time for which this ReconstructionTree was generated.

Return type:float
get_relative_stage_rotation(from_reconstruction_tree, to_reconstruction_tree, moving_plate_id, fixed_plate_id[, use_identity_for_missing_plate_ids])

[staticmethod] Return the finite rotation that rotates from the fixed_plate_id plate to the moving_plate_id plate and from the time of from_reconstruction_tree to the time of to_reconstruction_tree.

Parameters:
  • from_reconstruction_tree (ReconstructionTree) – the reconstruction tree created for the from time
  • to_reconstruction_tree (ReconstructionTree) – the reconstruction tree created for the to time
  • moving_plate_id (int) – the plate id of the moving plate
  • fixed_plate_id (int) – the plate id of the fixed plate
  • use_identity_for_missing_plate_ids (bool) – whether to return an identity rotation or return None for missing plate ids (default is to use identity rotation)
Return type:

FiniteRotation, or None (if use_identity_for_missing_plate_ids is False)

Get the stage rotation of plate 802 (relative to plate 291) from 20Ma to 15Ma:

reconstruction_tree_at_20Ma = pygplates.ReconstructionTree(rotation_features, 20)
reconstruction_tree_at_15Ma = pygplates.ReconstructionTree(rotation_features, 15)
stage_rotation = pygplates.ReconstructionTree.get_relative_stage_rotation(
    reconstruction_tree_at_20Ma,
    reconstruction_tree_at_15Ma,
    802,
    291)

#...or even better...

rotation_model = pygplates.RotationModel(rotation_features)
stage_rotation = rotation_model.get_rotation(15, 802, 20, 291)

Note

This function, unlike get_equivalent_stage_rotation(), will still work correctly if the anchored plate of both reconstruction trees differ (not that this is usually the case - just that it’s allowed).

If there is no plate circuit path from fixed_plate_id or moving_plate_id to the anchor plate (in either reconstruction tree) then an identity rotation is returned if use_identity_for_missing_plate_ids is True, otherwise None is returned. See Plate reconstruction hierarchy for details on how a plate id can go missing and how to work around it.

This function essentially does the following:

def get_relative_stage_rotation(from_reconstruction_tree, to_reconstruction_tree, moving_plate_id, fixed_plate_id):
    fixed_plate_from_rotation = from_reconstruction_tree.get_equivalent_total_rotation(fixed_plate_id)
    fixed_plate_to_rotation = to_reconstruction_tree.get_equivalent_total_rotation(fixed_plate_id)
    moving_plate_from_rotation = from_reconstruction_tree.get_equivalent_total_rotation(moving_plate_id)
    moving_plate_to_rotation = to_reconstruction_tree.get_equivalent_total_rotation(moving_plate_id)
    if fixed_plate_from_rotation and fixed_plate_to_rotation and moving_plate_from_rotation and moving_plate_to_rotation:
        return fixed_plate_to_rotation.get_inverse() * moving_plate_to_rotation * moving_plate_from_rotation.get_inverse() * fixed_plate_from_rotation

Note

See Relative stage rotation for the derivation of the stage rotation.

get_relative_total_rotation(moving_plate_id, fixed_plate_id[, use_identity_for_missing_plate_ids=True])

Return the finite rotation of the moving_plate_id plate relative to the fixed_plate_id plate.

Parameters:
  • moving_plate_id (int) – the plate id of plate to calculate the relative rotation
  • fixed_plate_id (int) – the plate id of plate that the rotation is relative to
  • use_identity_for_missing_plate_ids (bool) – whether to return an identity rotation or return None for missing plate ids (default is to use identity rotation)
Return type:

FiniteRotation, or None (if use_identity_for_missing_plate_ids is False)

Get the rotation of plate 802 (relative to plate 291) at 10Ma (relative to present-day):

reconstruction_tree = pygplates.ReconstructionTree(rotation_features, 10)
finite_rotation = reconstruction_tree.get_relative_total_rotation(802, 291)

#...or even better...

rotation_model = pygplates.RotationModel(rotation_features)
stage_rotation = rotation_model.get_rotation(10, 802, fixed_plate_id=291)

The total in the method name indicates that the rotation is also relative to present day.

This method is useful if fixed_plate_id and moving_plate_id have more than one edge between them. If fixed_plate_id is the anchored plate then this method gives the same result as get_equivalent_total_rotation(). Another way to calculate this result is to create a new ReconstructionTree using fixed_plate_id as the anchored plate. See Plate reconstruction hierarchy for a description of some subtle differences between these two approaches.

If there is no plate circuit path from fixed_plate_id or moving_plate_id to the anchor plate then an identity rotation is returned if use_identity_for_missing_plate_ids is True, otherwise None is returned. See Plate reconstruction hierarchy for details on how a plate id can go missing and how to work around it.

This method essentially does the following:

def get_relative_total_rotation(reconstruction_tree, moving_plate_id, fixed_plate_id):
    fixed_plate_rotation = reconstruction_tree.get_equivalent_total_rotation(fixed_plate_id)
    moving_plate_rotation = reconstruction_tree.get_equivalent_total_rotation(moving_plate_id)
    if fixed_plate_rotation and moving_plate_rotation:
        return fixed_plate_rotation.get_inverse() * moving_plate_rotation

Note

See Relative total rotation for the derivation of the rotation.

Previous topic

pygplates.FiniteRotation

Next topic

pygplates.ReconstructionTreeBuilder

This Page