gmtconvert

gmtconvert - Convert, Paste, and/or Extract columns from data tables

Synopsis

gmtconvert [ table ] [ -A ] [ -D[template] ] [ -E[f|l|mstride] ] [ -L ] [ -I[tsr] ] [ -N ] [ -Q[~]*selection* ] [ -S[~]“search string” | -S[~]/regexp/[i] ] [ -T ] [ -V[level] ] [ -acol=name[...] ] [ -b[i|o][ncol][type][w][+L|+B] ] [ -f[i|o]colinfo ] [ -g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] ] [ -h[i|o][n][+c][+d][+rremark][+rtitle] ] [ -icols[l][sscale][ooffset][,...] ] [ -ocols[,...] ] [ -s[cols][a|r] ] [ -:[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 seven 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, and (7) reverse the order of items on output. 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 different number of columns.
-D[template]
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]. 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.
-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.
-I
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).
-N
Do not write records that only contain NaNs in every field [Default writes all records].
-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, a range of segment numbers start-stop, or a range with stepped increments given via start:step:stop. 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 caseless 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 ...)
Select verbosity level [c].
-acol=name[...] (more ...)
Set aspatial column associations col=name.
-bi[ncols][type] (more ...)
Select binary input.
-bo[ncols][type] (more ...)
Select binary output. [Default is same as input].
-f[i|o]colinfo (more ...)
Specify data types of input and/or output columns.
-g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more ...)
Determine data gaps and line breaks.
-h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
Skip or produce header record(s).
-icols[l][sscale][ooffset][,...] (more ...)
Select input columns.
-ocols[,...] (more ...)
Select output columns.
-s[cols][a|r] (more ...)
Set handling of NaN records.
-:[i|o] (more ...)
Swap 1st and 2nd column on input and/or output.
-^
Print a short message about the syntax of the command, then exits. (NOTE: on Windows use just -)
+
Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exits
-?
Print a complete usage (help) message, including the explanation of options, then exits.
--version
Print GMT version and exit.
--show-datadir
Print full path to GMT share directory and exit.

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, whereas other values are formatted according to FORMAT_FLOAT_OUT. Be aware that the format in effect can lead to loss of precision in the 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.

Examples

To convert the binary file test.b (single precision) with 4 columns to ASCII:

gmt gmtconvert test.b -bi4f > test.dat

To convert the multiple segment ASCII table test.d to a double precision binary file:

gmt gmtconvert 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 gmtconvert 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 gmtconvert 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 gmtconvert 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 gmtconvert 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 gmtconvert -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 gmtconvert 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 gmtconvert lots_of_segments.txt -Q0,20:2:40 > my_segments.txt

See Also

gmt, gmtinfo, gmtselect