R Practice - [rgplates] Installation, Introduction, Getting Started

1. rgplates installation

1.1 easy way

install.packages("rgplates")

1.2 Recording method

• Install stable version from GITHUB

install.packages(
    "https://github.com/adamkocsis/rgplates/raw/main/_archive/source/rgplates_0.2.1.tar.gz", 
    repos=NULL, type="source")

• Installing the development version from GitHub
  If you encounter technical issues with a package that is not described anywhere, you may want to check out the development version .

If you wish to install the development version, I recommend installing it manually:

1. Clone the repository to your local hard drive.
2. Open a terminal and navigate to the directory you cloned. From there you should see the rgplates directory.
3. run this line in terminal

R CMD INSTALL rgplates

• If you see an error that R was not found, you must add it to your PATH environment variable.
• If the R package that rgplates depends on is not installed, it must be installed manually, otherwise an error will be reported.

2. Introduction to rgplates

Out of the box, the package relies on GPlates Web Services (GWS) , an online service that performs paleogeographic reconstructions using data provided in URLs. rgplates (1) sends the data to GWS, GWS (2) calculates paleocoordinates, and then (3) rgplates reads the returned results. To use this online service, you must be connected to the Internet.

3. Getting Started with the rgplates Online Method

3.1 Load rgplates

Before using, load this package

library(rgplates)

Once loaded, rgplates automatically loads the Simple Features for R (sf) package , a standard R package for working with vector spatial data.

3.2 Plate reconstruction

All paleo coordinate reconstructions are done with the reconstruct() function. The default model it uses is that of the PALEOMAP project developed by C. Scotese .

Every tectonic model relies on plates rotating across the Earth's surface. Plate positions can be reconstructed to any age covered by the model. The current position of the plates can be queried using the reconstruct() function, passing the string "plates" as the first argument and setting the target age to 0 (in Ma).

pl0 = reconstruct("plates", age=0)
pl0

Simple feature collection with 501 features and 0 fields
Geometry type: POLYGON
Dimension:     XY
Bounding box:  xmin: -180 ymin: -90 xmax: 180 ymax: 90
Geodetic CRS:  WGS 84
First 10 features:
                         geometry
