pybacktrack.backtrack_and_write_well

pybacktrack.backtrack_and_write_well(decompacted_output_filename, 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, 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 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.

• times (list of float, optional) – A list of times to decompact sediment. If specified then a pybacktrack.DecompactedWell is returned (and a row written to text file) 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 there is a decompacted well/row 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. Currently only used for oceanic floor (ie, well location inside age grid) it is not used if well is on continental crust (passive margin).

  Can be either:

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

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

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

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

• sea_level_model (string, optional) – Used to obtain sea levels relative to present day. Can be either the name of a bundled sea level model, or a sea level filename. Bundled sea level models include 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.

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

  • pybacktrack.BACKTRACK_COLUMN_PALEO_LATITUDE

  • pybacktrack.BACKTRACK_COLUMN_COMPACTED_THICKNESS

  • pybacktrack.BACKTRACK_COLUMN_COMPACTED_DEPTH

  • pybacktrack.BACKTRACK_COLUMN_COMPACTED_DENSITY

  • pybacktrack.BACKTRACK_COLUMN_DECOMPACTED_THICKNESS

  • pybacktrack.BACKTRACK_COLUMN_DECOMPACTED_DENSITY

  • pybacktrack.BACKTRACK_COLUMN_DECOMPACTED_SEDIMENT_RATE

  • pybacktrack.BACKTRACK_COLUMN_DECOMPACTED_DEPTH

  • pybacktrack.BACKTRACK_COLUMN_DYNAMIC_TOPOGRAPHY

  • pybacktrack.BACKTRACK_COLUMN_TECTONIC_SUBSIDENCE

  • pybacktrack.BACKTRACK_COLUMN_WATER_DEPTH

  • pybacktrack.BACKTRACK_COLUMN_SEA_LEVEL

  • pybacktrack.BACKTRACK_COLUMN_COMPOSITE_POROSITY

  • pybacktrack.BACKTRACK_COLUMN_COMPOSITE_DECAY

  • pybacktrack.BACKTRACK_COLUMN_LITHOLOGY

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

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

Backtrack well in well_filename and write decompacted data to decompacted_output_filename.

Also optionally write ammended well data (ie, including extra stratigraphic base unit) to ammended_well_output_filename if specified.

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

• Added pybacktrack.BACKTRACK_COLUMN_PALEO_LONGITUDE, pybacktrack.BACKTRACK_COLUMN_PALEO_LATITUDE, pybacktrack.BACKTRACK_COLUMN_SEA_LEVEL, pybacktrack.BACKTRACK_COLUMN_COMPACTED_DENSITY, pybacktrack.BACKTRACK_COLUMN_COMPOSITE_POROSITY and pybacktrack.BACKTRACK_COLUMN_COMPOSITE_DECAY to available columns for decompacted_columns.

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