Provided by: gmt_4.5.11-1build1_amd64 bug

NAME

       gmtconvert - Converts, Pastes, and/or Extracts columns from ASCII and binary 1-D tables

SYNOPSIS

       gmtconvert [ inputfiles ] [ -A ] [ -D[template] ] [ -E[f|l] ] [ -Fcols ] [ -H[i][nrec] ] [
       -L  ]  [  -I  ]  [  -N  ]  [  -S[~]"search  string"   ]   [   -V   ]   [   -:[i|o]   ]   [
       -b[i|o][s|S|d|D[ncol]|c[var1/...]]        ]        [        -f[i|o]colinfo       ]       [
       -g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] ] [ -m[i|o][flag] ]

DESCRIPTION

       gmtconvert reads its standard input [or inputfiles] and writes out the desired information
       to  standard  output.  It can do a combination of three things: (1) convert between binary
       and ASCII data tables, (2) paste corresponding records from multiple files into  a  single
       file,  (3) extract a subset of the columns, (4) only extract segments whose header matches
       a text pattern search, (5) just list all multisegment headers and no data records, and (6)
       extract  first  and  last data record for each segment.  Input (and hence output) may have
       multiple subheaders if -m is selected, and ASCII tables may have regular headers as well.

       datafile(s)
              ASCII (or binary, see -bi) file(s) holding a number of data columns.

OPTIONS

       -A     The records from the input  files  should  be  pasted  horizontally,  not  appended
              vertically.   [Default processes one file at the time].  Note for binary input, all
              the files you want to paste must have the same number of columns (as set with -bi).

       -D     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 segment number); this is usually %d but could be
              %8.8d which gives leading zeros, etc. [Default is gmtconvert_segment_%d.d].

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

       -F     Give a comma-separated list of desired  columns  or  ranges  (0  is  first  column)
              [Default outputs all columns].

       -H     Input  file(s) has header record(s).  If used, the default number of header records
              is N_HEADER_RECS.  Use -Hi if only input data should have header  records  [Default
              will  write  out header records if the input data have them]. Blank lines and lines
              starting with # are always skipped.

       -I     Invert the order of rows, i.e., output the final records in reverse order, starting
              with the last and ending up with the first input row [Default goes forward].

       -L     Only  output  a  listing  of  all  multisegment  header records and no data records
              (requires -m and ASCII data).

       -N     Do not write records that only contain NaNs in  every  field  [Default  writes  all
              records].

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

       -V     Selects verbose mode, which will send progress  reports  to  stderr  [Default  runs
              "silently"].

       -:     Toggles  between (longitude,latitude) and (latitude,longitude) input and/or output.
              [Default is (longitude,latitude)].  Append i to select input only or  o  to  select
              output only.  [Default affects both].

       -bi    Selects  binary  input.   Append  s  for  single precision [Default is d (double)].
              Uppercase S or D will force byte-swapping.  Optionally, append ncol, the number  of
              columns  in your binary input file if it exceeds the columns needed by the program.
              Or append c if the input  file  is  netCDF.  Optionally,  append  var1/var2/...  to
              specify the variables to be read.

       -bo    Selects  binary  output.   Append  s  for single precision [Default is d (double)].
              Uppercase S or D will force byte-swapping.  Optionally, append ncol, the number  of
              desired columns in your binary output file.  [Default is same as input].

       -f     Special  formatting  of  input  and/or  output columns (time or geographical data).
              Specify i or o to make this apply only to  input  or  output  [Default  applies  to
              both].   Give one or more columns (or column ranges) separated by commas.  Append T
              (absolute calendar time), t (relative time in chosen TIME_UNIT since TIME_EPOCH), x
              (longitude),  y  (latitude),  or  f (floating point) to each column or column range
              item.  Shorthand -f[i|o]g means -f[i|o]0x,1y (geographic coordinates).

       -g     Examine the spacing between consecutive data points in order to  impose  breaks  in
              the line.  Append x|X or y|Y to define a gap when there is a large enough change in
              the x or y coordinates, respectively, or d|D for distance gaps; use upper  case  to
              calculate  gaps  from  projected coordinates.  For gap-testing on other columns use
              [col]z; if col is not prepended the it defaults to 2 (i.e.,  3rd  column).   Append
              [+|-]gap  and  optionally  a  unit u.  Regarding optional signs: -ve means previous
              minus current column value must exceed |gap to be a gap, +ve  means  current  minus
              previous  column value must exceed gap, and no sign means the absolute value of the
              difference must exceed gap.  For geographic data (x|y|d), the unit u may  be  meter
              [Default], kilometer, miles, or nautical miles.  For projected data (X|Y|D), choose
              from inch, centimeter, meter, or points [Default unit set by MEASURE_UNIT].   Note:
              For  x|y|z  with time data the unit is instead controlled by TIME_UNIT.  Repeat the
              option to specify multiple criteria, of which any can be  met  to  produce  a  line
              break.  Issue an additional -ga to indicate that all criteria must be met instead.

       -m     Multiple  segment  file(s).  Segments are separated by a special record.  For ASCII
              files the first character must be flag [Default is  '>'].   For  binary  files  all
              fields  must  be  NaN  and -b must set the number of output columns explicitly.  By
              default the -m setting applies to both input and output.  Use -mi and -mo  to  give
              separate settings to input and output.

ASCII FORMAT PRECISION

       The  ASCII  output  formats  of  numerical  data  are  controlled  by  parameters  in your
       .gmtdefaults4   file.    Longitude   and   latitude    are    formatted    according    to
       OUTPUT_DEGREE_FORMAT,  whereas other values are formatted according to D_FORMAT.  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
       D_FORMAT setting.

EXAMPLES

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

       gmtconvert test.b -bis 4 > test.dat

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

       gmtconvert test.d -m -bo > test.b

       You have an ASCII table with 6 columns and you want to plot column 5 versus column 0.  Try

       gmtconvert table.d -F 5,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

       gmtconvert results.b -F 8,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:

       gmtconvert left.d right.d -A -F 1,2 | psxy ...

       To  extract  all  segments  in the file big_file.d whose headers contain the string "RIDGE
       AXIS", try

       gmtconvert big_file.d -m -S"RIDGE AXIS" > subset.d

SEE ALSO

       GMT(1), minmax(1)