NAME

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


SYNOPSIS

     fitcircle [ xyfile ] -Lnorm [ -H[nrec] ] [ -S ] [ -V ] [  -:
     ] [ -bi[s][n] ]


DESCRIPTION

     fitcircle reads lon,lat [or lat,lon] values from  the  first
     two  columns  on standard input [or xyfile].  These are con-
     verted 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
     method.

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


OPTIONS

     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).  Number  of  header
          records  can  be  changed  by editing your .gmtdefaults
          file.  If used, GMT default is 1 header record.

     -S   Attempt to fit a small circle instead of a  great  cir-
          cle.   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.

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

     -:   Toggles      between      (longitude,latitude)      and
          (latitude,longitude)    input/output.     [Default   is
          (longitude,latitude)].

     -bi  Selects binary input.  Append s  for  single  precision
          [Default  is  double].   Append  n  for  the  number of
          columns in the binary file(s).   [Default  is  2  input
          columns].


EXAMPLES

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

     fitcircle ship.xyg -L2

     project ship.xyg -Oox/oy -Ppx/py -S -pz  |  sample1d  -S-100
     -I1 > output.pg

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


SEE ALSO

     gmt(l), project(l), sample1d(l)