back to [[software:gplates:grot:start|GROT: A new rotation file format for GPlates]] ====== 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 [[mailto:chhei@paleoearthlabs.org|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 @ATTRIBUTE"VALUE" @AU"CHHEI" 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 @ATTRIBUTE:subattribute"Value" @MPRS:name"North America" @MPRS:pid"101" @MPRS:code"NAM" Attribute and subattributes allow nesting at deeper levels. Consider the following example: Nested attributes can be written in compact or verbose forms Template @ATTRIBUTE:subattribute:subsubattribute"Value" Compact version @DC:contributor"JODO|John Doe|john.doe@example.com" Extended version @DC:contributor:name"John Doe" @DC:contributor:id"JODO" @DC:contributor:email"john.doe@example.com" 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 Template @ATTRIBUTE:subattribute"ID | Name | Email" Header info @DC:contributor"JODO | John Doe | john.doe@example.com" @DC:contributor"FOBA | Foo Bar | foo.bar@example.com" @DC:contributor"FOBOO | Foo Boo | foo.boo@example.com" This creates an alias alias @AU = @DC:contributor:id User-defined aliases are currently not supported! Use alias in rotation sequence @AU"JODO" @AU"FOBOO" @AU"FOBA" 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 @BIBINFO:bibliographyfile"file://rotationfile.bib" # Alias alias @REF = @BIBINFO:bibliographyfile:citekey # Actual rotation metadata @REF"Heine.AGU-GM.04" 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 @GPML:namespace"http://www.earthbyte.org/Resources/GPGIM/public/" # 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 [[http://www.earthbyte.org/Resources/GPGIM/public/#PolarityChronId|the GPGIM]] for details. Such a geospatial query can be run for all applicable features. ----- continue to [[software:gplates:grot:fileheader|GROT File format: File header]]