= GPlates Data Manual == Introduction The purpose of this document is to describe how data is stored in GPlates, and provide information on how to use and access it. For experienced GPlates users, an xref:FeatureTable[Appendix] is provided with tables of all currently available features and properties, that can be used to look up a specific feature or property. [[Walththrough]] == Walkthrough of Features and Properties Everything in GPlates is modeled as a feature. Mid-ocean ridges, hotspots, seamounts, faults, coastlines, and all other geological elements, are all features. Features are distinguished between each other by their feature type. A mid-ocean ridge can be classified as a xref:feat-MidOceanRidge[MidOceanRidge] feature type, a hotspot as a xref:feat-HotSpot[HotSpot] feature type, a seamount as a Seamount feature type, etc. A complete list of GPlates features can be found in the xref:FeaturesTable[Appendix]. A feature is further distinguished by its "properties". A property can be anything from the name of a feature, its geometry (location and shape), its age, to information regarding which plates are on either side of a plate boundary. As a practical matter, the only property specifically required by GPlates is its geometry. To perform a reconstruction, GPlates would also have to know the period of time a feature existed (the property xref:prop-gml:validTime[validTime]), and its reconstruction plate ID. Most other properties are used to provide information about the feature. === Properties Common to All Features Regardless of what the feature is, for example a xref:feat-Volcano[volcano] or an xref:feat-Isochron[isochron]), it will have a xref:prop-gml:name[name], xref:prop-identity[identity], and a xref:prop-reconstructionPlateId[plate ID number], among other properties. Below is a description of all properties that are common to all feature types. ==== General Information * xref:prop-gml:name[gml:name] * xref:prop-gml:description[gml:description] * xref:prop-gml:metaDataProperty[gml:metaDataProperty] xref:prop-gml:name[Name] and xref:prop-gml:description[description] are strings used to describe the feature. A name and description should be descriptive enough so for another user to quickly understand what the feature. There are no explicit character limits on either. All features have a name, even if it is a blank string, whereas a description and xref:prop-gml:metaDataProperty[gml:metaDataProperty] are optional. xref:prop-gml:metaDataProperty[gml:metaDataProperty] is a optional "catch all" property that can be applied to any GML features. xref:GML[GML] is the language that the GPlates information model is based on. In practice, users will likely have little interaction with this property. ==== Identification * xref:prop-identity[identity] This is the unique feature identification number for the feature. The ID number for each feature must be unique because GPlates uses this to reference the feature internally. Among other sources, it uses the user's name, hostname, and local time as sources of uniqueness. It is generated by GPlates at the creation of the feature, and the user will generally have little contact this property. ==== Revision Information * xref:prop-revisionID[revisionID] * xref:prop-supersededRevision[supersededRevision] These properties store a code internal to GPlates about the revision status of features. A user will in general have little contact with these properties. ==== Plate ID Number * xref:prop-reconstructionPlateId[reconstructionPlateId] A plate tectonic reconstruction involves a series of plates, features and Euler poles of rotation. The term rotation in this context refers to the Euler Pole of rotation that is used to describe how a plate or feature moves through time. In a GPlates reconstruction, each plate is given a series of rotations to describe its movement throughout time in the reconstruction. xref:prop-reconstructionPlateId[reconstructionPlateId] is the property which specifies with which plate the feature should move. IMPORTANT: Note that there is a similarly named property called xref:prop-reconstructedPlateId[reconstructedPlateId], which is NOT used for this purpose and in fact the user will have little interaction with. ==== Geometry * xref:prop-position[position] * xref:prop-centerLineOf[centerLineOf] * xref:prop-outlineOf[outlineOf] * xref:prop-errorBounds[errorBounds] * xref:prop-unclassifiedGeometry[unclassifiedGeometry] A user effectively defines the geometry of the feature on creation by entering the point(s) that make up the geometry of the feature. The different geometry properties reflect different types of geometry: the xref:prop-position[position] property should be used for features best represented by a single point in space, such as a xref:feat-HotSpot[hotspot] or a xref:feat-Volcano[volcano]. xref:prop-centerLineOf[centerLineOf] is best used for features with a geometry best represented by a line, such as an xref:feat-Isochron[Isochron]. xref:prop-outlineOf[outlineOf] is best used for features with a polygon geometry, such as a xref:feat-LargeIgneousProvince[LargeIgneousProvince]. xref:prop-errorBounds[errorBounds] and xref:prop-unclassifiedGeometry[unclassifiedGeometry] can used to capture elements additional elements of geometry, such as the uncertainty of a xref:feat-HotSpotTrail[hotspot trail]. GPlates handles the storage and rotation of the geometry through time. As the plate associated with the feature moves through time, GPlates adjusts the geometry of the feature to move with the plate. When saving a reconstruction to a file, GPlates stores the geometry of each feature as its geometry in the present (0Mya). ==== Valid Time * xref:prop-gml:validTime[gml:validTime] This is the period of time that the feature is in existence. It is defined by a start date, in millions of years ago (Ma), and an end date, also in Ma. The start date can also be set to "Distant Past" to indicate that the origin of the feature predates the start of the reconstruction, and the end date can be set to "Distant Future" to indicate the the destruction of the feature postdates the present. === Plate Boundaries and Common Properties The following features are used to model plate boundaries and have several properties in common: . Active Plate Boundaries * xref:feat-ContinentalRift[ContinentalRift] * xref:feat-MidOceanRidge[MidOceanRidge] * xref:feat-Transform[Transform] * xref:feat-SubductionZone[SubductionZone] . Paleo Plate Boundaries * xref:feat-FractureZone[FractureZone] * xref:feat-PassiveContinentalBoundary[PassiveContinentalBoundary] ==== Common Properties All plate boundary features have the following properties in common: * xref:prop-leftPlate[leftPlate] * xref:prop-rightPlate[rightPlate] * xref:prop-conjugatePlateId[conjugatePlateId] xref:prop-leftPlate[leftPlate] and xref:prop-rightPlate[rightPlate] point to the plates on either side of the plate boundary. Note that in this context, "left" specifically refers to the left hand side from the perspective of an observer travelling through the geometry of the object. This means "left" is entirely dependent on the order in which the points that comprise the geometry of the plate boundary were digitised. That is to say, if the plate boundary was digitised with the first point being in the South, and the last point being to the North, then the "left" is the plate to the West. If on the other hand, the exact same plate boundary were digitised with the first point being in the North, and the last point in the South, then the "left" plate is to the East. See diagram below. [[leftRightDiagram]] image::leftRight.jpg[] The plate boundary itself will be given a xref:prop-reconstructionPlateId[reconstructionPlateId], which will likely correspond to a plate on one side of the plate boundary. xref:prop-conjugatePlateId[conjugatePlateId] is used to track a plate on the opposite side of the plate boundary. Several plates may border a plate boundary on one side. It may be necessary for dynamic polygon closure to split all plate boundaries into pieces in order to avoid this. Otherwise, the choice of xref:prop-leftPlate[leftPlate] and xref:prop-rightPlate[rightPlate] is somewhat arbitrary. A good rule of thumb may be to use the plate which takes up the largest percentage of the boundary on the side. ==== ContinentalRift and MidOceanRidge The xref:feat-ContinentalRift[ContinentalRift] and xref:feat-MidOceanRidge[MidOceanRidge] features contain another property: * xref:prop-isActive[isActive] which specifies as of the present if the rift/ridge is actively spreading (isActive = True), or the rift/ridge is no longer spreading (isActive = False). ==== Transform The xref:feat-Transform[Transform] feature is used to model strike-slip plate boundaries, and so has an additional property: * xref:prop-motion[motion] which specifies whether the motion of the boundary is dextral (right lateral) or sinistral (left lateral). ==== SubductionZone The following property is used by the xref:feat-SubductionZone[SubductionZone] feature: * xref:prop-subductingSlab[subductingSlab] The xref:prop-subductingSlab[subductingSlab] property specifies on which side of the xref:feat-SubductionZone[SubductionZone] is the slab that is being subducted into the mantle. It takes a value of "left" or "right". Note that in this context, "left" specifically refers to the left hand side from the perspective of an observer travelling through the geometry of the object. This means "left" is entirely dependent on the order in which the points that comprise the geometry of the plate boundary were digitised. That is to say, if the plate boundary was digitised with the first point being in the South, and the last point being to the North, then the "left" is the plate to the West. If on the other hand, the exact same plate boundary were digitised with the first point being in the North, and the last point in the South, then the "left" plate is to the East. See diagram below. image::leftRight.jpg[] === Geological Planes and Common Properties GPlates also contains a number of features designed to model various types of geological planes, units, and contacts. * xref:feat-BasicRockUnit[BasicRockUnit] * xref:feat-Fault[Fault] * xref:feat-FoldPlane[FoldPlane] * xref:feat-GeologicalPlane[GeologicalPlane] * xref:feat-Unconformity[Unconformity] * xref:feat-UnknownContact[UnknownContact] xref:feat-BasicRockUnit[BasicRockUnit] can be used to model any unit of rock, xref:feat-Fault[Fault] can be used to model faults, xref:feat-FoldPlane[FoldPlane] can be used to model a fold axis plane, xref:feat-GeologicalPlane[GeologicalPlane] can be used to model bedding/cleavage planes, xref:feat-Unconformity[Unconformity] can be used to model the planes of unconformities, and xref:feat-UnknownContact[UnknownContact] can be used a general "catch all" feature. The "strike" of the geological plane should be contained in the xref:prop-centerLineOf[centerLineOf] property. Topographical representation of the plane could be stored in xref:prop-unclassifiedGeometry[unclassifiedGeometry]. ==== Common Properties All "geological plane" features have the following common properties: * xref:prop-dipAngle[dipAngle] * xref:prop-dipSide[dipSide] * xref:prop-leftUnit[leftUnit] (not currently working) * xref:prop-rightUnit[rightUnit] (not currently working) xref:prop-dipAngle[dipAngle] is the angle of the "dip" of the plane in degrees below the horizontal, while xref:prop-dipSide[dipSide] is the side (left or right) to which the plane dips. Note that again "left" and "right" are determined by the direction in which the geometry of the plane is defined -- if the line points North, left is to the West; if the same line points South, left is to the East. leftUnit and rightUnit in the future could be used to point to xref:feat-BasicRockUnit[BasicRockUnit]s on either side of the plane, but currently these properties are not enabled. ==== Faults A xref:feat-Fault[Fault] has the following additional properties: * xref:prop-dipSlip[dipSlip] * xref:prop-strikeSlip[strikeSlip] * xref:prop-primarySlipComponent[primarySlipComponent] xref:prop-dipSlip[dipSlip] specifies if the fault has a dip component or not, and if so whether it is a normal or reverse fault. xref:prop-strikeSlip[strikeSlip] specifies if the fault has a strike component or not, and if so, whether it is dextral or sinistral. xref:prop-primarySlipComponent[primarySlipComponent] specifies which of the two components, if any, is the larger. ==== Folds A xref:feat-FoldPlane[FoldPlane] also has the the additional property: * xref:prop-FoldAnnotation[FoldAnnotation] which specifies whether the fold is a syncline or anticline. ==== Bedding/Cleavage Planes A xref:feat-GeologicalPlane[GeologicalPlane] is used to store information for geological planes such as bedding and cleavage planes, for example. The specific type (ie "Bedding" or "Cleavage") can be stored in the xref:prop-subcategory[subcategory] property. === Other Physical Features and Common Properties Other physical GPlates features are listed below: * xref:feat-Basin[Basin] * xref:feat-Craton[Craton] * xref:feat-Isochron[Isochron] * xref:feat-HotSpot[HotSpot] * xref:feat-HotSpotTrail[HotSpotTrail] * xref:feat-LargeIgneousProvince[LargeIgneousProvince] * xref:feat-PseudoFault[PseudoFault] * xref:feat-Seamount[Seamount] * xref:feat-Suture[Suture] * xref:feat-Volcano[Volcano] * xref:feat-IslandArc[IslandArc] xref:feat-Basin[Basin], xref:feat-Craton[Craton], xref:feat-LargeIgneousProvince[LargeIgneousProvince], xref:feat-Volcano[Volcano], xref:feat-Seamount[Seamount], and xref:feat-Suture[Suture] are features with no unique properties. The user can use the xref:prop-subcategory[subcategory] property to further classify these features. For example, a xref:feat-Seamount[Seamount] can be classified as either a "seamount" or a "guyot". ==== Isochrons An xref:feat-Isochron[Isochron] has the following unique properties: * xref:prop-conjugate[conjugate] * xref:prop-conjugatePlateId[conjugatePlateId] These properties are used for keeping track of the conjugate isochron on the opposite side of the spreading ridge. Multiple instances of these properties can be added to keep track of multiple sections of the conjugate. xref:prop-conjugate[conjugate] points to a conjugate isochron feature, while xref:prop-conjugatePlateId[conjugatePlateId] refers to the plateId that associated it. ==== Hotspots and Hotspot Trails A xref:feat-HotSpot[HotSpot] has the unique property * xref:prop-trail[trail] which references the xref:feat-HotSpotTrail[HotSpotTrail] to which the xref:feat-HotSpot[HotSpot] is associated. ==== Island Arcs An xref:feat-IslandArc[IslandArc] has the unique property: * xref:prop-isActive[isActive] to specify whether the island arc is currently being generated by subduction. === Abstract Fields * xref:feat-Bathymetry[Bathymetry] * xref:feat-CrustalThickness[CrustalThickness] * xref:feat-DynamicTopography[DynamicTopography] * xref:feat-GlobalElevation[GlobalElevation] * xref:feat-Gravimetry[Gravimetry] * xref:feat-HeatFlow[HeatFlow] * xref:feat-OceanicAge[OceanicAge] * xref:feat-Topography[Topgraphy] The features above are designed to store "abstract field" field, such oceanic seafloor depth (bathymetry), topography, dynamic topography, etc. In the current version of GPlates, data regarding these features can be stored as contour lines, for example, a contour line indicating a seafloor depth of 4000m could be stored as a Bathymetry feature. In a future version of GPlates, it is intended to provide support for gridded (raster) data for these features. [[FileFormat]] == GPlates File Format === Overview GPlates stores its data in its own proprietary file format called GPlates Markup Language, or GPML. GPML is based on Geography Markup Language (GML), which is in turn based on eXtensible Markup Language (XML). === XML XML is a set of rules for encoding documents electronically. Data is encoded in plain-text, as elements in between "tags", which effectively define the purpose of the element. An XML document can often be read simply in a text editor. Because the meaning of each piece of data is stored with the data, an XML document can often be very easy to interpret. Below is an example XML document creating a "note" object, to "Bob" from "Bill". You can see the data portion of the "subject" element, for example, inbetween the "" tags. --------------------------------- Bob Bill The subject of the note. This is an XML representation of a note from Bill to Bob. --------------------------------- [[GML]] === GML GML is a grammar based on XML with the purpose of defining a framework for describing geographic objects. GML provides a number of geometry elements and tools such as feature relationships to create features in geographic models. The standardization of GML allows different GIS applications to communicate with each other in the same language. An example GML geometry element is provided below. The example is a line which forms a square with the coordinates (0,0), (1,0), (1,1) and (0,1). --------------------------------- 0 0 1 0 1 1 0 1 0 0 --------------------------------- === GPML GML provides built-in geometries and other elements for describing geographic objects. GPML contains a series of new features built based on GML structure to describe geographic features that may be useful in plate tectonic reconstructions. A GPML feature will consist of several GML properties such as name, description, and a GML geometry such as Point, LineString, or Polygon, and also several properties unique to GPML. For example, a MidOceanRidge feature in GPML will have an isActive property, which specifies whether the ridge is actively spreading or if it has become inactive. An example of a GPML file produced by GPlates is provided below. The file consists of a single feature, the famous Nakata Isochron. The GML geometry for LineString can be seen in the gpml:centerLineOf property. --------------------------------- It's an Isochron CARLSBERG RIDGE, INDIA-AFRICA ANOMALY 5 ISOCHRON Nakata Isochron GPlates-1163390205.0-jboyden.aurora.28095 GPlates-1163390205.4-jboyden.aurora.28095 GPlates-1163390205.1-jboyden.aurora.9528 GPlates-1163390205.2-jboyden.aurora.9528 GPlates-1163390205.1-jclark.polygon.3287 GPlates-1163390205.3-jboyden.aurora.28095 11 22 3333 CARLSBERG RIDGE 501 00010.9 999.0 IS 4444 Z 502 078 2 10.9 http://gplates.org/times/distantFuture gpml:plateId 501 gpml:Isochron GPlates-1163486717.5-jboyden.aurora.28095 502 gml:OrientableCurve 89.95 71.66 45.33 70.80 --------------------------------- [[Conversion]] == Converting From Other File Formats GPlates is able to read and write in a diverse set of file formats. The primary issue when converting file formats is the information that is stored under each file format. For example, Shapefiles produced from ArcGIS contain the geometry of features, and the metadata in these files can be used to store important information such as beginning/ending time, however, in general they do not store a lot of important information that GPlates expects to have. This is because ArcGIS is a more general GIS modeling tool that is not designed specifically for plate tectonics. On the other hand, PLATES4 was a program designed for a similar purpose as GPlates, and contains much data that GPlates finds useful, however, not all GPlates properties will be populated by a PLATES program. === Shapefiles Shapefiles are a popular data format for geographic information software. GPlates is able to read in shapefiles given that certain conditions are met. A shapefile is a digital storage format for storing geometric location data and associated attributes. It can store primitive geometrical data types of points, lines and polygons. A shapefile actually consists of several files: the .shp which contains the feature geometry, the .shx index file, and the .dbf file for storing attribute data. GPlates needs all three in order to properly read a shapefile. GPlates reads in the geometry of the feature from the .shp file. When GPlates reads a shapefile, it assumes that the (x,y) coordinates in the shapefile are in the format (latitude, longitude), in degrees from -90 to 90 for latitude and -180 to +180 for longitude. GPlates can also read in other information from the attribute information, but because attributes can be named anything in a shapefile, GPlates needs to know what exactly to look for. This is dealt with in http://www.gplates.org/user-manual/Shapefiles.html[Chapter 12 of the GPlates User Documentation]. === PLATES Files PLATES is an older software with a similar design to GPlates. It is useful for GPlates to be able to read PLATES files, partly because of the information stored in these input files, but also due to the legacy software programs that use PLATES files as input. GPlates data can be converted into PLATES data in order to make use of these programs. PLATES files come with the following header information for each feature. GPlates stores the entire header (in the xref:prop-oldPlatesHeader[oldPlatesHeader] property), but does not actually use most of it. * regionNumber (2 digit integer) * referenceNumber (2 digit integer) * stringNumber (4 digit integer) * geographicDescription(ASCII string, no specified length) * plateIdNumber (3 digit integer) * ageOfAppearance (6 char, 1 double precision floating point number, in Ma) * ageOfDisappearance (6 char, 1 double precision floating point number, in Ma) * dataTypeCode (ASCII string, 2 characters) * dataTypeCodeNumber (4 digit integer) * dataTypecodeNumberAdditional (1 character) * conjugatePlateIdNumber (3 digit integer) * colourCode (3 digit integer) * numberOfPoints (5 digit integer) geographicDescription is used to populate xref:prop-gml:name[name]. plateIDnumber is used to populate xref:prop-reconstructionPlateId[reconstructionPlateId]. ageOfAppearance and ageOfDisappearance are used to populate xref:prop-gml:validTime[gml:validTime]. For appropriate feature types, such as xref:feat-Isochron[Isochron], conjugatePlateIdNumber is used to populate xref:prop-conjugatePlateId[conjugatePlateId]. dataTypeCode is a two character code that is used to specify the type of feature. GPlates maps this code to GPlates feature types using the table below: [[PLATESTable]] .PLATES Table [format="csv",grid="all",width="50%", valign="middle", cols="1^,1<"] |================================ *PLATES Code*,*GPlates Data Type* include::platestable_out.csv[] |================================ == Appendix: GPlates Features and Properties Tables [[FeatureTable]] .Features Table [format="csv",grid="all", valign="middle", width="75%", cols="20%^strong,20%^,60%<"] |==================================== *Feature*,*Properties*,*Description* include::features_out.csv[] |==================================== [[PropertiesTable]] .Properties Table [format="csv",grid="all", valign="middle", width="75%", cols="15%^strong,15%^,15%^,55%<"] |==================================== *Property*,*Optionality*,*Used In*,*Description* include::properties_out.csv[] |====================================