Overview¶

This document gives a brief overview of the scripts inside the pybacktrack package.

Running pyBacktrack
Running the scripts built into pyBacktrack
Running your own script that imports pyBacktrack

Running pyBacktrack ¶

Once installed, the pybacktrack Python package is available to:

run built-in scripts (inside pybacktrack), or
import pybacktrack into your own script.

It is generally easier to run the built-in scripts since you only need to specify parameters on the command-line.

However you may need to create your own script if you want to combine pybacktrack functionality with other research functionality. In this case it is generally better to import pybacktrack, along with the other modules, into your own script. This also gives a finer granularity of control compared to the command-line.

The following two sections give an overview of both approaches.

Note

The input files used in the examples below are available in the example data.

Please ensure you have installed the example data before running any of these examples.

Running the scripts built into pyBacktrack ¶

PyBacktrack is a Python package containing modules. And each module can be run as a script using python -m pybacktrack.<module>_cli followed by command line options that are specific to that module. For example, the backtrack module can be run as python -m pybacktrack.backtrack_cli ..., or the backstrip module can be run as python -m pybacktrack.backstrip_cli ..., with ... replaced by command-line options.

The following sections give an introduction to each module.

Note

In each module you can use the --help option to see all available command-line options for that specific module. For example, python -m pybacktrack.backtrack_cli --help describes all options available to the backtrack module.

backtrack ¶

The backtrack module is used to find paleo water depths from a tectonic subsidence model (such as an age-to-depth curve in ocean basins, or rifting near continental passive margins) and sediment decompaction over time.

This example takes an ocean drill site as input and outputs a file containing a backtracked water depth for each age in the drill site:

python -m pybacktrack.backtrack_cli -w pybacktrack_examples/test_data/ODP-114-699-Lithology.txt -d age water_depth -- ODP-114-699_backtrack_decompat.txt

…where the -w option specifies the input drill site file pybacktrack_examples/test_data/ODP-114-699-Lithology.txt, the -d option specifies the desired columns (age and water_depth) of the output file, and ODP-114-699_backtrack_decompat.txt is the output file.

There are other command-line options available to the backtrack module (use the --help option to list them) but they all have default values and hence only need to be specified if the default does not suit.

backstrip ¶

The backstrip module is used to find tectonic subsidence (typically due to lithospheric stretching) from paleo water depths and sediment decompaction over time.

This example takes a passive margin site as input and outputs a file containing a backstripped tectonic subsidence for each age in the drill site:

python -m pybacktrack.backstrip_cli -w pybacktrack_examples/test_data/sunrise_lithology.txt -l primary extended -d age average_tectonic_subsidence -- sunrise_backstrip_decompat.txt

…where the -w option specifies the input drill site file pybacktrack_examples/test_data/sunrise_lithology.txt, the -l option specifies the lithology definitions, the -d option specifies the desired columns (age and average_tectonic_subsidence) of the output file, and sunrise_backstrip_decompat.txt is the output file.

Note

It is necessary to specify the bundled primary and extended lithology definitions, with -l primary extended, because the input drill site references lithologies in both lithology definition files. See Bundled lithology definitions. This is unlike the backtracking example above that only references the primary lithologies, and hence does not need to specify lithology definitions because primary is the default (when -l is not specified).

Note

average_tectonic_subsidence is an average of the minimum and maximum tectonic subsidences, that are in turn a result of the minimum and maximum water depths specified in the drill site file.

There are other command-line options available to the backstrip module (use the --help option to list them) but they all have default values and hence only need to be specified if the default does not suit.

paleo_bathymetry ¶

The paleo_bathymetry module is used to generate paleo bathymetry grids by reconstructing and backtracking present-day sediment-covered crust through time.

This example generates paleobathymetry grids at 12 minute resolution from 0Ma to 240Ma in 1Myr increments using the M7 dynamic topography model and the GDH1 oceanic subsidence model:

python -m pybacktrack.paleo_bathymetry_cli -gm 12 -ym M7 -m GDH1 --use_all_cpus -- 240 paleo_bathymetry_12m_M7_GDH1

