gmtconvert - Convert, Paste, and/or Extract columns from data
tables
gmtconvert [ table ] [ -A ] [
-C[+lmin][+umax][+i]] [
-D[template[+oorig]] ] [
-E[f|l|mstride] ] [ -L ] [
-F[c|n|r|v][refpoint] ] [
-I[tsr] ] [ -Q[~]selection] [
-S[~]"search string" |
-S[~]/regexp/[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.
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 corresponding records from multiple files horizontally into a
single file, (3) extract a subset of the available columns, (4) only extract
segments 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.
- 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 different 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 output.
- -D[template[+oorig]]
- For multiple segment data, dump each segment to a separate output 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 specifiers 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 modifier 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,...] 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 leading ~ 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[~]"search
string" 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 segments]. 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.
- -:[i|o] (more ...)
- 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 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.
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
FORMAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point values
are formatted according to FORMAT_FLOAT_OUT. Be aware that the format 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 setting.
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
precision 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
single-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 "RIDGE AXIS", try
gmt convert big_file.d -S"RIDGE AXIS" > subset.d
To invert the selection of segments whose headers begin with
"profile " followed by an integer number and any letter between
"g" and "l", 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
2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F.
Wobbe