pygplates.ReconstructionTree

class pygplates.ReconstructionTree

Bases: Boost.Python.instance

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

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__(): Deprecated since version 0.25: Use RotationModel.get_reconstruction_tree() instead.

Methods

`__init__`()	Deprecated since version 0.25.
`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 (not in this 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.

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

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

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

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

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.