Provided by: gmt_4.5.11-1build1_amd64 bug


       fitcircle - find mean position and pole of best-fit great [or small] circle to points on a


       fitcircle [ xyfile ]  -Lnorm  [  -H[i][nrec]  ]  [  -S[lat]  ]  [  -V  ]  [  -:[i|o]  ]  [
       -bi[s|S|d|D[ncol]|c[var1/...]] ] [ -f[i|o]colinfo ]


       fitcircle  reads  lon,lat [or lat,lon] values from the first two columns on standard input
       [or xyfile].  These are converted to Cartesian three-vectors on the unit sphere.  Then two
       locations  are  found:   the mean of the input positions, and the pole to the great circle
       which best fits the input positions.  The user may choose one  or  both  of  two  possible
       solutions  to  this  problem.  The first is called -L1 and the second is called -L2.  When
       the data are closely grouped along a great circle both solutions are similar.  If the data
       have  large dispersion, the pole to the great circle will be less well determined than the
       mean.  Compare both solutions as a qualitative check.

       The -L1 solution is so called because it approximates  the  minimization  of  the  sum  of
       absolute values of cosines of angular distances.  This solution finds the mean position as
       the Fisher average of the data, and the pole position as the Fisher average of the  cross-
       products  between  the mean and the data.  Averaging cross-products gives weight to points
       in proportion to their distance from the mean, analogous  to  the  "leverage"  of  distant
       points in linear regression in the plane.

       The  -L2  solution  is  so  called  because it approximates the minimization of the sum of
       squares of cosines of angular distances.  It creates a 3 by 3 matrix of sums of squares of
       components  of  the  data vectors.  The eigenvectors of this matrix give the mean and pole
       locations.  This method may be more subject to roundoff errors when there are thousands of
       data.   The  pole is given by the eigenvector corresponding to the smallest eigenvalue; it
       is the least-well represented factor in the data and is not  easily  estimated  by  either

       -L     Specify the desired norm as 1 or 2, or use -L or  -L3 to see both solutions.


       xyfile ASCII  [or  binary, see -b] file containing lon,lat [lat,lon] values in the first 2
              columns.  If no file is specified, fitcircle will read from standard input.

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

       -S     Attempt  to  fit  a  small  circle  instead  of  a  great circle.  The pole will be
              constrained to lie on the great circle connecting the pole of  the  best-fit  great
              circle  and  the  mean  location  of the data.  Optionally append the desired fixed
              latitude of the small circle [Default will determine the latitude].

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

       -:     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.  [Default is 2 input columns].

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


       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.


       Suppose you have lon,lat,grav data along a twisty ship track in the  file  ship.xyg.   You
       want  to  project  this  data onto a great circle and resample it in distance, in order to
       filter it or check its spectrum.  Do the following:

       fitcircle ship.xyg -L 2

       project ship.xyg -Cox/oy -Tpx/py -S -F pz | sample1d -S-100 -I 1 >

       Here, ox/oy is the lon/lat of the mean from fitcircle, and px/py is  the  lon/lat  of  the
       pole.   The  file has distance, gravity data sampled every 1 km along the great
       circle which best fits ship.xyg


       GMT(1), project(1), sample1d(1)