manpagez: man pages & more
man gmtconvert(1)
Home | html | info | man
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
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.