This document provides an overview about the gptools
(short for "Tools for GPlates") script
collection in this Fossil repository.
The purpose of these Python-based routines is to carry out
some housekeeping on rotation files (both, the new *.grot
format and legacy
*.rot
formats) as well as for generating other useful datasets such as
reconstructable graticules for the free and open source
GPlates software for plate kinematic modelling or
extracting bibliographic information from rotation files.
See "License" or the below link for a license of the tools in
this repository. If you end up using any of the scripts in your publications,
please acknowledge the author(s) and the repository URL
http://code.paleoearthlabs.org/gptools
along with access date/check-in tag/version.
Tools
The repository is subdivided into different directories containing a number of different Python scripts:
1. Formatting of rotation files
Metadata is critical for reproducible science through providing a context for
models or acquired data. Plate kinematic models usually consist of two key
input data - a spatial data set describing the extent and lifespan of tectonic
plates and a second dataset describing the plate kinematic framework through
a time-dependent, tree-like hierarchical structure of finite rotation sequences.
The latter are commonly denoted as rotation files which have been following a
standard based on the old PLATES4
software. This standard, however,
only specifies the critical input data structure (moving plate ID
, age
,
pole lat
, pole lon
, angle
, fixed plate ID
) and that this information
is supposed to come in blocks of so-called moving plate rotation sequences with
rotations of the same moving plate rotation sequence
(MPRS) grouped. A free
form comment was allowed to follow the actual rotation data providing knowledge
about the author/origin of the data (e.g. citations, a modification date, a
short comment on observational constraints).
A number of problems arise with free form comments and unstructured blocks of
MPRSs. Firstly, given the rise in popularity of source code management tools
such as GIT, SVN or Fossil
file structuration and line ordering becomes important for diff
operations.
Secondly, structuration and standardisation of meta data (comments, citations,
key-value pairs) is also required for file comparison. Lastly, metadata
fosters and improves reproducibility by providing e.g. citations/DOIs to
papers used, comments on observations or changes and allows for easier
interchange of model data. The scripts related to rotation file formatting and
conversion in this repository help to cast rotation files into the more
standardised *.grot
format (see supplemental material to
Qin et al., 2012 and
GROT file format description).
The formatting
directory contains two main scripts to reformat, convert
and clean up rotation files, in particular the new GPlates *.grot
format:
rotconv.py
converts and formats standard*.rot
files to the new-ish*.grot
rotation file format which GPlates can read and has a richer and structured set of metadata. It is also able to convert*.dbf
files which are the default format when exporting from PaleoGIS(r) to the new*.grot
format.rotconv
will report statics such as the number of plates, plate acronyms, plate names, zero rotations, future rotations. A (evolving) documentation is available heregrotcat.py
allows to concatenateGROT
-formatted rotation files.
2. Reconstructable graticules
Plate tectonic reconstructions require to provide a present-day reference for the readers. While country outlines or coastlines are one of the most common features used for such visual guidance, present-day map graticules, rotated back in time and cookie-cut to tectonic block outlines can provide a time-independent visual guidance.
The graticules
subdirectory contains a script
to generate graticule lines for reconstructions. The graticule is generated as
reconstructable feature which can be cookie-cut.
.
3. Plotting time-dependent reconstruction tree hierarchies
vis-rot
is a Python2 script which was written by
James Boyden at the University of Sydney's EarthByte group in 2006 to visualise
time-dependent rotation tree hierarchies and released under the GPL v2 license.
I have translated it to Python3 syntax using the 2to3
converter.
The script visualises a rotation tree at a specfific time using the dot
program of the Graphviz software, which is required to
be installed. However, as James points out:
"[...] please note that this program was not written by the authors of the Graphviz package; please do not email them about any problems you may have with this program."
The vis-rot
script has a short help menu explaining the usage and can be
invoked with vis-rot -h
. The source file is accessible here.
./vis-rot.py test.png ../tests/Global_EB_250-0Ma_GK07_Matthews_etal.rot 130 280:714
generates the graph shown below, with plates between 714
and 280
at 130 Ma
coloured:
See the original size image output here.
Requirements/dependencies
See wiki for requirements
Repository use
This repository is hosted using the self-contained Fossil distributed version control software.
- A zip file of the repository content can be downloaded on the Downloads page
- A Forum to discuss the scripts
- An issue tracker to log tickets
- A timeline
Tickets and forum can be used anonymously, however, users can also create an account.
To clone the repository, you have to install Fossil
first. The workflow is similar to git
, yet you will also have access to the
wiki, documentation, and tickets in one go:
fossil clone https://code.paleoearthlabs.org/gptools/ gptools
cd
/mkdir
to the directory which you want to be the root of your directory tree for this repository, thenfossil open <path>/<to>/<gptools clone>/gptools.fossil
For detailed instructions, please see the Fossil Quick Start guide.
License
Unless otherwise stated the scripts are licensed using the GNU General Public License v3 GPLv3 .
Documentation is relased under a Creative Commons Attribution--ShareAlike 3.0 Unported License.
Copyright (c) Christian Heine, 2013-2022 PaleoGIS (TM) is a registered trademark of the Rothwell Group L.P.