1  POLYGON ((-155.2068 19.5404...
2  POLYGON ((-77.6715 24.7979,...
3  POLYGON ((-77.6715 24.7979,...
4  POLYGON ((-71.9396 20.9241,...
5  POLYGON ((-78.3856 27.3354,...
6  POLYGON ((-180 90, 180 90, ...
7  POLYGON ((164.2599 89.0123,...
8  POLYGON ((-106.0379 21.2018...
9  POLYGON ((-112.1621 28.3617...
10 POLYGON ((-108.7002 23.7579...

The gplates package relies on sf to work with vector spatial data - such as plates. You can do with it anything you would normally do with an sf object: manipulate it, change its map projection, export or use it for calculations. The data is a standard equirectangular projection with longitude and latitude data.

You can plot plate distributions using the plot() function. To focus on the spatial data rather than the attributes of the feature (technical in nature), you can plot the geometry of that object.

plot(pl0$geometry)

Setting the age parameter allows you to access the state of plate tectonics at past points in time. Age accepts a date in millions of years. To reconstruct plate positions near the Triassic/Jurassic boundary (around 200Ma), you have to set the age parameter to 200:

pl200 = reconstruct("plates", age=200)
pl200

Simple feature collection with 142 features and 0 fields
Geometry type: POLYGON
Dimension:     XY
Bounding box:  xmin: -180 ymin: -77.0625 xmax: 180 ymax: 90
Geodetic CRS:  WGS 84
First 10 features:
                         geometry
1  POLYGON ((17.3375 17.8127, ...
2  POLYGON ((-19.2369 72.1231,...
3  POLYGON ((-19.3706 71.9604,...
4  POLYGON ((-19.3706 71.9604,...
5  POLYGON ((-2.4637 32.5774, ...
6  POLYGON ((-19.7326 72.67, -...
7  POLYGON ((-19.7326 72.67, -...
8  POLYGON ((-19.6809 73.003, ...
9  POLYGON ((-18.0301 72.7282,...
10 POLYGON ((-18.6014 71.6729,...

You can plot the result in a similar fashion:

plot(pl200$geometry)

Note that unlike today's (0Ma) results, past plate configurations do not return oceanic plates. (Most models do not return oceanic plates, which is a feature of the PALEOMAP model)

Likewise, both pl0 and pl200 objects are objects of class sf. You can customize their drawing just as you would any other sf object - for example setting a fill color for polygons without drawing their borders.

plot(pl200$geometry, col="gray", border=NA)

3.3 Independent location coordinates

That's fine, but that's about all there is to drawing tiles individually. The real use of reconstruct() is to be able to calculate the paleo coordinates of the current location at a given age.

3.3.1 A single existing coordinate point

Let's consider the location of London! Whether it is in the website or using the user interface of Google Maps, you can find the coordinates of the city center at about 51.52 (latitude) north latitude and 0.38 (longitude) west longitude. In order to find out where the city is on the Triassic/Jurassic boundary, you need to:(1) enter these coordinates in R; and (2) provide them to the reconstruct() function.

Note that we are dealing with approximate coordinates on a global scale here. For more accurate results, always make sure the CRS of the points matches the CRS of the map (including ellipses)!

Because in the commonly used equirectangular projection, the x-axis of the plot is longitude and the y-axis is latitude, we usually record the coordinates first in the order of longitude and then in the order of latitude (East longitude and north latitude are recorded as positive values ).

To make this structure absolutely clear, it's best to enter the coordinates as a two-column matrix, with the first being longitude and the second being latitude:

london = c(-0.38, 51.52)
londonMat = matrix(london, ncol=2, byrow=TRUE)
colnames = c("long", "lat")
londonMat

      [,1]  [,2]
[1,] -0.38 51.52

Because the map's coordinate reference system (CRS) is longitude-latitude, you can use these coordinates to represent the city's location x directly on the current map with a point(), in this case a red plus sign:

plot(pl0$geometry)
points(londonMat, col="red", pch=3)

3.3.2 Ancient coordinates of a single point

Finding the paleo-coordinates of these sites is as simple as calculating the coordinates of the plates. You must use the previously defined matrix (londonMat) as the first argument to reconstruct() ("plates" was given earlier), and provide the target age in millions of years:

londonMat200 = reconstruct(londonMat, age=200)
londonMat200

     paleolong paleolat
[1,]    2.3267  38.1654

The result of this calculation is a similar matrix: includes paleolongitude and paleolatitude columns. If you provide the coordinates as a normal matrix, the coordinates are inferred as longitude and latitude.

You can visualize this the same way you visualize the current location of the place:

plot(pl200$geometry, col="gray", border=NA)
points(londonMat200, col="red", pch=3)

3.3.3 Ancient coordinates of multiple points

If multiple locations are to be reconstructed, simply provide more rows in the matrix. For example, if you also wanted to calculate the locations of Sydney, Australia (33.85°S, 151.11°E) and Montreal, Canada (45.52°N, 73.61°W), you would need to add those locations in a similar fashion.

sydney = c(151.17, -33.85)
montreal = c(-73.61, 45.52)
cities = rbind(london, sydney, montreal)
colnames(cities) = c("long", "lat")

Now that we have our longitude and latitude matrix, all we need to do is use it as the first argument to the reconstruct() function:

cities200 = reconstruct(cities, age=200)

Note that the order of entities remains unchanged. We can draw these maps in a similar way to individual cities.

plot(pl200$geometry, col="gray", border=NA)
points(cities200, col="red", pch=3)

3.4 The coastline today

Some models, including the PaleoMAP model, allow you to access the reconstructed location of the coastline today, which may help you better locate reconstructed plates. You can get this data if you pass the string "coastlines" as the first argument to the reconstruct() function:

coast200 = reconstruct("coastlines", age=200)

This will return an sf class object, similar to plates. You can use plot() to visualize these and plot them on top of other maps, but you must set add=TRUE, otherwise a new plot will be created.

plot(pl200$geometry, col="gray", border=NA)
points(cities200, col="red", pch=3)
plot(coast200$geometry, add=TRUE)

3.5 Other reconstruction models

If you look at the details of the reconstruct() reference , you'll see that the model parameters can be set to other strings besides "PALEOMAP". These represent additional models that can be accessed through the GPLates web service. For example, if you want to use the Seton et al. 2012 model to perform the same calculations at 200Ma to reconstruct the position of the plate, all you have to do is set model="SETON2012":

pl200seton = reconstruct("plates", age=200, model="SETON2012")

You can compare this result to the PALEOMAP model by plotting this result on top of the result with some transparency (eg semi-transparent red in HTML RGBA: " #FF000077 "):

plot(pl200$geometry, col="gray", border=NA)
plot(pl200seton$geometry, col="#FF000077", add=TRUE, border=NA)

You can see that the two reconstructions are quite different, and this becomes more apparent over time. Also, through the transparency, you can see how the plates overlap in areas of convergence.

3.6 Disadvantages of online methods

Although easy to set up, the online method has several limitations. For more complete control over the rotation, you might want to try the offline method.

If you want to stick with the online method, you need to be aware of the following limitations:

3.6.1 Decimal places and data quality

Data for online methods are passed to GWS via URL, which imposes some technical constraints on reconstruction. The first constraint isAge must be rounded to a whole number, which may affect the quality of the results.

The second potential problem is that,The amount of data that can be transferred is somewhat limited. This is fine for hundreds of points, but for reconstructing thousands of coordinates, you'll definitely want to use an offline method.

Offline methods can handle ages like 17.24 Ma without problem, and any amount of data.

3.6.2 Pre-built models

While the online method is easy to set up, theIt uses a predefined model to actually perform the reconstruction. If you want to use custom or other models that GWS has not yet implemented, you will need to use the offline method.

3.6.3 Network connection

Since calculations are not performed on your computer, but by the server hosting GWS, theThis method will not work if you do not have an internet connection. Also, if you think about reproducibility, it's easy to see that you have no control over whether the service will still be available in the future.

There are docker containers that allow you to instantiate GWS which might help with this - but if you really want to make sure your code stays reproducible - you might want to try the offline approach.

3.6.4 Other options

You can also customize some other options that are not exposed in GWS for you to set, which may affect your results.

4. Getting started with rgplates offline method

While online reconstruction methods can help with fast calculations, the real power of the rgplates package lies in what we call offline reconstruction methods.

4.1 Introduction

The offline method does not rely on a connection to the GPlates web service , but instead allows you to perform plate tectonic rotations locally on your computer. For this, you need two things on your computer in addition to the rgplates package:

• GPlates desktop application for reconstruction calculations
• Actual construction model files for reconstruction.

4.2 GPlates desktop application

GPlates is currently the standard program we use to build, manipulate and apply plate tectonic reconstructions. GPlates has a very well developed graphical user interface (GUI) that you can use independently from anything in this tutorial. If you want to learn more about GPlates, you can find a lot of material here .

In order to use GPlates' offline methods, you don't have to leave the R environment or use gplates' GUI. You just need to make sure you have the application installed on your computer and rgplates will take care of the rest.

4.2.1 GPlates installation

In addition to installing the rgplates package, you must also have the gplates desktop application installed on your computer. After seeing which file is required for your operating system, you must scroll down to the bottom of the page, select the file you wish to download, and follow the instructions.

This has been tested on all major operating systems (Windows, Mac, and GNU/Linux) and has worked reliably on gplates versions 2.2 and 2.3. rgplates will be able to find out-of-the-box installations of GPlates on Mac and GNU/Linux. As long as you install GPlates into the default installation directory, you should have no problems on Windows (don't change the suggested content during installation - unless you're asking for trouble!)

4.3 Construction model

To use the offline method, you must have a construction model on your computer. Actually, there is no such thing as a model of plate tectonics. From a technical point of view, each model contains at least two data items:

• the Partitioning polygons
• and the Reconstruction tree (aka. rotation file)

Segmented polygons are vector spatial data (polygons) that represent the distribution of tectonic plates today. GPlates moves these polygons on the Earth's surface by rotation, as described in Reconstructing Trees. These are usually developed together (we usually call them models), but they are stored separately in different files. In other words, GPlates is just the program that does the rotation/reconstruction, but you also need to have the file

The online method relies on files on the GPlates web service server. For example, the segmented polygons of ancient map models are visible if you only ask for "plates", which are today's age (i.e. 0Ma).

partPol = reconstruct("plates", age=0)
plot(partPol$geometry)

In order to use the offline method, we need

• Having both partition polygons and reconstructed trees on our computer
• denote them with R
• Pass them to the reconstruct() function

4.4 PALEOMAP model file

To simplify the first experiments, we will use the model files from the PaleoMAP project distributed with the rgplates package.

These files are located in the package's installation directory in the zip archive. What we have to do is:

• Create a new temporary directory to store our model files
• unzip the model files there, and
• Load them into R.

Note: There are easier ways to take these files and represent them into R in other ways (such as using the chronosphere, which we will investigate in Tutorial 4.) But for teaching purposes, I recommend doing this first with The operation is as follows.

4.4.1 Create a temporary folder

The temp directory is the best place to store temporary data, files, created during calculations and not needed outside of an R session (of course you don't need to store these here, you can use any directory on your computer).

Temporary directories are easy to create, you just need to use the tempdir() function, it will create such a directory for you and tell you where to find it:

td = tempdir()

[1] "C:\\Users\\bailo\\AppData\\Local\\Temp\\RtmpgRghHL"

Each OS handles these differently, so don't be surprised if yours doesn't match the results above - in fact, when you run the function above, things are different in each session may be different.

4.4.2 Unzip the model file

The model files are large, larger than recommended by the CRAN guidelines, so they must be compressed. We will have to unzip them using the unzip() function - but first we have to find their location.

The installation path of an R package can be found using the system.file() function.

rgPath = system.file(package="rgplates")

[1] "D:/ALL_Softwares/R-4.2.0/library/rgplates"

You can confirm this is the correct path by listing the contents of that directory with list.files()

list.files(rgPath)

 [1] "CITATION"     "DESCRIPTION"  "extdata"      "help"         "html"         "INDEX"       
 [7] "MD5"          "Meta"         "NAMESPACE"    "NEWS.md"      "R"            "rgplates.pdf"

The model data is located in the extdata directory, in the archive paleomap_v3.zip. We have to find this archive and extract it to a temporary directory (exdir parameter)

unzip(file.path(rgPath,"extdata/paleomap_v3.zip"), exdir=td)

You can confirm that the extraction actually happened by looking in the temp directory:

list.files(file.path(td))

 [1] "20e8cc60218b4655a3881a246b5b14f2.png"            
 [2] "3d5d7aba18ec4ea09ad3afe6d6c3ab4f.png"            
 [3] "617dc5e784fb413bb4f181837cd7bf7b.png"            
 [4] "9b9c99ee368f4989bfb89c9755d96e87.png"            
 [5] "c1e2330ed82e491fbb8afd581c4af79e.png"            
 [6] "d44dcec927d64eb99923a4da09e245cd.png"            
 [7] "ded46f127eb44d17a1b85ecdbbcd66f5.png"            
 [8] "ef2d31134c49404684bf9638119de99c.png"            
 [9] "ffad242897fd47839324f4fa08c96d63.png"            
[10] "PALEOMAP_PlateModel.rot"                         
[11] "PALEOMAP_PlatePolygons.gpml"                     
[12] "PALEOMAP_PoliticalBoundaries.gpml"               
[13] "rs-graphics-9d334d49-dded-4ee1-be86-5b71e69d6008"

Two files are important to us: one ending in .gpml (partition polygons in GPlates markup language format) and one ending in .rot (rebuild tree/rotate files). We know the absolute paths to these files and they can be found at:

pathToPolygons = file.path(td, "PALEOMAP_PlatePolygons.gpml")
pathToRotations = file.path(td, "PALEOMAP_PlateModel.rot")

> pathToPolygons
[1] "C:\\Users\\bailo\\AppData\\Local\\Temp\\RtmpgRghHL/PALEOMAP_PlatePolygons.gpml"
> pathToRotations
[1] "C:\\Users\\bailo\\AppData\\Local\\Temp\\RtmpgRghHL/PALEOMAP_PlateModel.rot"

4.5 Plate model class

Now that we have the files and know how to find them, we have represented them in R somehow, so we can indicate that we want to use them with GPlates for plate tectonic reconstructions.

We need to create a platemodel class object to do this. All we need to provide are the paths to these files, for the partition polygon and rotation files respectively:

pm = platemodel(polygons = pathToPolygons,
                rotation = pathToRotations)

GPlates plate tectonic model.
static polygons:  "PALEOMAP_PlatePolygons.gpml" 
rotation:         "PALEOMAP_PlateModel.rot" 

This is a PlateModel class object, which is really just a wrapper around the actual location of the file.
Now is a good time to mention that this is where the real flexibility of the offline approach comes in. You can use any third-party model file here, as long as you provide the appropriate absolute path to the file, the approach below should work. See details below

4.6 Rebuild Plates

The reconstruction itself works in the same way as the online method, the only difference is that we will use the platemodel class object pm instead of using strings as model parameters ("PALEOMAP" by default).

Below is the plate reconstructed for 200Ma using the PaleoMAP model - now calculated using the offline method:

pl0ff200 = reconstruct("plates", age=200, model=pm, path.gplates="D:/ALL_Softwares/GPlates/gplates-2.2.0.exe")

Note that this is an sf-like object similar to the one we saw earlier in the online method, although it has more properties. However, you can visualize it in the same way using plot().

plot(pl0ff200$geometry, border=NA, col="gray")

4.7 Reconstruction site

The location of the reconstruction points is similar to the online method. Again, the only difference is that you must provide a platemodel object as a model parameter. Here's an example of computing and visualizing past positions of some cities before, now using an offline method:

First, we fetch the location data:

london = c(-0.38, 51.52)
sydney = c(151.17, -33.85)
montreal = c(-73.61, 45.52)

cities = rbind(london, sydney, montreal)
colnames(cities) = c("long", "lat")

           long    lat
london    -0.38  51.52
sydney   151.17 -33.85
montreal -73.61  45.52

Second, we reconstruct with our model

cities200 = reconstruct(cities, age=200, model=pm, path.gplates="D:/ALL_Softwares/GPlates/gplates-2.2.0.exe")

               long       lat
london     2.326686  38.16536
sydney    79.175489 -60.67032
montreal -20.890271  26.08778

Then we plot:

plot(pl0ff200$geometry, col="gray", border=NA)
points(cities200, col="red", pch=3, add=TRUE)

4.8 Other ways to obtain model files

Model files are available from the EarthByte resource page. For example, the files for the paleoatlas model we used here are available at https://www.earthbyte.org/paleomap-paleoatlas-for-gplates/ .

At the bottom of the page you will find a link: Link to rasters, reconstruction files and tutorial, from which you can download the Scotese_Paleoatlas_v3.zip file. In this zip file, in the PALEOMAP Global Plate Model directory, you can see the same files we had earlier.

These files, or any similar files, can be used to create a PlateModel object as long as the absolute path to the file is provided.

4.9 chronosphere

As you can see, working with these files is rather tedious, and we, the developers of rgplates , rarely use them in this way. In practice, we recommend using the offline rgplates method and chronosphere, which you can learn more about in the next tutorial.

5. Use the data obtained by chronosphere to reconstruct

Originally, all functionality in rgplates was developed in the chronosphere project. However, the functionality of these modules has diverged since the project's inception: rgplates contains functionality to perform plate tectonic reconstructions in R, while chronosphere is a data distribution and versioning system. These two are associated with construction model data: we will download this data and import it into chronosphere and use it with rgplates.

5.1 Loading packages

library(rgplates)
library(chronosphere)

To indicate which functions we called, we will use the :: operator. This operator allows us to indicate which package we want to use the function from.

5.2 Download data

A detailed tutorial on how to use chronosphere-portal will be provided later. For now, we just need to know how to access the platemodel class object.

Downloading data from the chronosphere is easy: all you need is one line of code, and the appropriate ID for the data you choose. To download the tectonic model (plate polygons and reconstruction tree) we used earlier (PaleoMAP model), we just need this command:

pm = chronosphere::fetch(dat="paleomap", var="model", ver="v3-GPlates")

GPlates plate tectonic model.
PALEOMAP plate tectonic reconstruction files (C. Scotese) 
 - v3 (GPlates resource) 
static polygons:  "PALEOMAP_PlatePolygons.gpml" 
rotation:         "PALEOMAP_PlateModel.rot" 

The arguments to chronosphere::fetch() are the dataset (dat), variable (var) and version (ver) IDs of the items you want to download.

5.3 Actual reconstruction

We can immediately use it with offline reconstruction methods.

pl400 = rgplates::reconstruct("plates", age=400, model=pm,
                              path.gplates="D:/ALL_Softwares/GPlates/gplates-2.2.0.exe")

plot(pl400$geometry, col="gray", border=NA)

5.4 Conclusion

With three lines of code, we downloaded the construction information, calculated the rotation and drew the reconstructed geometry.

This is how we originally intended to use the offline method of the reconstruct() function, and this is what we recommend adopting as a general workflow.

Note that we intend to add as many models as possible to chronosphere, which is being overhauled to make it as flexible and useful as possible. However, retaining all currently available data and maintaining all functionality will not be easy - but it is expected to be completed by the first half of 2023.