Provided by: gmt-common_5.4.5+dfsg-1_all bug

NAME

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

SYNOPSIS

       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.

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  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.

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.

       -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.

       -V[level] (more ...)
              Select verbosity level [c].

       -acol=name[...] (more ...)
              Set aspatial column associations col=name.

       -bi[ncols][t] (more ...)
              Select native binary input.

       -bo[ncols][type] (more ...)
              Select native binary output. [Default is same as input].

       -d[i|o]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.

       -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 and transformations (0 is first column).

       -ocols[,...] (more ...)
              Select output columns (0 is first column).

       -s[cols][a|r] (more ...)
              Set handling of NaN records.

       -:[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.

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 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.

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 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

SEE ALSO

       gmt, gmtinfo, gmtselect

COPYRIGHT

       2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe