1FITCIRCLE(1)                 Generic Mapping Tools                FITCIRCLE(1)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

14       fitcircle  reads lon,lat [or lat,lon] values from the first two columns
15       on standard input [or xyfile].  These are converted to Cartesian three-
16       vectors on the unit sphere.  Then two locations are found:  the mean of
17       the input positions, and the pole to the great circle which  best  fits
18       the  input  positions.  The user may choose one or both of two possible
19       solutions to this problem.  The first is called -L1 and the  second  is
20       called  -L2.   When  the  data are closely grouped along a great circle
21       both solutions are similar.  If the data  have  large  dispersion,  the
22       pole  to  the  great circle will be less well determined than the mean.
23       Compare both solutions as a qualitative check.
24
25       The -L1 solution is so called because it approximates the  minimization
26       of  the  sum  of absolute values of cosines of angular distances.  This
27       solution finds the mean position as the Fisher average of the data, and
28       the  pole  position as the Fisher average of the cross-products between
29       the mean and the data.  Averaging cross-products gives weight to points
30       in proportion to their distance from the mean, analogous to the "lever‐
31       age" of distant points in linear regression in the plane.
32
33       The -L2 solution is so called because it approximates the  minimization
34       of  the sum of squares of cosines of angular distances.  It creates a 3
35       by 3 matrix of sums of squares of components of the data vectors.   The
36       eigenvectors  of  this  matrix  give the mean and pole locations.  This
37       method may be more subject to roundoff errors when there are  thousands
38       of  data.   The  pole  is given by the eigenvector corresponding to the
39       smallest eigenvalue; it is the least-well  represented  factor  in  the
40       data and is not easily estimated by either method.
41
42       -L     Specify  the  desired  norm  as 1 or 2, or use -L or  -L3 to see
43              both solutions.
44

OPTIONS

46       xyfile ASCII [or binary, see -b] file containing lon,lat [lat,lon] val‐
47              ues  in the first 2 columns.  If no file is specified, fitcircle
48              will read from standard input.
49
50       -H     Input file(s) has header record(s).  If used, the default number
51              of  header records is N_HEADER_RECS.  Use -Hi if only input data
52              should have  header  records  [Default  will  write  out  header
53              records  if  the  input  data  have them]. Blank lines and lines
54              starting with # are always skipped.
55
56       -S     Attempt to fit a small circle instead of a  great  circle.   The
57              pole  will  be constrained to lie on the great circle connecting
58              the pole of the best-fit great circle and the mean  location  of
59              the  data.   Optionally append the desired fixed latitude of the
60              small circle [Default will determine the latitude].
61
62       -V     Selects verbose mode, which will send progress reports to stderr
63              [Default runs "silently"].
64
65       -:     Toggles  between  (longitude,latitude)  and (latitude,longitude)
66              input and/or output.  [Default is (longitude,latitude)].  Append
67              i  to  select  input  only or o to select output only.  [Default
68              affects both].
69
70       -bi    Selects binary input.  Append s for single precision [Default is
71              d  (double)].   Uppercase  S  or  D  will  force  byte-swapping.
72              Optionally, append ncol, the number of columns  in  your  binary
73              input  file if it exceeds the columns needed by the program.  Or
74              append c  if  the  input  file  is  netCDF.  Optionally,  append
75              var1/var2/...  to specify the variables to be read.  [Default is
76              2 input columns].
77
78       -f     Special formatting of input and/or output columns (time or  geo‐
79              graphical  data).   Specify  i  or  o to make this apply only to
80              input or output [Default applies to both].   Give  one  or  more
81              columns (or column ranges) separated by commas.  Append T (abso‐
82              lute calendar time), t (relative time in chosen TIME_UNIT  since
83              TIME_EPOCH),  x (longitude), y (latitude), or f (floating point)
84              to each column or column range item.  Shorthand  -f[i|o]g  means
85              -f[i|o]0x,1y (geographic coordinates).
86

ASCII FORMAT PRECISION

88       The ASCII output formats of numerical data are controlled by parameters
89       in your .gmtdefaults4  file.   Longitude  and  latitude  are  formatted
90       according  to  OUTPUT_DEGREE_FORMAT, whereas other values are formatted
91       according to D_FORMAT.  Be aware that the format in effect can lead  to
92       loss  of  precision  in  the output, which can lead to various problems
93       downstream.  If you find the output is not written with  enough  preci‐
94       sion, consider switching to binary output (-bo if available) or specify
95       more decimals using the D_FORMAT setting.
96

EXAMPLES

98       Suppose you have lon,lat,grav data along a twisty  ship  track  in  the
99       file  ship.xyg.   You want to project this data onto a great circle and
100       resample it in distance, in order to filter it or check  its  spectrum.
101       Do the following:
102
103       fitcircle ship.xyg -L2
104
105       project  ship.xyg  -Cox/oy -Tpx/py -S -Fpz | sample1d -S-100 -I1 > out‐
106       put.pg
107
108       Here, ox/oy is the lon/lat of the mean from fitcircle, and px/py is the
109       lon/lat  of  the  pole.   The file output.pg has distance, gravity data
110       sampled every 1 km along the great circle which best fits ship.xyg
111

SEE ALSO

113       GMT(1), project(1), sample1d(1)
114
115
116
117GMT 4.5.6                         10 Mar 2011                     FITCIRCLE(1)
Impressum