manpagez: man pages & more
man fitcircle(1)
Home | html | info | man
fitcircle(1)                          GMT                         fitcircle(1)




NAME

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


SYNOPSIS

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

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


DESCRIPTION

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


REQUIRED ARGUMENTS

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


OPTIONAL ARGUMENTS

       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.

       -Ff|m|n|s|c
              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).

       -S[lat]
              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 a|)
              Select verbosity level [c].

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

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

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

       -:[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

       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 > 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 sam-
       pled 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


SEE ALSO

       gmt(1), gmtvector(1), project(1), mapproject(1), sample1d(1)


COPYRIGHT

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



5.4.2                            Jun 24, 2017                     fitcircle(1)

gmt5 5.4.2 - Generated Wed Jun 28 15:20:14 CDT 2017
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.