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.

Detail

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 and KM16.

    • 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 and KM16.

    • 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).
Returns:
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, 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) – The oldest time (in Ma) that output is generated back to (from present day). Value must not be negative.
  • 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 and KM16.

    • 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.
  • 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 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).
  • 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 ‘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 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.

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, 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) – The oldest time (in Ma) that output is generated back to (from present day). Value must not be negative.
  • 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 and KM16.

    • 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.
  • 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 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).
  • 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 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.

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:

  1. name
  2. density
  3. surface_porosity
  4. 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:

  1. name
  2. density
  3. surface_porosity
  4. 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

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
__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:

  1. Youngest unit does not have zero depth, or
  2. 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:

  1. Youngest unit does not have zero depth, or
  2. 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:
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()).

Type:float, optional
dynamic_topography

Dynamic topography elevation relative to present day (in metres).

Note

This attribute contains dynamic topography relative to present day.

Note

This attribute is only available when backtracking (not backstripping) and if a dynamic topography model was specified. For example, it is available if dynamic_topography_model was specified in pybacktrack.backtrack_well() or pybacktrack.backtrack_and_write_well()

Note

Dynamic topography is elevation which is opposite to tectonic subsidence in that an increase in dynamic topography results in a decrease in tectonic subsidence.

New in version 1.2.

Type:float, optional
decompacted_stratigraphic_units

Decompacted stratigraphic units. They are sorted from top to bottom (in depth) which is the same as youngest to oldest.

Type:list of pybacktrack.DecompactedStratigraphicUnit
__init__(surface_unit)

Create a decompacted well whose top stratigraphic unit is surface_unit.

Parameters:surface_unit (pybacktrack.StratigraphicUnit) – Top stratigraphic unit in this decompacted well.

Notes

You still need to add the decompacted units with pybacktrack.DecompactedWell.add_decompacted_unit().

add_decompacted_unit(stratigraphic_unit, decompacted_thickness, decompacted_density)

Add a decompacted stratigraphic unit.

Parameters:
  • stratigraphic_unit (pybacktrack.StratigraphicUnit) – Stratigraphic unit referenced by decompacted stratigraphic unit.
  • decompacted_thickness (float) – Decompacted thickness.
  • decompacted_density (float) – Decompacted density.

Notes

Stratigraphic units should be decompacted from top of well column to bottom.

get_age()
Returns:Age of the surface of the decompacted column of the well.
Return type:float
get_average_decompacted_density()
Returns:Average density of the entire decompacted column of the well.
Return type:float
get_dynamic_topography(default_dynamic_topography=0.0)

Returns the dynamic topography elevation relative to present day, or default_dynamic_topography if a dynamic topography model was not specified (when backtracking).

Returns:Dynamic topography elevation relative to present day.
Return type:float

Notes

Note

Returns dynamic topography relative to present day.

Returns the dynamic_topography attribute if a dynamic_topography_model was specified to pybacktrack.backtrack_well() or pybacktrack.backtrack_and_write_well(), otherwise returns default_dynamic_topography.

Note

Dynamic topography is elevation which is opposite to tectonic subsidence in that an increase in dynamic topography results in a decrease in tectonic subsidence.

Note

default_dynamic_topography can be set to None

New in version 1.2.

get_min_max_tectonic_subsidence()

Returns the minimum and maximum tectonic subsidence obtained directly from subsidence model (if backtracking) or indirectly from minimum and maximum water depth and sea level (if backstripping).

Returns:
  • min_tectonic_subsidence (float) – Minimum tectonic subsidence (unloaded water depth) of this decompacted well.
  • max_tectonic_subsidence (float) – Maximum tectonic subsidence (unloaded water depth) of this decompacted well.

Notes

When backtracking, the tectonic subsidence is obtained directly from the tectonic_subsidence attribute. In this case the minimum and maximum tectonic subsidence are the same.

When backstripping, the tectonic subsidence is obtained indirectly from the min_water_depth and max_water_depth attributes and optional sea_level attribute (if a sea level model was specified).

New in version 1.2.

get_min_max_tectonic_subsidence_from_water_depth(min_water_depth, max_water_depth, sea_level=None)

Returns the minimum and maximum tectonic subsidence obtained from specified minimum and maximum water depths (and optional sea level).

Parameters:
  • min_water_depth (float) – Minimum water depth.
  • max_water_depth (float) – Maximum water depth.
  • sea_level (float, optional) – Sea level relative to present day (positive to sea-level rise and negative for sea-level fall).