…where the -gm option specifies the grid spacing (in minutes), the -ym specifies the dynamic topography model, the -m option specifies the oceanic subsidence model, the --use_all_cpus option uses all CPUs (it also accepts an optional number of CPUs) and the generated paleobathymetry grid files are named paleo_bathymetry_12m_M7_GDH1_<time>.nc.

There are other command-line options available to the paleo_bathymetry module (use the --help option to list them) but they all have default values and hence only need to be specified if the default does not suit.

age_to_depth ¶

The age_to_depth module is used to convert ocean floor age to ocean basement depth (in ocean basins).

This example takes an input file containing a column of ages, and outputs a file containing two columns (age and depth):

python -m pybacktrack.age_to_depth_cli -- pybacktrack_examples/test_data/test_ages.txt test_ages_and_depths.txt

Here the input file pybacktrack_examples/test_data/test_ages.txt contains ages in the first (and only) column. If they had been in another column, for example if there were other unused columns, then we would need to specify the age column with the -a option.

The output file test_ages_and_depths.txt contains ages in the first column and depths in the second column. To reverse this order you can use the -r option.

There are three built-in age-to-depth ocean models:

RHCW18 - Richards et al. (2020) Structure and dynamics of the oceanic lithosphere-asthenosphere system
CROSBY_2007 - Crosby, A.G., (2007) Aspects of the relationship between topography and gravity on the Earth and Moon, PhD thesis
GDH1 - Stein and Stein (1992) Model for the global variation in oceanic depth and heat flow with lithospheric age

Here the conversion was performed using the default model RHCW18 since the -m command-line option was not specified. However you can specify the alternate CROSBY_2007 model using -m CROSBY_2007 (or GDH1 using -m GDH1).

Note

The default age-to-depth model was updated in pyBacktrack version 1.4. It is now RHCW18. Previously it was GDH1.

Or you can use your own age-to-depth model by specifying a file containing an age column and a depth column followed by two integers representing the age and depth column indices. For example, if you have your own age-to-depth file called age-depth-model.txt where age is in the first column and depth is in the second column then you can specify this using -w age-depth-model.txt 0 1.

Note

Use python -m pybacktrack.age_to_depth_cli --help to see a description of all command-line options.

interpolate ¶

The interpolate module can perform linear interpolation of any piecewise linear function y=f(x). As such it can be used for any type of data.

However, for pyBacktrack, it is typically used to interpolate a model where age is a function of depth (age=function(depth)). Here the age-depth model is specified as a file containing a column of depths and a column of ages that forms a piecewise linear function of age with depth. Then another file specifies the input depths (which are typically stratigraphic layer boundaries). Finally a third file is created containing the output ages, where each interpolated age is a result of querying the piecewise linear function using a depth:

python -m pybacktrack.util.interpolate_cli -cx 1 -cy 0 -c pybacktrack_examples/test_data/ODP-114-699_age-depth-model.txt -- pybacktrack_examples/test_data/ODP-114-699_strat_boundaries.txt ODP-114-699_strat_boundaries_depth_age.txt

Here the age=function(depth) model is specified with the -c, -cx and -cy options. The -c option specifies the pybacktrack_examples/test_data/ODP-114-699_age-depth-model.txt file containing a column of ages and a column of depths. The -cx and -cy options specify the x and y columns of the model function y=f(x). These default to 0 and 1 respectively. However since age (y) happens to be in the first column (0) and depth (x) in the second column (1) we must swap the default order of column indices using -cx 1 -cy 0.

The input depths are in pybacktrack_examples/test_data/ODP-114-699_strat_boundaries.txt in the first (and only) column. If they had been in another column, for example if there were other unused columns, then we would need to specify the depth column with the -ix option.

The output depths and (interpolated) ages are written to the output file ODP-114-699_strat_boundaries_depth_age.txt. The first column contains depth and the second column contains (interpolated) age. To reverse this order you can use the -r option.

Note

Use python -m pybacktrack.util.interpolate_cli --help to see a description of all command-line options.

Running your own script that imports pyBacktrack ¶

An alternative to running the built-in scripts is to write your own script (using a text editor) that imports pybacktrack and calls its functions. You might do this if you want to combine pyBacktrack functionality with other research functionality into a single script.

