gplately.SeafloorGrid

class gplately.SeafloorGrid(PlateReconstruction_object, PlotTopologies_object, max_time: float | int, min_time: float | int, ridge_time_step: float | int, save_directory: str | Path = 'seafloor-grid-output', file_collection: str = '', refinement_levels: int = 5, ridge_sampling: float = 0.5, extent: Tuple = (-180, 180, -90, 90), grid_spacing: float = 0.1, subduction_collision_parameters=(5.0, 10.0), initial_ocean_mean_spreading_rate: float = 75.0, resume_from_checkpoints=False, zval_names: List[str] = ['SPREADING_RATE'], continent_mask_filename=None, use_continent_contouring=False)[source]

Bases: object

Generate grids that track data atop global ocean basin points (which emerge from mid ocean ridges) through geological time.

__init__(PlateReconstruction_object, PlotTopologies_object, max_time: float | int, min_time: float | int, ridge_time_step: float | int, save_directory: str | Path = 'seafloor-grid-output', file_collection: str = '', refinement_levels: int = 5, ridge_sampling: float = 0.5, extent: Tuple = (-180, 180, -90, 90), grid_spacing: float = 0.1, subduction_collision_parameters=(5.0, 10.0), initial_ocean_mean_spreading_rate: float = 75.0, resume_from_checkpoints=False, zval_names: List[str] = ['SPREADING_RATE'], continent_mask_filename=None, use_continent_contouring=False)[source]

Constructor. Create a SeafloorGrid object.

Parameters:

  • PlateReconstruction_object (PlateReconstruction) – A PlateReconstruction object with a pygplates.RotationModel and a pygplates.FeatureCollection containing topology features.

  • PlotTopologies_object (PlotTopologies) – A PlotTopologies object with a continental polygon or COB terrane polygon file to mask grids with.

  • max_time (float) – The maximum time for age gridding.

  • min_time (float) – The minimum time for age gridding.

  • ridge_time_step (float) – The delta time for resolving ridges (and thus age gridding).

  • save_directory (str, default=None) – The top-level directory to save all outputs to.

  • file_collection (str, default="") – A string to identify the plate model used (will be automated later).

  • refinement_levels (int, default=5) – Control the number of points in the icosahedral mesh (higher integer means higher resolution of continent masks).

  • ridge_sampling (float, default=0.5) – Spatial resolution (in degrees) at which points that emerge from ridges are tessellated.

  • extent (tuple of 4, default=(-180.,180.,-90.,90.)) – A tuple containing the mininum longitude, maximum longitude, minimum latitude and maximum latitude extents for all masking and final grids.

  • grid_spacing (float, default=0.1) – The degree spacing/interval with which to space grid points across all masking and final grids. If grid_spacing is provided, all grids will use it. If not, grid_spacing defaults to 0.1.

  • subduction_collision_parameters (len-2 tuple of float, default=(5.0, 10.0)) – A 2-tuple of (threshold velocity delta in kms/my, threshold distance to boundary per My in kms/my)

  • initial_ocean_mean_spreading_rate (float, default=75.) – A spreading rate to uniformly allocate to points that define the initial ocean basin. These points will have inaccurate ages, but most of them will be phased out after points with plate-model prescribed ages emerge from ridges and spread to push them towards collision boundaries (where they are deleted).

  • resume_from_checkpoints (bool, default=False) – If set to True, and the gridding preparation stage (continental masking and/or ridge seed building) is interrupted, SeafloorGrids will resume gridding preparation from the last successful preparation time. If set to False, SeafloorGrids will automatically overwrite all files in the save_directory if re-run after interruption, or normally re-run, thus beginning gridding preparation from scratch. False will be useful if data allocated to the MOR seed points need to be augmented.

  • zval_names (list of str) – A list containing string labels for the z values to attribute to points. Will be used as column headers for z value point dataframes.

  • continent_mask_filename (str) – An optional parameter pointing to the full path to a continental mask for each timestep. Assuming the time is in the filename, i.e. /path/to/continent_mask_0Ma.nc, it should be passed as /path/to/continent_mask_{}Ma.nc with curly brackets. Include decimal formatting if needed.

Methods

__init__(PlateReconstruction_object, ...[, ...])

Constructor.

build_all_MOR_seedpoints()

Resolve mid-ocean ridges for all times between min_time and max_time, divide them into points that make up their shared sub-segments.

build_all_continental_masks()

Create a continental mask to define the ocean basin for all times between min_time and max_time.

create_initial_ocean_seed_points()

Create the initial ocean basin seed point domain (at max_time only) using Stripy's icosahedral triangulation with the specified self.refinement_levels.

lat_lon_z_to_netCDF(zval_name[, time_arr, ...])

Produce a netCDF4 grid of a z-value identified by its zval_name for a given time range in time_arr.

prepare_for_reconstruction_by_topologies()

Prepare three main auxiliary files for seafloor data gridding:

reconstruct_by_topological_model()

Use pygplates.TopologicalModel class to reconstruct seed points.

reconstruct_by_topologies()

Obtain all active ocean seed points which are points that have not been consumed at subduction zones or have not collided with continental polygons.

save_netcdf_files(name[, times, unmasked, ...])

Interpolate the sample points to create regular grids and save as NetCDF files.

update_time(max_time)

Set the new reconstruction time.

Attributes

PlotTopologiesTime

The PlotTopologies.time attribute.

max_time

The reconstruction time.
property PlotTopologiesTime

The PlotTopologies.time attribute.

