Package: gplately
GPlately was created to accelerate spatio-temporal data analysis leveragingpyGPlatesandPlateTectonicToolswithin a simplified Python interface. This object-oriented package enables the reconstruction of data through deep geologic time (points, lines, polygons, and rasters), the interrogation of plate kinematic information (plate velocities, rates of subduction and seafloor spreading), the rapid comparison between multiple plate motion models, and the plotting of reconstructed output data on maps. All tools are designed to be parallel-safe to accelerate spatio-temporal analysis over multiple CPU processors.GPlately requires a working installation of pyGPlates, which is freely
available athttps://www.gplates.org/download.
All major system architectures (e.g. Linux, MacOS, Windows) are supported and installation instructions
arewell documented.
Sample data is also available fromEarthByte servers, which
includes rasters, seafloor age grids, rotation files, and more to get started with plate reconstructions.CitationMather, 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},}DependenciespyGPlatesplate-model-manager>= 1.2.0ShapelyNumPy> 1.16SciPy> 1.0MatplotlibCartopy(for mapping)ShapelyPoochGeoPandasnetCDF4Installation1. Using conda (recommended)You can install the latest stable public release ofGPlatelyand all of its dependencies using conda.
This is the preferred method to installGPlatelywhich downloads binaries from the conda-forge channel.condainstall-cconda-forgegplatelyCreating a new conda environmentWe recommend creating a new conda environment inside which to installGPlately. This avoids any potential conflicts in your base Python environment. In the example below we create a new environment called "my-env":condacreate-nmy-env
condaactivatemy-env
condainstall-cconda-forgegplatelymy-envneeds to be activated whenever you useGPlately: i.e.conda activate my-env.2. Using pipAlternatively, you can install the latest stable public release ofGPlatelyusing the pip package manager.pipinstallgplatelyor from this GitHub repository:pipinstallgit+https://github.com/GPlates/gplately.gitPull from repositoryFirst-time installation:To install the latest version of GPlately from a specific repository branch (e.g.master), copy the following commands into your terminal:cd/path/to/desired/directory#Change your command directory to where you'd like to clone GPlatelygitclonehttps://github.com/GPlates/gplately.gitcdgplately# navigate within the gplately foldergitcheckoutmaster# or the name of whichever branch you needgitpull# fetch all recent changes from this branchpipinstall.Update installation from cloned repo:To update your installation of GPlately by fetching the latest pushes from a specific repository branch (e.g.master), copy the following commands into your terminal:cd/path/to/gplately/directory#Should be where gplately is cloned - must end in /.../gplatelygitcheckoutmaster# or the name of whichever branch you needgitpull# fetch all recent changes from this branchpipinstall.UsageGPlately uses objects to accomplish a variety of common tasks. The common objects include: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 teethTheDataServerobjectGPlately'sDataServerobject can be used to download:rotation modelstopology featuresstatic polygonscoastlinescontinentscontinent-ocean boundariesage grids and rastersgeological feature datafrom assorted plate reconstruction models. These files are needed to construct most ofGPlately's objects. For example,
we can download arotation model, a set oftopology featuresand somestatic polygonsfrom theMüller et al. 2019global Mesozoic–Cenozoic deforming plate motion model.gDownload=gplately.DataServer("Muller2019")rotation_model,topology_features,static_polygons=gDownload.get_plate_reconstruction_files()ThePlateModelManagerobject... was designed as a substitute ofDataServerobject. ThePlateModelManagerobject can be used to download and manage the plate reconstruction model files.pm_manager = PlateModelManager()
  model = pm_manager.get_model("Muller2019")
  model.set_data_dir("plate-model-repo")

  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,
  )ThePlateReconstructionobject... contains methods to reconstruct the positions of present-day feature data back through geological time. You can also use
