psternary

Plot data on ternary diagrams

Synopsis

gmt psternary [ table ] [ -JXwidth[unit] ] [ -Rwest/east/south/north[/zmin/zmax][+r][+uunit] ] [ -B[p|s]parameters ] [ -Ccpt ] [ -Gfill ] [ -K ] [ -La/b/c ] [ -M ] [ -N ] [ -O ] [ -P ] [ -S[symbol][size[u] ] [ -U[stamp] ] [ -V[level] ] [ -W[pen][attr] ] [ -X[a|c|f|r][xshift[u]] ] [ -Y[a|c|f|r][yshift[u]] ] [ -aflags ] [ -bibinary ] [ -dinodata ] [ -eregexp ] [ -fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [ -pflags ] [ -ttransp ] [ -:[i|o] ] [ --PAR=value ]

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

Description

Reads (a,b,c[,z]) records from files [or standard input] and plots symbols at those locations on a ternary diagram. If a symbol is selected and no symbol size given, then we will interpret the fourth column of the input data as symbol size. Symbols whose size is <= 0 are skipped. If no symbols are specified then the symbol code (see -S below) must be present as last column in the input.

Required Arguments

Either -M (for dumping data) or -R and -J must be selected.

Optional Arguments

table
One or more ASCII (or binary, see -bi[ncols][type]) data table file(s) holding a number of data columns. If no tables are given then we read from standard input. Use -T to ignore all input files, including standard input (see below).
-B[a|b|c]args
For ternary diagrams the three sides are referred to as a, b, and c. Thus, to give specific settings for one of these axis you must include the axis letter before the arguments. If all axes have the same arguments then only give one option without the axis letter. For more details, see the -B discussion in basemap.
-Ccpt
Give a CPT or specify -Ccolor1,color2[,color3,…] to build a linear continuous CPT from those colors automatically. In this case colorn can be a r/g/b triplet, a color name, or an HTML hexadecimal color (e.g. #aabbcc ). If -S is set, let symbol fill color be determined by the z-value in the fourth column. Additional fields are shifted over by one column (optional size would be 5th rather than 4th field, etc.). If modern mode and no argument is given then we select the current CPT.
-Gfill (more …)
Select color or pattern for filling of symbols [Default is no fill]. Note that we will search for -G and -W strings in all the segment headers and let any values thus found over-ride the command line settings.
-JXwidth [unit]
The only valid projection is linear plot with specified ternary width.
-La/b/c
Set the labels for the three diagram vertices [none]. These are placed a distance of 3 times the MAP_LABEL_OFFSET setting from their respective corners.
-M
Do no plotting. Instead, convert the input (a,b,c[,z]) records to Cartesian (x,y,[,z]) records, where x, y are normalized coordinates on the triangle (i.e., 0–1 in x and 0–sqrt(3)/2 in y).
-N
Do NOT clip symbols that fall outside map border [Default plots points whose coordinates are strictly inside the map border only].
-Ramin/amax/bmin/bmax/cmin/cmax
Give the min and max limits for each of the three axis a, b, and c.
-S[symbol][size[u]]

Plot individual symbols. If present, size is symbol size in the unit set in gmt.conf (unless c, i, or p is appended). If the symbol code (see below) is not given it will be read from the last column in the input data; this cannot be used in conjunction with binary input. Optionally, append c, i, or p to indicate that the size information in the input data is in units of cm, inch, or point, respectively [Default is PROJ_LENGTH_UNIT]. Note: if you provide both size and symbol via the input file you must use PROJ_LENGTH_UNIT to indicate the unit used for the symbol size or append the units to the sizes in the file. If symbol sizes are expected via the third data column then you may convert those values to suitable symbol sizes via the -i mechanism.

The uppercase symbols A, C, D, G, H, I, N, S, T are normalized to have the same area as a circle with diameter size, while the size of the corresponding lowercase symbols refers to the diameter of a circumscribed circle.

You can change symbols by adding the required -S option to any of your multisegment headers.

Choose between these symbol codes:

-S-
x-dash (-). size is the length of a short horizontal (x-dir) line segment.
-S+
plus (+). size is diameter of circumscribing circle.
-Sa
star. size is diameter of circumscribing circle.
-Sb[size[c|i|p|u]][+b[base]]
Vertical bar extending from base to y. The size is bar width. Append u if size is in x-units [Default is plot-distance units]. By default, base = 0. Append +b[base] to change this value. If base is not appended then we read it from the last input data column. Use +B[base] if the bar height is measured relative to base [Relative to origin].
-SB[size[c|i|p|u]][+b[base]]
Horizontal bar extending from base to x. The size is bar width. Append u if size is in y-units [Default is plot-distance units]. By default, base = 0. Append +b[base] to change this value. If base is not appended then we read it from the last input data column. Use +B[base] if the bar length is measured relative to base [Relative to origin].
-Sc
circle. size is diameter of circle.
-Sd
diamond. size is diameter of circumscribing circle.
-Se
ellipse. Direction (in degrees counter-clockwise from horizontal), major_axis, and minor_axis must be found in columns 3, 4, and 5.
-Sg
octagon. size is diameter of circumscribing circle.
-Sh
hexagon. size is diameter of circumscribing circle.
-Si
inverted triangle. size is diameter of circumscribing circle.
-Sj
Rotated rectangle. Direction (in degrees counter-clockwise from horizontal), x-dimension, and y-dimension must be found in columns 3, 4, and 5.
-Sk
kustom symbol. Append name/size, and we will look for a definition file called name.def in (1) the current directory or (2) in ~/.gmt or (3) in $GMT_SHAREDIR/custom. The symbol as defined in that file is of size 1.0 by default; the appended size will scale symbol accordingly. Users may add their own custom *.def files; see CUSTOM SYMBOLS below.
-Sl
letter or text string (less than 256 characters). Give size, and append +tstring after the size. Note that the size is only approximate; no individual scaling is done for different characters. Remember to escape special characters like *. Optionally, you may append +ffont to select a particular font [Default is FONT_ANNOT_PRIMARY] and +jjustify to change justification [CM].
-Sn
pentagon. size is diameter of circumscribing circle.
-Sp
point. No size needs to be specified (1 pixel is used).
-Sr
rectangle. No size needs to be specified, but the x- and y-dimensions must be found in columns 3 and 4.
-SR
Rounded rectangle. No size needs to be specified, but the x- and y-dimensions and corner radius must be found in columns 3, 4, and 5.
-Ss
square. size is diameter of circumscribing circle.
-St
triangle. size is diameter of circumscribing circle.
-Sw
pie wedge. Start and stop directions (in degrees counter-clockwise from horizontal) for pie slice must be found in columns 3 and 4. Append /inner to select a separate inner diameter [0]. Append +a[dr] to draw the arc line (at inner and outer diameter); if dr is appended then we draw all arc lines separated radially by dr. Append +r[da] to draw radial lines (at start and stop directions) if da is appended then we draw all radial lines separated angularly by da. These spider-web lines are drawn using the current pen unless +ppen is added.
-SW
Same as -Sw, except azimuths (in degrees east of north) should be given instead of the two directions. The azimuths will be mapped into angles based on the chosen map projection (-Sw leaves the directions unchanged). Specify size as a geographical diameter. For allowable geographical units, see UNITS [Default is k for km]. To instead specify a diameter in plot units, you must append the desired unit. Append /inner to select a separate inner diameter [0]. Append +a[dr] to draw the arc line (at inner and outer diameter); if dr is appended then we draw all arc lines separated radially by dr. Append +r[da] to draw radial lines (at start and stop directions) if da is appended then we draw all radial lines separated angularly by da. These spider-web lines are drawn using the current pen unless +ppen is added.
-Sx
cross (x). size is diameter of circumscribing circle.
-Sy
y-dash (|). size is the length of a short vertical (y-dir) line segment.
-U[label][+c][+jjust][+odx/dy] (more …)
Draw GMT time stamp logo on plot.
-V[level] (more …)
Select verbosity level [c].
-W[pen][attr] (more …)
Set pen attributes for the outline of symbols.

-X[a|c|f|r][xshift[u]]

-Y[a|c|f|r][yshift[u]] (more …)
Shift plot origin.
-bi[ncols][t] (more …)
Select native binary format for primary input. [Default is the required number of columns given the chosen settings].
-acol=name[] (more …)
Set aspatial column associations col=name.
-dinodata (more …)
Replace input columns that equal nodata with NaN.
-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.
-g[a]x|y|d|X|Y|D|[col]zgap[u][+n|p] (more …)
Determine data gaps and line breaks. The -g option is ignored if -S is set.
-h[i|o][n][+c][+d][+rremark][+rtitle] (more …)
Skip or produce header record(s).
-icols[+l][+sscale][+ooffset][,][,t[word]] (more …)
Select input columns and transformations (0 is first column, t is trailing text, append word to read one word only).
-:[i|o] (more …)
Swap 1st and 2nd column on input and/or output.
-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more …)
Select perspective view.
-t[transp] (more …)
Set transparency level in percent.
-^ or just -
Print a short message about the syntax of the command, then exits (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 exits.
-? or no arguments
Print a complete usage (help) message, including the explanation of all options, then exits.
--PAR=value
Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Units

For map distance unit, append unit d for arc degree, m for arc minute, and s for arc second, or e for meter [Default], f for foot, k for km, M for statute mile, n for nautical mile, and u for US survey foot. By default we compute such distances using a spherical approximation with great circles (-jg) using the authalic radius (see PROJ_MEAN_RADIUS). You can use -jf to perform “Flat Earth” calculations (quicker but less accurate) or -je to perform exact geodesic calculations (slower but more accurate; see PROJ_GEODESIC for method used).

Vector Attributes

Several modifiers may be appended to vector-producing options for specifying the placement of vector heads, their shapes, and the justification of the vector. Below, left and right refers to the side of the vector line when viewed from the start point to the end point of a segment:

+aangle sets the angle of the vector head apex [30].

+b places a vector head at the beginning of the vector path [none]. Optionally, append t for a terminal line, c for a circle, a for arrow [Default], i for tail, A for plain open arrow, and I for plain open tail. Further append l|r to only draw the left or right half-sides of this head [both sides].

+e places a vector head at the end of the vector path [none]. Optionally, append t for a terminal line, c for a circle, a for arrow [Default], i for tail, A for plain open arrow, and I for plain open tail. Further append l|r to only draw the left or right half-sides of this head [both sides].

+g-|fill turns off vector head fill (if -) or sets the vector head fill [Default fill is used, which may be no fill].

+hshape sets the shape of the vector head (range -2/2). Default is controlled by MAP_VECTOR_SHAPE [0].

+l draws half-arrows, using only the left side of specified heads [both sides].

+m places a vector head at the mid-point the vector path [none]. Append f or r for forward or reverse direction of the vector [forward]. Optionally, append t for a terminal line, c for a circle, a for arrow [Default], i for tail, A for plain open arrow, and I for plain open tail. Further append l|r to only draw the left or right half-sides of this head [both sides]. Cannot be combined with +b or +e.

+nnorm scales down vector attributes (pen thickness, head size) with decreasing length, where vector plot lengths shorter than norm will have their attributes scaled by length/norm [arrow attributes remains invariant to length]. For Cartesian vectors specify a length in plot units, while for geovectors specify a length in km.

+o[plon/plat] specifies the oblique pole for the great or small circles. Only needed for great circles if +q is given. If no pole is appended then we default to the north pole.

+p[-][pen] sets the vector pen attributes. If pen has a leading - then the head outline is not drawn. [Default pen is half the width of stem pen, and head outline is drawn]

+q means the input angle, length data instead represent the start and stop opening angles of the arc segment relative to the given point. See +o to specify a specific pole for the arc [north pole].

+r draws half-arrows, using only the right side of specified heads [both sides].

+t[b|e]trim[unit] will shift the beginning or end point (or both) along the vector segment by the given trim; append suitable unit (c, i, or p). If the modifiers b|e are not used then trim may be two values separated by a slash, which is used to specify different trims for the beginning and end. Positive trims will shorted the vector while negative trims will lengthen it [no trim].

In addition, all but circular vectors may take these modifiers:

+jjust determines how the input x,y point relates to the vector. Choose from beginning [default], end, or center.

+s means the input angle, length are instead the x, y coordinates of the vector end point.

Finally, Cartesian vectors may take these modifiers:

+zscale[unit] expects input dx,dy vector components and uses the scale to convert to polar coordinates with length in given unit.

Classic Mode Arguments

These options are used to manipulate the building of layered GMT PostScript plots in classic mode. They are not available when using GMT modern mode.

-K (more …)
Do not finalize the PostScript plot.
-O (more …)
Append to existing PostScript plot.
-P (more …)
Select “Portrait” plot orientation.

Examples

Note: Below are some examples of valid syntax for this module. The examples that use remote files (file names starting with @) can be cut and pasted into your terminal for testing. Other commands requiring input files are just dummy examples of the types of uses that are common but cannot be run verbatim as written.

To plot circles (diameter = 0.1 cm) on a 6-inch-wide ternary diagram at the positions listed in the file ternary.txt, with default annotations and gridline spacings, using the specified labeling, tru

gmt psternary ternary.txt -R0/100/0/100/0/100 -JX6i -P -Xc -Baafg+l"Water component"+u" %" \
-Bbafg+l"Air component"+u" %" -Bcagf+l"Limestone component"+u" %" \
-B+givory+t"Example data from MATLAB Central" -Sc0.1c -Ct.cpt -Y2i -LWater/Air/Limestone > map.ps