Reference

This section documents the Python functions and classes that make up the public interface of the pybacktrack package.

The pybacktrack package has the __version__ attribute:

import pybacktrack

pybacktrack.__version__

Backtracking 

Find decompacted total sediment thickness and water depth through time.

`pybacktrack.backtrack_well`	Finds decompacted total sediment thickness and water depth for each age in a well.
`pybacktrack.write_backtrack_well`	Write decompacted parameters as columns in a text file.
`pybacktrack.backtrack_and_write_well`	Same as `pybacktrack.backtrack_well()` but also writes decompacted results to a text file.

Backstripping 

Find decompacted total sediment thickness and tectonic subsidence through time.

`pybacktrack.backstrip_well`	Finds decompacted total sediment thickness and tectonic subsidence for each age in well.
`pybacktrack.write_backstrip_well`	Write decompacted parameters as columns in a text file.
`pybacktrack.backstrip_and_write_well`	Same as `pybacktrack.backstrip_well()` but also writes decompacted results to a text file.

Paleobathymetry 

Generate paleo bathymetry grids through time.

`pybacktrack.generate_lon_lat_points`	Generates a global grid of points uniformly spaced in longitude and latitude.
`pybacktrack.reconstruct_paleo_bathymetry`	Reconstructs and backtracks sediment-covered crust through time to get paleo bathymetry.
`pybacktrack.write_paleo_bathymetry_grids`	Grid paleo bathymetry into a NetCDF grid for each time step.
`pybacktrack.reconstruct_paleo_bathymetry_grids`	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.
`pybacktrack.merge_paleo_bathymetry_grid`	Merge a backtracked paleobathymetry grid with an external paleobathymetry grid and write to a merged output grid file.

Creating lithologies 

Create lithologies or read them from file(s).

`pybacktrack.Lithology`	Class containing lithology data.
`pybacktrack.read_lithologies_file`	Reads a text file with each row representing lithology parameters.
`pybacktrack.read_lithologies_files`	Reads each lithologies text file in the sequence and merges their lithologies.
`pybacktrack.create_lithology`	Looks up a lithology using a name.
`pybacktrack.create_lithology_from_components`	Creates a combined lithology (if necessary) from multiple weighted lithologies.

Reading and writing well files 

Read/write well site files.

`pybacktrack.read_well_file`	Reads a text file with each row representing a stratigraphic unit.
`pybacktrack.write_well_file`	Writes a text file with each row representing a stratigraphic unit.
`pybacktrack.write_well_metadata`	Writes well metadata to file object `well_file`.

Compacted well 

Query a well and its stratigraphic layers.

`pybacktrack.Well`	Class containing all the stratigraphic units in a well sorted by age (from youngest to oldest).
`pybacktrack.StratigraphicUnit`	Class to hold data for a stratigraphic unit.

Decompacted well 

Query decompacted sections at past times.

`pybacktrack.DecompactedWell`	Class containing the decompacted well data at a specific age.
`pybacktrack.DecompactedStratigraphicUnit`	Class to hold data for a decompacted stratigraphic unit (decompacted at a specific age).

Converting oceanic age to depth 

Convert ocean basin ages (Ma) to basement depth (metres) using different age/depth models.

`pybacktrack.convert_age_to_depth`	Convert ocean basin age to basement depth using a specified age/depth model.
`pybacktrack.convert_age_to_depth_files`	Converts age to depth by reading age rows from input file and writing rows containing both age and depth to output file.

Continental rifting 

Continental passive margin initial rifting subsidence and subsequent thermal subsidence. Rifting is assumed instantaneous in that thermal contraction only happens after rifting has ended.

`pybacktrack.estimate_rift_beta`	Estimate the stretching factor (beta).
`pybacktrack.total_rift_subsidence`	Total subsidence as syn-rift plus post-rift.
`pybacktrack.syn_rift_subsidence`	Initial subsidence (in metres) due to continental stretching.
`pybacktrack.post_rift_subsidence`	Thermal subsidence (in metres) as a function of time.

Dynamic topography 

Sample time-dependent dynamic topography in the mantle reference frame.

`pybacktrack.DynamicTopography`	Class that reconstructs point location(s) and samples (and interpolates) time-dependent dynamic topography mantle frame grid files.
`pybacktrack.InterpolateDynamicTopography`	Class that just samples and interpolates time-dependent dynamic topography mantle frame grid files.

Average sea level variations 

Read a sea level file and compute average sea level variations during time periods.

pybacktrack.SeaLevel

Class to calculate integrated sea levels (relative to present day) over a time period.

Converting stratigraphic depth to age 

Convert stratigraphic depths (metres) to age (Ma) using an depth-to-age model.

`pybacktrack.convert_stratigraphic_depth_to_age`	Convert stratigraphic depth to age using a specified depth-to-age model.
`pybacktrack.convert_stratigraphic_depth_to_age_files`	Converts stratigraphic depth to age by reading depth rows (in first column) from input file and writing rows containing both age and depth to output file.

Utilities 

Interpolate a sequence of linear segments read from a 2-column file at the values read from a 1-column file.

