Getting Started¶
Installation¶
You can install pybacktrack
either:
Docker is typically more straightforward since all the dependencies of pybacktrack
have been pre-installed.
Install 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
- SciPy
- Generic Mapping Tools (GMT) (>=5.0.0)
- PyGPlates
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
python -m pip install --user pybacktrack
to avoid confusing Macports
(which installs to the system install directory).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
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>
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.
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 the pybacktrack package.
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
install_examples()
function above.python -c "import pybacktrack; pybacktrack.install_examples('pybacktrack/examples')"
creates a new sub-directory of your current working directory called pybacktrack/examples
.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.
Install using Docker¶
This method of running pybacktrack
relies on Docker, so before installing
the pybacktrack
docker image, ensure you have installed Docker.
Note
Once Docker is installed, open a terminal (command-line interface).
Note
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
/usr/src/pybacktrack/
.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
pybacktrack_examples
and then notebooks
.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,
- the
writing the amended drill site to
ODP-114-699_backtrack_amended.txt
, andwriting 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