it to calculate plate model data like topological plate velocities, or total trench and ridge lengths per Ma! You can create
the object by passing arotation model, a set oftopology featuresand somestatic polygons:model=gplately.PlateReconstruction(rotation_model,topology_features,static_polygons)Launch thePlate Reconstructionnotebook to see more.ThePointsobject... can be used to reconstruct the positions of geological point features and calculate their underlying plate velocities
through geological time.pt_lon=np.array([-107.662152,-58.082792,17.483189,133.674590,80.412876])pt_lat=np.array([48.797807,-12.654857,11.884395,-26.415630,31.368509])# Call the Points object: pass the PlateReconstruction object, and the latitudes and longitudes of the seed points!gpts=gplately.Points(model,pt_lon,pt_lat)TheRasterobject...can be used to read, resample and resize assorted raster data likenetCDF4seafloor age grids, continental grids and ETOPO
relief rasters. You can also reconstruct raster data back through geological time!etopo=gdownload.get_raster("ETOPO1_tif")raster=gplately.Raster(model,data=etopo,time=0,origin="upper",)white_rgb=(255,255,255)# RGB code for white, to fill gaps in outputreconstructed=raster.reconstruct(time=50,fill_value=white_rgb,threads=4,)Below is a plot of theETOPO1 global relief rasterat present day, and reconstructed to 50Ma:ThePlotTopologiesobject... can be used to visualise reconstructed feature geometries through time. To call the object, pass a set ofcontinents,coastlinesandCOBs(either as file paths or as<pyGPlates.FeatureCollection>objects), as well as aPlateReconstructionobject, and a reconstructiontime.coastlines,continents,COBs=gDownload.get_topology_geometries()time=50#MagPlot=gplately.plot.PlotTopologies(model,time,coastlines,continents,COBs)Below are some continents, coastlines, COBs, ridges and transforms, trenches, subduction teeth and
seafloor age grids plotted usingPlotTopologies!Sample workflowsTo see GPlately in action, launch a Jupyter Notebook environment and check out thesample notebooks:01 - Getting Started: A brief overview of how to initialise GPlately's main objects02 - Plate Reconstructions: Setting up aPlateReconstructionobject, reconstructing geological data through time03 - Working with Points: Setting up aPointsobject, 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 fields05 - Working with Feature Geometries: Processing and plotting assorted polyline, polygon and point data fromGPlates 2.3's sample data sets06 - Rasters: Reading, resizing, resampling raster data, and linearly interpolating point data onto raster data07 - Plate Tectonic Stats: UsingPlateTectonicToolsto 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 flowines of points on a tectonic plate to illustrate the plate's trajectory through geological time.10 - SeafloorGrid: Defines the parameters needed to set up aSeafloorGridobject, and demonstrates how to produce age and spreading rate grids from a set of plate reconstruction model files.API DocumentationDocumentation of GPlately's objects and methods can be foundhere!Command Line ToolsGPlately comes with a suite of useful command line tools. These tools are designed as GPlately subcommands. Rungplately -hto show the list of tools.combineCombine multiple feature collections into one. Rungplately combine -hfor details.filterFilter feature collection by various criteria. See scripts/test_feature_filter.sh for usage examples. Runglately filter -hfor details.agegrid (ag)Create age grids for a plate model. Runglately agegrid -hfor details.fix_crossoversLoads one or more input rotation files, fixes any crossovers and saves the rotations to output rotation files. Rungplately fix_crossovers -hfor details.remove_rotationsRemove one or more plate IDs from a rotation model (consisting of one or more rotation files). Rungplately remove_rotations -hfor details.cleanup_topologiesRemove any regular features not referenced by topological features. Rungplately cleanup_topologies -hfor details.convert_xy_to_gplatesConverts geometry in one or more input ascii files (such as '.xy' files) to output files suitable for loading into GPlates. Rungplately convert_xy_to_gplates -hfor details.diagnose_rotationsDiagnose one or more rotation files to check for inconsistencies. Rungplately diagnose_rotations -hfor details.resolve_topologiesResolve 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). Rungplately resolve_topologies -hfor details.rotation_toolsCalculate stage rotations between consecutive finite rotations in plate pairs. Rungplately rotation_tools -hfor details.separate_ridge_transform_segmentsSplit the geometries of isochrons and mid-ocean ridges into ridge and transform segments. Rungplately separate_ridge_transform_segments -hfor details.subduction_convergenceFind the convergence rates along trenches (subduction zones) over time. Rungplately subduction_convergence -hfor details.gpmdbRetrieve paleomagnetic data fromhttps://www.gpmdb.net, create GPlates-compatible VGP features and save the VGP features in a .gpmlz file. Rungplately gpmdb -hfor details.