Module gplately.utils

Define a global point mesh with Stripy's icosahedral triangulated mesh and turn all mesh domains into pyGPlates MultiPointOnSphere types.

This global mesh will be masked with a set of continental or COB terrane polygons to define the ocean basin at a given reconstruction time. The refinement_levels integer is proportional to the resolution of the mesh and the ocean/continent boundary.

Parameters

refinement_levels : int

Refine the number of points in the triangulation. The larger the refinement level, the sharper the ocean basin resolution.

Returns

multi_point : instance of <pygplates.MultiPointOnSphere>

The longitues and latitudes that make up the icosahedral ocean mesh collated into a MultiPointOnSphere object.

icosahedral_global_mesh : instance of <stripy.spherical_meshes.icosahedral_mesh>

The original global icosahedral triangulated mesh.

Ensure COB terrane/continental polygon geometries are polygons with reconstruction plate IDs and valid times.

Notes

This step must be done so that the initial set of ocean basin points (the Stripy icosahedral mesh) can be partitioned into plates using each reconstruction plate ID for the given plate model.

This allows for an oceanic point-in-continental polygon query for every identified plate ID. See documentation for point_in_polygon_routine() for more details.

ensure_polygon_geometry() works as follows: COB terrane/continental polygons are assumed to have been reconstructed already in reconstructed_polygons (a list of type ). The list contents are turned into a to be ascribed a PolygonOnSphere geometry, a reconstruction plate ID, and a valid time. Once finished, this feature collection is turned back into a list of instance and returned.

This revert must be completed for compatibility with the subsequent point-in-polygon routine.

Parameters

reconstructed_polygons : list of instance <pygplates.ReconstructedFeatureGeometry>

If used in SeafloorGrid, these are automatically obtained from the PlotTopologies.continents attribute (the reconstructed continental polygons at the current reconstruction time).

rotation_model : instance of <pygplates.RotationModel>

A parameter for turning the back into a list of instance for compatibility with the point-in-polygon routine.

Add subduction teeth to a plot.

The subduction polarity used for subduction teeth can be specified manually or detected automatically if geometries is a geopandas.GeoDataFrame object with a polarity column.

Parameters

geometries : geopandas.GeoDataFrame, sequence of shapely geometries, or str

If a geopandas.GeoDataFrame is given, its geometry attribute will be used. If geometries is a string, it must be the path to a file, which will be loaded with geopandas.read_file. Otherwise, geometries must be a sequence of shapely geometry objects (instances of the shapely.geometry.base.BaseGeometry class).

width : float

The (approximate) width of the subduction teeth. If a projection is used, this value will be in projected units.

polarity : {"left", "l", "right", "r", None}, default None

The subduction polarity of the geometries. If no polarity is provided, and geometries is a geopandas.GeoDataFrame, this function will attempt to find a polarity column in the data frame and use the values given there. If polarity is not manually specified and no appropriate column can be found, an error will be raised.

height : float, default None

If provided, the height of the subduction teeth. As with width, this value should be given in projected units. If no value is given, the height of the teeth will be equal to 0.6 * width.

spacing : float, default None

If provided, the spacing between the subduction teeth. As with width and height, this value should be given in projected units. If no value is given, spacing will default to width, producing tightly packed subduction teeth.

projection : cartopy.crs.Transform, "auto", or None, default "auto"

The projection of the plot. If the plot has no projection, this value can be explicitly given as None. The default value is "auto", which will acquire the projection automatically from the plot axes.

transform : cartopy.crs.Transform, or None, default None

If the plot is projected, a transform value is usually needed. Frequently, the appropriate value is an instance of cartopy.crs.PlateCarree.

ax : matplotlib.axes.Axes, or None, default None

The axes on which the subduction teeth will be drawn. By default, the current axes will be acquired using matplotlib.pyplot.gca.

**kwargs

Any further keyword arguments will be passed to matplotlib.patches.Polygon.

Raises

ValueError

If width <= 0, or if polarity is an invalid value or could not be determined.

Perform Plate Tectonic Tools' point in polygon routine to partition points in a multi_point MultiPointOnSphere feature based on whether they are inside or outside the polygons in COB_polygons.

Notes

Assuming the COB_polygons have passed through ensure_polygon_geometry(), each polygon should have a plate ID assigned to it.

This PIP routine serves two purposes for SeafloorGrid:

1) It identifies continental regions in the icosahedral global mesh MultiPointOnSphere feature and 'erases' in-continent oceanic points for the construction of a continental mask at each timestep;

2) It identifies oceanic points in the icosahedral global mesh. These points will be passed to a function that calculates each point's proximity to its nearest MOR segment (if any) within the polygonal domain of its allocated plate ID. Each distance is divided by half the initial_ocean_mean_spreading_rate (an attribute of SeafloorGrids) to determine a simplified seafloor age for each point.

Number 2) only happens once at the start of the gridding process to momentarily fill the gridding region with initial ocean points that have set ages (albeit not from a plate model file). After multiple time steps of reconstruction, the ocean basin will be filled with new points (with plate-model prescribed ages) that emerge from ridge topologies.

Returns

pygplates.MultiPointOnSphere(points_in_arr) : instance <pygplates.MultiPointOnSphere>

Point features that are within COB terrane polygons.

pygplates.MultiPointOnSphere(points_out_arr) : instance <pygplates.MultiPointOnSphere>

Point features that are outside COB terrane polygons.

zvals : list

A binary list. If an entry is == 0, its corresponing point in the MultiPointOnSphere object is on the ocean. If == 1, the point is in the COB terrane polygon.

Generate Shapely MultiPolygon or MultiLineString geometries from reconstructed feature polygons.

Notes

Some Shapely polygons generated by shapelify_features() cut longitudes of 180 or -180 degrees. These features may appear unclosed at the dateline, so Shapely "closes" these polygons by connecting any of their open ends with lines. These lines may manifest on GeoAxes plots as horizontal lines that span the entire global extent. To prevent this, shapelify_features() uses pyGPlates' DateLineWrapper to split a feature polygon into multiple closed polygons if it happens to cut the antimeridian. Another measure taken to ensure features are valid is to order exterior coordinates of Shapely polygons anti-clockwise.

Parameters

features : iterable of <pygplates.Feature>, <ReconstructedFeatureGeometry> or <GeometryOnSphere>

Iterable containing reconstructed polygon features.

central_meridian : float

Central meridian around which to perform wrapping; default: 0.0.

tessellate_degrees : float or None

If provided, geometries will be tessellated to this resolution prior to wrapping.

Returns

all_geometries : list of shapely.geometry.BaseGeometry

Shapely geometries converted from the given reconstructed features. Any geometries at the dateline are split.

See Also

geometry.pygplates_to_shapely

convert PyGPlates geometry objects to Shapely geometries.