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.

Summary 

pybacktrack.backtrack_well() finds decompacted total sediment thickness and water depth for each age in a well.

pybacktrack.write_backtrack_well() writes decompacted parameters as columns in a text file.

pybacktrack.backtrack_and_write_well() both backtracks well and writes decompacted data.

pybacktrack.backtrack_well(well_filename, 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, dynamic_topography_model=None, sea_level_model=None, base_lithology_name=pybacktrack.DEFAULT_BASE_LITHOLOGY_NAME, ocean_age_to_depth_model=pybacktrack.AGE_TO_DEPTH_DEFAULT_MODEL, rifting_period=None, well_location=None, well_bottom_age_column=0, well_bottom_depth_column=1, well_lithology_column=2)

Finds decompacted total sediment thickness and water depth for each age in a well.

Parameters:

well_filename (string) – Name of well text file.
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 seafloor at well location. Can be explicitly set to None if well site is known to be on continental crust (and hence age grid should be ignored). Note that this is different than not specifying a filename (since that will use the default bundled age grid).
topography_filename (string, optional) – Topography filename. Used to obtain water depth at well location.
total_sediment_thickness_filename (string, optional) – Total sediment thickness filename. Used to obtain total sediment thickness at well location. Can be explicitly set to None if well site is known to be drilled to basement depth (and hence total sediment thickness grid should be ignored). Note that this is different than not specifying a filename (since that will use the default bundled total sediment thickness grid).
crustal_thickness_filename (string, optional) – Crustal thickness filename. Used to obtain crustal thickness at well location.
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 well 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 Haq87_SealevelCurve and Haq87_SealevelCurve_Longterm.
base_lithology_name (string, optional) – Lithology name of the stratigraphic unit at the base of the well (must be present in lithologies file). The stratigraphic units in the well might not record the full depth of sedimentation. The base unit covers the remaining depth from bottom of well to the total sediment thickness. Defaults to Shale.
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 well 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 on continental passive margin - not used for oceanic floor). 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). If specified then overrides value in well file (and value from builtin rift start/end grids). If well is on continental passive margin then at least rift end age should be specified either here or in well file, or well location must be inside rifting region of builtin rift start/end grids, otherwise a ValueError exception will be raised.
well_location (tuple, optional) – Optional location of well. If not provided then is extracted from the well_filename file. If specified then overrides value in well file. If specified then must be a 2-tuple (longitude, latitude) in degrees.
well_bottom_age_column (int, optional) – The column of well file containing bottom age. Defaults to 0.
well_bottom_depth_column (int, optional) – The column of well file containing bottom depth. Defaults to 1.
well_lithology_column (int, optional) – The column of well file containing lithology(s). Defaults to 2.

Returns:

pybacktrack.Well – The well read from well_filename. It may also be amended with a base stratigraphic unit from the bottom of the well to basement.
list of pybacktrack.DecompactedWell – The decompacted wells associated with the well. There is one decompacted well per age, in same order (and ages) as the well units (youngest to oldest).

Raises:

ValueError – If lithology_column is not the largest column number (must be last column).
ValueError – If well_location is not specified and the well location was not extracted from the well file.
ValueError – If well is on continental passive margin but rift end age was not specified by user and was not extracted from well file, and well location was not inside rifting region of builtin rift start/end grids.

Notes

Each attribute to read from well file (eg, bottom_age, bottom_depth, etc) has a column index to direct which column it should be read from.

The tectonic subsidence at each age (of decompacted wells) is added as a tectonic_subsidence attribute to each decompacted well returned.

pybacktrack.write_backtrack_well(decompacted_wells, decompacted_wells_filename, well, well_attributes=None, decompacted_columns=[0, 1])

write_backtrack_well( decompacted_wells, decompacted_wells_filename, well, well_attributes=None, decompacted_columns=pybacktrack.BACKTRACK_DEFAULT_DECOMPACTED_COLUMNS): Write decompacted parameters as columns in a text file.

Parameters:

decompacted_wells (sequence of pybacktrack.DecompactedWell) – The decompacted wells returned by pybacktrack.backtrack_well().
decompacted_wells_filename (string) – Name of output text file.
well (pybacktrack.Well) – The well to extract metadata from.
well_attributes (dict, optional) – Optional attributes in pybacktrack.Well object to write to well file metadata. If specified then must be a dictionary mapping each attribute name to a metadata name. For example, {'longitude' : 'SiteLongitude', 'latitude' : 'SiteLatitude'}. will write well.longitude (if not None) to metadata ‘SiteLongitude’, etc. Not that the attributes must exist in well (but can be set to None).
decompacted_columns (list of columns, optional) –
The decompacted columns (and their order) to output to decompacted_wells_filename.

Available columns are:
- pybacktrack.BACKTRACK_COLUMN_AGE
- 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_COMPACTED_THICKNESS
- pybacktrack.BACKTRACK_COLUMN_LITHOLOGY
- pybacktrack.BACKTRACK_COLUMN_COMPACTED_DEPTH

Raises:

ValueError – If an unrecognised value is encountered in decompacted_columns.
ValueError – If pybacktrack.BACKTRACK_COLUMN_LITHOLOGY is specified in decompacted_columns but is not the last column.

pybacktrack.backtrack_and_write_well(decompacted_output_filename, well_filename, 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, dynamic_topography_model=None, sea_level_model=None, base_lithology_name=pybacktrack.DEFAULT_BASE_LITHOLOGY_NAME, ocean_age_to_depth_model=pybacktrack.AGE_TO_DEPTH_DEFAULT_MODEL, rifting_period=None, decompacted_columns=pybacktrack.BACKTRACK_DEFAULT_DECOMPACTED_COLUMNS, well_location=None, well_bottom_age_column=0, well_bottom_depth_column=1, well_lithology_column=2, ammended_well_output_filename=None)

Same as pybacktrack.backtrack_well() but also writes decompacted results to a text file.

Also optionally write amended well data (ie, including extra stratigraphic base unit from well bottom to ocean basement) to ammended_well_output_filename if specified.

Parameters:

decompacted_output_filename (string) – Name of text file to write decompacted results to.
well_filename (string) – Name of well text file.
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 seafloor at well location. Can be explicitly set to None if well site is known to be on continental crust (and hence age grid should be ignored). Note that this is different than not specifying a filename (since that will use the default bundled age grid).
topography_filename (string, optional) – Topography filename. Used to obtain water depth at well location.
total_sediment_thickness_filename (string, optional) – Total sediment thickness filename. Used to obtain total sediment thickness at well location. Can be explicitly set to None if well site is known to be drilled to basement depth (and hence total sediment thickness grid should be ignored). Note that this is different than not specifying a filename (since that will use the default bundled total sediment thickness grid).
crustal_thickness_filename (string, optional) – Crustal thickness filename. Used to obtain crustal thickness at well location.
dynamic_topography_model (string or tuple, optional) –
Represents a time-dependent dynamic topography raster grid. Currently only used for oceanic floor (ie, well location inside age grid) it is not used if well is on continental crust (passive margin).

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 well 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 Haq87_SealevelCurve and Haq87_SealevelCurve_Longterm.
base_lithology_name (string, optional) – Lithology name of the stratigraphic unit at the base of the well (must be present in lithologies file). The stratigraphic units in the well might not record the full depth of sedimentation. The base unit covers the remaining depth from bottom of well to the total sediment thickness. Defaults to Shale.
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 well 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 on continental passive margin - not used for oceanic floor). 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). If specified then overrides value in well file (and value from builtin rift start/end grids). If well is on continental passive margin then at least rift end age should be specified either here or in well file, or well location must be inside rifting region of builtin rift start/end grids, otherwise a ValueError exception will be raised.
decompacted_columns (list of columns, optional) –
The decompacted columns (and their order) to output to decompacted_wells_filename.

