pygplates.find_crossovers

pygplates.find_crossovers(rotation_features[, crossover_filter][, crossover_type_function=CrossoverTypeFunction.type_from_xo_tags_in_comment])

Find crossovers in rotation features.

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

• crossover_filter (a callable accepting a single named-tuple 'Crossover' argument, or None) – A predicate function to determine which crossovers to return

• crossover_type_function (a callable, or a CrossoverType enumerated value) – A function that determines a crossover’s type, or one of the CrossoverType enumerated values, or CrossoverTypeFunction.type_from_xo_tags_in_comment if using default scheme for determining crossover type (see below) - default is CrossoverTypeFunction.type_from_xo_tags_in_comment

Returns

A time-sorted list, from most recent (youngest) to least recent (oldest), of crossover named-tuple ‘Crossover’ (see table below)

Return type

list of named-tuple ‘Crossover’

A crossover occurs when the motion of a (moving) plate crosses over from one (fixed) plate to move relative to another (fixed) plate at a particular geological time.

A crossover is represented as a named-tuple ‘Crossover’ with the following named elements:

Name	Type	Description
type	int	One of the enumerated values of CrossoverType (see table below).
time	float	The crossover time.
moving_plate_id	int	The moving plate ID.
young_crossover_fixed_plate_id	int	The fixed plate ID after (younger than) the crossover.
old_crossover_fixed_plate_id	int	The fixed plate ID before (older than) the crossover.
young_crossover_rotation_sequence	list of GpmlFiniteRotation	The time sequence of enabled finite rotations after (younger than) the crossover.
old_crossover_rotation_sequence	list of GpmlFiniteRotation	The time sequence of enabled finite rotations before (older than) the crossover.

Note

Younger means more recent (smaller time values) and older means less recent (larger time values).

Note

Both the young and old crossover rotation sequences will each have at least one enabled time sample. And the disabled time samples are not included.

Note

The returned list of crossovers is sorted by time from most recent (younger) to least recent (older). The returned list is also optionally filtered if crossover_filter is specified.

A rotation feature has a feature type of total reconstruction sequence and contains a time sequence of finite rotations (see total reconstruction pole) for a specific fixed/moving plate pair. Each crossover essentially returns information of the total reconstruction pole for the rotation feature after the crossover and for the rotation feature before the crossover, as well as the time and type of the crossover - note that both rotation features will have the same moving plate ID but differing fixed plate IDs. In some cases a single moving/fixed rotation sequence is separated into two (or more) rotation features in the rotation file. In this case a crossover will return all finite rotations in the sequence (ie, correspond to more than one feature before and/or after the crossover).

Note

Modifying the rotation sequences in the returned crossovers will modify the finite rotations in the rotation features. This is what happens if the returned crossovers are passed into synchronise_crossovers(). The modified rotation features can then be used to create a new RotationModel with updated rotations.

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

CrossoverType supports the following enumeration values:

Value	Description
CrossoverType.unknown	The crossover is of unknown type (it will not be synchronised).
CrossoverType.ignore	The crossover will be ignored (it will not be synchronised).
CrossoverType.synch_old_crossover_and_stages	All finite rotations in the old crossover sequence will be synchronised (such that old stage rotations are preserved). All finite rotations in the young crossover sequence are preserved.
CrossoverType.synch_old_crossover_only	Only the crossover finite rotation in the old crossover sequence will be synchronised (such that the older finite rotations are preserved). All finite rotations in the young crossover sequence are preserved.
CrossoverType.synch_young_crossover_and_stages	All finite rotations in the young crossover sequence will be synchronised (such that young stage rotations are preserved). All finite rotations in the old crossover sequence are preserved. Note: This can result in non-zero finite rotations at present day if the younger sequence includes present day.
CrossoverType.synch_young_crossover_only	Only the crossover finite rotation in the young crossover sequence will be synchronised (such that the younger finite rotations are preserved). All finite rotations in the old crossover sequence are preserved.

crossover_type_function supports the following arguments:

Type	Description
Arbitrary callable (function)	A callable accepting the following arguments: crossover_time moving_plate_id young_crossover_fixed_plate_id old_crossover_fixed_plate_id young_crossover_rotation_sequence old_crossover_rotation_sequence …and returning a CrossoverType enumerated value.
CrossoverTypeFunction.type_from_xo_tags_in_comment	A callable (with same arguments as arbitrary callable) that uses the comment/description field of the young crossover pole to determine the crossover type according to the presence of the following strings/tags: @xo_ig : CrossoverType.ignore @xo_ys : CrossoverType.synch_old_crossover_and_stages @xo_yf : CrossoverType.synch_old_crossover_only @xo_os : CrossoverType.synch_young_crossover_and_stages @xo_of : CrossoverType.synch_young_crossover_only …and if none of those tags are present then the crossover type is CrossoverType.unknown. This is the default for crossover_type_function.
CrossoverTypeFunction.type_from_xo_tags_in_comment_default_xo_ys	Same as CrossoverTypeFunction.type_from_xo_tags_in_comment except defaults to CrossoverType.synch_old_crossover_and_stages if no tags are present in the comment/description field of the young crossover pole.
CrossoverTypeFunction.type_from_xo_tags_in_comment_default_xo_ig	Same as CrossoverTypeFunction.type_from_xo_tags_in_comment except defaults to CrossoverType.ignore if no tags are present in the comment/description field of the young crossover pole.
CrossoverType.unknown	All crossovers will be of type CrossoverType.unknown.
CrossoverType.ignore	All crossovers will be of type CrossoverType.ignore.
CrossoverType.synch_old_crossover_and_stages	All crossovers will be of type CrossoverType.synch_old_crossover_and_stages.
CrossoverType.synch_old_crossover_only	All crossovers will be of type CrossoverType.synch_old_crossover_only.
CrossoverType.synch_young_crossover_and_stages	All crossovers will be of type CrossoverType.synch_young_crossover_and_stages.
CrossoverType.synch_young_crossover_only	All crossovers will be of type CrossoverType.synch_young_crossover_only.

Find all crossovers in a rotation file where crossover types are determined by ‘@xo_’ tags in the young crossover description/comment:

crossovers = pygplates.find_crossovers('rotations.rot')
for crossover in crossovers:
    print 'Crossover time: %f' % crossover.time
    print 'Crossover moving plate ID: %d' % crossover.moving_plate_id
    print 'Crossover younger fixed plate ID: %d' % crossover.young_crossover_fixed_plate_id
    print 'Crossover older fixed ID: %d' % crossover.old_crossover_fixed_plate_id
    print 'Crossover younger finite rotation: %d' % \
        crossover.young_crossover_rotation_sequence[-1] \
        .get_finite_rotation().get_lat_lon_euler_pole_and_angle_degrees()
    print 'Crossover older finite rotation: %d' % \
        crossover.old_crossover_rotation_sequence[0] \
          .get_finite_rotation().get_lat_lon_euler_pole_and_angle_degrees()

Find crossovers affecting moving plate 801 assuming all crossovers are of type CrossoverType.synch_old_crossover_and_stages:

crossovers_801 = pygplates.find_crossovers(
    rotation_feature_collection,
    lambda crossover: crossover.moving_plate_id==801,
    pygplates.CrossoverType.synch_old_crossover_and_stages)