Type: Package
Title: R Interface for the GPlates Web Service and Desktop Application
Version: 0.6.0
Description: Query functions to the GPlates https://www.gplates.org/ Desktop Application and the GPlates Web Service https://gws.gplates.org/ allow users to reconstruct past positions of geographic entities based on user-selected rotation models without leaving the R running environment. The online method (GPlates Web Service) makes the rotation of static plates, coastlines, and a low number of geographic coordinates available using nothing but an internet connection. The offline method requires an external installation of the GPlates Desktop Application, but allows the efficient batch rotation of thousands of coordinates, Simple Features (sf) and Spatial (sp) objects with custom reconstruction trees and partitioning polygons. Examples of such plate tectonic models are accessible via the chronosphere https://cran.r-project.org/package=chronosphere. This R extension is developed under the umbrella of the DFG (Deutsche Forschungsgemeinschaft) Research Unit TERSANE2 (For 2332, TEmperature Related Stressors in ANcient Extinctions).
License: CC BY 4.0
Date: 2025-04-26
URL: https://gplates.github.io/rgplates/
BugReports: https://github.com/gplates/rgplates/issues
Encoding: UTF-8
LazyData: true
Depends: R (≥ 3.5.0), sf
Imports: methods, utils
NeedsCompilation: no
RoxygenNote: 7.3.1
Suggests: knitr, rmarkdown, chronosphere, httr2, geojsonsf, sp, terra
Packaged: 2025-04-25 22:06:43 UTC; adam
Author: Adam T. Kocsis ORCID iD [cre, aut], Nussaibah B. Raja ORCID iD [ctb], Simon Williams ORCID iD [ctb], Elizabeth M. Dowding ORCID iD [ctb], Deutsche Forschungsgemeinschaft [fnd], FAU GeoZentrum Nordbayern [fnd]
Maintainer: Adam T. Kocsis <adam.t.kocsis@gmail.com>
Repository: CRAN
Date/Publication: 2025-04-25 22:20:02 UTC

R Interface for the GPlates Web Service and Desktop Application

Description

Query functions to the GPlates <https://www.gplates.org/> Desktop Application and the GPlates Web Service <https://gws.gplates.org/> allow users to reconstruct coordinates, static plates, Simple Features and Spatial objects without leaving the R running environment. This R extension is developed under the umbrella of the DFG (Deutsche Forschungsgemeinschaft) Research Unit TERSANE2 (For 2332, TEmperature Related Stressors in ANcient Extinctions).

Details

This is still the Beta version. As is R, this is free software and comes with ABSOLUTELY NO WARRANTY. Nevertheless, notes about found bugs and suggestions are more than welcome.

Author(s)

Adam T. Kocsis (adam.t.kocsis@gmail.com), Nussaibah B. Raja, Simon Williams and Elizabeth M. Dowding

See Also

Useful links:

Return and set the remote URL for the GPlates Web Service

Description

This set of functions allows the configuration of the remote URL, so the R client package can be used with a different instance of the GPlates web service, including a local implementation (served on localhost).

The function will use the http get method to access the version number of the GPlates Web Service.

Usage

getgws()

setgws(url = "", check = TRUE, reset = FALSE, silent = FALSE)

checkgws(silent = FALSE)

Arguments

url

(character) A single string specifying the URL of the GPlates Web Service (with trailing slash).

check

(logical) Flag to specify whether the immediate querying of the GWS is to be performed? If this fails the url won't be set!

reset

(logical) Flag to specify whether the factory default should be reset.

silent

Logical flag indicating wheth the output should be silent?

Details

The getws function returns the current url of the GPLates Web Service (defaults to: https://gws.gplates.org/). The setws function allows the setting of GPLates Web Service URL.

Value

getws returns a single character string with the URL of the GWS.

Invisible return, either FALSE, or a character string with the version number.

Examples

# Access currently set remote URL.
getgws()
# In case you have the GWS running on localhost (default port 18000):
# At time of writing this, the local instance does not return version, checking
# does not work!
setgws("http://localhost:18000/", check=FALSE)
# To reset factory defaults
setgws(reset=TRUE, check=FALSE)

Valid reconstructable feature collections of the GPlates Web Service

Description

This is version 1.2. The object contains valid returns of GWS v1.0.0, as of 2025-03-14.

Usage

data(gws)

Format

A data.frame with 5 variables and 26 observations.

Details

The valid return combinations for selected models and feature collections are copied from https://gwsdoc.gplates.org/models.

model

The name of the reconstruction model.

feature

The name of the feature collection.

from

The oldest reconstruction age accepted by the model to return the feature collection.

to

The youngest reconstruction age accepted by the model to return the feature collection.

description

The short description of the feature collection.

Function to quickly draft the edge of the equirectangular projection

Description

Function to plot the edge of a map with different projections.

Usage

mapedge(
  x = 360,
  y = 180,
  xmin = -180,
  xmax = 180,
  ymin = -90,
  ymax = 90,
  out = "sf"
)

Arguments

x

(numeric) Number of segments in the x (longitude) dimension.

y

(numeric) Number of segments in the y (latitude) dimension.

xmin

(numeric) Minimum value of x (longitude).

xmax

(numeric) Minimum value of x (longitude).

ymin

(numeric) Maximum value of y (latitude).

ymax

(numeric) Maximum value of y (latitude).

out

(character) Output format, either "sf" or "sp". The default "sf" returns simple feature geometries, "sp" returns SpatialPolygons from the sp package.

Value

An sfc-, or SpatialPolygons-class object.

Examples

# requires rgdal
edge <- mapedge()
molledge <- st_transform(edge, "ESRI:54009")
plot(molledge)

Class of objects representing plate tectonic models

Description

Meta-object containing paths to a unique plate tectonic model

Usage

## S4 method for signature 'platemodel'
initialize(
  .Object,
  rotation = NULL,
  features = NULL,
  name = NULL,
  polygons = NULL
)

Arguments

.Object

Constructor argument (not needed).

rotation

(character) The path to the rotation file.

features

(character) Named vector of features with the paths to the individual files.

name

(character) (Optional) name of the model.

polygons

(character) (Deprecated) The path to the static plate polygon file.

Value

A platemodel class object.

Examples

# path to provided archive
archive <- file.path(
  system.file("extdata", package="rgplates"), 
  "paleomap_v3.zip")
# extract to temporary directory
unzip(archive, exdir=tempdir())
# path to the rotation file
rotPath <- file.path(tempdir(), 
  "PALEOMAP_PlateModel.rot")
# path to the polygons
polPath <- file.path(tempdir(), 
  "PALEOMAP_PlatePolygons.gpml")
# register in R - to be used in reconstruct()
model <- platemodel(rotation=rotPath, features=c("static_polygons"=polPath))

Reconstruct geographic features

Description

Reconstruct the geographic locations from present day coordinates and spatial objects back to their paleo-positions. Each location will be assigned a plate id and moved back in time using the chosen reconstruction model.

Usage

reconstruct(x, ...)

## S4 method for signature 'matrix'
reconstruct(
  x,
  age = 0,
  model = "MERDITH2021",
  from = 0,
  listout = TRUE,
  verbose = FALSE,
  enumerate = TRUE,
  chunk = NULL,
  reverse = FALSE,
  path.gplates = NULL,
  cleanup = TRUE,
  dir = NULL,
  plateperiod = NULL,
  partitioning = "static_polygons",
  check = TRUE,
  warn = TRUE,
  anchor = 0,
  validtime = TRUE
)

## S4 method for signature 'data.frame'
reconstruct(x, ...)

## S4 method for signature 'numeric'
reconstruct(x, ...)

## S4 method for signature 'character'
reconstruct(
  x,
  age,
  model = "MERDITH2021",
  listout = TRUE,
  verbose = FALSE,
  path.gplates = NULL,
  cleanup = TRUE,
  dir = NULL,
  partitioning = "static_polygons",
  check = TRUE,
  anchor = 0
)

## S4 method for signature 'Spatial'
reconstruct(
  x,
  age,
  model,
  listout = TRUE,
  verbose = FALSE,
  path.gplates = NULL,
  cleanup = TRUE,
  dir = NULL,
  plateperiod = NULL,
  partitioning = "static_polygons",
  check = TRUE,
  validtime = TRUE
)

## S4 method for signature 'sf'
reconstruct(
  x,
  age,
  model,
  listout = TRUE,
  verbose = FALSE,
  path.gplates = NULL,
  cleanup = TRUE,
  dir = NULL,
  plateperiod = NULL,
  gmeta = FALSE,
  partitioning = "static_polygons",
  check = TRUE,
  validtime = TRUE
)

## S4 method for signature 'SpatRaster'
reconstruct(
  x,
  age,
  model,
  from = 0,
  listout = TRUE,
  verbose = FALSE,
  plateperiod = NULL,
  check = TRUE,
  validtime = TRUE
)

Arguments

x

The features to be reconstructed. Can be a vector with longitude and latitude representing a single point or a matrix/dataframe with the first column as longitude and second column as latitude. For the online subroutine, the character strings "static_polygons", "coastlines" and "plate_polygons" return static plate polygons, rotated present-day coastlines and topological plates, respectively. For the offline subroutine, it can be a name of the feature set defined in the model object. Some Spatial*, sf and SpatRaster classes are also accepted, although this input is still experimental.

...

arguments passed to class-specific methods.

age

(numeric) is the target age in Ma at which the feature will be reconstructed. Defaults to 0 Ma.

model

(character or platemodel) The reconstruction model. The class of this argument selects the submodule used for reconstruction, a character value will invoke the remote reconstruction submodule and will submit x to the GPlates Web Service. A platemodel class object will call the local-reconstruction submodule. The default is "PALEOMAP". See details for available models.

from

(numeric) The original age of the features to be reconstructed. A single value, defaults to 0Ma. Only used with the online reconstruction module.

listout

(logical)If multiple ages are given, the output can be returned as a list if listout = TRUE.

verbose

(logical) Should call URLs (remote submodule) or console feedback (local-submodule) be printed?

enumerate

(logical) Should be all coordinate/age combinations be enumerated and reconstructed (set to TRUE by default)? FALSE is applicable only if the number of rows in x is equal to the number elementes in age. Then a point will be reconstructed to the age that has the same index in age as the row of the coordinates in x. List output is not available in this case.

chunk

(numeric) Deprected argument of the online reconstruction method. Ignored.

reverse

(logical) Argument of the remote reconstruction submodule. The flag to control the direction of reconstruction. If reverse = TRUE, the function will calculate the present-day coordinates of the given paleo-coordinates, with age setting the target. Not recommended, kept only for compatibility with the GPlates Web Service. Using from instead of age will automatically trigger reverse reconstruction.

path.gplates

(character) Argument of the local reconstruction submodule. In case the GPlates executable file is not found at the coded default location, the full path to the executable (gplates-<ver>.exe on Windows) can be entered here. e.g. "C:/gplates_2.3.0_win64/gplates.exe".

cleanup

(logical) Argument of the local reconstruction submodule. Should the temporary files be deleted immediately after reconstructions?

dir

(character) Argument of the local reconstruction submodule. Directory where the temporary files of the reconstruction are stored (defaults to a temporary directory created by R). Remember to toggle cleanup if you want to see the files.

plateperiod

(logical) Deprecated argument, renamed to validtime for higher compatibility with the GPlates Web Service.

partitioning

(character) Argument of the local reconstruction submodule, which feature collection of the tectonic model should be used to assing plate IDs to the features? It defaults to "static_polygons".

check

(logical) Should the validity of the entries for the GWS checked with the information stored in gws? (default: TRUE)

warn

(character) Argument of the online reconstruction submodule, used in reverse-reconstructions (calculation of present-day coordinates from paleocoordinates). If set to 'TRUE' (default), the function will produce a warning when paleocoordinates are not assigned to any of the paritioning polygons (missing values are returned for these). When set to 'FALSE', the warnings will not be displayed.

anchor

(character) Argument of the online reconstruction submodule. The Plate ID of the anchored plate. This is the 'anchored_plate_id' parameter of the GPlates Web Service.

validtime

(logical) Argument of the local reconstuction submodule. Should the durations of the plates be forced on the partitioned feature? If these are set to TRUE and the plate duration estimates are long, then you might lose some data. This is the inverse of the ignore.valid.time argument of the GWS.

gmeta

(logical) Argument of the local reconstruction submodule, in the case, when sf objects are supplied. Should the metadata produced by GPlates be included in the output object?

Details

The function implements two reconstruction submodules, which are selected with the model argument:

If model is a character entry, then the reconstruct() function uses the GPlates Web Service (https://gwsdoc.gplates.org/, remote reconstruction submodule). The available reconstruction models for this submodule are (as of 2024-02-02):

If model is a platemodel class object, then the function will try to use the GPLates desktop application (https://www.gplates.org/) to reconstruct the coordinates (local reconstruction submodule). Plate models are available in chronosphere with the fetch function. See datasets for the available models. The function will try to find the main GPlates executable in its default installation directory. If this does not succeed, use path.gplates to enter the full path to the GPlates executable as a character string.

Value

A numeric matrix if x is a numeric, matrix or data.frame, or Spatial* class objects, depending on input. NULL in case no model is specified.

References

Matthews, K. J., Maloney, K. T., Zahirovic, S., Williams, S. E., Seton, M., & Müller, R. D. (2016). Global plate boundary evolution and kinematics since the late Paleozoic. Global and Planetary Change, 146, 226–250. https://doi.org/10.1016/j.gloplacha.2016.10.002

Andrew S. Merdith, Simon E. Williams, Alan S. Collins, Michael G. Tetley, Jacob A. Mulder, Morgan L. Blades, Alexander Young, Sheree E. Armistead, John Cannon, Sabin Zahirovic, R. Dietmar Müller, (2021). Extending full-plate tectonic models into deep time: Linking the Neoproterozoic and the Phanerozoic, Earth-Science Reviews, Volume 214, 2021, 103477, ISSN 0012-8252, https://doi.org/10.1016/j.earscirev.2020.103477.

Müller, R. D., Seton, M., Zahirovic, S., Williams, S. E., Matthews, K. J., Wright, N. M., … Cannon, J. (2016). Ocean Basin Evolution and Global-Scale Plate Reorganization Events Since Pangea Breakup. Annual Review of Earth and Planetary Sciences, 44(1), 107–138. https://doi.org/10.1146/annurev-earth-060115-012211

Müller, R. D., Zahirovic, S., Williams, S. E., Cannon, J., Seton, M., Bower, D. J., Tetley, M. G., Heine, C., Le Breton, E., Liu, S., Russell, S. H. J., Yang, T., Leonard, J., and Gurnis, M. (2019), A global plate model including lithospheric deformation along major rifts and orogens since the Triassic. Tectonics, vol. 38, https://doi.org/10.1029/2018TC005462.

Müller, R. D., Flament, N., Cannon, J., Tetley, M. G., Williams, S. E., Cao, X., Bodur, Ö. F., Zahirovic, S., and Merdith, A.: A tectonic-rules-based mantle reference frame since 1 billion years ago – implications for supercontinent cycles and plate–mantle system evolution, Solid Earth, 13, 1127–1159, https://doi.org/10.5194/se-13-1127-2022, 2022.

Scotese, C. R. (2016). PALEOMAP PaleoAtlas for GPlates and the PaleoData Plotter Program. http://www.earthbyte.org/paleomap‐ paleoatlas‐for‐gplates

Seton, M., Müller, R. D., Zahirovic, S., Gaina, C., Torsvik, T., Shephard, G., … Chandler, M. (2012). Global continental and ocean basin reconstructions since 200Ma. Earth-Science Reviews, 113(3–4), 212–270. https://doi.org/10.1016/j.earscirev.2012.03.002

Torsvik and Cocks (2017). Earth History and Palaeogeography. Cambridge University Press, 317 pp.

Wright, N., Zahirovic, S., Müller, R. D., & Seton, M. (2013). Towards community-driven paleogeographic reconstructions: integrating open-access paleogeographic and paleobiology data with plate tectonics. Biogeosciences, 10(3), 1529–1541. https://doi.org/10.5194/bg-10-1529-2013

Examples

# With the web service 
# simple matrices
# replace model with desired choice
reconstruct(matrix(c(95, 54), nrow=1), 140, model=NULL)

# points reconstruction
xy <-cbind(long=c(95,142), lat=c(54, -33))
reconstruct(xy, 140, model=NULL)

Draw lines with sawteeth on side

Description

Function used for plotting subduction lines

Usage

sawteeth(
  x,
  left,
  cex = 1,
  shape = 1,
  splineshape = -0.5,
  col = "black",
  lwd = 1,
  ...
)

Arguments

x

(numeric) Two dimensional matrix of coordinates (x and y) columns.

left

(logical) Switch indicating whether to put the teeth on the left- or right-hand side.

cex

(numeric) Standard scaling argument, controls the size and number of sawteeth. Defaults are based on plot parameters (cxy), different device dimensions will lead to differently sized triangles.

shape

(numeric) Proportion of tooth height to its base.

splineshape

(numeric) Shape parameter of xspline (called twice!).

col

(numeric) The color of the teeth and the lines.

lwd

(numeric) The width of the line.

...

Additional arguments passed to polygon.

Value

The function has no return value.

Examples

# define points
x <- c(0.42, 1.90, 2.06, 1.28, 1.01, 1.05, 1.34, 2.14,
	4.25, 6.69, 7.96, 8.88, 9.35, 9.41, 8.84)

y <- c(1.06, 0.86, 1.91, 2.90, 4.25, 5.52, 6.81, 8.03,
	9.03, 9.25, 9.30, 8.88, 8.36, 7.00, 6.50)

# visualize the line with a sawteeth
plot(x, y, xlim=c(0,10), ylim=c(0, 10))

sawteeth(cbind(x,y), left=TRUE, col="#99000077")
sawteeth(cbind(x,y), left=TRUE, col="black", shape=0.5)

# use combination of cex and shape to control the size triangles
plot(x, y, xlim=c(0,10), ylim=c(0, 10))
sawteeth(cbind(x,y), left=TRUE, col="#99000077", cex=0.5, shape=3)

Plot subduction lines

Description

Plot subduction lines

Usage

subductionlines(x, add = TRUE, ...)

Arguments

x

An sf-class object with additional class label of subduction.zones, or plate.boundaries. returned by the online reconstruct method.

add

(logical) By default the plot will be plotting on existing plots. Use add=FALSE to plot from scratch.

...

Arguments passed to the sawteeth function.

Value

The function has no return value.

Calculate velocities of plate tectonic movements

Description

Queries to return meshes of tectonic plate velocities.

Usage

velocities(x, ...)

## S4 method for signature 'missing'
velocities(x, ...)

## S4 method for signature 'character'
velocities(
  x,
  age,
  model,
  domain = "longLatGrid",
  type = "MagAzim",
  output = "data.frame",
  polecrop = TRUE,
  verbose = FALSE,
  check = TRUE
)

Arguments

x

character: What should the velocities be calculated for? If nothing is given (i.e. signature(x="missing")) the argument defaults to the only currently working feature collection, the "static_polygons". This is expected to be expanded in the future.

...

Arguments of class-specific methods.

age

numeric: The age in millions of years at which the velocities are to be returned.

model

character: The name of the tectonic model. Similar to that of reconstruct.

domain

character: Either "longLatGrid" or "healpix". "longLatGrid" returns the velocites with the domain of a regular, one-by-one degree longitude-latitude grid. "healpix" will return velocities with the domain of an icosahedral, nearly equidistant grid.

type

character: The type of velocity format that is to be returned, either magnitude and azimuth (type="MagAzim") or easting and northing velocity vectors (type="east_north"). Both result in two variables.

output

character: The class name of the output to be returned. Either data.frame or SpatRaster. The latter requires the terra extension (suggested) and is only available with domain="longLatGrid".

polecrop

logical: Only applicable if output="SpatRaster". The original velocity values are provided as a grid-registered raster, which forces the extent of the raster to be beyond the regular [-180, 180] longitude and [-90, 90] domain, producing warnings when the SpatRaster is used. The default cellraster=TRUE resamples this raster to a native, cell-registered grid. This is an issue only with latitudes, so they get cropped by default. Setting this argument to FALSE will skip cropping.

verbose

logical: Are you interested in more messages?

check

logical Should the validity of the entries for the GWS checked with the information stored in gws? (default: TRUE)

Details

The function returns a mesh of velocities: two variables, either magnitude (mm/year) and azimuth (rad): type="MagAzim" or easting and northing velocity vectors (mm/year): type="east_north". Currently only the online method is supported using the GPlates Web Service (internet connection is required). Available models are in the gws object, and can be provided with arguments similar to reconstruct.

Value

Velocities of tectonic movements. If output="data.frame" then the function returns a data.frame with the longitude, latitude, the two velocity variables and the plate ids they belong to. If output="SpatRaster" then the output will be a multilayered SpatRaster object.

Examples

# dummy example,
# set model to the desired model string, e.g. model="MERDITH2021"
velocities("static_polygons", age=45, model=NULL)