Available columns are:
- pybacktrack.BACKTRACK_COLUMN_AGE
- 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_COMPACTED_THICKNESS
- pybacktrack.BACKTRACK_COLUMN_LITHOLOGY
- pybacktrack.BACKTRACK_COLUMN_COMPACTED_DEPTH
well_location (tuple, optional) – Optional location of well. If not provided then is extracted from the well_filename file. If specified then overrides value in well file. If specified then must be a 2-tuple (longitude, latitude) in degrees.
well_bottom_age_column (int, optional) – The column of well file containing bottom age. Defaults to 0.
well_bottom_depth_column (int, optional) – The column of well file containing bottom depth. Defaults to 1.
well_lithology_column (int, optional) – The column of well file containing lithology(s). Defaults to 2.
ammended_well_output_filename (string, optional) – Amended well data filename. Useful if an extra stratigraphic base unit is added from well bottom to ocean basement.

Raises:

ValueError – If lithology_column is not the largest column number (must be last column).
ValueError – If well_location is not specified and the well location was not extracted from the well file.
ValueError – If well is on continental passive margin but rift end age was not specified by user and was not extracted from well file, and well location was not inside rifting region of builtin rift start/end grids.

Notes

Each attribute to read from well file (eg, bottom_age, bottom_depth, etc) has a column index to direct which column it should be read from.

Backstripping 

Find decompacted total sediment thickness and tectonic subsidence through time.

Summary 

pybacktrack.backstrip_well() finds decompacted total sediment thickness and tectonic subsidence for each age in a well.

pybacktrack.write_backstrip_well() writes decompacted parameters as columns in a text file.

Detail 

pybacktrack.backstrip_well(well_filename, lithology_filenames=[pybacktrack.DEFAULT_BUNDLE_LITHOLOGY_FILENAME], total_sediment_thickness_filename=pybacktrack.BUNDLE_TOTAL_SEDIMENT_THICKNESS_FILENAME, sea_level_model=None, base_lithology_name=pybacktrack.DEFAULT_BASE_LITHOLOGY_NAME, well_location=None, well_bottom_age_column=0, well_bottom_depth_column=1, well_min_water_depth_column=2, well_max_water_depth_column=3, well_lithology_column=4)

Finds decompacted total sediment thickness and tectonic subsidence for each age in well.

Parameters:

well_filename (str) – Name of well text file.
lithology_filenames (list of string, optional) – One or more text files containing lithologies.
total_sediment_thickness_filename (str, optional) – Total sediment thickness filename. Used to obtain total sediment thickness at well location. Can be explicitly set to None if well site is known to be drilled to basement depth (and hence total sediment thickness grid should be ignored). Note that this is different than not specifying a filename (since that will use the default bundled total sediment thickness grid).
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 Haq87_SealevelCurve and Haq87_SealevelCurve_Longterm.
base_lithology_name (string, optional) – Lithology name of the stratigraphic unit at the base of the well (must be present in lithologies file). The stratigraphic units in the well might not record the full depth of sedimentation. The base unit covers the remaining depth from bottom of well to the total sediment thickness. Defaults to Shale.
well_location (tuple, optional) – Optional location of well. If not provided then is extracted from the well_filename file. If specified then overrides value in well file. If specified then must be a 2-tuple (longitude, latitude) in degrees.
well_bottom_age_column (int, optional) – The column of well file containing bottom age. Defaults to 0.
well_bottom_depth_column (int, optional) – The column of well file containing bottom depth. Defaults to 1.
well_min_water_depth_column (int, optional) – The column of well file containing minimum water depth. Defaults to 2.
well_max_water_depth_column (int, optional) – The column of well file containing maximum water depth. Defaults to 3.
well_lithology_column (int, optional) – The column of well file containing lithology(s). Defaults to 4.

Returns:

pybacktrack.Well – The well read from well_filename. It may also be amended with a base stratigraphic unit from the bottom of the well to basement.
list of pybacktrack.DecompactedWell – The decompacted wells associated with the well. There is one decompacted well per age, in same order (and ages) as the well units (youngest to oldest).

Raises:

ValueError – If well_lithology_column is not the largest column number (must be last column).
ValueError – If well_location is not specified and the well location was not extracted from the well file.

Notes

Each attribute to read from well file (eg, bottom_age, bottom_depth, etc) has a column index to direct which column it should be read from.

The min/max paleo water depths at each age (of decompacted wells) are added as min_water_depth and max_water_depth attributes to each decompacted well returned.

pybacktrack.write_backstrip_well(decompacted_wells, decompacted_wells_filename, well, well_attributes=None, decompacted_columns=[0, 1])

write_backstrip_well( decompacted_wells, decompacted_wells_filename, well, well_attributes=None, decompacted_columns=pybacktrack.BACKTRACK_DEFAULT_DECOMPACTED_COLUMNS): Write decompacted parameters as columns in a text file.

Parameters:

decompacted_wells (sequence of pybacktrack.DecompactedWell) – The decompacted wells returned by pybacktrack.backstrip_well().
decompacted_wells_filename (string) – Name of output text file.
well (pybacktrack.Well) – The well to extract metadata from.
well_attributes (dict, optional) – Optional attributes in pybacktrack.Well object to write to well file metadata. If specified then must be a dictionary mapping each attribute name to a metadata name. For example, {'longitude' : 'SiteLongitude', 'latitude' : 'SiteLatitude'}. will write well.longitude (if not None) to metadata ‘SiteLongitude’, etc. Not that the attributes must exist in well (but can be set to None).
decompacted_columns (list of columns, optional) –
The decompacted columns (and their order) to output to decompacted_wells_filename.

Available columns are:
- pybacktrack.BACKSTRIP_COLUMN_AGE
- 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_COMPACTED_THICKNESS
- pybacktrack.BACKSTRIP_COLUMN_LITHOLOGY
- pybacktrack.BACKSTRIP_COLUMN_COMPACTED_DEPTH

Raises:

ValueError – If an unrecognised value is encountered in decompacted_columns.
ValueError – If pybacktrack.BACKSTRIP_COLUMN_LITHOLOGY is specified in decompacted_columns but is not the last column.

pybacktrack.backstrip_and_write_well(decompacted_output_filename, well_filename, lithology_filenames=[pybacktrack.DEFAULT_BUNDLE_LITHOLOGY_FILENAME], total_sediment_thickness_filename=pybacktrack.BUNDLE_TOTAL_SEDIMENT_THICKNESS_FILENAME, sea_level_model=None, base_lithology_name=pybacktrack.DEFAULT_BASE_LITHOLOGY_NAME, decompacted_columns=DEFAULT_DECOMPACTED_COLUMNS, well_location=None, well_bottom_age_column=0, well_bottom_depth_column=1, well_min_water_depth_column=2, well_max_water_depth_column=3, well_lithology_column=4, ammended_well_output_filename=None)

Same as pybacktrack.backstrip_well() but also writes decompacted results to a text file.

Also optionally write amended well data (ie, including extra stratigraphic base unit from well bottom to ocean basement) to ammended_well_output_filename if specified.

Parameters:

