Provided by: gmt-common_5.4.5+dfsg-2_all bug


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


       fitcircle [ table ]  -Lnorm [  -Fflags ] [  -S[lat] ] [   -V[level]  ]  [  -bibinary  ]  [
       -dinodata  ]  [  -eregexp ] [ -fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [ -oflags ] [
       -:[i|o] ]

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


       fitcircle reads lon,lat [or lat,lon] values from the first two columns on  standard  input
       [or  table].  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


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


       table  One or more ASCII [or binary, see -bi] files containing lon,lat  [or  lat,lon;  see
              -:[i|o]]  values  in  the  first 2 columns. If no file is specified, fitcircle will
              read from standard input.

              Normally, fitcircle will write its results in the form of a text report,  with  the
              values intermingled with report sentences.  Use -F to only return data coordinates,
              and append flags to specify which coordinates you would like. You can choose from f
              (Flat  Earth  mean  location), m (mean location), n (north pole of great circle), s
              (south pole of great circle), and c (pole of small circle and its colatitude, which
              requires -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[level] (more ...)
              Select verbosity level [c].

       -bi[ncols][t] (more ...)
              Select native binary input. [Default is 2 input columns].

       -dinodata (more ...)
              Replace input columns that equal nodata with NaN.

       -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
              Only accept data records that match the given pattern.

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

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

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

       -ocols[,...] (more ...)
              Select output 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
              just use -).

       -+ 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  all  options,
              then exits.


       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 FORMAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point
       values are formatted according to FORMAT_FLOAT_OUT. Be aware that the format 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 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:

              gmt fitcircle ship.xyg -L2
              gmt project ship.xyg -Cox/oy -Tpx/py -S -Fpz | sample1d -S-100 -I1 >

       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

       If  you  have  lon,  lat  points  in  the  file  data.txt  and wish to return the northern
       hemisphere great circle pole location using the L2 norm, try

              gmt fitcircle data.txt -L2 -Fn > pole.txt


       gmt, gmtvector, project, mapproject, sample1d


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