GPlately was created to accelerate spatio-temporal data analysis by leveraging pyGPlates and PlateTectonicTools within a simplified Python interface. This object-oriented package enables the reconstruction of data through deep geologic time (such as points, lines, polygons, and rasters), the interrogation of plate kinematic information (plate velocities, rates of subduction and seafloor spreading), the rapid comparison of multiple plate motion models, and the plotting of reconstructed output data on maps. All tools are designed to be parallel-safe, accelerating spatio-temporal analysis over multiple CPU processors.
GPlately requires a working installation of pyGPlates, which is freely available at https://www.gplates.org/download. All major system architectures (e.g., Linux, macOS, Windows) are supported, and installation instructions are well documented. Sample data is also available from EarthByte servers, which include rasters, seafloor age grids, rotation files, and more to help you get started with plate reconstructions.
Mather, B.R., Müller, R.D., Zahirovic, S., Cannon, J., Chin, M., Ilano, L., Wright, N.M., Alfonso, C., Williams, S., Tetley, M., Merdith, A. (2023) Deep time spatio-temporal data analysis using pyGPlates with PlateTectonicTools and GPlately. Geoscience Data Journal, 1–8. Available from: https://doi.org/10.1002/gdj3.185
@article{Mather2023,
author = {Mather, Ben R. and Müller, R. Dietmar and Zahirovic, Sabin and Cannon, John and Chin, Michael and Ilano, Lauren and Wright, Nicky M. and Alfonso, Christopher and Williams, Simon and Tetley, Michael and Merdith, Andrew},
title = {Deep time spatio-temporal data analysis using pyGPlates with PlateTectonicTools and GPlately},
year = {2023},
journal = {Geoscience Data Journal},
pages = {1-8},
keywords = {geospatial, plate reconstructions, pyGPlates, python, tectonics},
doi = {https://doi.org/10.1002/gdj3.185},
url = {https://rmets.onlinelibrary.wiley.com/doi/abs/10.1002/gdj3.185},
eprint = {https://rmets.onlinelibrary.wiley.com/doi/pdf/10.1002/gdj3.185},
}- pyGPlates
- plate-model-manager >= 1.2.2
- Shapely
- NumPy > 1.16
- SciPy > 1.0
- Matplotlib
- Cartopy (for mapping)
- Shapely
- Pooch
- GeoPandas
- netCDF4
- pygmt
- rioxarray
You can install the latest stable public release of GPlately and all its dependencies using conda.
This is the preferred method for installing GPlately, as it downloads binaries from the "conda-forge" channel.
conda install -c conda-forge gplatelyWe recommend creating a new conda environment in which to install GPlately. This avoids any potential conflicts within your base Python environment. In the example below, we create a new environment called my-env.
conda create -n my-env
conda activate my-env
conda install -c conda-forge gplatelyThe my-env environment needs to be activated before using GPlately, i.e., conda activate my-env.
Alternatively, you can install the latest stable public release of GPlately using the pip package manager.
pip install gplatelyor from this GitHub repository:
pip install git+https://github.com/GPlates/gplately.gitFirst-time installation: To install the latest version of GPlately from a specific repository branch (e.g., master), run the following commands in your terminal:
cd /directory-to-keep-gplately-files # go into the directory in which you'd like to keep the GPlately repository
git clone https://github.com/GPlates/gplately.git gplately.git
cd gplately.git # go into the root directory of your cloned gplately repository
git checkout master # check out the "master" branch or the name of branch you want
git pull # fetch all recent code changes from the GitHub remote repository to your computer
pip install . # alternatively, you can use "pip install -e ." to install gplately in editable modeUpdate installation: To update your installation of GPlately by fetching the latest code from a specific repository branch (e.g., master), run the following commands in your terminal:
cd /path-to-gplately-repository # go into the root directory of your cloned gplately repository, such as ./gplately.git
git checkout master # check out the "master" branch or the name of branch you want
git pull # fetch all recent code changes from the GitHub remote repository to your computer
pip install . # alternatively, you can use "pip install -e ." to install gplately in editable mode👉 Run GPlately example notebooks with Docker
docker pull gplates/gplatelydocker run --rm -ti -p 8888:8888 gplates/gplately- http://localhost:8888
👉 Run GPlately command with Docker
docker run gplates/gplately gplately --versiondocker run gplates/gplately gplately --help
👉 Run your Python script with Docker
docker run -it --rm -v "$PWD":/ws -w /ws gplates/gplately python my_script_to_run.py(assume my_script_to_run.py is in the current working directory)
See details docker/README.md.
DataServer- download rotation files and topology features from plate models on EarthByte's webDAV serverPlateModelManager- download and manage the plate reconstruction model filesPlateReconstruction- reconstruct features, tesselate mid ocean ridges, subduction zonesPoints- partition points onto plates, rotate back through timeRaster- read in NetCDF grids, interpolation, resamplingPlotTopologies- one stop shop for plotting ridges, trenches, subduction teeth
The PlateModelManager class was introduced as a more efficient alternative to the DataServer class, designed specifically for downloading and managing plate reconstruction model files.
A complete example of using the PlateModelManager class is available at https://github.com/GPlates/gplately/blob/master/Notebooks/Examples/introducing-plate-model-manager.py .
from plate_model_manager import PlateModelManager, PresentDayRasterManager
from gplately import PlateReconstruction, PlotTopologies, Raster
model = PlateModelManager().get_model(
"Muller2019", # model name
data_dir="plate-model-repo" # the local folder where you would like to save the model files
)
recon_model = PlateReconstruction(
model.get_rotation_model(),
topology_features=model.get_layer("Topologies"),
static_polygons=model.get_layer("StaticPolygons"),
)
gplot = PlotTopologies(
recon_model,
coastlines=model.get_layer("Coastlines"),
COBs=model.get_layer("COBs"),
time=55,
)
# get present-day topography raster
raster = Raster(PresentDayRasterManager().get_raster("topography"))
# get paleo-agegrid raster at 100Ma from Muller2019 model
agegrid = Raster(model.get_raster("AgeGrids", time=100)) The DataServer class can be used to download:
- rotation models
- topology features
- static polygons
- coastlines
- continents
- continent-ocean boundaries
- age grids and rasters
- geological feature data
from assorted plate reconstruction models. These files are needed to construct most of GPlately's objects. For example,
we can download a rotation model, a set of topology features and some static polygons from the Müller et al. 2019
global Mesozoic–Cenozoic deforming plate motion model. (Use the newer PlateModelManager class when it is possible.)
import gplately
gdownload = gplately.download.DataServer("Muller2019")
# Download plate reconstruction files and geometries from the Müller et al. 2019 model
rotation_model, topology_features, static_polygons = gdownload.get_plate_reconstruction_files()
coastlines, continents, COBs = gdownload.get_topology_geometries()
# Download the Müller et al. 2019 100 Ma age grid
age_grid = gdownload.get_age_grid(times=100)
# Download the ETOPO1 geotiff raster
etopo = gdownload.get_raster("ETOPO1_tif")The PlateReconstruction class contains tools to reconstruct geological features like tectonic plates and plate boundaries, and to interrogate plate kinematic data like plate motion velocities, and rates of subduction and seafloor spreading.
A complete Jupyter notebook example is available at https://github.com/GPlates/gplately/blob/master/Notebooks/02-PlateReconstructions.ipynb .
from plate_model_manager import PlateModelManager
from gplately import PlateReconstruction
model = PlateModelManager().get_model("Muller2019")
# Build a plate reconstruction model using a rotation model, a set of topology features and static polygons
recon_model = PlateReconstruction(
model.get_rotation_model(),
topology_features=model.get_layer("Topologies"),
static_polygons=model.get_layer("StaticPolygons"),
)The methods in the Points class track the motion of a point (or group of points) represented by a latitude and longitude through geologic time. This motion can be visualised using flowlines or motion paths and quantified with point motion velocities.
A complete Jupyter notebook example is available at https://github.com/GPlates/gplately/blob/master/Notebooks/03-WorkingWithPoints.ipynb .
import numpy as np
import gplately
from plate_model_manager import PlateModelManager
model = PlateModelManager().get_model("Muller2019")
# Create a plate reconstruction model using a rotation model, a set of topology features and static polygons
recon_model = gplately.auxiliary.get_plate_reconstruction(model)
# Define some points using their latitude and longitude coordinates so we can track them though time!
pt_lons = np.array([140., 150., 160.])
pt_lats = np.array([-30., -40., -50.])
# Create a Points instance from these points
gpts = gplately.Points(recon_model, pt_lons, pt_lats)
The Raster class contains methods to work with netCDF4 or MaskedArray gridded data. Grids may be filled, resized, resampled, and reconstructed back and forwards through geologic time. Other array data can also be interpolated onto Raster grids.
A complete Jupyter notebook example is available at https://github.com/GPlates/gplately/blob/master/Notebooks/06-Rasters.ipynb .
import gplately
from plate_model_manager import PlateModelManager, PresentDayRasterManager
model = PlateModelManager().get_model("Muller2019")
# Create a plate reconstruction model using a rotation model, a set of topology features and static polygons
recon_model = gplately.auxiliary.get_plate_reconstruction(model)
# Any numpy array can be turned into a Raster object!
raster = gplately.Raster(
plate_reconstruction=recon_model,
data=PresentDayRasterManager().get_raster("topography"),
extent="global", # equivalent to (-180, 180, -90, 90)
origin="lower", # or set extent to (-180, 180, -90, 90)
)
# Reconstruct the raster data to 50 million years ago!
reconstructed_raster = raster.reconstruct(
time=50,
partitioning_features=model.get_layer("ContinentalPolygons")
)Below is a plot of the ETOPO1 global relief raster at present day, and reconstructed to 50Ma:
The PlotTopologies class works with the PlateReconstruction class to plot geologic features of different types listed here, as well as coastline, continent and continent-ocean boundary geometries reconstructed through time using pyGPlates.
A complete Jupyter notebook example is available at https://github.com/GPlates/gplately/blob/master/Notebooks/02-PlateReconstructions.ipynb .
import gplately
from plate_model_manager import PlateModelManager
from gplately import PlotTopologies
model = PlateModelManager().get_model("Muller2019")
recon_model = gplately.auxiliary.get_plate_reconstruction(model)
gplot = PlotTopologies(
recon_model,
coastlines=model.get_layer("Coastlines"),
COBs=model.get_layer("COBs"),
continents= model.get_layer("ContinentalPolygons"),
time=55)Below are some continents, coastlines, COBs, ridges and transforms, trenches, subduction teeth and
seafloor age grids plotted using PlotTopologies.
To see GPlately in action, launch a Jupyter Notebook environment and check out the sample notebooks:
- 01 - Getting Started: A brief overview of how to initialise GPlately's main objects
- 02 - Plate Reconstructions: Setting up a
PlateReconstructionobject, reconstructing geological data through time - 03 - Working with Points: Setting up a
Pointsobject, reconstructing seed point locations through time with. This notebook uses point data from the Paleobiology Database (PBDB). - 04 - Velocity Basics: Calculating plate velocities, plotting velocity vector fields
- 05 - Working with Feature Geometries: Processing and plotting assorted polyline, polygon and point data from GPlates 2.3's sample data sets
- 06 - Rasters: Reading, resizing, resampling raster data, and linearly interpolating point data onto raster data
- 07 - Plate Tectonic Stats: Using PlateTectonicTools to calculate and plot subduction zone and ridge data (convergence/spreading velocities, subduction angles, subduction zone and ridge lengths, crustal surface areas produced and subducted etc.)
- 08 - Predicting Slab Flux: Predicting the average slab dip angle of subducting oceanic lithosphere.
- 09 - Motion Paths and Flowlines: Using pyGPlates to create motion paths and flowlines of points on a tectonic plate to illustrate the plate's trajectory through geological time.
- 10 - SeafloorGrid: Defines the parameters needed to set up a
SeafloorGridobject, and demonstrates how to produce age and spreading rate grids from a set of plate reconstruction model files. - 11 - AndesFluxes: Demonstrates how the reconstructed subduction history along the Andean margin can be potentially used in the plate kinematics analysis and data mining.
Documentation of GPlately's classes and methods can be found here (latest official release)!
Other documentation versions:
- Documentation dev (latest unstable)
- Documentation v1.3.0 (latest stable)
- Documentation v1.2.0
- Documentation v1.1.0
- Documentation v1.0.0
GPlately comes with a suite of useful command line tools. These tools are designed as GPlately subcommands. Run gplately -h to show the list of tools.
Display a list of available plate models from GPlates server. These model names can then be used by the Plate Model Manager to download model files over the Internet. Run gplately list -h for details.
Examples:
- `gplately list`
(list all available plate models from GPlates server)
- `gplately list -m merdith2021`
(show details about model merdith2021)
If you are using GPlately Docker image
- `docker run gplates/gplately gplately list`
- `docker run gplates/gplately gplately list -m merdith2021`
Combine multiple feature collections into one. Run gplately combine -h for details.
Filter feature collection by various criteria. Run gplately filter -h for details.
Examples:
- `gplately filter input_file output_file -n Africa "North America"`
(get features whose name contains "Africa" or "North America")
- `gplately filter input_file output_file -p 701 714 715 101`
(get features whose plate ID is one of 701 714 715 101)
- `gplately filter input_file output_file --min-birth-age 500`
(get features whose birth age is older than 500Myr)
- `gplately filter input_file output_file --max-birth-age 500`
(get features whose birth age is younger than 500Myr)
- `gplately filter input_file output_file -n Africa "North America" -p 701 714 715 101 --min-birth-age 500`
(get features whose name contains "Africa" or "North America" and plate ID is one of 701 714 715 101 and birth age is older than 500Myr)
- `gplately filter input_file output_file -t gpml:Basin`
(get all gpml:Basin features)
- `gplately filter input_file output_file -t "gpml:IslandArc|gpml:Basin"`
(get all gpml:Basin and gpml:IslandArc features)
If you are using Docker, prefix `docker run gplates/gplately ` to the command, such as `docker run gplates/gplately gplately filter input_file output_file -t gpml:Basin`.
See https://github.com/GPlates/gplately/blob/master/tests-dir/unittest/test_feature_filter.sh for more examples.
Reset the feature type for the selected features. Run gplately reset_feature_type -h for details.
Examples:
- `gplately reset_feature_type -s gpml:ClosedContinentalBoundary -t gpml:UnclassifiedFeature input_file output_file`
(change all gpml:ClosedContinentalBoundary to gpml:UnclassifiedFeature)
- `gplately reset_feature_type -s "gpml:ContinentalFragment|gpml:Coastline" -t gpml:UnclassifiedFeature input_file output_file`
(change all gpml:ContinentalFragment and gpml:Coastline to gpml:UnclassifiedFeature)
- `gplately reset_feature_type -s ".*" -t gpml:UnclassifiedFeature input_file output_file`
(change all feature types to gpml:UnclassifiedFeature)
If you are using Docker, prefix `docker run gplates/gplately ` to the command, such as `docker run gplates/gplately gplately reset_feature_type -s ".*" -t gpml:UnclassifiedFeature input_file output_file`.
See https://github.com/GPlates/gplately/blob/master/tests-dir/unittest/test_reset_feature_type.sh for more examples.
Create age grids for a plate model. Run gplately agegrid -h for details.
Loads one or more input rotation files, fixes any crossovers and saves the rotations to output rotation files. Run gplately fix_crossovers -h for details.
Remove one or more plate IDs from a rotation model (consisting of one or more rotation files). Run gplately remove_rotations -h for details.
Remove any regular features not referenced by topological features. Run gplately cleanup_topologies -h for details.
Converts geometry in one or more input ascii files (such as '.xy' files) to output files suitable for loading into GPlates. Run gplately convert_xy_to_gplates -h for details.
Diagnose one or more rotation files to check for inconsistencies. Run gplately diagnose_rotations -h for details.
Resolve topological plate polygons (and deforming networks) and saves (to separate files) the resolved topologies, and their boundary sections as subduction zones, mid-ocean ridges (ridge/transform) and others (not subduction zones or mid-ocean ridges). Run gplately resolve_topologies -h for details.
Calculate stage rotations between consecutive finite rotations in plate pairs. Run gplately rotation_tools -h for details.
Split the geometries of isochrons and mid-ocean ridges into ridge and transform segments. Run gplately separate_ridge_transform_segments -h for details.
Find the convergence rates along trenches (subduction zones) over time. Run gplately subduction_convergence -h for details.
Retrieve paleomagnetic data from https://www.gpmdb.net, create GPlates-compatible VGP features and save the VGP features in a .gpmlz file. Run gplately gpmdb -h for details.