Getting Started

Installation 

Install pybacktrack 

You can install pybacktrack using:

conda, or
pip, or
Docker.

We recommend using conda since it installs all the dependencies of pybacktrack (using pip currently only installs some of the dependencies, the rest must be install manually). Using Docker is also more straightforward than pip since all the dependencies have been pre-installed.

Using conda 

We recommend installing pyBacktrack using conda.

To install the latest stable version of pyBacktrack type the following in a terminal or command window (on macOS and Ubuntu this is a Terminal window, and on Windows you’ll need to open an Anaconda prompt from the Start menu):

conda install -c conda-forge pybacktrack

We recommend installing pyBacktrack into a new conda environment. For example, the following creates and activates a Python 3.10 environment named pybacktrack_py310 containing pyBacktrack and all its dependencies:

conda create -n pybacktrack_py310 -c conda-forge python=3.10 pybacktrack
conda activate pybacktrack_py310

You can then use pyBacktrack. For example, to see the pyBacktrack version:

python -c "import pybacktrack; print(pybacktrack.__version__)"

Using pip 

Python packages installed using pip will typically also have their dependency packages automatically installed also. However pybacktrack requires manual installation of some of its dependencies.

Requirements 

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 python, pip and installed packages. However, currently pyGPlates does not yet work in virtual environments (at least on Mac systems).

Install Python, Pip, GMT and pyGPlates on Ubuntu 

This is an example demonstrating how to install GMT and pyGPlates on Ubuntu 18.04 (Bionic).

Note

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:

export PYTHONPATH=$PYTHONPATH:/usr/lib

Install Python, Pip, GMT and pyGPlates on Mac using Macports 

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

Note

You will likely need to add /opt/local/lib/gmt5/bin/ to your PATH environment variable, for example in your ~/.bashrc, ~/.bash_profile or ~/.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

Note

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

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:

export PYTHONPATH=~/pygplates_0.36.0_py38_Darwin-x86_64:$PYTHONPATH

Note

The above line can be added to your ~/.bashrc, ~/.bash_profile or ~/.zprofile file so that PYTHONPATH is set each time you open a new terminal window.

Install pybacktrack 

To install the latest stable version, run:

python -m pip install pybacktrack

Warning

On Mac systems, when using Macports, it might be better to install to the local user install directory with python -m pip install --user pybacktrack to avoid confusing Macports (which installs to the system install directory).

And on linux systems, if you have admin privileges, you can install to the system install directory with sudo python -m pip install pybacktrack.

Note

We generally recommend using python -m pip install pybacktrack instead of pip install pybacktrack to ensure pybacktrack is installed into the python you are actually using. For example, when using Conda Python it might be that python executes the Conda Python interpreter but 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 --upgrade flag:

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"

Note

You may need to update your Git if you receive an error ending with tlsv1 alert protocol version.

This is apparently due to an update on GitHub.

…or download the pyBacktrack source code, extract to a local directory and run:

python -m pip install <path-to-local-directory>

Note

Installing pyBacktrack will automatically install the NumPy and SciPy requirements. However, as mentioned in requirements, GMT and pyGPlates still need to be manually installed.

Using Docker 

This method of running pybacktrack relies on Docker, so before installing the pybacktrack docker image, ensure you have installed Docker.

Note

On Windows platforms you can install Docker Desktop for Windows. Note that Docker Toolbox has been deprecated (and now Docker Desktop for Windows is recommended).

A similar situation applies on Mac platforms where you can install Docker Desktop for Mac (with Docker Toolbox being deprecated).

Once Docker is installed, open a terminal (command-line interface).

Note

For Docker Desktop for Windows and Docker Desktop for Mac this a regular command-line terminal.

Also on Linux systems this a regular command-line terminal.

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

This should bring up a command prompt inside the running docker container.
The current working directory should be /usr/src/pybacktrack/.
It should have a pybacktrack_examples sub-directory containing test data.

Note

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

From the current working directory you can run the backtracking example below, or any other examples in this documentation. For example, you could run:

python3 -m pybacktrack.backtrack_cli -w pybacktrack_examples/example_data/ODP-114-699-Lithology.txt -d age water_depth -- ODP-114-699_backtrack_decompacted.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:

./notebook.sh

Then you can start a web browser on your local machine and type the following in the URL field:

http://localhost:18888/tree

This will display the current working directory in the docker container.
In the web browser, navigate to pybacktrack_examples and then notebooks.
Then click on a notebook (such as backtrack.ipynb).
You should be able to run the notebook, or modify it and then run it.

Install the examples 

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

The following command installs the examples (example data and notebooks) to a new sub-directory of your current working directory called pybacktrack_examples:

python -c "import pybacktrack; pybacktrack.install_examples()"

Note

The current working directory is whatever directory you are in when you run the above command.

Note

Alternatively you can choose a different sub-directory by providing an argument to the install_examples() function above.
For example, python -c "import pybacktrack; pybacktrack.install_examples('pybacktrack/examples')"
creates a new sub-directory of your current working directory called pybacktrack/examples.
However the example below assumes the default directory (pybacktrack_examples).

Install supplementary scripts 

You can optionally install supplementary scripts. These are not necessary for running the pybacktrack module. 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 pybacktrack_supplementary:

python -c "import pybacktrack; pybacktrack.install_supplementary()"

Note

Like the examples you can specify your own sub-directory.

A Backtracking Example 

Once installed, pybacktrack is available to:

run built-in scripts (inside pybacktrack), or
import pybacktrack into 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 pybacktrack_examples/example_data/ODP-114-699-Lithology.txt,

Note

This 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:
- the M2 dynamic topography model, and
- the Haq87_SealevelCurve_Longterm sea-level model,
writing the amended drill site to ODP-114-699_backtrack_amended.txt, and
writing the following columns to ODP-114-699_backtrack_decompacted.txt:
- age
- compacted_depth
- compacted_thickness
- decompacted_thickness
- decompacted_density
- decompacted_sediment_rate
- decompacted_depth
- dynamic_topography
- water_depth
- tectonic_subsidence
- lithology

Use a built-in module script 

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/example_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_decompacted.txt

Import into your own script 

An alternative to running a built-in script 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 Python code does the same as the built-in script by calling the pybacktrack.backtrack_and_write_well() function:

import pybacktrack

# Input and output filenames.
input_well_filename = 'pybacktrack_examples/example_data/ODP-114-699-Lithology.txt'
amended_well_output_filename = 'ODP-114-699_backtrack_amended.txt'
decompacted_output_filename = 'ODP-114-699_backtrack_decompacted.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:

python my_backtrack_script.py