decompacted_output_filename (string) – Name of text file to write decompacted results to.
well_filename (string) – Name of well text file.
lithology_filenames (list of string, optional) – One or more text files containing lithologies.
total_sediment_thickness_filename (string, optional) – Total sediment thickness filename. Used to obtain total sediment thickness at well location.
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 Haq87_SealevelCurve and Haq87_SealevelCurve_Longterm.
base_lithology_name (string, optional) – Lithology name of the stratigraphic unit at the base of the well (must be present in lithologies file). The stratigraphic units in the well might not record the full depth of sedimentation. The base unit covers the remaining depth from bottom of well to the total sediment thickness. Defaults to Shale.
decompacted_columns (list of columns, optional) –
The decompacted columns (and their order) to output to decompacted_wells_filename.

Available columns are:
- pybacktrack.BACKSTRIP_COLUMN_AGE
- 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_COMPACTED_THICKNESS
- pybacktrack.BACKSTRIP_COLUMN_LITHOLOGY
- pybacktrack.BACKSTRIP_COLUMN_COMPACTED_DEPTH
well_location (tuple, optional) – Optional location of well. If not provided then is extracted from the well_filename file. If specified then overrides value in well file. If specified then must be a 2-tuple (longitude, latitude) in degrees.
well_bottom_age_column (int, optional) – The column of well file containing bottom age. Defaults to 0.
well_bottom_depth_column (int, optional) – The column of well file containing bottom depth. Defaults to 1.
well_min_water_depth_column (int, optional) – The column of well file containing minimum water depth. Defaults to 2.
well_max_water_depth_column (int, optional) – The column of well file containing maximum water depth. Defaults to 3.
well_lithology_column (int, optional) – The column of well file containing lithology(s). Defaults to 4.
ammended_well_output_filename (string, optional) – Amended well data filename. Useful if an extra stratigraphic base unit is added from well bottom to ocean basement.

Raises:

ValueError – If well_lithology_column is not the largest column number (must be last column).
ValueError – If well_location is not specified and the well location was not extracted from the well file.

Notes

Each attribute to read from well file (eg, bottom_age, bottom_depth, etc) has a column index to direct which column it should be read from.

The min/max paleo water depths at each age (of decompacted wells) are added as min_water_depth and max_water_depth attributes to each decompacted well returned.

Paleobathymetry 

Generate paleo bathymetry grids through time.

Summary 

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 NetCDF grids files.

pybacktrack.reconstruct_paleo_bathymetry_grids() generates a global grid of points, reconstructs/backtracks their bathymetry and writes paleo bathymetry grids.

Detail 

pybacktrack.generate_lon_lat_points(grid_spacing_degrees)

Generates a global grid of points uniformly spaced in longitude and latitude.

Parameters:: grid_spacing_degrees (float) – Spacing between points (in degrees).
Return type:: list of (longitude, latitude) tuples
Raises:: ValueError – If grid_spacing_degrees is negative or zero.

Notes

Longitudes start at -180 (dateline) and latitudes start at -90. If 180 is an integer multiple of grid_spacing_degrees then the final longitude is also on the dateline (+180).

New in version 1.4.

pybacktrack.reconstruct_paleo_bathymetry(input_points, oldest_time=None, time_increment=1, 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, exclude_distances_to_trenches_kms=None, region_plate_ids=None, anchor_plate_id=0, output_positive_bathymetry_below_sea_level=False, use_all_cpus=False)

Reconstructs and backtracks sediment-covered crust through time to get paleo bathymetry.

Parameters:

input_points (sequence of (longitude, latitude) tuples) – The point locations 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 input points on oceanic crust) and rift start ages (for those input points on continental crust) is used instead.
time_increment (float) – The time increment (in My) that output is generated (from present day back to oldest time). Value must be positive.
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 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).
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).
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).

Returns:

The reconstructed paleo bathymetry points from present day to the oldest time (see oldest_time) in increments of time_increment. Each key in the returned dict is one of those times and each value in the dict is a list of reconstructed paleo bathymetries represented as a 3-tuple containing reconstructed longitude, reconstructed latitude and paleo bathmetry.

Return type:

dict mapping each time to a list of 3-tuple (longitude, latitude, bathymetry)

Raises:

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

Notes

The output paleo bathymetry values are negative 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).

New in version 1.4.

Changed in version 1.5: oldest_time no longer needs to be specified (defaults to oldest of ocean crust ages and continental rift start ages of input points).

pybacktrack.write_paleo_bathymetry_grids(paleo_bathymetry, grid_spacing_degrees, output_file_prefix, output_xyz=False, use_all_cpus=False)

Grid paleo bathymetry into a NetCDF grid for each time step.

Parameters:

paleo_bathymetry (dict) – A dict mapping each reconstructed time to a list of 3-tuple (longitude, latitude, bathymetry) The reconstructed paleo bathymetry points over a sequence of reconstructed times. Each key in the returned dict is one of those times and each value in the dict is a list of reconstructed paleo bathymetries represented as a 3-tuple containing reconstructed longitude, reconstructed latitude and paleo bathmetry.
grid_spacing_degrees (float) – Lat/lon grid spacing (in degrees). Ideally this should match the spacing of the input points used to generate the paleo bathymetries.
output_file_prefix (string) – The prefix of the output paleo bathymetry grid filenames over time, with “_<time>.nc” appended.
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).
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).

Notes

New in version 1.4.

pybacktrack.reconstruct_paleo_bathymetry_grids(output_file_prefix, grid_spacing_degrees, oldest_time=None, time_increment=1, 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, exclude_distances_to_trenches_kms=None, region_plate_ids=None, anchor_plate_id=0, output_positive_bathymetry_below_sea_level=False, output_xyz=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 over time, with “_<time>.nc” appended.
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 present day back to oldest time). Value must be positive.
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 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).
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).
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 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).

New in version 1.4.

Changed in version 1.5: oldest_time no longer needs to be specified (defaults to oldest of ocean crust ages and continental rift start ages of grid points).

Creating lithologies 

Create lithologies or read them from file(s).

Summary 

pybacktrack.Lithology is a class containing data for a lithology.

pybacktrack.read_lithologies_file() reads lithologies from a text file.

pybacktrack.read_lithologies_files() reads and merges lithologies from one or more text files.

pybacktrack.create_lithology() creates a lithology by looking up a name in a dictionary of lithologies.

pybacktrack.create_lithology_from_components() creates a lithology by combining multiple lithologies using different weights.

Detail 

class pybacktrack.Lithology(density, surface_porosity, porosity_decay)

Class containing lithology data.

__init__(density, surface_porosity, porosity_decay)

Create a lithology from density, surface porosity and porosity decay.

Parameters:

density (float) – Density (in kg/m3).
surface_porosity (float) – Surface porosity (unit-less).
porosity_decay (float) – Porosity decay (in metres).

pybacktrack.read_lithologies_file(lithologies_filename)

Reads a text file with each row representing lithology parameters.

Parameters:: lithologies_filename (str) – Filename of the lithologies text file.
Returns:: Dictionary mapping lithology names to pybacktrack.Lithology objects.
Return type:: dict

Notes

The four parameter columns in the lithologies text file should contain:

name
density
surface_porosity
porosity_decay

pybacktrack.read_lithologies_files(lithologies_filenames)

Reads each lithologies text file in the sequence and merges their lithologies.

Parameters:: lithologies_filenames (sequence of str) – Filenames of the lithologies text files.
Returns:: Dictionary mapping lithology names to pybacktrack.Lithology objects.
Return type:: dict

Notes

The four parameter columns in each lithologies text file should contain:

name
density
surface_porosity
porosity_decay

The order of filenames is important. If a lithology name exists in multiple files but has different definitions (values for density, surface porosity and porosity decay) then the definition in the last file containing the lithology name is used.

New in version 1.2.

pybacktrack.create_lithology(lithology_name, lithologies)

Looks up a lithology using a name.

Parameters:

lithology_name (str) – The name of the lithology to look up.
lithologies (dict) – A dictionary mapping lithology names to pybacktrack.Lithology objects.

Returns:

The lithology matching lithology_name.

Return type:

pybacktrack.Lithology

Raises:

KeyError – If lithology_name is not found in lithologies.

pybacktrack.create_lithology_from_components(components, lithologies)

Creates a combined lithology (if necessary) from multiple weighted lithologies.

Parameters:

components (sequence of tuples) – A sequence (eg, list) of tuples (str, float) containing a lithology name and its fraction of contribution.
lithologies (dict) – A dictionary mapping lithology names to pybacktrack.Lithology objects.

Returns:

The combined lithology.

Return type:

pybacktrack.Lithology

Raises:

ValueError – If all fractions do not add up to 1.0.
KeyError – If a lithology name is not found in lithologies.

Decompacting well sites 

Read/write well site files,
query a well and its stratigraphic layers, and
query decompacted sections at past times.

Reading and writing well files 

Read/write well site files.

Summary 

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 a text file.

Detail 

pybacktrack.read_well_file(well_filename, lithologies, bottom_age_column=0, bottom_depth_column=1, lithology_column=2, other_columns=None, well_attributes=None)

Reads a text file with each row representing a stratigraphic unit.

Parameters:

well_filename (str) – Name of well text file.
lithologies (dict) – Dictionary mapping lithology names to pybacktrack.Lithology objects.
well_bottom_age_column (int, optional) – The column of well file containing bottom age. Defaults to 0.
well_bottom_depth_column (int, optional) – The column of well file containing bottom depth. Defaults to 1.
well_lithology_column (int, optional) – The column of well file containing lithology(s). Defaults to 2.
other_columns (dict, optional) – Dictionary of extra columns (besides age, depth and lithology(s)). Each dict value should be a column index (to read from file), and each associated dict key should be a string that will be the name of an attribute (added to each pybacktrack.StratigraphicUnit object in the returned pybacktrack.Well) containing the value read. For example, backstripping will add min_water_depth and max_water_depth attributes (when pybacktrack.backstrip_well() or pybacktrack.backstrip_and_write_well() has been called, which in turn calls this function).
well_attributes (dict, optional) – Attributes to read from well file metadata and store in returned pybacktrack.Well object. If specified then must be a dictionary mapping each metadata name to a 2-tuple containing attribute name and a function to convert attribute string to attribute value. For example, {‘SiteLongitude’ : (‘longitude’, float), ‘SiteLatitude’ : (‘latitude’, float)} will look for metadata name ‘SiteLongitude’ and store a float value in Well.longitude (or None if not found), etc. Each metadata not found in well file will store None in the associated attribute of pybacktrack.Well object.

Returns:

Well read from file.

Return type:

pybacktrack.Well

Raises:

ValueError – If lithology_column is not the largest column number (must be last column).

Notes

Each attribute to read (eg, bottom_age, bottom_depth, etc) has a column index to direct which column it should be read from.