Type:

float

build_all_MOR_seedpoints()[source]

Resolve mid-ocean ridges for all times between min_time and max_time, divide them into points that make up their shared sub-segments. Rotate these points to the left and right of the ridge using their stage rotation so that they spread from the ridge.

Z-value allocation to each point is done here. In future, a function (like the spreading rate function) to calculate general z-data will be an input parameter.

Note

If MOR seed point building is interrupted, progress is safeguarded as long as resume_from_checkpoints is set to True.

This assumes that points spread from ridges symmetrically, with the exception of large ridge jumps at successive timesteps. Therefore, z-values allocated to ridge-emerging points will appear symmetrical until changes in spreading ridge geometries create asymmetries.

In future, this will have a checkpoint save feature so that execution (which occurs during preparation for ReconstructByTopologies and can take several hours) can be safeguarded against run interruptions.

See also

Get tessellated points along a mid ocean ridge.

build_all_continental_masks()[source]

Create a continental mask to define the ocean basin for all times between min_time and max_time.

Note

Continental masking progress is safeguarded if ever masking is interrupted, provided that resume_from_checkpoints is set to True.

The continental masks will be saved to continent_mask_{time}Ma.nc as compressed netCDF4 files.

create_initial_ocean_seed_points()[source]

Create the initial ocean basin seed point domain (at max_time only) using Stripy’s icosahedral triangulation with the specified self.refinement_levels.

The ocean mesh starts off as a global-spanning Stripy icosahedral mesh. create_initial_ocean_seed_points passes the automatically-resolved-to-current-time continental polygons from the PlotTopologies.continents attribute (which can be from a COB terrane file or a continental polygon file) into Plate Tectonic Tools’ point-in-polygon routine. It identifies ocean basin points that lie:

  • outside the polygons (for the ocean basin point domain)

  • inside the polygons (for the continental mask)

Points from the mesh outside the continental polygons make up the ocean basin seed point mesh. The masked mesh is outputted as a compressed GPML (GPMLZ) file with the filename: ocean_basin_seed_points_{}Ma.gpmlz if a save_directory is passed. Otherwise, the mesh is returned as a pygplates.FeatureCollection object.

Note

This point mesh represents ocean basin seafloor that was produced before SeafloorGrid.max_time, and thus has unknown properties like valid time and spreading rate. As time passes, the plate reconstruction model sees points emerging from MORs. These new points spread to occupy the ocean basins, moving the initial filler points closer to subduction zones and continental polygons with which they can collide. If a collision is detected, these points are deleted.

Ideally, if a reconstruction tree spans a large time range, all initial mesh points would collide with a continent or be subducted, leaving behind a mesh of well-defined MOR-emerged ocean basin points that data can be attributed to. However, some of these initial points situated close to contiental boundaries are retained through time - these form point artefacts with anomalously high ages. Even deep-time plate models (e.g. 1 Ga) will have these artefacts - removing them would require more detail to be added to the reconstruction model.

Returns:

ocean_basin_point_mesh – A pygplates.FeatureCollection object containing the seed points on the ocean basin.

Return type:

pygplates.FeatureCollection

lat_lon_z_to_netCDF(zval_name, time_arr=None, unmasked=False, nprocs=1)[source]

Produce a netCDF4 grid of a z-value identified by its zval_name for a given time range in time_arr.

Seafloor age can be gridded by passing zval_name as SEAFLOOR_AGE, and spreading rate can be gridded with SPREADING_RATE.

Saves all grids to compressed netCDF format in the attributed directory. Grids can be read into ndarray format using gplately.read_netcdf_grid().

Parameters:

  • zval_name (str) – A string identifier for the z-value.

  • time_arr (list of float, default=None) – A time range to turn lons, lats and z-values into netCDF4 grids. If not provided, time_arr defaults to the full time_array provided to SeafloorGrid.

  • unmasked (bool, default=False) – Save unmasked grids, in addition to masked versions.

  • nprocs (int, defaullt=1) – Number of processes to use for certain operations (requires joblib). Passed to joblib.Parallel, so -1 means all available processes.

property max_time

The reconstruction time.

Type:

float

prepare_for_reconstruction_by_topologies()[source]

Prepare three main auxiliary files for seafloor data gridding:

  • Initial ocean seed points (at max_time)

  • Continental masks (from max_time to min_time)

  • MOR points (from max_time to min_time)

Return lists of all attributes for the initial ocean point mesh and all ridge points for all times in the reconstruction time array.

reconstruct_by_topological_model()[source]

Use pygplates.TopologicalModel class to reconstruct seed points. This method is an alternative to reconstruct_by_topologies() which uses Python code to do the reconstruction.

reconstruct_by_topologies()[source]

Obtain all active ocean seed points which are points that have not been consumed at subduction zones or have not collided with continental polygons. Active points’ latitudes, longitues, seafloor ages, spreading rates and all other general z-values are saved to a gridding input file (.npz).

save_netcdf_files(name, times=None, unmasked: bool = False, nprocs: int | None = None)[source]

Interpolate the sample points to create regular grids and save as NetCDF files.

Parameters:

  • name (str) – The variable name, such as SEAFLOOR_AGE or SPREADING_RATE.

  • times (list) – A list of times of interest.

  • unmasked (bool) – A flag to indicate if the unmasked grids should be saved.

  • nprocs (int) – The number of processes to use for multiprocessing.

update_time(max_time: float)[source]

Set the new reconstruction time.

Parameters:

max_time (float) – The new reconstruction time.