- A Backtracking Example
You can install
Docker is typically more straightforward since all the dependencies of
pybacktrack have been pre-installed.
Python packages installed using pip will typically also have their dependency packages automatically installed also.
pybacktrack requires manual installation of some of its dependencies.
PyBacktrack depends on:
NumPy and SciPy are automatically installed by pip when pybacktrack is installed, however GMT (version 5 or above) and pyGPlates need to be manually installed.
GMT is called via the command-line (shell) and so just needs to be in the PATH in order for pyBacktrack to find it. Also ensure that version 5 or above (supports NetCDF version 4) is installed since the bundled grid files in pyBacktrack are in NetCDF4 format.
PyGPlates is not currently installable as a package and so needs to be in the python path (sys.path or PYTHONPATH). Installation instructions are available here.
PyGPlates supports Python 3 (in addition to Python 2.7) so you can now use pyBacktrack with either.
The Macports install example below shows one approach to selecting the default Python using
sudo port select.
Another approach is using Python virtual environments where each environment has its own
pip and installed packages.
However, currently pyGPlates does not yet work in virtual environments (at least on Mac systems).
This is an example demonstrating how to install GMT and pyGPlates on Ubuntu 18.04 (Bionic).
The main difference for other Ubuntu versions will be the pyGPlates install package (you’ll need to select the package appropriate for your Ubuntu version).
First install GMT 5:
sudo apt install gmt
Then install Python 3 (and Pip):
sudo apt update sudo apt install python3 python3-pip sudo pip3 install --upgrade pip
Then download the pyGPlates Python 3 debian package pygplates_0.36.0_py36_ubuntu-18.04-amd64.deb, and install it:
sudo apt install ./pygplates_0.36.0_py36_ubuntu-18.04-amd64.deb
Then add the installed location of pyGPlates to the PYTHONPATH environment variable:
This is an example demonstrating how to install GMT and pyGPlates on a Mac system using Macports.
First install GMT 5:
sudo port install gmt5
You will likely need to add
/opt/local/lib/gmt5/bin/ to your
PATH environment variable,
for example in your
~/.zprofile file so that PATH
is set each time you open a new terminal window.
After doing this, typing
gmt should find GMT and show some help options.
Then install Python 3 (and Pip):
sudo port install python38 sudo port install py38-pip
Set your default
python to Python 3.8:
sudo port select --set python python38 sudo port select --set pip pip38
If you already have
python referencing Python 2 then you can instead use
python3 to reference Python 3:
sudo port select --set python3 python38 sudo port select --set pip3 pip38
…but this will require using
python3 on the command-line to run
pybacktrack (instead of just
Then download a pyGPlates Mac zip file, such as pygplates_0.36.0_py38_Darwin-x86_64.zip for Python 3.8 on an Intel Mac, and extract it to your home directory.
Then add the unzipped location of pyGPlates to the PYTHONPATH environment variable, such as:
The above line can be added to your
so that PYTHONPATH is set each time you open a new terminal window.
To install the latest stable version, run:
python -m pip install pybacktrack
python -m pip install --user pybacktrackto avoid confusing Macports (which installs to the system install directory).
sudo python -m pip install pybacktrack.
We generally recommend using
python -m pip install pybacktrack instead of
pip install pybacktrack to ensure
pybacktrack is installed
python you are actually using. For example, when using Conda Python it might be that
python executes the Conda Python interpreter
pip installs into the system Python (eg, because the base Conda environment is not activated).
If you already have
pybacktrack installed and would like to upgrade to the latest version then use the
python -m pip install --upgrade pybacktrack
To install the latest development version (requires Git on local system), run:
python -m pip install "git+https://github.com/EarthByte/pyBacktrack.git#egg=pybacktrack"
tlsv1 alert protocol version.
…or download the pyBacktrack source code, extract to a local directory and run:
python -m pip install <path-to-local-directory>
Before running the example below, or any other examples, you’ll also need to install the example data (from the pybacktrack package itself). This assumes you’ve already installed the pybacktrack package.
The following command installs the examples (example data and notebooks) to a new sub-directory of your current working directory called
python -c "import pybacktrack; pybacktrack.install_examples()"
The current working directory is whatever directory you are in when you run the above command.
python -c "import pybacktrack; pybacktrack.install_examples('pybacktrack/examples')"creates a new sub-directory of your current working directory called
You can optionally install supplementary scripts. These are not necessary for running the
They are various pre/post processing, conversion and test scripts that have only been included for reference (for those interested).
The following command installs the supplementary scripts to a new sub-directory of your current working directory called
python -c "import pybacktrack; pybacktrack.install_supplementary()"
Like the examples you can specify your own sub-directory.
Once Docker is installed, open a terminal (command-line interface).
To install the
pybacktrack docker image, type:
docker pull earthbyte/pybacktrack
To run the docker image:
docker run -it --rm -p 18888:8888 -w /usr/src/pybacktrack earthbyte/pybacktrack
pybacktrack_examplessub-directory containing test data.
On Linux systems you may have to use sudo when running docker commands. For example:
sudo docker pull earthbyte/pybacktrack sudo docker run -it --rm -p 18888:8888 -w /usr/src/pybacktrack earthbyte/pybacktrack
python3 -m pybacktrack.backtrack_cli -w pybacktrack_examples/test_data/ODP-114-699-Lithology.txt -d age water_depth -- ODP-114-699_backtrack_decompat.txt
If you wish to run the example notebooks
then there is a
notebook.sh script to start a Jupyter notebook server in the running docker container:
Then you can start a web browser on your local machine and type the following in the URL field:
pybacktrack is available to:
- run built-in scripts (inside
import pybacktrackinto your own script.
The following example is used to demonstrate both approaches. It backtracks an ocean drill site and saves the output to a text file by:
reading the ocean drill site file
NoteThis file is part of the example data.However if you have your own ocean drill site file then you can substitute it in the example below if you want.
backtracking it using:
M2dynamic topography model, and
writing the amended drill site to
writing the following columns to
Since there is a
backtrack module inside
pybacktrack that can be run as a script,
we can invoke it on the command-line using
python -m pybacktrack.backtrack_cli followed by command line options that are specific to that module.
This is the easiest way to run backtracking.
To see its command-line options, run:
python -m pybacktrack.backtrack_cli --help
The backtracking example can now be demonstrated by running the script as:
python -m pybacktrack.backtrack_cli \ -w pybacktrack_examples/test_data/ODP-114-699-Lithology.txt \ -d age compacted_depth compacted_thickness decompacted_thickness decompacted_density decompacted_sediment_rate decompacted_depth dynamic_topography water_depth tectonic_subsidence lithology \ -ym M2 \ -slm Haq87_SealevelCurve_Longterm \ -o ODP-114-699_backtrack_amended.txt \ -- \ ODP-114-699_backtrack_decompat.txt
An alternative to running a built-in script is to write your own script (using a text editor) that imports
calls its functions. You might do this if you want to combine pyBacktrack functionality with other research functionality into a single script.
import pybacktrack # Input and output filenames. input_well_filename = 'pybacktrack_examples/test_data/ODP-114-699-Lithology.txt' amended_well_output_filename = 'ODP-114-699_backtrack_amended.txt' decompacted_output_filename = 'ODP-114-699_backtrack_decompat.txt' # Read input well file, and write amended well and decompacted results to output files. pybacktrack.backtrack_and_write_well( decompacted_output_filename, input_well_filename, dynamic_topography_model='M2', sea_level_model='Haq87_SealevelCurve_Longterm', # The columns in decompacted output file... decompacted_columns=[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_WATER_DEPTH, pybacktrack.BACKTRACK_COLUMN_TECTONIC_SUBSIDENCE, pybacktrack.BACKTRACK_COLUMN_LITHOLOGY], # Might be an extra stratigraphic well layer added from well bottom to ocean basement... ammended_well_output_filename=amended_well_output_filename)
If you save the above code to a file called
my_backtrack_script.py then you can run it as: