This document was published as supplementary material with our paper on the GPlates Geographic Markup language GPML by X. Qin et al. in EGU's open access journal Geoscientific Instrumentation, Methods and Data Systems (GI) in 2012.

GROT: A new rotation file format for GPlates

With the advent of GPlates 1.5 came the ability to read a new version of the rotation file format called *.grot. In analogy to JSON and OGR_GMT formats it allows for much more verbose and structured addition of metadata to rotation sequences.

Revision GROT version Date
1 (svn: 1793) 1.0 2012-05-11

For the document revisions, please see the History of this page.


GPlates and the GPlate Geological Information Model (GPGIM) and the GPlates markup language (GPML) have opened new ways of working with plate tectonic data. Whereas the feature-centric data model has been vastly improved, the way the rotation model data is handled has not changed since the early days of the PLATES software. There is, however, a need to enhance the “richness” of the rotation file in terms of metadata, bibliographic annotation, revision histories and integration of rotation uncertainty estimates. I propose to model this new standard on the currently implemented GMT OGR format and a Multimarkdown-type set of attributes which should allow for an easy, streamlined processing in tools such as awk, Python or simple shell scripts as well as integration of these enhanced features into the GPlates software.

The new GPlates rotation file format encapsulates important rotation metadata in a simple and logical way. It emulates various language syntaxes such as GMT OGR, MultiMarkDown, LATEX Python and XML to provide a clean, logical and easy-to-use metadata framework. The file suffix for the new rotation file format is *.grot for GPlates rotation file, pronounced g-rot (and not grot…).


How to cite: Qin, X., Müller, R. D., Cannon, J., Landgrebe, T. C. W., Heine, C., Watson, R. J., and Turner, M.: The GPlates Geological Information Model and Markup Language, Geosci. Instrum. Method. Data Syst., 1, 111–134,, 2012.

	Author = {Qin, X. and M{\"u}ller, R. D. and Cannon, J. and Landgrebe, T. C. W. and Heine, C. and Watson, R. J. and Turner, M.},
	Date-Added = {2012-11-20 14:43:33 +1100},
	Date-Modified = {2020-06-01 22:37:22 +0200},
	Doi = {10.5194/gi-1-111-2012},
	Journal = {Geoscientific Instrumentation, Methods and Data Systems},
	Journaltitle = {Geoscientific Instrumentation, Methods and Data Systems},
	Number = {2},
	Pages = {111--134},
	Title = {{The GPlates Geological Information Model and Markup Language}},
	Url = {},
	Volume = {1},
	Year = {2012}

Basic features of the *.grot syntax

The following section outlines the proposed new standard for encoding metadata (essentially everything beyond the mandatory rotation parameters) which is backward-compatible, and machine-digestible. Please comment or send feedback to Christian Heine

Commented lines in current rotation files

Previously rotation files only allowed comments if they were denoted as 999 rotations. 999 rotations to comment out lines This is error prone as already pointed out during the early phases of the GPlates development and cumbersome when directly working with rotation files in a text editor.

An example of a commented line using the current practice of replacing the Plate ID of the moving plate with a 999 to disable it. The inactive rotation sequence data looks like this:

  999   200.00 -55.810  -41.520  101.880 802 ! FLI-ANT Norton & Sclater 1979 fit

This methods has the severe disadvantage, that the original plate ID (PlateID1, moving plate) is lost when inserting a comment. Secondly the comment area is not structured well enough for automatic processing, e.g. extracting bibliographic references related to individual rotations or groups of rotations. It is quite easy to conceive that simple file exchange in PICT PICT collaborations or the omission of metadata can lead to a significant loss of important information contained in the rotation file. In addition, the introduction of novel methods, such as deformation, or Hellinger-style rotation uncertainty parameters requires a much larger set of rotations to be dealt with.

Flags: Comments and moving plate rotation sequences

Two new flags are introduced in the new *.grot rotation file format: Flags: # for comments and > for denoting moving plate rotation sequences

Lines starting with # and followed by text are ignored by GPlates unless they contain marked @ATTRIBUTE data. Lines starting with # and followed by text are ignored by GPlates If the # is followed by a valid rotation pole specification, the line will be read by GPlates but the rotation pole itself will be disabled (inactive). In the new file format commented lines and comments would appear as: Lines starting with # and followed by a valid rotation pole specification are regarded disabled/inactive by GPlates

  # Comment which is ignored by GPlates 
  @C"Comment which is read by GPlates and associated with the next rotation pole below" 
  288  200.00 -55.81 -41.52  101.88 802 
  #288  200.00 -55.81 -41.52  101.88 802 @C"Comment read by GPlates but DISABLED rotation"

For legacy applications using rotation files a simple awk one-liner using RegExp can be used strip off all commented lines or simply preceed them by a 999 0.0 0.0 0.0 0.0 999 # rotation line.

A new Moving Plate Rotation Sequence (MPRS) is introduced in this version of the rotation file. The MPRS serves as header or “segment” and follows the idea of “bookmarking” individual blocks of rotation sequences in various text editors as well as in GPlates as well as the concept of multi line segments in GMT. Detailed info on the syntax of the MPRS in Sec. FIXME .

Moving Plate Rotation Sequences (MPRS) are all rotations applying to an individual moving plate, including cross overs
  > @MPRS:pid"002" @MPRS:code"PHS" @MPRS:name"Pacific Hotspots" 
  002     0.780  49.3000  -49.500   -1.020  901
  002     2.580  53.7200  -56.880   -2.660  901 
  002     5.890  59.6500  -66.050   -5.390  901
  002     8.860  62.8700  -70.870   -8.230  901

Standardised metadata attribute/value format

Metadata attributes recognised by GPlates in the new format have a specific format. They are prefixed by an @ symbol followed by a text string which is the name of the attribute. The attribute value is enclosed in a pair of double quotes . The allowed set of keywords is listed completely in Sec. “FIXME”.

@ATTRIBUTE”VALUE“ is the basic metadata format

The syntax allows to have multiple fields for the Value. These fields must be separated by vertical bars/pipes without whitespace before or after the attribute (akin to GMT OGR): Attribute Values can have multiple fields

  @ATTRIBUTE"Value 1 | Value 2 | Value 3"
  @MPRS"101|NAM|North America"

The following variations for the different attribute:value pairs are allowed, depending on the complexity of the original attribute: Attributes can have (nested) child attributes

  @MPRS:name"North America"

Attribute and subattributes allow nesting at deeper levels. Consider the following example: Nested attributes can be written in compact or verbose forms



Compact version

  @DC:contributor"JODO|John Doe|"

Extended version

  @DC:contributor:name"John Doe"

Here, one complex set of subattribute and subsubattributes can be combined in one line or listed separately in sequence on individual lines.

Attribute aliases and external structures

This method also allows the creation of aliases which can be created by referencing certain fields to reduce complexity of nested parent:children attributes. Nested attributes can be aliased In the current version the use ofuser-defined aliases is not supported. Example: User-defined aliases are notsupported at present


  @ATTRIBUTE:subattribute"ID | Name | Email"

Header info

  @DC:contributor"JODO | John Doe |" 
  @DC:contributor"FOBA | Foo Bar |" 
  @DC:contributor"FOBOO | Foo Boo |"

This creates an alias

 alias @AU = @DC:contributor:id 
User-defined aliases are currently not supported!

Use alias in rotation sequence


In this example, an attribute and subattribute (DC:contributor) contains a list of values, all separated by a vertical bar/pipe. These attribute values conform to a standardised list where the first element is a unique Author ID, the second specifies the real world name of this author and the third his email. The attribute alias can now be created by assigning the @AU attribute a list of possible values which are all derived from all available DC:contributor”ID“ fields.

This setup allows even to fetch complex structures from external files. Attributes can reference external sources Say we keep a BibTeX bibliographic database along with our rotation file. In this file, bibliographic data is collected, with each entry having a unique identifier (the so-called citekey). Using nested attributes and aliases we are able to create the following setup:

  # Header
  # Alias 
  alias @REF = @BIBINFO:bibliographyfile:citekey
  # Actual rotation metadata

This creates the possiblity to relatively link unique elements from one source into the rotation file by direct mapping of this unique identifier. A possibly query would yield the BibTeX record for the citation key Heine.SE.2013 in the associated bibliographic data file which was specified in the header record using the @BIBINFO:bibliographyfile attribute.

Another application is the possiblity of spatial queries by referencing certain feature types in an associated GPML file or a remote data source. Attributes can be used to generate spatial queries Consider the followingexample:

  # Header
  # Alias
  alias @CHRONID = @GPML:MagneticAnomalyIdentification:polarityChronID
  # Rotation
  101    33.100  75.9900    5.9800    9.770  714 @CHRONID"C13"

With the available information, GPlates can go and run a spatial query to extract all the relevant features from a source file (e.g. a GPML file with all magnetic anomaly picks). The query would look like:

Find all C13 picks on plate ID 101 which have a conjugate plate id 714

Naturally, a magnetic anomaly picking scheme has to be agreed upon or explicity stated in the CHRONID (e.g. the young end of C13– C13y). As the GPGIM specification states, this information should be included in the value part of this attribute. Refer to the GPGIM for details. Such a geospatial query can be run for all applicable features.

File header elements

New GPlates rotation files have a mandatory file header which must be present in all rotation files. The file header contains important information on how to processes different parts of the file and also carries important metadata, such as information on the Geological Time Scale used for rotations. The file header contains global metadata which are referenced in the file body. It adheres to specific format and contains mandatory attributes Apart from the mandatory metadata in the header, there are also optional blocks which allow the user to put revision information or any other data the user finds necessary. Future version of GPlates (> 1.3) will include the opportunity to edit this information through a GUI.

The file header follows the core elements of the Dublin Core metadata initiative which specifies 15 standard tags to identify electronic documents (see DublinCore terms).

Let’s start out with the mandatory information in the file header, here’s the overview:

Rotation file version

The first line uses the @GPLATESROTATIONFILE:version”xx“ attribute to specify that this file adheres to the new rotation file standard and gives the current rotation file version number.

@GPLATESROTATIONFILE:version – File format versioning

Dublin Core document metadata

The subsequent attributes use the @DC parent attribute to denote a set of Dublin Core metadata describing the file content (see the Wikipedia article on Dublin Core. This also includes links to licenses, modification dates and proper citations for the file. See the GPlates GROT Format attribute list for a complete listing and explanation of the header attributes.

@DC — file metadata
  @DC:title"GPlates rotation file -  NEW ROTATION FORMAT SAMPLE FILE"
  @DC:creator:name"Foo Bar" 
  @DC:creator:affiliation"EarthByte Research Group, School of Geosciences" 
  @DC:creator:affiliation"The University of Sydney, NSW 2006, Australia" 
  @DC:rights:license"Attribution-NonCommercial-ShareAlike 3.0 Unported (CC BY-NC-SA 3.0)" 
  @DC:date:created"2/06/11 4:08:05 PM" 
  @DC:date:modified"$Date: 2012-05-12 00:48:08 +1000 (Sat, 12 May 2012) $" 
  @DC:coverage:temporal"0-600 Ma"
  @DC:bibliographicCitation"""Chin, Mueller, Cannon, Landgrebe, Heine, 
                              Watson, Turner (2012) The GPGIM vol:pp-pp, 
                              J. Digitial Earth. doi:xxxxxxxxx """
   A sample rotation file in the new GPlates rotation file format v1.1 
   Based on moving Indian/Atlantic hotspots (O'Neill et. al. 2005) 
   to 100 Ma and true polar wander corrected palaeomagnetic 
   reference frame (derived from Steinberger and Torsvik 2008) 
   from 100 - 200 Ma.  250 Ma is the extent of this rotation model. 
   Pacific absolute reference frame based on Wessell and Kroenke 2008 
   with a switch to Wessel et. al. 2006 at 118.4 Ma 
   Reference for rotation model: Seton et. al. (submitted to ESR)"""

Contributing authors

The next mandatory block is the contributor information related to individuals who have worked on various parts of the rotation sequences. In order to correctly attribute contributions which have not made it into publications, this section lists authors with their contact details and full name. The lines use the @DC:contributor form of the Dublin Core specifications and the value field contains multiple values. In most cases, especially in intra-institutional use, not all rotations are published in the form of a citable reference, enlisting contributing authors still provides a reference to the creator.

@DC:contributor – Contributing authors


  @DC:contributor"id | Real Name | Email | URL | [Postal address, other contact details] 

Example (single line)

  @DC:contributor"""FOBA | Foo Bar | | | The FooBar Geodynamics Group, BarFoo University, Jupiter"""

Example (multi line)

  @DC:contributor"""FILA |
                    Firstname Lastname | 
                    FooBar Research Group, BarFoo University"""

Bibliographic and reference section

The next mandatory block encompasses the bibliographic or reference data valid for the file globally. The field contain a reference to a bibliographic data base in BibTeX format as well as to the GPlates Information Model (GPGIM) website and a base URL for the Digital Object Identifier (DOI). All these attribute will be referenced from the individual MPRS or rotations.

@BIBINFO — Optional inclusion of bibliographic databases

The inclusion of mandatory bibliographic reference data allows a future use of GPlates in conjunction with hyperlinks (through the DOI) to a PICT PICT publication as well as direct links to a bibliographic companion database file:


Geological time scales

One of the most important piece of metadata is information about the geological time scales (GTS) used to convert relative geological ages to absolute times.

@GEOTIMESCALE – Mandatory inclusion of Geological Time Scales

These GTS constantly evolve and a Base Aptian on some timescale from the 1990’s has a few Million Years difference to a Base Aptian from the 2010’s. The GTS are listed in the header section and are referenced through a tag at individual rotation level.


  @GEOTIMESCALE" ID | DOI/URL/ISSN (specify) | CiteKey | Bibliographic record/Comment" 

Multiline specification of GTS

                doi:10.1016/B978-044452748-6.00097-3 |
                Gee.ToC.07 | 
                Gee, J.S. and Kent, D.V. (2012) 5.12 - Source of Oceanic \ 
   Magnetic Anomalies and the Geomagnetic Polarity Timescale, in: Treatise on\ 
   Geophysics, Volume 5, Pages 455--507, Elsevier, Amsterdam"""
               doi:10.1029/94JB03098; doi:10.1029/94JB01889|
               Cande.JGR.95; Gradstein.JGR.94 | 
               S. C. Cande and D. V. Kent. Revised Calbration of the\ 
   geomagnetic polarity timescale for the Late Cretaceous and Cenozoic. \ 
   J. Geophys. Res., 100(B4):6093--6095, 1995.; 
   F. M. Gradstein, F. P. Agterberg, J. G. Ogg, J. Hardenbol, P. van Veen,\ 
   J. Thierry, and Z. Huang. A Mesozoic time scale. J. Geophys. Res.,\ 
   99:24051--24074, 1994. doi:10.1029/94JB01889."""
  @GEOTIMESCALE""" Absolute 
               Absolute numerical time in Ma"""

OPTIONAL: Revision history

The optional revision history block is used for versioning. The actual list of applicable subattributes depends on the versioning system used.

@REVISIONHIST – Optional inclusion of versioning information

Each Keyword shouldbe shortened and prefixed by @REVISIONHIST[keyword]“value”. Example for a Subversion repository setup:

  @REVISIONHIST"$Id: CHHEI_RotFileStd.tex 1793 2012-05-11 14:48:08Z christian $"
FIXME This needs to be adopted to GIT and other systems taking over from SVN.

File body elements: The rotation sequences

The file body contains all data outside the file header. These are Moving Plate Rotation Sequences (MPRS) which are in turn composed of individual lines listing rotation parameters.

Moving plate rotation sequence (MPRS) header

The moving plate rotation sequence (MPRS) specifies a block of rotations which all have the same moving plate id. It is denoted by a > flag at the start of each line and allows multi-line headers.

@MPRS – The Moving plate rotation sequence

The introduction of a header for any moving plate rotation sequence follows the idea that most metadata is applied to a whole sequence of rotations and allows for better “bookmarking” in GPlates' rotation file editor or other external text editors. The rotation header sequence denominator is modelled as follows:


  > @MPRS:pid"PID1" @MPRS:code"XXX" @MPRS:name"Moving Plate name"

Compact version

  > @MPRS"288 | FLI | Falkland Islands"

Extended version

  > @MPRS:pid"288" @MPRS:code"FLI" @MPRS:name"Falkland Islands" @C"optional comment"

Multiline version

  > @MPRS:pid"288"
  > @MPRS:code"FLI"
  > @MPRS:name"Falkland Islands" 
  > @C"Optional comment" @AU"CHHEI"

Oftentimes the full moving plate rotation sequence is taken from a single author/publication. In that case, adding metadata to each rotation line would increase the possibility for mistakes.

>@MPRS – Default metadata for individual rotations

The new rotation file format allows the user to specify metadata for a whole MPRS in the header which then applies to all rotations in that sequence:

  > @MPRS:pid"002" @MPRS:code"PHS" @MPRS:name"Pacific Hotspots" 
  002     2.580  53.7200  -56.880   -2.660  901 @PP"PHS-PAC" @REF"Wessel.JGR.08" @C"Model WK08-A" @GTS"GeeK07" 
  002     5.890  59.6500  -66.050   -5.390  901 @PP"PHS-PAC" @REF"Wessel.JGR.08" @C"Model WK08-A" @GTS"GeeK07" 
  002     8.860  62.8700  -70.870   -8.230  901 @PP"PHS-PAC" @REF"Wessel.JGR.08" @C"Model WK08-A" @GTS"GeeK07" 
  002    12.290  65.3700  -68.680  -10.300  901 @PP"PHS-PAC" @REF"Wessel.JGR.08" @C"Model WK08-A" @GTS"GeeK07" 
  002    17.470  68.2500  -61.530  -15.500  901 @PP"PHS-PAC" @REF"Wessel.JGR.08" @C"Model WK08-A" @GTS"GeeK07" 
  002    24.060  68.7800  -69.830  -20.400  901 @PP"PHS-PAC" @REF"Wessel.JGR.08" @C"Model WK08-A" @GTS"GeeK07" 
  002    28.280  67.7200  -70.800  -23.600  901 @PP"PHS-PAC" @REF"Wessel.JGR.08" @C"Model WK08-A" @GTS"GeeK07" 
  002    33.540  66.5700  -68.730  -27.700  901 @PP"PHS-PAC" @REF"Wessel.JGR.08" @C"Model WK08-A" @GTS"GeeK07" 
  002    40.100  65.4300  -64.250  -31.600  901 @PP"PHS-PAC" @REF"Wessel.JGR.08" @C"Model WK08-A" @GTS"GeeK07"

can now be replaced with

  > @MPRS:pid"002" @MPRS:code"PHS" @MPRS:name"Pacific Hotspots" 
  > @PP"PHS-PAC" @REF"Wessel.JGR.08" @C"Model WK08-A" @GTS"GeeK07" 
  002     2.580  53.7200  -56.880   -2.660  901
  002     5.890  59.6500  -66.050   -5.390  901 
  002     8.860  62.8700  -70.870   -8.230  901
  002    12.290  65.3700  -68.680  -10.300  901 
  002    17.470  68.2500  -61.530  -15.500  901
  002    24.060  68.7800  -69.830  -20.400  901 
  002    28.280  67.7200  -70.800  -23.600  901
  002    33.540  66.5700  -68.730  -27.700  901 
  002    40.100  65.4300  -64.250  -31.600  901

In case there are changes to individual rotations in the MPRS these can be done on line/rotation pole level and will overide the MPRS header data: Multiline comment metadata in @MPRS header

  > @MPRS:pid"002" @MPRS:code"PHS" @MPRS:name"Pacific Hotspots" 
  > @PP"PHS-PAC" @REF"Wessel.JGR.08" @C"Model WK08-A" @GTS"GeeK07" 
  002     2.580  53.7200  -56.880   -2.660  901
  002     5.890  59.6500  -66.050   -5.390  901 
  002     9.0    62.8700  -70.870   -8.230  901 @AU"CHHEI" @T"2012-05-03" @C"Changed time from 8.860" 
  002    12.290  65.3700  -68.680  -10.300  901
  002    17.470  68.2500  -61.530  -15.500  901 
  002    24.060  68.7800  -69.830  -20.400  901
  002    28.280  67.7200  -70.800  -23.600  901 
  002    33.540  66.5700  -68.730  -27.700  901
  002    40.100  65.4300  -64.250  -31.600  901

Given the above, the new 9.0 Ma rotation will carry the metadata specified on for the individual pole and only the specified pole metadata overrides the MPRS metadata (non-overridden metadata is still inherited from the MPRS).

Rotation Line Data

We adopt the legacy PLATES rotation format which consists of 6 mandatory parameters specifying the stage pole of any given rotation. Backwards compatibility with PLATES rotation data The format has not changed andis fully compatible with legacy applications.

Parameter name Description
PID1 Plate ID 1 (moving plate)
FromAge Excuse the french. Start age.
POLELAT Rotation pole latitude
POLELON Rotation pole longitude
ANGLE Rotation pole angle
PID2 Fixed Plate, plate ID 2

New optional meta data attributes from the dictionary can be added to the individual lines. Rotation metadata attributes The optional attributes follow the structure layed out in Sec. FIXME and can consist of the following elements:

Attribute Description
@PP Abbreviated description of the relative plate motions, e.g. Africa-South America to @PP”SAM-AFR“, the abbreviated names have to adhere to the @MPRS:code from the MPRS.
@C Free form comment
@GTS:id Unique ID of the geological time scale used in identifying the magnetic anomaly picks. References the @GEOTIMESCALE:id in the file header
@AU Abbreviation/ID of modification author. Alias which references @DC:contributor:id in the file header.
@DOI Digitial object identifier for reference related to that individual rotation. Alias to @BIBINFO:doibase:doi. Citation key for reference related to that individual rotation.
@REF Alias for @BIBINFO:bibliographyfile:citekey
@HELL Set of attribute:value pairs for uncertainty parameters for this rotation. For details see Sec. FIXME.
@T Modification date/time. Adhere to ISO standard (ie [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]).
@CHRONID Magnetic anomaly chron ID. Alias to @GPML:MagneticAnomalyIdentification:polarityChronID and adheres to strict naming convention. The identifier used for magnetic picks evolved to be a combination of letters and numbers, of the form of (C/M)<number><combination of letters>. See the GPGIM for details.

For a complete list of attributes see GPlates GROT Format attribute list


  833    53.300 -14.1900  130.4100   -0.7200  801 @PP"LHR-AUS"  @DOI"10.1029/98JB00386" @CHRONID"C24o"

Uncertainty data for rotations

The Hellinger method allows to compute statistical uncertainties for rotations, representing them as a series of parameters and a 3D-covariance matrix. Hellinger Statistics attributes for individual rotations

These parameters are:

  • total misfit (sum of squares of the weighted distances of data points to great circle segment) in [km]
  • number of data points
  • number of great circle segments
  • number of degrees of freedom
  • kappahat: quality factor which relates the uncertainties assigned to the data to their true estimates
  • a 3 × 3 covariance matrix which needs to be divided by the factor kappahat to convert in square radians

An example matrix is given here obtained from the file satl.34 and running the hellinger1 program:

(                                    )
  8.71113084   - 4.33230877  -4.97091355
|| -4.33230877   4.01436998   3.23033819|| × 10-7
|( -4.97091355   3.23033819    3.6493551 |)

So far, Hellinger-fit criteria have not been explicity expressed in the rotation file. For the new standard, the Hellinger statistics need to be included explicity in the format expressed below. The complete Hellinger values can either be represented as coherent string with the some matrix values omitted due to the rotational symmetry of the matrix:


or as a separate set of arguments using the @HELL Parent:Children attributes:

  • total misfit
  • number of data points and segment length
  • number of degrees of freedom
  • Quality factor ^κ
  • Covariance matrix, here we ONLY USE 1) due to the rotational symmetry of the matrix used.


Multi line version:

  @HELL:cov"(8.71113084E-07,-4.33230877E-07,-4.97091355E-07) \ 

Compact single line:

  @HELL"""41.1911338 |75,16 | 40.| 0.971082763|\
   (8.71113084E-07,-4.33230877E-07,-4.97091355E-07) \ 

Bibliography information

Each rotation file should come with a companion bibliographic reference database which maps @REF-Keys to DOIs or citations.

Through the @BIBINFO:bibfile mapping a bibliographic data base, e.g. in BibTeX format. The choice for BibTeX is driven by the fact that the format is text-based, accepted as one of the bibliographic data standards and many software tools allow to either directly use this format (BibDesk, JabREF) or import/export it (e.g. Endnote). At a future data the bibliographic information can possibly be incorporated consistently into the rotation file format without the need for two separate files.

Online resources: