Bases: Boost.Python.instance
Represents the platereconstruction 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().
Create a platereconstruction hierarchy at the specified reconstruction time with equivalent rotations relative to the specified anchored plate.
Parameters: 


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 platereconstruction 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. 
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 topdown (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 subtrees.
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)
Return the anchor plate id for which this ReconstructionTree was generated.
Return type:  int 

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.
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()))
[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: 


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.
Return the equivalent finite rotation of the plate_id plate relative to the anchored plate.
Parameters: 


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 presentday):
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.
Return the reconstruction time for which this ReconstructionTree was generated.
Return type:  float 

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


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.
Return the finite rotation of the moving_plate_id plate relative to the fixed_plate_id plate.
Parameters: 


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 presentday):
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.