gmtconvert(1) GMT gmtconvert(1)
NAME
gmtconvert - Convert, Paste, and/or Extract columns from data tables
SYNOPSIS
gmtconvert [ table ] [ -A ] [ -C[+lmin][+umax][+i]] [ -D[tem-
plate[+oorig]] ] [ -E[f|l|mstride] ] [ -L ] [ -F[c|n|r|v][refpoint]
] [ -I[tsr] ] [ -Q[~]selection] [ -S[~]^<i>asearch string^<i>a | -S[~]/reg-
exp/[i] ] [ -T ] [ -V[level] ] [ -aflags ] [ -bbinary ] [ -dnodata ]
[ -eregexp ] [ -fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [ -oflags
] [ -sflags ] [ -:[i|o] ]
Note: No space is allowed between the option flag and the associated
arguments.
DESCRIPTION
gmtconvert reads its standard input [or input files] and writes out the
desired information to standard output. It can do a combination of nine
tasks: (1) convert between binary and ASCII data tables, (2) paste cor-
responding records from multiple files horizontally into a single file,
(3) extract a subset of the available columns, (4) only extract seg-
ments whose header record matches a text pattern search, (5) only list
segment headers and no data records, (6) extract first and/or last data
record for each segment, (7) reverse the order of items on output, (8)
output only ranges of segment numbers, and (9) output only segments
whose record count matches criteria. Input (and hence output) may have
multiple sub-headers, and ASCII tables may have regular headers as
well.
REQUIRED ARGUMENTS
None
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.
-A The records from the input files should be pasted horizontally,
not appended vertically [Default]. All files must have the same
number of segments and number of rows per segment. Note for
binary input, all the files you want to paste must have the same
number of columns (as set with -bi); ASCII tables can have dif-
ferent number of columns.
-C[+lmin][+umax][+i]
Only output segments whose number of records matches your given
criteria: Append +lmin to ensure all segment must have at least
min records to be written to output [0], and append +umax to
ensure all segments must have at most max records to be written
[inf]. You may append +i to invert the selection, i.e., only
segments with record counts outside the given range will be out-
put.
-D[template[+oorig]]
For multiple segment data, dump each segment to a separate out-
put file [Default writes a multiple segment file to stdout].
Append a format template for the individual file names; this
template must contain a C format specifier that can format an
integer argument (the running segment number across all tables);
this is usually %d but could be %08d which gives leading zeros,
etc. [Default is gmtconvert_segment_%d.{txt|bin}, depending on
-bo]. Append +oorig to start the numbering from orig instead of
zero. Alternatively, give a template with two C format speci-
fiers and we will supply the table number and the segment number
within the table to build the file name. Append +otorig/sorig
to start the numbering of tables from torig and numbering of
segments within a table from sorig instead of zero. The +o mod-
ifier will be stripped off before the template is used.
-E[f|l|mstride]
Only extract the first and last record for each segment of
interest [Default extracts all records]. Optionally, append f or
l to only extract the first or last record of each segment,
respectively. Alternatively, append mstride to extract only one
out of stride records.
-F[c|n|r|v][refpoint]
Alter the way points are connected (by specifying a scheme) and
data are grouped (by specifying a method). Append one of four
line connection schemes: c: Form continuous line segments for
each group [Default]. r: Form line segments from a reference
point reset for each group. n: Form networks of line segments
between all points in each group. v: Form vector line segments
suitable for psxy -Sv+s. Optionally, append the one of four
segmentation methods to define the group: a: Ignore all segment
headers, i.e., let all points belong to a single group, and set
group reference point to the very first point of the first file.
f: Consider all data in each file to be a single separate group
and reset the group reference point to the first point of each
group. s: Segment headers are honored so each segment is a
group; the group reference point is reset to the first point of
each incoming segment [Default]. r: Same as s, but the group
reference point is reset after each record to the previous point
(this method is only available with the -Fr scheme). Instead of
the codes a|f|s|r you may append the coordinates of a refpoint
which will serve as a fixed external reference point for all
groups.
-I[tsr]
Invert the order of items, i.e., output the items in reverse
order, starting with the last and ending up with the first item
[Default keeps original order]. Append up to three items that
should be reversed: t will reverse the order of tables, s will
reverse the order of segments within each table, and r will
reverse the order of records within each segment [Default].
-L Only output a listing of all segment header records and no data
records (requires ASCII data).
-Q[~]selection
Only write segments whose number is included in selection and
skip all others. Cannot be used with -S. The selection syntax is
range[,range,a|] where each range of items is either a single
segment number or a range with stepped increments given via
start[:step:]:stop (step is optional and defaults to 1). A lead-
ing ~ will invert the selection and write all segments but the
ones listed. Instead of a list of ranges, use +ffile to supply
a file list with one range per line.
-S[~]^<i>asearch string^<i>a or -S[~]/regexp/[i]
Only output those segments whose header record contains the
specified text string. To reverse the search, i.e., to output
segments whose headers do not contain the specified pattern, use
-S~. Should your pattern happen to start with ~ you need to
escape this character with a backslash [Default output all seg-
ments]. Cannot be used with -Q. For matching segments based on
aspatial values (via OGR/GMT format), give the search string as
varname=value and we will compare value against the value of
varname for each segment. Note: If the features are polygons
then a match of a particular polygon perimeter also means that
any associated polygon holes will also be matched. For matching
segment headers against extended regular expressions enclose the
expression in slashes. Append i for case-insensitive matching.
For a list of such patterns, give +ffile with one pattern per
line. To give a single pattern starting with +f, escape it with
a backslash.
-T Suppress the writing of segment headers on output.
-V[level] (more a|)
Select verbosity level [c].
-acol=name[^<i>a|] (more a|)
Set aspatial column associations col=name.
-bi[ncols][t] (more a|)
Select native binary input.
-bo[ncols][type] (more a|)
Select native binary output. [Default is same as input].
-d[i|o]nodata (more a|)
Replace input columns that equal nodata with NaN and do the
reverse on output.
-e[~]^<i>apattern^<i>a | -e[~]/regexp/[i] (more a|)
Only accept data records that match the given pattern.
-f[i|o]colinfo (more a|)
Specify data types of input and/or output columns.
-g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more a|)
Determine data gaps and line breaks.
-h[i|o][n][+c][+d][+rremark][+rtitle] (more a|)
Skip or produce header record(s).
-icols[+l][+sscale][+ooffset][,^<i>a|] (more a|)
Select input columns and transformations (0 is first column).
-ocols[,a|] (more a|)
Select output columns (0 is first column).
-s[cols][a|r] (more a|)
Set handling of NaN records.
-:[i|o] (more a|)
Swap 1st and 2nd column on input and/or output.
-^ 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 explana-
tion 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.
ASCII FORMAT PRECISION
The ASCII output formats of numerical data are controlled by parameters
in your gmt.conf file. Longitude and latitude are formatted according
to FORMAT_GEO_OUT, absolute time is under the control of FOR-
MAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point val-
ues are formatted according to FORMAT_FLOAT_OUT. Be aware that the for-
mat in effect can lead to loss of precision in ASCII output, which can
lead to various problems downstream. If you find the output is not
written with enough precision, consider switching to binary output (-bo
if available) or specify more decimals using the FORMAT_FLOAT_OUT set-
ting.
EXAMPLES
To convert the binary file test.b (single precision) with 4 columns to
ASCII:
gmt convert test.b -bi4f > test.dat
To convert the multiple segment ASCII table test.d to a double preci-
sion binary file:
gmt convert test.d -bo > test.b
You have an ASCII table with 6 columns and you want to plot column 5
versus column 0. Try
gmt convert table.d -o5,0 | psxy ...
If the file instead is the binary file results.b which has 9 sin-
gle-precision values per record, we extract the last column and columns
4-6 and write ASCII with the command
gmt convert results.b -o8,4-6 -bi9s | psxy ...
You want to plot the 2nd column of a 2-column file left.d versus the
first column of a file right.d:
gmt convert left.d right.d -A -o1,2 | psxy ...
To extract all segments in the file big_file.d whose headers contain
the string aRIDGE AXISa, try
gmt convert big_file.d -S"RIDGE AXIS" > subset.d
To invert the selection of segments whose headers begin with aprofile a
followed by an integer number and any letter between aga and ala, try
gmt convert -S~"/^profile [0-9]+[g-l]$/"
To reverse the order of segments in a file without reversing the order
of records within each segment, try
gmt convert lots_of_segments.txt -Is > last_segment_first.txt
To extract segments 20 to 40 in steps of 2, plus segment 0 in a file,
try
gmt convert lots_of_segments.txt -Q0,20:2:40 > my_segments.txt
To extract the attribute ELEVATION from an ogr gmt file like this
# @VGMT1.0 @GPOINT
...
# @NELEVATION|DISPX|DISPY
# @Tdouble|double|double
# FEATURE_DATA
# @D4.945000|-106500.00000000|-32700.00000000
-9.36890245902635 39.367156766570389
do
gmt convert file.gmt -a2=ELEVATION > xyz.dat
or just
gmt convert file.gmt -aELEVATION > xyz.dat
To connect all points in the file sensors.txt with the specified origin
at 23.5/19, try
gmt convert sensors.txt -F23.5/19 > lines.txt
To write all segments in the two files A.txt and B.txt to individual
files named profile_005000.txt, profile_005001.txt, etc., where we
reset the origin of the sequential numbering from 0 to 5000, try
gmt convert A.txt B.txt -Dprofile_%6.6d.txt+o5000
SEE ALSO
gmt(1), gmtinfo(1), gmtselect(1)
COPYRIGHT
2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
5.4.2 Jun 24, 2017 gmtconvert(1)
gmt5 5.4.2 - Generated Wed Jun 28 16:16:16 CDT 2017