`pybacktrack.read_interpolate_function`	Read x and y columns from a curve file and return a function y(x) that linearly interpolates.
`pybacktrack.interpolate_file`	Interpolate curve_function at x positions, read from input file, and store both x and interpolated y values to output file.

Constants 

This section covers the various pre-defined constants that can be passed to the above functions and classes.

Bundle data 

The following bundled data comes included with the pybacktrack package:

a lithologies text file
an age grid
a sediment thickness grid
a crustal thickness grid
a topography grid
a collection of common dynamic topography models
a couple of sea level curves

The following attributes are available to access the bundled data:

pybacktrack.BUNDLE_PATH

Base directory of the bundled data.

This is an absolute path so that scripts outside the pybacktrack package can also reference the bundled data. All bundle data paths are derived from this base path.

pybacktrack.BUNDLE_LITHOLOGY_FILENAMES

A list of bundled lithology filenames.

pybacktrack.DEFAULT_BUNDLE_LITHOLOGY_FILENAME

Same as pybacktrack.PRIMARY_BUNDLE_LITHOLOGY_FILENAME.

pybacktrack.PRIMARY_BUNDLE_LITHOLOGY_FILENAME

The primary lithology filename contains the lithologies covered in Table 1 in the pyBacktrack paper:

Müller, R. D., Cannon, J., Williams, S. and Dutkiewicz, A., 2018, PyBacktrack 1.0: A Tool for Reconstructing Paleobathymetry on Oceanic and Continental Crust, Geochemistry, Geophysics, Geosystems, 19, 1898-1909, doi: 10.1029/2017GC007313.

pybacktrack.EXTENDED_BUNDLE_LITHOLOGY_FILENAME

The optional extended lithology filename extends the primary lithologies, and mostly contains lithologies in shallow water.

pybacktrack.BUNDLE_AGE_GRID_FILENAME

Bundled age grid file.

pybacktrack.BUNDLE_TOPOGRAPHY_FILENAME

Bundled topography/bathymetry grid file.

pybacktrack.BUNDLE_TOTAL_SEDIMENT_THICKNESS_FILENAME

Bundled total sediment thickness grid file.

pybacktrack.BUNDLE_CRUSTAL_THICKNESS_FILENAME

Bundled crustal thickness grid file.

pybacktrack.BUNDLE_DYNAMIC_TOPOGRAPHY_MODELS

Bundled dynamic topography models.

This is a dict mapping dynamic topography model name to model information 3-tuple of (grid list filenames, static polygon filename and rotation filenames). Each key or value in the dict can be passed to the dynamic_topography_model argument of pybacktrack.backtrack_well() and pybacktrack.backtrack_and_write_well().

pybacktrack.BUNDLE_DYNAMIC_TOPOGRAPHY_MODEL_NAMES

A list of bundled dynamic topography model names (keys in BUNDLE_DYNAMIC_TOPOGRAPHY_MODELS).

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

pybacktrack.BUNDLE_SEA_LEVEL_MODELS

Bundled sea level models.

This is a dict mapping sea level model name to sea level file. Each key or value in the dict can be passed to the sea_level_model argument of pybacktrack.backtrack_well() and pybacktrack.backtrack_and_write_well().

pybacktrack.BUNDLE_SEA_LEVEL_MODEL_NAMES

A list of bundled sea level model names (keys in BUNDLE_SEA_LEVEL_MODELS).

Choices include Miller2024_SealevelCurve, Haq2024_Hybrid_SealevelCurve, Haq2024_Hybrid_SealevelCurve_Longterm, Haq87_SealevelCurve and Haq87_SealevelCurve_Longterm.

pybacktrack.BUNDLE_RECONSTRUCTION_ROTATION_FILENAMES

Rotation files of the Zahirovic 2022 default reconstruction model used to reconstruct sediment-deposited crust (at drill sites and for paleobathymetry gridding).

pybacktrack.BUNDLE_RECONSTRUCTION_STATIC_POLYGON_FILENAME

Static polygon file of the Zahirovic 2022 default reconstruction model used to assign plate IDs to points on sediment-deposited crust (at drill sites and for paleobathymetry gridding).

Backtracking 

pybacktrack.BACKTRACK_DEFAULT_DECOMPACTED_COLUMNS: Default list of decompacted columns used for decompacted_columns argument of pybacktrack.backtrack_well() and pybacktrack.backtrack_and_write_well().

List of column types available for the decompacted_columns argument of pybacktrack.backtrack_well() and pybacktrack.backtrack_and_write_well():

