pybacktrack.backtrack_well

pybacktrack.backtrack_well(well_filename, times=None, *, 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, output_rift_stretching_factor=False, rotation_filenames=pybacktrack.BUNDLE_RECONSTRUCTION_ROTATION_FILENAMES, static_polygon_filename=pybacktrack.BUNDLE_RECONSTRUCTION_STATIC_POLYGON_FILENAME, anchor_plate_id=0, 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.
times (list of float, optional) – A list of times to decompact sediment. If specified then a pybacktrack.DecompactedWell is returned for each listed time. And it’s OK to specify times that are outside the period of sediment deposition recorded in the drill site (eg, older than the drill site’s bottom age or younger than its surface age). Defaults to the ages of the top of each stratigraphic unit in the well (in which case a pybacktrack.DecompactedWell is returned for each top age).
lithology_filenames (list of string, optional) – One or more text files containing lithologies.
age_grid_filename (string, optional) – Age grid filename. Used to obtain age of seafloor at well location. Can be explicitly set to None if well site is known to be on continental crust (and hence age grid should be ignored). Note that this is different than not specifying a filename (since that will use the default bundled age grid).
topography_filename (string, optional) – Topography filename. Used to obtain water depth at well location.
total_sediment_thickness_filename (string, optional) – Total sediment thickness filename. Used to obtain total sediment thickness at well location. Can be explicitly set to None if well site is known to be drilled to basement depth (and hence total sediment thickness grid should be ignored). Note that this is different than not specifying a filename (since that will use the default bundled total sediment thickness grid).
crustal_thickness_filename (string, optional) – Crustal thickness filename. Used to obtain crustal thickness at well location.
dynamic_topography_model (string or tuple, optional) –
Represents a time-dependent dynamic topography raster grid (in mantle frame).

Can be either:
- A string containing the name of a bundled dynamic topography model.
  
  Choices include terra, M1, M2, M3, M4, M5, M6, M7, ngrand, s20rts, smean, AY18, KM16, D10_gmcm9 and gld428.
- A tuple containing the three elements (dynamic topography list filename, static polygon filename, rotation filenames).
  
  The first tuple element is the filename of file containing list of dynamic topography grids (and associated times). Each row in this list file should contain two columns. First column containing filename (relative to list file) of a dynamic topography grid at a particular time. Second column containing associated time (in Ma). The second tuple element is the filename of file containing static polygons associated with dynamic topography model. This is used to assign plate ID to well location so it can be reconstructed. The third tuple element is the filename of the rotation file associated with model. Only the rotation file for static continents/oceans is needed (ie, deformation rotations not needed).
sea_level_model (string, optional) – Used to obtain sea levels relative to present day. Can be either the name of a bundled sea level model, or a sea level filename. Bundled sea level models include Miller2024_SealevelCurve, Haq2024_Hybrid_SealevelCurve, Haq2024_Hybrid_SealevelCurve_Longterm, 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 (or value in builtin rift start/end grids if not provided in well file).
output_rift_stretching_factor (bool, optional) – Whether to output the rift stretching (beta) factor. This is the optimal stretching factor at the well location if it is on submerged continental crust (not just the areas that are rifting), otherwise None. Defaults to False (not output).
rotation_filenames (list of string, optional) – List of filenames containing rotation features (to reconstruct the well location). 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 a plate ID to the well location). 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.
anchor_plate_id (int, optional) – The anchor plate id used when reconstructing the well location. Defaults to zero.
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:

well (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.
decompacted_wells (list of pybacktrack.DecompactedWell) – The decompacted wells associated with the well. If times is specified, then there is one decompacted well for each listed time (in the same order as the listed times). Otherwise there is one decompacted well for each stratigraphic unit (at its top age) in the same order as the units (youngest to oldest).
rift_stretching_factor (float or None) – Only provided when output_rift_stretching_factor is True. Optimal stretching (beta) factor at well location if it is on submerged continental crust (not just the areas that are rifting), otherwise None. Note that if output_rift_stretching_factor is False then nothing is returned here (not even None).

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.

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.

Changed in version 1.5: The following changes were made:

Added optional times argument to explicitly specify when to decompact sediment.
Added optional rotation_filenames, static_polygon_filename and anchor_plate_id arguments for reconstructing the present day well location through time (as new DecompactedWell.paleo_longitude and DecompactedWell.paleo_latitude attributes).
Added optional output_rift_stretching_factor argument (and corresponding optional rift_stretching_factor return value).
Some arguments (after *) are now keyword-only (ie, can no longer be specified as positional arguments).
Now returns tuple (well, decompacted_wells, and optionally rift_stretching_factor). Previously returned nothing.