pybacktrack.reconstruct_paleo_bathymetry_grids

pybacktrack.reconstruct_paleo_bathymetry_grids(output_file_prefix, grid_spacing_degrees, oldest_time=None, time_increment=1, *, youngest_time=0.0, lithology_filenames=[pybacktrack.DEFAULT_BUNDLE_LITHOLOGY_FILENAME], age_grid_filename=pybacktrack.BUNDLE_AGE_GRID_FILENAME, topography_filename=pybacktrack.BUNDLE_TOPOGRAPHY_FILENAME, total_sediment_thickness_filename=pybacktrack.BUNDLE_TOTAL_SEDIMENT_THICKNESS_FILENAME, crustal_thickness_filename=pybacktrack.BUNDLE_CRUSTAL_THICKNESS_FILENAME, rotation_filenames=pybacktrack.bundle_data.BUNDLE_RECONSTRUCTION_ROTATION_FILENAMES, static_polygon_filename=pybacktrack.bundle_data.BUNDLE_RECONSTRUCTION_STATIC_POLYGON_FILENAME, dynamic_topography_model=None, sea_level_model=None, lithology_name=pybacktrack.DEFAULT_PALEO_BATHYMETRY_LITHOLOGY_NAME, ocean_age_to_depth_model=pybacktrack.AGE_TO_DEPTH_DEFAULT_MODEL, rifting_period=None, exclude_distances_to_trenches_kms=None, region_plate_ids=None, anchor_plate_id=0, output_positive_bathymetry_below_sea_level=False, output_xyz=False, output_file_decimal_places_in_time=1, output_rift_stretching_factor_grid_filename=None, merge_paleo_bathymetry_filename_format=None, merge_paleo_bathymetry_file_decimal_places_in_time=0, merge_paleo_bathymetry_is_positive_below_sea_level=False, use_all_cpus=False)

Same as pybacktrack.reconstruct_paleo_bathymetry() but also generates present day input points on a lat/lon grid and outputs paleobathymetry as a NetCDF grid for each time step.

