Overview
This document gives a brief overview of the scripts inside the pybacktrack
package.
Running pyBacktrack
Once installed, the pybacktrack
Python package is available to:
run built-in scripts (inside
pybacktrack
), orimport 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
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/example_data/ODP-114-699-Lithology.txt -d age water_depth -- ODP-114-699_backtrack_decompacted.txt
…where the -w
option specifies the input drill site file pybacktrack_examples/example_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_decompacted.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.
See also
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/example_data/sunrise_lithology.txt -l primary extended -d age average_tectonic_subsidence -- sunrise_backstrip_decompacted.txt
…where the -w
option specifies the input drill site file pybacktrack_examples/example_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_decompacted.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.
See also
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.
See also
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/example_data/ages.txt ages_and_depths.txt
Here the input file pybacktrack_examples/example_data/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 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 systemCROSBY_2007
- Crosby, A.G., (2007) Aspects of the relationship between topography and gravity on the Earth and Moon, PhD thesisGDH1
- 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.
stratigraphic_depth_to_age
The stratigraphic_depth_to_age
module is used to convert stratigraphic depths to ages using a depth-to-age model.
Here the depth-to-age model is specified as a file containing a column of ages and a column of depths that forms a piecewise linear function of age with depth
(a model where age is a function of depth age=function(depth)
).
Then another file specifies the input stratigraphic depths that you wish to convert to ages.
Finally a third file is created containing the input depths and output ages, where each interpolated output age is a result of querying the piecewise linear function using the input depth:
python -m pybacktrack.stratigraphic_depth_to_age_cli -m pybacktrack_examples/example_data/Site1089B_age_depth.txt -- pybacktrack_examples/example_data/Site1089B_strat_depth.txt Site1089B_age_strat_depth.txt
Here the age=function(depth)
model is specified with the -m
option, where the pybacktrack_examples/example_data/Site1089B_age_depth.txt
file
contains a column of ages and a column of depths. By default, age is the first column and depth the second but you can optionally choose any column by specifying
two integers representing the age and depth column indices in the -m
option. For example, you can change -m pybacktrack_examples/example_data/Site1089B_age_depth.txt
to -m pybacktrack_examples/example_data/Site1089B_age_depth.txt 1 0
to select the second column (index 1
) for age and the first column (index 0
) for depth.
The input stratigraphic depths are in pybacktrack_examples/example_data/Site1089B_strat_depth.txt
and must be in the first column.
Any text after the depth value in a row (eg, lithologies) is copied to the output file. Also any metadata at the top of the file is copied to the output file.
The interpolated ages and associated depths are written to the output file Site1089B_age_strat_depth.txt
.
The first column contains (interpolated) age and the second column contains depth. To reverse this order you can use the -r
option.
Note
The output file Site1089B_age_strat_depth.txt
does not contain rows for depths that are outside the depth range of the model Site1089B_age_depth.txt
.
This is the default behaviour. You can change this using the -m
option which, in addition to specifying optional age and depth column indices, allows you to
optionally specify how to handle out-of-bounds depth values with exclude
(to exclude rows outside depth range), clamp
(to use boundary age values) or
extrapolate
(to extrapolate age from boundary).
Note
Use python -m pybacktrack.stratigraphic_depth_to_age_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.
Here the y=f(x)
model is specified as a file containing a column of x values and a column of y values that forms a piecewise linear function of y with x.
Then another file specifies the input x values. Finally a third file is created containing the input x values and the output y values,
where each interpolated output y value is a result of querying the piecewise linear function using an input x value:
python -m pybacktrack.util.interpolate_cli -cx 1 -cy 0 -c function_y_of_x.txt -- input_x_values.txt output_x_y_values.txt
Note
These files, specifically function_y_of_x.txt
and input_x_values.txt
, do not exist in the example data.
They are just placeholders for your own data that you would like to interpolate.
Here the y=f(x)
model is specified with the -c
, -cx
and -cy
options.
The -c
option specifies the file function_y_of_x.txt
containing a column of y
values followed by a column of x
values.
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 if y happens to be in the first column (0
) and x in the second column (1
)
then you can swap the default order of column indices using -cx 1 -cy 0
.
The input x
values are in input_x_values.txt
in the first column (by default).
If they had been in another column, for example if there were other unused columns, then we would need to specify the x column with the -ix
option.
The output (interpolated) y values (and associated x values) are written to the output file output_x_y_values.txt
.
The first column contains the x values and the second column contains the (interpolated) y values. 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_decompacted.txt',
'pybacktrack_examples/example_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/example_data/ODP-114-699-Lithology.txt -d age water_depth -- ODP-114-699_backtrack_decompacted.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_decompacted.txt',
'pybacktrack_examples/example_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/example_data/sunrise_lithology.txt -l primary extended -d age average_tectonic_subsidence -- sunrise_backstrip_decompacted.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/example_data/ages.txt',
'ages_and_depths.txt')
…is equivalent to running the age-to-depth script example:
python -m pybacktrack.age_to_depth_cli -- pybacktrack_examples/example_data/ages.txt ages_and_depths.txt
stratigraphic_depth_to_age
The following Python source code (using these functions):
import pybacktrack
# Read the age=f(depth) function, where 'x' is depth and 'y' is age (in the returned function y=f(x)).
age_column_index = 0 # age is in the first column
depth_column_index = 1 # depth is in the second column
# This determines the age values for depth values outside the depth range of the depth-to-model model.
# It can be 'exclude' to exclude age values outside range, or 'clamp' to use boundary age values, or 'extrapolate' to extrapolate age from boundary.
# Here we use 'exclude' (instead of the default 'clamp') to avoid getting the same age value for different depth values (outside depth range).
out_of_bounds = 'exclude'
# Ignore the x (depth) and y (age) values read from file by using '_'.
depth_to_age_model, _, _ = pybacktrack.read_interpolate_function('pybacktrack_examples/example_data/Site1089B_age_depth.txt', depth_column_index, age_column_index, out_of_bounds)
# Convert depth values in input file to age and depth values in output file.
pybacktrack.convert_stratigraphic_depth_to_age_files(
'pybacktrack_examples/example_data/Site1089B_strat_depth.txt',
'Site1089B_age_strat_depth.txt',
depth_to_age_model)
…is equivalent to running the stratigraphic depth-to-age script example:
python -m pybacktrack.stratigraphic_depth_to_age_cli -m pybacktrack_examples/example_data/Site1089B_age_depth.txt -- pybacktrack_examples/example_data/Site1089B_strat_depth.txt Site1089B_age_strat_depth.txt
interpolate
The following Python source code (using these functions):
import pybacktrack
# Read the y=f(x) function from a 2-column file.
# Ignore the x and y values read from file by using '_'.
function_y_of_x, _, _ = pybacktrack.read_interpolate_function('function_y_of_x.txt', 1, 0)
# Convert x values in a 1-column input file to x and y values in a 2-column output file.
pybacktrack.interpolate_file(
function_y_of_x,
'input_x_values.txt',
'output_x_y_values.txt')
…is equivalent to running the interpolate script example:
python -m pybacktrack.util.interpolate_cli -cx 1 -cy 0 -c function_y_of_x.txt -- input_x_values.txt output_x_y_values.txt