xenial (1) splitxyz.1gmt.gz

Provided by: gmt-common_5.2.1+dfsg-3build1_all bug

NAME

       splitxyz - Split xyz[dh] data tables into individual segments

SYNOPSIS

       splitxyz  [  table ] [ azimuth/tolerance ] [ course_change] [ minimum_distance ] [ xy_filter/z_filter ] [
       template ] [ flags ] [  ] [ [level] ] [ -b<binary> ] [  -d<nodata>  ]  [  -f<flags>  ]  [  -g<gaps>  ]  [
       -h<headers> ] [ -i<flags> ] [ -:[i|o] ]

       Note: No space is allowed between the option flag and the associated arguments.

DESCRIPTION

       splitxyz  reads  a  series  of (x,y[,z]) records [or optionally (x,y,z,d,h); see -S option] from standard
       input [or xyz[dh]file] and splits this into separate lists of (x,y[,z]) series, such that each series has
       a nearly constant azimuth through the x,y plane. There are options to choose only those series which have
       a certain orientation, to set a minimum length for series, and to high- or low-pass filter the  z  values
       and/or the x,y values. splitxyz is a useful filter between data extraction and pswiggle plotting, and can
       also be used to divide a large x,y[,z] dataset into segments.

REQUIRED ARGUMENTS

       none.

OPTIONAL ARGUMENTS

       table  One or more ASCII [or binary, see -bi] files with 2, 3, or 5 columns holding (x,y,[z[,d,h]])  data
              values.  To  use  (x,y,z,d,h)  input,  sorted  so that d is non-decreasing, specify the -S option;
              default expects (x,y,z) only. If no files are specified, splitxyz will read from standard input.

       -Aazimuth/tolerance
              Write out only those segments which are within  +/-  tolerance  degrees  of  azimuth  in  heading,
              measured  clockwise  from North, [0 - 360]. [Default writes all acceptable segments, regardless of
              orientation].

       -Ccourse_change
              Terminate a segment when a course change exceeding course_change degrees of  heading  is  detected
              [ignore course changes].

       -Dminimum_distance
              Do not write a segment out unless it is at least minimum_distance units long [0]

       -Fxy_filter/z_filter
              Filter the z values and/or the x,y values, assuming these are functions of d coordinate. xy_filter
              and z_filter are filter widths in distance units. If a filter width is zero, the filtering is  not
              performed.  The absolute value of the width is the full width of a cosine-arch low-pass filter. If
              the width is positive, the data are  low-pass  filtered;  if  negative,  the  data  are  high-pass
              filtered  by  subtracting the low-pass value from the observed value. If z_filter is non-zero, the
              entire series of input z values is filtered before any segmentation is performed, so that the only
              edge effects in the filtering will happen at the beginning and end of the complete data stream. If
              xy_filter is non-zero, the data is first divided into segments and then the  x,y  values  of  each
              segment  are filtered separately. This may introduce edge effects at the ends of each segment, but
              prevents a low-pass x,y filter from rounding off the corners of  track  segments.  [Default  =  no
              filtering].

       -Ntemplate
              Write  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
              splitxyz_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.

       -Qflags
              Specify your desired output using any combination of xyzdh, in any order. Do not space between the
              letters. Use lower case. The output  will  be  ASCII  (or  binary,  see  -bo)  columns  of  values
              corresponding to xyzdh [Default is -Qxyzdh (-Qxydh if only 2 input columns)].

       -S     Both  d  and  h  are  supplied.  In this case, input contains x,y,z,d,h.  [Default expects (x,y,z)
              input, and d,h are computed from delta x, delta y. Use -fg to indicate  map  data;  then  x,y  are
              assumed to be in degrees of longitude, latitude, distances are considered to be in kilometers, and
              angles are actually azimuths. Otherwise, distances are Cartesian in same units as x,y  and  angles
              are counter-clockwise from horizontal].

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

       -bi[ncols][t] (more ...)
              Select native binary input. [Default is 2, 3, or 5 input columns as set by -S].

       -bo[ncols][type] (more ...)
              Select native binary output. [Default is 1-5 output columns as set by -Q].

       -d[i|o]nodata (more ...)
              Replace input columns that equal nodata with NaN and do the reverse on output.

       -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. Do not let a segment have a gap exceeding gap; instead, split
              it into two segments. [Default ignores gaps].

       -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
              Skip or produce header record(s).

       -icols[l][sscale][ooffset][,...] (more ...)
              Select input columns (0 is first column).

       -:[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 use just -).

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

DISTANCE CALCULATIONS

       The type of input data is dictated by the -f option.  If  -fg  is  given  then  x,y  are  in  degrees  of
       longitude,  latitude,  distances  are  in  kilometers,  and angles are azimuths. Otherwise, distances are
       Cartesian in same units as x,y and angles are counter-clockwise from horizontal.

EXAMPLES

       Suppose you want to make a wiggle plot of magnetic anomalies on segments oriented approximately east-west
       from  a  NGDC-supplied  cruise  called  JA020015  in the region -R300/315/12/20. You want to use a 100 km
       low-pass filter to smooth the tracks and a 500km high-pass filter to detrend the magnetic anomalies.  Try
       this:

              gmt mgd77list JA020015 -R300/315/12/20 -Flon,lat,mag,dist,azim | gmt splitxyz -A90/15 -F100/-500 \
                  -D100 -S -V -fg | gmt pswiggle -R300/315/12/20 -Jm0.6i -Baf -B+tJA020015 -T1 \
                  -W0.75p -Ggray -Z200 > JA020015_wiggles.ps

       MGD-77  users:  For  this  application we recommend that you extract dist,azim from mgd77list rather than
       have splitxyz compute them separately.

       Suppose you have been given a binary, double-precision file containing lat, lon, gravity  values  from  a
       survey, and you want to split it into profiles named survey_###.txt (when gap exceeds 100 km). Try this:

              gmt splitxyz survey.bin -Nsurvey_%03d.txt -V -gd100k -D100 -: -fg -bi3d

SEE ALSO

       gmt, filter1d, mgd77list, pswiggle

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