pybacktrack.BACKTRACK_COLUMN_AGE
pybacktrack.BACKTRACK_COLUMN_PALEO_LONGITUDE
pybacktrack.BACKTRACK_COLUMN_PALEO_LATITUDE
pybacktrack.BACKTRACK_COLUMN_COMPACTED_THICKNESS
pybacktrack.BACKTRACK_COLUMN_COMPACTED_DEPTH
pybacktrack.BACKTRACK_COLUMN_COMPACTED_DENSITY
pybacktrack.BACKTRACK_COLUMN_DECOMPACTED_THICKNESS
pybacktrack.BACKTRACK_COLUMN_DECOMPACTED_DENSITY
pybacktrack.BACKTRACK_COLUMN_DECOMPACTED_SEDIMENT_RATE
pybacktrack.BACKTRACK_COLUMN_DECOMPACTED_DEPTH
pybacktrack.BACKTRACK_COLUMN_DYNAMIC_TOPOGRAPHY
pybacktrack.BACKTRACK_COLUMN_TECTONIC_SUBSIDENCE
pybacktrack.BACKTRACK_COLUMN_WATER_DEPTH
pybacktrack.BACKTRACK_COLUMN_SEA_LEVEL
pybacktrack.BACKTRACK_COLUMN_COMPOSITE_POROSITY
pybacktrack.BACKTRACK_COLUMN_COMPOSITE_DECAY
pybacktrack.BACKTRACK_COLUMN_LITHOLOGY

Backstripping 

pybacktrack.BACKSTRIP_DEFAULT_DECOMPACTED_COLUMNS: Default list of decompacted columns used for decompacted_columns argument of pybacktrack.backstrip_well() and pybacktrack.backstrip_and_write_well().

List of column types available for the decompacted_columns argument of pybacktrack.backstrip_well() and pybacktrack.backstrip_and_write_well():

pybacktrack.BACKSTRIP_COLUMN_AGE
pybacktrack.BACKSTRIP_COLUMN_PALEO_LONGITUDE
pybacktrack.BACKSTRIP_COLUMN_PALEO_LATITUDE
pybacktrack.BACKSTRIP_COLUMN_COMPACTED_THICKNESS
pybacktrack.BACKSTRIP_COLUMN_COMPACTED_DEPTH
pybacktrack.BACKSTRIP_COLUMN_COMPACTED_DENSITY
pybacktrack.BACKSTRIP_COLUMN_DECOMPACTED_THICKNESS
pybacktrack.BACKSTRIP_COLUMN_DECOMPACTED_DENSITY
pybacktrack.BACKSTRIP_COLUMN_DECOMPACTED_SEDIMENT_RATE
pybacktrack.BACKSTRIP_COLUMN_DECOMPACTED_DEPTH
pybacktrack.BACKSTRIP_COLUMN_AVERAGE_TECTONIC_SUBSIDENCE
pybacktrack.BACKSTRIP_COLUMN_MIN_TECTONIC_SUBSIDENCE
pybacktrack.BACKSTRIP_COLUMN_MAX_TECTONIC_SUBSIDENCE
pybacktrack.BACKSTRIP_COLUMN_AVERAGE_WATER_DEPTH
pybacktrack.BACKSTRIP_COLUMN_MIN_WATER_DEPTH
pybacktrack.BACKSTRIP_COLUMN_MAX_WATER_DEPTH
pybacktrack.BACKSTRIP_COLUMN_SEA_LEVEL
pybacktrack.BACKSTRIP_COLUMN_COMPOSITE_POROSITY
pybacktrack.BACKSTRIP_COLUMN_COMPOSITE_DECAY
pybacktrack.BACKSTRIP_COLUMN_LITHOLOGY

Paleobathymetry 

pybacktrack.DEFAULT_PALEO_BATHYMETRY_LITHOLOGY_NAME: Default name of the lithology of all sediment (for paleo bathymetry gridding the total sediment thickness at all sediment locations consists of a single lithology). This lithology is the average of the ocean floor sediment. This differs from the base lithology of drill sites where the undrilled portions are usually below the Carbonate Compensation Depth (CCD) where shale dominates.

Lithology 

pybacktrack.DEFAULT_BASE_LITHOLOGY_NAME: Default name of the lithology of the stratigraphic unit at the base of a drill site (the undrilled portion). This lithology is shale since the undrilled portions are usually below the Carbonate Compensation Depth (CCD) where shale dominates.

Oceanic subsidence 

pybacktrack.AGE_TO_DEPTH_MODEL_RHCW18

Richards et al. (2020) Structure and dynamics of the oceanic lithosphere-asthenosphere system.

The parameters of the preferred RHCW18 Plate Model used in pyBacktrack include a potential mantle temperature of 1333 in °C, a plate thickness of 130 km and a zero-age ridge depth of 2500 m, as described in Richards et al. (2020) (updated from Richards et al. (2018) and on the related github repository).

pybacktrack.AGE_TO_DEPTH_MODEL_CROSBY_2007

Crosby, A.G., (2007) Aspects of the relationship between topography and gravity on the Earth and Moon, PhD thesis.

The Python source code that implements this age-depth relationship can be found here. And note that additional background information on this model can be found in: Crosby, A.G. and McKenzie, D., 2009. An analysis of young ocean depth, gravity and global residual topography.

pybacktrack.AGE_TO_DEPTH_MODEL_GDH1

Stein and Stein (1992) Model for the global variation in oceanic depth and heat flow with lithospheric age.

pybacktrack.AGE_TO_DEPTH_DEFAULT_MODEL

The age-to-depth model to use by default.