gmtpmodeler¶

Evaluate a plate motion model at given locations

Synopsis¶

gmt pmodeler table -Erot_file|ID1-ID2|lon/lat/angle[+i] -Sflags [ -Fpolygonfile ] [ -Tage ] [ -V[level] ] [ -bbinary ] [ -d[+ccol]nodata ] [ -eregexp ] [ -fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [ -oflags ] [ -qflags ] [ -sflags ] [ -:[i|o] ] [ --PAR=value ]

Note: No space is allowed between the option flag and the associated arguments.

Description¶

pmodeler reads a table with lon, lat and optionally age triplets and a plate motion model and evaluates one of several model predictions. Optionally, the user may supply a clipping polygon in multiple-segment format; then, only the part of the points inside the polygon are used to determine the model prediction. The results are written to standard output.

Required Arguments¶

table: Name of one or more tables with geographical (lon, lat) coordinates and optionally a third column with ages in Myr. If no file is given then we read from standard input.

-Erot_file|ID1-ID2|lon/lat/angle[+i]

Rotations can be specified in one of three ways: (1): Give file with rotation parameters. This file must contain one record for each rotation; each record must be of the following format:

lon lat tstart [tstop] angle [ khat a b c d e f g df ]

where tstart and tstop are in Myr and lon lat angle are in degrees. tstart and tstop are the ages of the old and young ends of a stage. If tstop is not present in the record then a total reconstruction rotation is expected and tstop is implicitly set to 0 and should not be specified for any of the records in the file. If a covariance matrix C for the rotation is available it must be specified in a format using the nine optional terms listed in brackets. Here, C = (g/khat)*[ a b d; b c e; d e f ] which shows C made up of three row vectors. If the degrees of freedom (df) in fitting the rotation is 0 or not given it is set to 10000. Blank lines and records whose first column contains # will be ignored. (2): Give the filename composed of two plate IDs separated by a hyphen (e.g., PAC-MBL) and we will instead extract that rotation from the GPlates rotation database. We return an error if the rotation cannot be found. (3): Specify lon/lat/angle, i.e., the longitude, latitude, and opening angle (all in degrees and separated by /) for a single total reconstruction rotation. Regardless of method, you may append +i to the argument to indicate you wish to invert the rotation(s).

-Sflags: Type of model prediction(s). Append one or more items: choose from a for plate motion azimuth, d for great-circle distance between current location and its origin at the ridge (in km), s for plate motion model stage ID (1 is youngest), v for plate motion rate (in mm/yr), w for plate rotation rate (degree/Myr), x for change in longitude relative to location of crust formation, y for change in latitude relative to location of crust formation, X for longitude of crust formation, and Y for latitude of crust formation. If no arguments are given we default to all [adsvwxyXY].

Optional Arguments¶

-Fpolygonfile: Specify a multisegment closed polygon file that describes the area where the model should be evaluated; points outside will be skipped [use all data points].

-Tage: Use a fixed age for model evaluation (i.e., override the ages given in the input table). This lets you evaluate the model at a snapshot in time, and is a required option if the input table does not contain ages.

-V[level]: Select verbosity level [w]. (See full description) (See cookbook information).

-birecord[+b|l] (more …): Select native binary format for primary table input. [Default is 2 input columns].

-d[i|o][+ccol]nodata (more …): Replace input columns that equal nodata with NaN and do the reverse on output.

-e[~]“pattern” | -e[~]/regexp/[i] (more …): Only accept data records that match the given pattern.

-f[i|o]colinfo (more …): Specify data types of input and/or output columns.

-gx|y|z|d|X|Y|Dgap[u][+a][+ccol][+n|p] (more …): Determine data gaps and line breaks.

-h[i|o][n][+c][+d][+msegheader][+rremark][+ttitle] (more …): Skip or produce header record(s).

-icols[+l][+ddivisor][+sscale|d|k][+ooffset][,…][,t[word]] (more …): Select input columns and transformations (0 is first column, t is trailing text, append word to read one word only).

-ocols[,…][,t[word]] (more …): Select output columns (0 is first column; t is trailing text, append word to write one word only).

-q[i|o][~]rows|limits[+ccol][+a|f|s] (more …): Select input or output rows or data limit(s) [all].

-s[cols][+a][+r] (more …): Set handling of NaN records for output.

-^ or just -: Print a short message about the syntax of the command, then exit (NOTE: on Windows just use -).
-+ or just +: Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exit.
-? or no arguments: Print a complete usage (help) message, including the explanation of all options, then exit.
--PAR=value: Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Geodetic versus Geocentric Coordinates¶

All spherical rotations are applied to geocentric coordinates. This means that incoming data points and grids are considered to represent geodetic coordinates and must first be converted to geocentric coordinates. Rotations are then applied, and the final reconstructed points are converted back to geodetic coordinates. This default behavior can be bypassed if the ellipsoid setting PROJ_ELLIPSOID is changed to Sphere.

Inside/outside Status¶

To determine if a point is inside, outside, or exactly on the boundary of a polygon we need to balance the complexity (and execution time) of the algorithm with the type of data and shape of the polygons. For any Cartesian data we use a non-zero winding algorithm, which is quite fast. For geographic data we will also use this algorithm as long as (1) the polygons do not include a geographic pole, and (2) the longitude extent of the polygons is less than 360. If this is the situation we also carefully adjust the test point longitude for any 360 degree offsets, if appropriate. Otherwise, we employ a full spherical ray-shooting method to determine a points status.

Examples¶

We will use a table with locations and ages of Pacific crust (pac_age.txt), a plate motion model (Pac_APM.txt), and a polygon that contains the outline of the present Pacific plate (pac_clip_path.txt). To evaluate the plate motion azimuths at the present time for the Pacific, try

gmt pmodeler pac_age.txt -EPac_APM.txt -V -Fpac_clip_path.txt \
                 -Sa -T0 > pac_dir_0.txt

To determine the changes in latitude since crust formation for the entire Pacific, try

gmt pmodeler pac_age.txt -EPac_APM.txt -V -Fpac_clip_path.txt \
                -Sy > pac_dlat.txt

To determine the plate motion velocities in effect when the Pacific crust was formed, try

gmt pmodeler pac_age.txt -EPac_APM.txt -V -Fpac_clip_path.txt \
                -Sv > pac_vel.txt

To determine how far the crust has moved since formation, try

gmt pmodeler pac_age.txt -EPac_APM.txt -V -Fpac_clip_path.txt \
                -Sd > pac_dist.txt

To save the coordinates of the crust’s formation, try

gmt pmodeler pac_age.txt -EPac_APM.txt -V -Fpac_clip_path.txt \
                -SXY > ac_origin_xy.txt

Notes¶

GMT distributes the EarthByte rotation model Global_EarthByte_230-0Ma_GK07_AREPS.rot. To use an alternate rotation file, create an environmental parameters named GPLATES_ROTATIONS that points to an alternate rotation file.