The following shows Python source code that is equivalent to the above examples running built-in scripts.

If you save any of the code examples below to a file called my_script.py then you can run that example as:

python my_script.py

backtrack ¶

The following Python source code (using these functions):

import pybacktrack

pybacktrack.backtrack_and_write_well(
    'ODP-114-699_backtrack_decompat.txt',
    'pybacktrack_examples/test_data/ODP-114-699-Lithology.txt',
    decompacted_columns=[pybacktrack.BACKTRACK_COLUMN_AGE,
                         pybacktrack.BACKTRACK_COLUMN_WATER_DEPTH])

…is equivalent to running the backtrack script example:

python -m pybacktrack.backtrack_cli -w pybacktrack_examples/test_data/ODP-114-699-Lithology.txt -d age water_depth -- ODP-114-699_backtrack_decompat.txt

Note

The backtrack module is covered in more detail here.

backstrip ¶

The following Python source code (using these functions):

import pybacktrack

pybacktrack.backstrip_and_write_well(
    'sunrise_backstrip_decompat.txt',
    'pybacktrack_examples/test_data/sunrise_lithology.txt',
    lithology_filenames=[pybacktrack.PRIMARY_BUNDLE_LITHOLOGY_FILENAME,
                         pybacktrack.EXTENDED_BUNDLE_LITHOLOGY_FILENAME],
    decompacted_columns=[pybacktrack.BACKSTRIP_COLUMN_AGE,
                         pybacktrack.BACKSTRIP_COLUMN_AVERAGE_TECTONIC_SUBSIDENCE])

…is equivalent to running the backstrip script example:

python -m pybacktrack.backstrip_cli -w pybacktrack_examples/test_data/sunrise_lithology.txt -l primary extended -d age average_tectonic_subsidence -- sunrise_backstrip_decompat.txt

Note

The backstrip module is covered in more detail here.

paleo_bathymetry ¶

The following Python source code (using these functions):

import pybacktrack

pybacktrack.reconstruct_paleo_bathymetry_grids(
    'paleo_bathymetry_12m_M7_GDH1',
    0.2,  # degrees (same as 12 minutes)
    240,
    dynamic_topography_model='M7',
    ocean_age_to_depth_model=pybacktrack.AGE_TO_DEPTH_MODEL_GDH1,
    use_all_cpus=True)  # can also be an integer (the number of CPUs to use)

…is equivalent to running the paleobathymetry script example:

python -m pybacktrack.paleo_bathymetry_cli -gm 12 -ym M7 -m GDH1 --use_all_cpus -- 240 paleo_bathymetry_12m_M7_GDH1

Note

The paleo_bathymetry module is covered in more detail here.

age_to_depth ¶

The following Python source code (using these functions):

import pybacktrack

pybacktrack.convert_age_to_depth_files(
    'pybacktrack_examples/test_data/test_ages.txt',
    'test_ages_and_depths.txt')

…is equivalent to running the age-to-depth script example:

python -m pybacktrack.age_to_depth_cli -- pybacktrack_examples/test_data/test_ages.txt test_ages_and_depths.txt

interpolate ¶

The following Python source code (using these functions):

import pybacktrack

# Read the age-depth function age=function(depth) from age-depth curve file.
# Ignore the x (depth) and y (age) values read from file by using '_'.
age_depth_function, _, _ = pybacktrack.read_interpolate_function('pybacktrack_examples/test_data/ODP-114-699_age-depth-model.txt', 1, 0)

# Convert x (depth) values in 1-column input file to x (depth) and y (age) values in 2-column output file.
pybacktrack.interpolate_file(
    age_depth_function,
    'pybacktrack_examples/test_data/ODP-114-699_strat_boundaries.txt',
    'ODP-114-699_strat_boundaries_depth_age.txt')

…is equivalent to running the interpolate script example:

python -m pybacktrack.util.interpolate_cli -cx 1 -cy 0 -c pybacktrack_examples/test_data/ODP-114-699_age-depth-model.txt -- pybacktrack_examples/test_data/ODP-114-699_strat_boundaries.txt ODP-114-699_strat_boundaries_depth_age.txt