Parameters:

  • output_file_prefix (string) – The prefix of the output paleo bathymetry grid filenames where each filename is generated from a time by appending _<time>.nc to the output file prefix. This is the default method of generating filenames. Alternatively, output_file_prefix can be a template string (see Template strings) containing the ${time} identifier (eg, paleo_bathymetry_${time}.nc). If this identifier is detected, then each filename is generated by replacing all occurrences of the time identifier with the time. For both methods of generating filenames, time is formatted to output_file_decimal_places_in_time decimal places.

  • grid_spacing_degrees (float) – Spacing between lat/lon points (in degrees) to sample bathymetry at present day. Note that any samples outside the masked region of the total sediment thickness grid are ignored.

  • oldest_time (float, optional) – The oldest time (in Ma) that output is generated back to (from present day). Value must not be negative. If not specified then the oldest of oceanic crustal ages (for those grid points on oceanic crust) and rift start ages (for those grid points on continental crust) is used instead.

  • time_increment (float) – The time increment (in My) that output is generated (from youngest to oldest time). Value must be positive.

  • youngest_time (float, default=0.0) – The youngest time (in Ma) that output is generated from. Value must not be negative. Defaults to present day.

  • lithology_filenames (list of string, optional) – One or more text files containing lithologies.

  • age_grid_filename (string, optional) – Age grid filename. Used to obtain age of oceanic crust at present day. Crust is oceanic at locations inside masked age grid region, and continental outside.

  • topography_filename (string, optional) – Topography filename. Used to obtain bathymetry at present day.

  • total_sediment_thickness_filename (string, optional) – Total sediment thickness filename. Used to obtain total sediment thickness at present day.

  • crustal_thickness_filename (string, optional) – Crustal thickness filename. Used to obtain crustal thickness at present day.

  • rotation_filenames (list of string, optional) – List of filenames containing rotation features (to reconstruct sediment-deposited crust). If not specified then defaults to the built-in global rotations associated with the topological model used to generate the built-in rift start/end time grids.

  • static_polygon_filename (string, optional) – Filename containing static polygon features (to assign plate IDs to points on sediment-deposited crust). If not specified then defaults to the built-in static polygons associated with the topological model used to generate the built-in rift start/end time grids.

  • dynamic_topography_model (string or tuple, optional) –

    Represents a time-dependent dynamic topography raster grid (in mantle frame).

    Can be either:

    • A string containing the name of a bundled dynamic topography model.

      Choices include terra, M1, M2, M3, M4, M5, M6, M7, ngrand, s20rts, smean, AY18, KM16, D10_gmcm9 and gld428.

    • A tuple containing the three elements (dynamic topography list filename, static polygon filename, rotation filenames).

      The first tuple element is the filename of file containing list of dynamic topography grids (and associated times). Each row in this list file should contain two columns. First column containing filename (relative to list file) of a dynamic topography grid at a particular time. Second column containing associated time (in Ma). The second tuple element is the filename of file containing static polygons associated with dynamic topography model. This is used to assign plate ID to a location so it can be reconstructed. The third tuple element is the filename of the rotation file associated with model. Only the rotation file for static continents/oceans is needed (ie, deformation rotations not needed).

  • sea_level_model (string, optional) – Used to obtain sea levels relative to present day. Can be either the name of a bundled sea level model, or a sea level filename. Bundled sea level models include Miller2024_SealevelCurve, Haq2024_Hybrid_SealevelCurve, Haq2024_Hybrid_SealevelCurve_Longterm, Haq87_SealevelCurve and Haq87_SealevelCurve_Longterm.

  • lithology_name (string, optional) – Lithology name of the all sediment (must be present in lithologies file). The total sediment thickness at all sediment locations consists of a single lithology. Defaults to Average_ocean_floor_sediment.

  • ocean_age_to_depth_model ({pybacktrack.AGE_TO_DEPTH_MODEL_RHCW18, pybacktrack.AGE_TO_DEPTH_MODEL_CROSBY_2007, pybacktrack.AGE_TO_DEPTH_MODEL_GDH1} or function, optional) – The model to use when converting ocean age to depth at a location (if on ocean floor - not used for continental passive margin). It can be one of the enumerated values, or a callable function accepting a single non-negative age parameter and returning depth (in metres).

  • rifting_period (tuple, optional) – Optional time period of rifting. If specified then overrides rift periods sampled from builtin rift start/end grids. Note that this overrides the spatially varying rift periods (of builtin rift start/end grids) with a constant rift period. Hence it is typically only useful for regional reconstructions (not global). Also, it is only used on continental crust (not oceanic). If specified then should be a 2-tuple (rift_start_age, rift_end_age) where rift_start_age can be None (in which case rifting is considered instantaneous from a stretching point-of-view, not thermal).

  • exclude_distances_to_trenches_kms (2-tuple of float, optional) – The two distances to present-day trenches (on subducting and overriding sides, in that order) to exclude bathymetry grid points (in kms), or None to use built-in per-trench defaults. Default is None.

  • region_plate_ids (list of int, optional) – Plate IDs of one or more plates to restrict paleobathymetry reconstruction to. Defaults to global.

  • anchor_plate_id (int, optional) – The anchor plate id used when reconstructing paleobathymetry grid points. Defaults to zero.

  • output_positive_bathymetry_below_sea_level (bool, optional) – Whether to output positive bathymetry values below sea level (the same as backtracked water depths at a drill site). However topography/bathymetry grids typically have negative values below sea level (and positive above). So the default (False) matches typical topography/bathymetry grids (ie, outputs negative bathymetry values below sea level).

  • output_xyz (bool, optional) – Whether to also create a GMT xyz file (with “.xyz” extension) for each output paleo bathymetry grid. Each row of each xyz file contains “longitude latitude bathymetry”. Default is to only create grid files (no xyz).

  • output_file_decimal_places_in_time (int, default=1) – Number of decimal places to format each time into its paleobathymetry filename. Defaults to 1 decimal place.

  • output_rift_stretching_factor_grid_filename (string, optional) – Optional output filename for the rift stretching (beta) factor grid. This will contain the optimal stretching factor at each present day grid point where there is submerged continental crust (not just the areas that are rifting).

  • merge_paleo_bathymetry_filename_format (str, optional) –

    Optional external paleobathymetry grids to merge into the reconstructed, backtracked paleobathymetry generated in this function. This is useful for filling in regions of sediment-covered crust that have subducted before present day. Backtracked paleobathymetry is only generated for crust that exists at present day (and it is given preference when merging). Regions not covered by backtracked paleobathymetry are then filled with external paleobathymetry after adding dynamic topography (if specified) to them. If specified then must contain the ${time} identifier that will be used to generate a filename for each time (see Template strings). For example, external_paleobathymetry/bathymetry_${time}Ma.nc will result in ${time} being replaced by each time accurate to the number of decimal places specified with merge_paleo_bathymetry_file_decimal_places_in_time (which defaults to zero). If not specified then no merging will occur.

  • merge_paleo_bathymetry_file_decimal_places_in_time (int, default=0) – Number of decimal places to format each time into its merged paleobathymetry input filename. This argument is only used if merge_paleo_bathymetry_filename_format is specified. Defaults to 0 decimal places.

  • merge_paleo_bathymetry_is_positive_below_sea_level (bool, optional) – Whether the external bathymetry values below sea level are positive. However topography/bathymetry grids typically have negative values below sea level (and positive above). So the default (False) matches typical topography/bathymetry grids (ie, outputs negative bathymetry values below sea level). This argument is only used if merge_paleo_bathymetry_filename_format is specified.

  • use_all_cpus (bool or int, optional) – If False (or zero) then use a single CPU. If True then distribute CPU processing across all CPUs (cores). If a positive integer then use that many CPUs (cores). Defaults to False (single CPU).

Raises:

ValueError – If youngest_time or oldest_time is negative (if specified), or if time_increment is not positive.

Notes

The output paleo bathymetry grids have negative values below sea level by default. Note that this is the inverse of water depth (which is positive below sea level).

Any input points outside the masked region of the total sediment thickness grid are ignored (since bathymetry relies on sediment decompaction over time).

Added in version 1.4.

Changed in version 1.5: The following changes were made:

  • oldest_time no longer needs to be specified (defaults to oldest of ocean crust ages and continental rift start ages of grid points).

  • Added optional youngest_time argument.

  • Added optional rifting_period argument.

  • output_file_prefix can alternatively be a template string.

  • Added optional output_file_decimal_places_in_time argument.

  • Added optional output_rift_stretching_factor_grid_filename argument.

  • Added optional merge_paleo_bathymetry_filename_format, merge_paleo_bathymetry_file_decimal_places_in_time and merge_paleo_bathymetry_is_positive_below_sea_level arguments.

  • Some arguments (after *) are now keyword-only (ie, can no longer be specified as positional arguments).