If file contains SurfaceAge = <age> in commented (#) lines then the top age of the youngest stratigraphic unit will have that age, otherwise it defaults to 0Ma (present day).

pybacktrack.write_well_file(well, well_filename, other_column_attribute_names=None, well_attributes=None)

Writes a text file with each row representing a stratigraphic unit.

Parameters:

well (pybacktrack.Well) – The well to write.
well_filename (str) – Name of well text file.
other_column_attribute_names (sequence of str) – Names of any extra column attributes to write as column before the lithology(s) column. For example, backstripping will add min_water_depth and max_water_depth attributes (when pybacktrack.backstrip_well() or pybacktrack.backstrip_and_write_well() has been called, which in turn calls this function).
well_attributes (dict, optional) – Attributes in pybacktrack.Well object to write to well file metadata. If specified then must be a dictionary mapping each attribute name to a metadata name. For example, {‘longitude’ : ‘SiteLongitude’, ‘latitude’ : ‘SiteLatitude’} will write well.longitude (if not None) to metadata ‘SiteLongitude’, etc. Not that the attributes must exist in well (but can be set to None).

pybacktrack.write_well_metadata(well_file, well, well_attributes=None)

Writes well metadata to file object well_file.

Parameters:

well_file (file object) – Well file object to write to.
well (pybacktrack.Well) – Well to extract metadata from.
well_attributes (dict, optional) – Attributes in pybacktrack.Well object to write to well file metadata. If specified then must be a dictionary mapping each attribute name to a metadata name. For example, {‘longitude’ : ‘SiteLongitude’, ‘latitude’ : ‘SiteLatitude’} will write well.longitude (if not None) to metadata ‘SiteLongitude’, etc. Not that the attributes must exist in well (but can be set to None).

Compacted well 

Query a well and its stratigraphic layers.

Summary 

pybacktrack.Well is a class containing all stratigraphic units in a well.

pybacktrack.StratigraphicUnit is a class containing data for a stratigraphic unit.

Detail 

class pybacktrack.Well(attributes=None, stratigraphic_units=None)

Class containing all the stratigraphic units in a well sorted by age (from youngest to oldest).

longitude

Longitude of the well location.

Note

This attribute is available provided pybacktrack.backtrack_well() or pybacktrack.backstrip_well() (or any function calling them) have been called.

Type:: float, optional

latitude

Latitude of the well location.

Note

This attribute is available provided pybacktrack.backtrack_well() or pybacktrack.backstrip_well() (or any function calling them) have been called.

Type:: float, optional

stratigraphic_units

List of stratigraphic units in this well sorted by age (from youngest to oldest).

Type:: list of pybacktrack.StratigraphicUnit

__init__(attributes=None, stratigraphic_units=None)

Create a well from optional stratigraphic units.

Parameters:

attributes (dict, optional) – Attributes to store on this well object. If specified then must be a dictionary mapping attribute names to values.
stratigraphic_units (sequence of pybacktrack.StratigraphicUnit, optional) – Sequence of StratigraphicUnit objects. They can be unsorted (by age) but will be added in sorted order.

Raises:

ValueError – If: #. Youngest unit does not have zero depth, or #. adjacent units do not have matching top and bottom ages and depths. …this ensures the units are contiguous in depth from the surface (ie, no gaps).

Notes

Stratigraphic units can also be added using pybacktrack.Well.add_compacted_unit()

add_compacted_unit(top_age, bottom_age, top_depth, bottom_depth, lithology_components, lithologies, other_attributes=None)

Add the next deeper stratigraphic unit.

Units must be added in order of age.

Parameters:

top_age (float) – Age of top of stratigraphic unit (in Ma).
bottom_age (float) – Age of bottom of stratigraphic unit (in Ma).
top_depth (float) – Depth of top of stratigraphic unit (in metres).
bottom_depth (float) – Depth of bottom of stratigraphic unit (in metres).
lithology_components (sequence of tuples (str, float)) – Sequence of tuples (name, fraction) containing a lithology name and its fraction of contribution.
lithologies (dict) – A dictionary mapping lithology names to pybacktrack.Lithology objects.
other_attributes (dict, optional) – A dictionary of attribute name/value pairs to set on stratigraphic unit object (using setattr). For example, backstripping will add the min_water_depth and max_water_depth attributes (when pybacktrack.backstrip_well() or pybacktrack.backstrip_and_write_well() has been called).

Raises:

ValueError – If: #. Youngest unit does not have zero depth, or #. adjacent units do not have matching top and bottom ages and depths. …this ensures the units are contiguous in depth from the surface (ie, no gaps).

decompact(age=None)

Finds decompacted total sediment thickness at ‘age’ (if specified), otherwise at each (top) age in all stratigraphic units.

Returns:: If ‘age’ is specified then returns the decompacted well at that age (or None if ‘age’ is not younger than bottom age of well), otherwise a list of decompacted wells with one per age in same order (and ages) as the well units (youngest to oldest).
Return type:: pybacktrack.DecompactedWell, or list of pybacktrack.DecompactedWell

Notes

Changed in version 1.4: Added the ‘age’ parameter.

class pybacktrack.StratigraphicUnit(top_age, bottom_age, top_depth, bottom_depth, lithology_components, lithologies, other_attributes=None)

Class to hold data for a stratigraphic unit.

top_age

Age of top of stratigraphic unit (in Ma).

Type:: float

bottom_age

Age of bottom of stratigraphic unit (in Ma).

Type:: float

top_depth

Depth of top of stratigraphic unit (in metres).

Type:: float

bottom_depth

Depth of bottom of stratigraphic unit (in metres).

Type:: float

decompacted_top_depth

Fully decompacted depth of top of stratigraphic unit (in metres) as if no portion of any layer had ever been buried (ie, using surface porosities only).

Type:: float

decompacted_bottom_depth

Fully decompacted depth of bottom of stratigraphic unit (in metres) as if no portion of any layer had ever been buried (ie, using surface porosities only).

Type:: float

min_water_depth

Minimum paleo-water depth of stratigraphic unit (in metres).

Note

This attribute is only available when backstripping (not backtracking). For example, it is available if pybacktrack.backstrip_well() or pybacktrack.backstrip_and_write_well() has been called.

Type:: float, optional

max_water_depth

Maximum paleo-water depth of stratigraphic unit (in metres).

Note

This attribute is only available when backstripping (not backtracking). For example, it is available if pybacktrack.backstrip_well() or pybacktrack.backstrip_and_write_well() has been called.

Type:: float, optional

lithology_components

Sequence of tuples (name, fraction) containing a lithology name and its fraction of contribution.

Type:: sequence of tuples (str, float)

__init__(top_age, bottom_age, top_depth, bottom_depth, lithology_components, lithologies, other_attributes=None)

Create a stratigraphic unit from top and bottom age, top and bottom depth and lithology components.

Parameters:

top_age (float) – Age of top of stratigraphic unit (in Ma).
bottom_age (float) – Age of bottom of stratigraphic unit (in Ma).
top_depth (float) – Depth of top of stratigraphic unit (in metres).
bottom_depth (float) – Depth of bottom of stratigraphic unit (in metres).
lithology_components (sequence of tuples (str, float)) – Sequence of tuples (name, fraction) containing a lithology name and its fraction of contribution.
lithologies (dict) – A dictionary mapping lithology names to pybacktrack.Lithology objects.
other_attributes (dict, optional) – A dictionary of attribute name/value pairs to set on stratigraphic unit object (using setattr). For example, backstripping will add the min_water_depth and max_water_depth attributes (when pybacktrack.backstrip_well() or pybacktrack.backstrip_and_write_well() has been called).

calc_decompacted_density(decompacted_thickness, decompacted_depth_to_top)

Calculate average decompacted density when top of this stratigraphic unit is at a decompacted depth.

Parameters:

decompacted_thickness (float) – Decompacted thickness of this stratigraphic unit as returned by pybacktrack.StratigraphicUnit.calc_decompacted_thickness().
decompacted_depth_to_top (float) – Decompacted depth of the top of this stratigraphic unit.

Returns:

Decompacted density.

Return type:

float

calc_decompacted_thickness(decompacted_depth_to_top)

Calculate decompacted thickness when top of this stratigraphic unit is at a decompacted depth.

Parameters:: decompacted_depth_to_top (float) – Decompacted depth of the top of this stratigraphic unit.
Returns:: Decompacted thickness.
Return type:: float

static create_partial_unit(unit, top_age)

Create a new stratigraphic unit equivalent to ‘unit’ but with the top part stripped off according to ‘top_age’.

Essentially sediment deposited from ‘top_age’ to the top age of ‘unit’ is stripped off (assuming a constant sediment deposition rate for ‘unit’). And so ‘top_age’ is expected to be older/earlier than the top age of ‘unit’ (and younger than the bottom age of ‘unit’).

Parameters:: top_age (float) – Top age of new stratigraphic unit.
Raises:: ValueError – If ‘top_age’ is outside the top/bottom age range of ‘unit’.

Notes

This does not partially decompact ‘unit’. It is simply adjusting the top depth of new unit to correspond to its new top age. Then when the returned partial stratigraphic unit is subsequently decompacted it’ll have the correct volume of grains (assuming a constant sediment deposition rate) and hence be decompacted correctly at its new top age.

New in version 1.4.

get_decompacted_sediment_rate()

Return fully decompacted sediment rate.

This is the fully decompacted thickness of this unit divided by its (deposition) time interval.

Returns:: Decompacted sediment rate (in units of metres/Ma).
Return type:: float

Notes

Fully decompacted is equivalent to assuming this unit is at the surface (ie, no units on top of it) and porosity decay within the unit is not considered (in other words the weight of the upper part of the unit does not compact the lower part of the unit).

get_fully_decompacted_thickness()

Get fully decompacted thickness. It is calculated on first call.

Returns:: Fully decompacted thickness.
Return type:: float

Notes

Fully decompacted is equivalent to assuming this unit is at the surface (ie, no units on top of it) and porosity decay within the unit is not considered (in other words the weight of the upper part of the unit does not compact the lower part of the unit).

New in version 1.4.

Decompacted well 

Query decompacted sections at past times.

Summary 

pybacktrack.DecompactedWell is a class containing the decompacted well data at a specific age.

pybacktrack.DecompactedStratigraphicUnit is a class to hold data for a decompacted stratigraphic unit.

Detail 

class pybacktrack.DecompactedWell(surface_unit)

Class containing the decompacted well data at a specific age.

surface_unit

Top stratigraphic unit in this decompacted well.

Type:: pybacktrack.StratigraphicUnit

total_compacted_thickness

Total compacted thickness of all stratigraphic units.

Type:: float

total_decompacted_thickness

Total decompacted thickness of all decompacted stratigraphic units.

Type:: float

tectonic_subsidence

Tectonic subsidence (in metres).

Note

This attribute is only available when backtracking (not backstripping). For example, it is available if pybacktrack.backtrack_well() or pybacktrack.backtrack_and_write_well() has been called.

Type:: float, optional

min_water_depth

Minimum water depth (in metres).

Note

This attribute is only available when backstripping (not backtracking). For example, it is available if pybacktrack.backstrip_well() or pybacktrack.backstrip_and_write_well() has been called.

New in version 1.2.

Type:: float, optional

max_water_depth

Maximum water depth (in metres).

Note

This attribute is only available when backstripping (not backtracking). For example, it is available if pybacktrack.backstrip_well() or pybacktrack.backstrip_and_write_well() has been called.

New in version 1.2.

Type:: float, optional

sea_level

Sea level in metres (positive for a sea-level rise and negative for a sea-level fall, relative to present day).

Note

This attribute is only available if a sea model was specified when backtracking or backstripping (for example, if sea_level_model was specified in pybacktrack.backtrack_well() or pybacktrack.backstrip_well()).

Converting oceanic age to depth 

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

Summary 

pybacktrack.convert_age_to_depth() converts a single ocean basin age to basement depth.

pybacktrack.convert_age_to_depth_files() converts a sequence of ages (read from an input file) to depths (and writes both ages and depths to an output file).

Detail 

pybacktrack.convert_age_to_depth(age, model=pybacktrack.AGE_TO_DEPTH_DEFAULT_MODEL)

Convert ocean basin age to basement depth using a specified age/depth model.

Parameters:

age (float) – The age in Ma.
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 basement depth. It can be one of the enumerated values, or a callable function accepting a single non-negative age parameter and returning depth (in metres).

Returns:

Depth (in metres) as a positive number.

Return type:

float

Raises:

ValueError – If age is negative.
TypeError – If model is not a recognised model, or a function accepting a single parameter.

pybacktrack.convert_age_to_depth_files(input_filename, output_filename, model=pybacktrack.AGE_TO_DEPTH_DEFAULT_MODEL, age_column_index=0, reverse_output_columns=False)

Converts age to depth by reading age rows from input file and writing rows containing both age and depth to output file.

Parameters:

input_filename (string) – Name of input text file containing the age values. A single age value is obtained from each row by indexing the age_column_index column (zero-based index).
output_filename (string) – Name of output text file containing age and depth values. Each row of output file contains an age value and its associated depth value (with order depending on reverse_output_columns).
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 basement depth. It can be one of the enumerated values, or a callable function accepting a single non-negative age parameter and returning depth (in metres).
age_column_index (int, optional) – Determines which column of input file to read age values from.
reverse_output_columns (bool, optional) – Determines order of age and depth columns in output file. If True then output depth age, otherwise output age depth.

Raises:

ValueError – If cannot read age value, as a floating-point number, from input file at column index age_column_index.

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.

Summary 

pybacktrack.estimate_rift_beta() estimates the stretching factor (beta).

pybacktrack.total_rift_subsidence() calcultaes the total subsidence as syn-rift plus post-rift.

pybacktrack.syn_rift_subsidence() calculates the initial subsidence due to continental stretching.

pybacktrack.post_rift_subsidence() calculates the thermal subsidence as a function of time.

Detail 

pybacktrack.estimate_rift_beta(present_day_subsidence, present_day_crustal_thickness, rift_end_time)

Estimate the stretching factor (beta).

Parameters:

present_day_subsidence (float) – The (sediment-free) subsidence at present day (in metres).
present_day_crustal_thickness (float) – The crustal thickness at present day (in metres).
rift_end_time (float) – The time that rifting ended (in My).

Returns:

beta (float) – The estimated stretching factor.
residual (float) – The inaccuracy between present day subsidence and subsidence calculated using the estimated stretching factor (beta).

Notes

Stretching factor (beta) is calculated by minimizing difference between actual subsidence and subsidence calculated from beta (both at present day).

pybacktrack.total_rift_subsidence(beta, pre_rift_crustal_thickness, time, rift_end_time, rift_start_time=None)

Total subsidence as syn-rift plus post-rift.

Parameters:

beta (float) – Stretching factor.
pre_rift_crustal_thickness (float) – Initial crustal thickness prior to rifting (in metres).
time (float) – Time to calculate subsidence (in My).
rift_end_time (float) – Time at which rifting ended (in My).
rift_start_time (float, optional) – Time at which rifting started (in My). If not specified then assumes initial (non-thermal) subsidence happens instantaneously at rift_end_time. Defaults to rift_end_time.

Returns:

Total subsidence (in metres).

Return type:

float

pybacktrack.syn_rift_subsidence(beta, pre_rift_crustal_thickness)

Initial subsidence (in metres) due to continental stretching.

Parameters:

beta (float) – Stretching factor.
pre_rift_crustal_thickness (float) – Initial crustal thickness prior to rifting (in metres).

Returns:

Initial subsidence (in metres) due to continental stretching.

Return type:

float

pybacktrack.post_rift_subsidence(beta, time)

Thermal subsidence (in metres) as a function of time.

Parameters:

beta (float) – Stretching factor.
time (float) – The amount of time that has passed after rifting/stretching has ended.

Returns:

Thermal subsidence (in metres).

Return type:

float

Dynamic topography 

Summary 

pybacktrack.DynamicTopography is a class that reconstructs point location(s) and samples (and interpolates) time-dependent dynamic topography mantle frame grids.

pybacktrack.InterpolateDynamicTopography is a class that just samples and interpolates time-dependent dynamic topography mantle frame grid files.

Detail 

class pybacktrack.DynamicTopography(grid_list_filename, static_polygon_filename, rotation_filenames, longitude, latitude, age=None)

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

longitude

Longitude of the point location, or list of longitudes (if multiple point locations).

Type:: float or list of float

latitude

Latitude of the point location, or list of latitudes (if multiple point locations).

Type:: float or list of float

age

The age of the crust that the point location is on, or list of ages (if multiple point locations).

Note

If no age(s) was supplied then the age(s) of the static polygon(s) containing location(s) is used (or zero when no polygon contains a location).

Type:: float or list of float

Notes

Changed in version 1.4: Can have multiple point locations (version 1.3 allowed only one location). So longitude, latitude and age can all have either a single value or multiple values (same number for each).

__init__(grid_list_filename, static_polygon_filename, rotation_filenames, longitude, latitude, age=None)

Load dynamic topography grid filenames and associated ages from grid list file ‘grid_list_filename’.

Parameters:

grid_list_filename (str) – The filename of the grid list file.
static_polygon_filename (str) – The filename of the static polygons file.
rotation_filenames (list of str) – The list of rotation filenames.
longitude (float or list of float) – Longitude of the point location, or list of longitudes (if multiple point locations).
latitude (float or list of float) – Latitude of the point location, or list of latitudes (if multiple point locations).
age (float or list of float, optional) – The age of the crust that the point location is on, or list of ages (if multiple point locations). If not specified then the appearance age(s) of the static polygon(s) containing the point(s) is used.

Raises:

ValueError – If any age is negative (if specified).
ValueError – If longitude and latitude (and age if specified) are all not a single value or all not a sequence (of same length).
ValueError – If grid_list_filename does not contain a grid at present day, or grid_list_filename contains fewer than two grids, or not all rows in grid_list_filename contain a grid filename followed by an age, or there are two ages in grid_list_filename with same age.

Notes

Each dynamic topography grid should be in the mantle reference frame (not plate reference frame) and should have global coverage (such that no sample location will return NaN).

Each row in the grid list file should contain two columns. First column containing filename (relative to directory of list file) of a dynamic topography grid at a particular time. Second column containing associated time (in Ma).

Each present day location is also assigned a plate ID using the static polygons, and the rotations are used to reconstruct each location when sampling the grids at a reconstructed time.

Changed in version 1.4: The following changes were made:

Added ability to specify a list of point locations (as an alternative to specifying a single location).
Raises ValueError if there’s no present day grid or if any age is negative.

static create_from_bundled_model(dynamic_topography_model_name, longitude, latitude, age=None)

Create a DynamicTopography instance from a bundled dynamic topography model name.

Parameters:

dynamic_topography_model_name (str) – 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.
longitude (float or list of float) – Longitude of the point location, or list of longitudes (if multiple point locations).
latitude (float or list of float) – Latitude of the point location, or list of latitudes (if multiple point locations).
age (float or list of float, optional) – The age of the crust that the point location is on, or list of ages (if multiple point locations). If not specified then the appearance age(s) of the static polygon(s) containing the point(s) is used.

Returns:

The bundled dynamic topography model.

Return type:

pybacktrack.DynamicTopography

Raises:

ValueError – If dynamic_topography_model_name is not the name of a bundled dynamic topography model.

Notes

New in version 1.2.

Changed in version 1.4: Added ability to specify a list of point locations (as an alternative to specifying a single location).

static create_from_model_or_bundled_model_name(dynamic_topography_model_or_bundled_model_name, longitude, latitude, age=None)

Create a DynamicTopography instance from a user-provided model or from a bundled model.

Parameters:

dynamic_topography_model_or_bundled_model_name (str or 3-tuple (str, str, list of str)) – Either the name of a bundled dynamic topography model (see pybacktrack.DynamicTopography.create_from_bundled_model()), or a user-provided model specified as a 3-tuple (filename of the grid list file, filename of the static polygons file, list of rotation filenames) (see first three parameters of pybacktrack.DynamicTopography.__init__()).
longitude (float or list of float) – Longitude of the point location, or list of longitudes (if multiple point locations).
latitude (float or list of float) – Latitude of the point location, or list of latitudes (if multiple point locations).
age (float or list of float, optional) – The age of the crust that the point location is on, or list of ages (if multiple point locations). If not specified then the appearance age(s) of the static polygon(s) containing the point(s) is used.

Returns:

The dynamic topography model loaded from a user-provided model or from a bundled model.

Return type:

pybacktrack.DynamicTopography

Notes

New in version 1.4.

static get_bundled_model(dynamic_topography_model_name)

Get the bundled model files for the specified dynamic topography model name.

Parameters:

dynamic_topography_model_name (str) – 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.

Returns:

The bundled dynamic topography model files (see first three parameters of pybacktrack.DynamicTopography.__init__()). This consists of a 3-tuple of:

Filename of the grid list file.
Filename of the static polygons file.
List of rotation filenames.

Return type:

3-tuple of (grid_list_filename, static_polygon_filename, rotation_filenames)

Raises:

ValueError – If dynamic_topography_model_name is not the name of a bundled dynamic topography model.

Notes

The returned model information is obtained from pybacktrack.BUNDLE_DYNAMIC_TOPOGRAPHY_MODELS (see Bundle data).

New in version 1.5.

sample(time, fallback=True)

Samples and interpolates the two time-dependent dynamic topography grids surrounding time at point location(s) reconstructed to time, but optionally falls back to a non-optimal sampling if necessary (depending on time)

Parameters:

time (float) – Time to sample dynamic topography.
fallback (bool) – Whether to fall back to a non-optimal sampling if neccessary (see notes below). Defaults to True.

Returns:

The sampled dynamic topography value or list of values. If constructed with a single location then returns a single value, otherwise returns a list of values (one per location).

When fallback is True then float('NaN`) will never be returned (see notes below). When fallback is False then float('NaN`) will be returned:

for all points when the oldest dynamic topography grid is younger than time, or
for each point location whose age is younger than time (ie, has not yet appeared).

Return type:

float or list of float

Notes

Each point location is first reconstructed to time before sampling the two grids surrounding time at the reconstructed location and interpolating between them.

For each point location, if time is older than its appearance age then it is still reconstructed to time when fallback is True, otherwise float('NaN`) is returned (for that location) when fallback is False.

If time is older than the oldest grid then the oldest grid is sampled when fallback is True, otherwise float('NaN`) is returned for all locations when fallback is False.

Changed in version 1.2: Previously this method was called sample_interpolated and did not fall back to non-optimal sampling when necessary.

Changed in version 1.4: The following changes were made:

Merged sample, sample_interpolated and sample_oldest methods into one method (this method).
Added fallback parameter (where False behaves like removed sample_interpolated method).
Added ability to specify a list of point locations (as an alternative to specifying a single location).
Changed how grids are interpolated:
- Version 1.3 (and earlier) reconstructed each location to two times (of the two grids surrounding time) to get two reconstructed locations. Then each reconstructed location sampled its respective grid (ie, each grid was sampled at a different reconstructed location). Then these two samples were interpolated (based on time).
- Version 1.4 reconstructs each location to the single time to get a single reconstructed location. Then that single reconstructed location samples both grids surrounding time (ie, each grid is sampled at the same reconstructed location). Then these two samples are interpolated (based on time).
…note that there is no difference at grid times (only between grid times).

class pybacktrack.InterpolateDynamicTopography(grid_list_filename)

Class that just samples and interpolates time-dependent dynamic topography mantle frame grid files.

This class accepts locations that have already been reconstructed whereas pybacktrack.DynamicTopography accepts present day locations and reconstructs them prior to sampling the dynamic topography grids.

Notes

New in version 1.4.

__init__(grid_list_filename)

Load dynamic topography grid filenames and associated ages from grid list file ‘grid_list_filename’.

Parameters:: grid_list_filename (str) – The filename of the grid list file.
Raises:: ValueError – If grid_list_filename does not contain a grid at present day, or grid_list_filename contains fewer than two grids, or not all rows in grid_list_filename contain a grid filename followed by an age, or there are two ages in grid_list_filename with same age.

Notes

Each dynamic topography grid should be in the mantle reference frame (not plate reference frame) and should have global coverage (such that no sample location will return NaN).

Each row in the grid list file should contain two columns. First column containing filename (relative to directory of list file) of a dynamic topography grid at a particular time. Second column containing associated time (in Ma).

New in version 1.4.

static create_from_bundled_model(dynamic_topography_model_name)

Create a InterpolateDynamicTopography instance from a bundled dynamic topography model name.

Parameters:: dynamic_topography_model_name (str) – 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.
Returns:: The bundled dynamic topography model.
Return type:: pybacktrack.InterpolateDynamicTopography
Raises:: ValueError – If dynamic_topography_model_name is not the name of a bundled dynamic topography model.

Notes

New in version 1.4.

static create_from_model_or_bundled_model_name(dynamic_topography_model_or_bundled_model_name)

Create a InterpolateDynamicTopography instance from a user-provided model or from a bundled model.

Parameters:: dynamic_topography_model_or_bundled_model_name (str) – Either the name of a bundled dynamic topography model (see pybacktrack.InterpolateDynamicTopography.create_from_bundled_model()), or a user-provided model specified as the filename of the grid list file (see parameter of pybacktrack.InterpolateDynamicTopography.__init__()).
Raises:: ValueError – If dynamic_topography_model_or_bundled_model_name is not the name of a bundled dynamic topography model or the filename of an existing grid list file.
Returns:: The dynamic topography model loaded from a user-provided model or from a bundled model.
Return type:: pybacktrack.InterpolateDynamicTopography

Notes

New in version 1.4.

sample(time, locations, fallback_to_oldest=True)

Samples and interpolates the two time-dependent dynamic topography grids surrounding time at the specified point location(s), but optionally falls back to sampling oldest grid (if time is too old).

Parameters:

time (float) – Time to sample dynamic topography.
locations (sequence of 2-tuple (float, float)) – A sequence of (longitude, latitude) point locations.
fallback_to_oldest (bool) – Whether to fall back to sampling oldest grid (if time is too old) rather than interpolating the two grids surrounding time. Defaults to True.

Returns:

The sampled dynamic topography values (one per location).

When time is older than the oldest dynamic topography grid:

if fallback_to_oldest is True then the oldest dynamic topography grid is sampled, or
if fallback_to_oldest is False then None is returned.

Return type:

list of float, or None

Notes

The point location(s) sample the two grids with ages bounding time and then interpolate between them.

However if time is older than the oldest grid then the oldest grid is sampled (if fallback_to_oldest is True).

All returned sample values are non-NaN.

New in version 1.4.

Average sea level variations 

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

Summary 

pybacktrack.SeaLevel is a class that calculates integrated sea levels (relative to present day) over a time period.

Detail 

class pybacktrack.SeaLevel(sea_level_filename)

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

__init__(sea_level_filename)

Load sea level curve (linear segments) from file.

Parameters:: sea_level_filename (str) – Text file with first column containing ages (Ma) and a corresponding second column of sea levels (m).

static create_from_bundled_model(sea_level_model_name)

Create a SeaLevel instance from a bundled sea level model name.

Parameters:: sea_level_model_name (string) – Name of a bundled sea level model. Bundled sea level models include Haq87_SealevelCurve and Haq87_SealevelCurve_Longterm.
Returns:: The bundled sea level model.
Return type:: pybacktrack.SeaLevel
Raises:: ValueError – If sea_level_model_name is not the name of a bundled sea level model.

Notes

New in version 1.2.

static create_from_model_or_bundled_model_name(sea_level_model_or_bundled_model_name)

Create a SeaLevel instance from a user-provided model or from a bundled model.

Parameters:: sea_level_model_or_bundled_model_name (string) – Either a user-provided model specified as a text filename containing sea level curve (see pybacktrack.SeaLevel.__init__()), or name of a bundled model (see pybacktrack.SeaLevel.create_from_bundled_model()), .
Returns:: The sea level model loaded from a user-provided model or from a bundled model.
Return type:: pybacktrack.SeaLevel

Notes

New in version 1.4.

get_average_level(begin_time, end_time)

Return the average sea level over the specified time period.

Parameters:

begin_time (float) – The begin time (in Ma). Should be larger than end_time.
end_time (float) – The end time (in Ma). Should be smaller than begin_time.

Returns:

Average sea level (in metres).

Return type:

float

Notes

The average sea level is obtained by integrating sea level curve over the specified time period and then dividing by time period.

Converting stratigraphic depth to age 

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

Summary 

pybacktrack.convert_stratigraphic_depth_to_age() converts a single stratigraphic depth to an age.

pybacktrack.convert_stratigraphic_depth_to_age_files() converts a sequence of stratigraphic depths (read from an input file) to ages (and writes both ages and depths, and any lithologies in the input file, to an output file).

Detail 

pybacktrack.convert_stratigraphic_depth_to_age(age, depth_to_age_model)

Convert stratigraphic depth to age using a specified depth-to-age model.

Parameters:

depth (float) – The stratigraphic depth in metres.
depth_to_age_model (function) – The model to use when converting stratigraphic depth to age. A callable function accepting a single non-negative depth parameter (in metres) and returning age (in Ma).

Returns:

Age (in Ma) as a positive number.

Return type:

float

Raises:

ValueError – If depth is negative.
TypeError – If depth_to_age_model is not a function accepting a single parameter.

Notes

New in version 1.5.

pybacktrack.convert_stratigraphic_depth_to_age_files(input_filename, output_filename, depth_to_age_model, reverse_output_columns=False)

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.

Parameters:

input_filename (string) – Name of input text file containing the depth values. A single depth value is obtained from each row by indexing the first column.
output_filename (string) – Name of output text file containing age and depth values. Each row of output file contains an age value and its associated depth value (with order depending on reverse_output_columns).
depth_to_age_model (function) – The model to use when converting stratigraphic depth to age. A callable function accepting a single non-negative depth parameter (in metres), and returning age (in Ma) or None to exclude from output.
reverse_output_columns (bool, optional) – Determines order of age and depth columns in output file. If True then output depth age, otherwise output age depth.

Raises:

ValueError – If cannot read depth value, as a floating-point number, from input file in the first column.
ValueError – If stratigraphic depths are not monotonically increasing.

Notes

New in version 1.5.

Utilities 

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

Summary 

pybacktrack.read_interpolate_function() reads x and y columns from a curve file and returns a function y(x) that linearly interpolates.

pybacktrack.interpolate_file() interpolates a curve function at x positions, read from input file, and stores both x and interpolated y values to output file.

Detail 

pybacktrack.read_interpolate_function(curve_filename, x_column_index=0, y_column_index=1, out_of_bounds='clamp')

Read x and y columns from a curve file and return a function y(x) that linearly interpolates.

Parameters:

curve_filename (string) – Name of input text file containing the x and y data from which to create the returned curve function.
x_column_index (int, optional) – Determines which column of input text file to read x values from.
y_column_index (int, optional) – Determines which column of input text file to read y values from.
out_of_bounds (string, optional) –
Determines the y value returned by curve function when x is outside the range of x values in curve file. This can be:
- clamp to return the boundary y value, or
- exclude to return None (eg, to indicate that there’s no y value), or
- extrapolate to return an extrapolated value.

Returns:

curve_function (function) – A callable function y=f(x) accepting a single x argument, and returning a y value or None (if no y value).
x_column (list of float) – The x values read from the curve file.
y_column (list of float) – The y values read from the curve file.

Raises:

ValueError – If cannot read x and y columns, as floating-point numbers, from the curve file at column indices x_column_index and y_column_index.
ValueError – If curve file contains no data.
ValueError – If out_of_bounds is not clamp, exclude or extrapolate.

Notes

The returned x and y columns are useful if integrating the curve function with scipy.integrate.quad (since can pass x column to its points argument and len(x) to its limit).

Changed in version 1.5: Added out_of_bounds argument. If out_of_bounds is exclude then returned curve function will return None for any input x outside the range of x values in curve file.

pybacktrack.interpolate_file(curve_function, input_filename, output_filename, input_x_column_index=0, reverse_output_columns=False)

Interpolate curve_function at x positions, read from input file, and store both x and interpolated y values to output file.

Parameters:

curve_function (function) – A callable function y=f(x) accepting a single x argument and returning a y value (or None to exclude from output).
input_filename (string) – Name of input text file containing the x positions at which to sample curve_function. A single x value is obtained from each row by indexing the input_x_column_index column (zero-based index).
output_filename (string) – Name of output text file containing x and y values. Each row of output file contains an x value and its associated y value (with order depending on reverse_output_columns).
input_x_column_index (int, optional) – Determines which column of input file to read x values from.
reverse_output_columns (bool, optional) – Determines order of x and y columns in output file. If True then output y x, otherwise output x y.

Raises:

ValueError – If cannot read an x value, as a floating-point number, from input file at column index input_x_column_index.

Notes

Changed in version 1.5: curve_function can return None, in which case there is no output row for the input x.

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 Haq87_SealevelCurve and Haq87_SealevelCurve_Longterm.

pybacktrack.BUNDLE_RECONSTRUCTION_ROTATION_FILENAMES

Rotation files of the reconstruction model used to reconstruct sediment-deposited crust for paleobathymetry gridding.

pybacktrack.BUNDLE_RECONSTRUCTION_STATIC_POLYGON_FILENAME

Static polygon file of the reconstruction model used to assign plate IDs to points on sediment-deposited crust 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_COMPACTED_DEPTH
pybacktrack.BACKTRACK_COLUMN_COMPACTED_THICKNESS
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_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_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_COMPACTED_THICKNESS
pybacktrack.BACKSTRIP_COLUMN_LITHOLOGY
pybacktrack.BACKSTRIP_COLUMN_COMPACTED_DEPTH

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.