Command Line Interface (CLI)

GPlately comes with a collection of useful command-line tools, each designed as a subcommand of GPlately.

Note

Run gplately -h to see a list of available subcommands.
Run gplately one-of-the-subcommands -h to see the usage of the given subcommand. For example, gplately list -h.

list 

Show a list of available plate reconstruction models. If a model name is given, show the details about this model.

👉 list all available plate reconstruction models

$ gplately list

👉 show details about model merdith2021

$ gplately list -m merdith2021

If you are using GPlately Docker image, run these commands.

$ docker run gplates/gplately gplately list
$ docker run gplates/gplately gplately list -m merdith2021

combine 

Combine multiple feature collections into one.

👉 combine three feature collections into one file output_file.gpmlz

$ gplately combine input_file_1.shp input_file_2.gpmlz input_file_3.gpml output_file.gpmlz

filter 

Filter feature collection by various criteria and save the result to the output_file.

👉 only keep features whose name contains “Africa” or “North America”

$ gplately filter input_file output_file -n Africa "North America"

👉 only keep features whose plate ID is one of “701 714 715 101”

$ gplately filter input_file output_file -p 701 714 715 101

👉 only keep features whose birth age is older than 500Myr

$ gplately filter input_file output_file --min-birth-age 500

👉 only keep features whose birth age is younger than 500Myr

$ gplately filter input_file output_file --max-birth-age 500

👉 only keep 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 -n Africa "North America" -p 701 714 715 101 --min-birth-age 500

👉 only keep gpml:Basin features

$ gplately filter input_file output_file -t gpml:Basin

👉 only keep gpml:Basin and gpml:IslandArc features

$ gplately filter input_file output_file -t "gpml:IslandArc|gpml:Basin"

Note

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.

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.

agegrid (ag)

Generate age grids for a plate reconstruction model.

👉 create age grids from 10Ma to 0Ma with 1Myr increment for the merdith2021 reconstruction mode

$ gplately ag output -m merdith2021 -e 0 -s 10

👉 create age grids from 10Ma to 0Ma with 1Myr increment using the specified reconstruction files

$ gplately ag rotations.rot topologies.gpmlz output -c continental_polygons.gpmlz -e 0 -s 10

fix_crossovers 

Fixes crossovers in rotation file(s).

👉 fix crossovers in two rotation files with a threshold 0.01 degree and ignore plate ID 201 and 701

$ gplately fix_crossovers -d -c 0.01 -i 201 701 -- input_rotations1.rot input_rotations2.rot

remove_rotations 

Remove one or more plate IDs from a rotation model (consisting of one or more rotation files).

👉 remove plate IDs 70,4,3 and 1 from a rotation file

$ gplately remove_rotations -p 70 4 3 1 -o removed_ref_frames_ -- rotations.rot

cleanup_topologies 

Remove any regular features not referenced by topological features.

👉 remove all features which are not referenced by any topological feature from topologies.gpml

$ gplately cleanup_topologies -o cleanup_topologies_ -- topologies.gpml

convert_xy_to_gplates 

Converts geometry in one or more input ascii files (such as ‘.xy’ files) to output files suitable for loading into GPlates.

👉 convert two .xy file into a shapefile

$ gplately convert_xy_to_gplates -e shp -- input1.xy input2.xy

diagnose_rotations 

Diagnose one or more rotation files to check for inconsistencies.

👉 check two rotation files and print the diagnostic results on screen

$ gplately diagnose_rotations input_rotations1.rot input_rotations2.rot

resolve_topologies 

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

👉 resolve topologies at 10Ma

$ gplately resolve_topologies -r rotations1.rot rotations2.rot -m topologies1.gpml topologies2.gpml -t 10

rotation_tools 

Calculate stage rotations between consecutive finite rotations in plate pairs.

👉 calculate stage rotations for moving plate 701 relative to the fixed plate 0

$ gplately rotation_tools -p 701 0 -o stage_ -- rotations.rot

separate_ridge_transform_segments 

Split the geometries of isochrons and mid-ocean ridges into ridge and transform segments.

👉 pick out ridge and transform features from the file spreading_features.gpml

$ gplately separate_ridge_transform_segments -r rotations.rot -d 45 -s _ridges -t _transforms -- spreading_features.gpml

subduction_convergence 

Find the convergence rates along trenches (subduction zones) over time.

👉 calculate the convergence rates along subduction zones from 200Ma to 0Ma

$ gplately subduction_convergence -r rotations.rot -m topologies.gpml -t 0 200 -i 1 -v 1 -d 0.5 -e xy -- convergence

gpmdb 

Retrieve the paleomagnetic data from the GPMDB website, create GPlates-compatible VGP features and save them in a .gpmlz file.

👉 download the paleomagnetic data and generate GPlates-compatible VGP features using the zahirovic2022 reconstruction model

$ gplately gpmdb -m zahirovic2022 -o vgp.gpmlz