Returns:

  • min_tectonic_subsidence (float) – Minimum tectonic subsidence (unloaded water depth) of this decompacted well from its minimum water depth.
  • max_tectonic_subsidence (float) – Maximum tectonic subsidence (unloaded water depth) of this decompacted well from its maximum water depth.

Notes

Optional sea level fluctuation is included if specified.

get_min_max_water_depth()

Returns the minimum and maximum water depth obtained directly from minimum and maximum water depth (if backstripping) or indirectly from tectonic subsidence model and sea level (if backtracking).

Returns:
  • min_water_depth (float) – Minimum water depth of this decompacted well.
  • max_water_depth (float) – Maximum water depth of this decompacted well.

Notes

When backstripping, the minimum and maximum water depths are obtained directly from the min_water_depth and max_water_depth attributes.

When backtracking, the water depth is obtained indirectly from the tectonic_subsidence attribute and optional sea_level attribute (if a sea level model was specified). In this case the minimum and maximum water depths are the same.

New in version 1.2.

get_sea_level(default_sea_level=0.0)

Returns the sea level relative to present day, or default_sea_level if a sea level model was not specified (when either backtracking or backstripping).

Returns:Sea level relative to present day (positive to sea-level rise and negative for sea-level fall).
Return type:float

Notes

Returns the sea_level attribute if a sea_level_model was specified to pybacktrack.backtrack_well() or pybacktrack.backstrip_well(), otherwise returns default_sea_level.

Note

default_sea_level can be set to None

New in version 1.2.

get_sediment_isostatic_correction()
Returns:Isostatic correction of this decompacted well.
Return type:float

Notes

The returned correction can be added to a known water depth to obtain the deeper isostatically compensated, sediment-free water depth (tectonic subsidence). Or the correction could be subtracted from a known tectonic subsidence (unloaded water depth) to get the depth at sediment/water interface.

get_tectonic_subsidence()

Returns the tectonic subsidence obtained directly from subsidence model (if backtracking) or indirectly from average of minimum and maximum water depth and sea level (if backstripping).

Returns:Tectonic subsidence (unloaded water depth) of this decompacted well.
Return type:float

Notes

When backtracking, the tectonic subsidence is obtained directly from the tectonic_subsidence attribute.

When backstripping, the tectonic subsidence is obtained indirectly from the min_water_depth and max_water_depth attributes and optional sea_level attribute (if a sea level model was specified).

New in version 1.2.

get_water_depth()

Returns the water depth obtained directly from average of minimum and maximum water depth (if backstripping) or indirectly from tectonic subsidence model and sea level (if backtracking).

Returns:Water depth of this decompacted well.
Return type:float

Notes

When backstripping, the water depth is obtained directly as an average of the min_water_depth and max_water_depth attributes.

When backtracking, the water depth is obtained indirectly from the tectonic_subsidence attribute and optional sea_level attribute (if a sea level model was specified).

New in version 1.2.

get_water_depth_from_tectonic_subsidence(tectonic_subsidence, sea_level=None)

Returns the water depth of this decompacted well from the specified tectonic subsidence (and optional sea level).

Parameters:
  • tectonic_subsidence (float) – Tectonic subsidence.
  • sea_level (float, optional) – Sea level relative to present day (positive to sea-level rise and negative for sea-level fall).
Returns:

Water depth of this decompacted well from its tectonic subsidence (unloaded water depth).

Return type:

float

Notes

Optional sea level fluctuation (relative to present day) is included if specified.

class pybacktrack.DecompactedStratigraphicUnit(stratigraphic_unit, decompacted_thickness, decompacted_density)

Class to hold data for a decompacted stratigraphic unit (decompacted at a specific age).

stratigraphic_unit

Stratigraphic unit referenced by this decompacted stratigraphic unit.

Type:pybacktrack.StratigraphicUnit
decompacted_thickness

Decompacted thickness.

Type:float
decompacted_density

Decompacted density.

Type:float
__init__(stratigraphic_unit, decompacted_thickness, decompacted_density)

Create a decompacted stratigraphic unit from a stratigraphic unit, decompacted thickness and decompacted density.

Parameters:
  • stratigraphic_unit (pybacktrack.StratigraphicUnit) – Stratigraphic unit referenced by this decompacted stratigraphic unit.
  • decompacted_thickness (float) – Decompacted thickness.
  • decompacted_density (float) – Decompacted density.

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 and KM16.
  • 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.

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 and KM16.
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.

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)

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.
Returns:

  • curve_function (function) – A callable function y=f(x) accepting a single x argument and returning a 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.

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).

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.
  • 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.

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:

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 and KM16.

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.
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.
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.