Provided by: gmt_4.5.11-1build1_amd64 bug

NAME

       greenspline  - Interpolate 1-D, 2-D, 3-D Cartesian or spherical surface data using Green's
       function splines.

SYNOPSIS

       greenspline [ datafile(s) ] [ -A[1|2|3|4|5,]gradfile ] [ -Ccut[/file] ] [ -Dmode ] [ -F  ]
       [  -Ggrdfile ] [ -H[i][nrec] ] [ -Ixinc[yinc[zinc]] ] [ -L ] [ -Nnodefile ] [ -Qaz|x/y/z ]
       [ -Rxmin/xmax[/ymin/ymax[/zminzmax]] ] [ -Sc|t|g|p|q[pars] ] [  -Tmaskgrid  ]  [  -V  ]  [
       -:[i|o]     ]    [    -bi[s|S|d|D[ncol]|c[var1/...]]    ]    [    -f[i|o]colinfo    ]    [
       -bo[s|S|d|D[ncol]|c[var1/...]] ]

DESCRIPTION

       greenspline uses the Green's function G(x; x') for  the  chosen  spline  and  geometry  to
       interpolate data at regular [or arbitrary] output locations.  Mathematically, the solution
       is composed as w(x) = sum {c(i) G(x; x(i))}, for i = 1,  n,  the  number  of  data  points
       {x(i),  w(i)}.  Once the n coefficients c(i) have been found then the sum can be evaluated
       at any output point x.  Choose between ten minimum curvature, regularized,  or  continuous
       curvature  splines  in  tension  for  either  1-D,  2-D,  or  3-D Cartesian coordinates or
       spherical surface coordinates. After first removing a linear or  planar  trend  (Cartesian
       geometries)  or mean value (spherical surface) and normalizing these residuals, the least-
       squares matrix solution for the spline coefficients c(i) is found by solving the  n  by  n
       linear  system  w(j) = sum-over-i {c(i) G(x(j); x(i))}, for j = 1, n; this solution yields
       an exact interpolation of the supplied data points.   Alternatively,  you  may  choose  to
       perform  a  singular  value  decomposition  (SVD)  and eliminate the contribution from the
       smallest eigenvalues; this approach yields an approximate solution.  Trends and scales are
       restored when evaluating the output.

OPTIONS

       datafile(s)
              The  name  of  one  or  more ASCII [or binary, see -bi] files holding the x, w data
              points.  If no file is given then we read standard input instead.

       -A     The solution will partly be constrained by surface gradients v = v*n,  where  v  is
              the gradient magnitude and n its unit vector direction.  The gradient direction may
              be specified either by Cartesian components (either unit vector n and  magnitude  v
              separately or gradient components v directly) or angles w.r.t. the coordinate axes.
              Specify one of five input formats: 0: For 1-D data  there  is  no  direction,  just
              gradient magnitude (slope) so the input format is x, gradient.  Options 1-2 are for
              2-D data sets: 1: records contain x, y, azimuth, gradient (azimuth  in  degrees  is
              measured  clockwise from the vertical (north) [Default]).  2: records contain x, y,
              gradient, azimuth (azimuth in degrees  is  measured  clockwise  from  the  vertical
              (north)).   Options  3-5  are  for  either  2-D  or 3-D data: 3: records contain x,
              direction(s), v (direction(s) in degrees are measured  counter-clockwise  from  the
              horizontal  (and  for 3-D the vertical axis).  4: records contain x, v.  5: records
              contain x, n, v.  Append name of ASCII file with the surface gradients (following a
              comma if a format is specified).

       -C     Find   an  approximate  surface  fit:  Solve  the  linear  system  for  the  spline
              coefficients by SVD and eliminate the contribution from all eigenvalues whose ratio
              to  the  largest eigenvalue is less than cut [Default uses Gauss-Jordan elimination
              to solve the linear system and fit the data exactly].  Optionally, append /file  to
              save the eigenvalue ratios to the specified file for further analysis.  Finally, if
              a negative cut is given then /file is required and execution will stop after saving
              the eigenvalues, i.e., no surface output is produced.

       -D     Sets  the  distance  flag  that  determines how we calculate distances between data
              points.  Select mode 0 for Cartesian 1-D spline interpolation: -D 0  means  (x)  in
              user  units,  Cartesian distances, Select mode 1-3 for Cartesian 2-D surface spline
              interpolation: -D 1 means (x,y) in user units, Cartesian distances, -D 2 for  (x,y)
              in  degrees,  flat  Earth  distances,  and  -D  3  for  (x,y) in degrees, spherical
              distances in km.  Then, if ELLIPSOID is spherical, we compute  great  circle  arcs,
              otherwise  geodesics.   Option  mode  =  4  applies  to  spherical  surface  spline
              interpolation only: -D 4 for (x,y) in degrees,  use  cosine  of  great  circle  (or
              geodesic) arcs.  Select mode 5 for Cartesian 3-D surface spline interpolation: -D 5
              means (x,y,z) in user units, Cartesian distances.

       -F     Force pixel registration.  [Default is gridline registration].

       -G     Name of resulting output file.  (1) If options -R, -I, and possibly -F are  set  we
              produce  an  equidistant output table.  This will be written to stdout unless -G is
              specified.  Note: for 2-D grids the -G option is required.  (2)  If  option  -T  is
              selected  then  -G  is  required  and  the  output  file is a 2-D binary grid file.
              Applies to 2-D interpolation only.  (3) If -N is selected then  the  output  is  an
              ASCII  (or binary; see -bo) table; if -G is not given then this table is written to
              standard output.  Ignored if -C or -C 0 is given.

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

       -I     Specify  equidistant  sampling  intervals,  on  for  each  dimension,  separated by
              slashes.

       -L     Do not remove a linear (1-D) or planer (2-D) trend when -D selects  mode  0-3  [For
              those  Cartesian  cases  a least-squares line or plane is modeled and removed, then
              restored after fitting a spline to the residuals].  However, in  mixed  cases  with
              both  data  values and gradients, or for spherical surface data, only the mean data
              value is removed (and later and restored).

       -N     ASCII file with coordinates of desired output locations x in the  first  column(s).
              The resulting w values are appended to each record and written to the file given in
              -G [or stdout if not specified]; see -bo for binary output  instead.   This  option
              eliminates the need to specify options -R, -I, and -F.

       -Q     Rather than evaluate the surface, take the directional derivative in the az azimuth
              and return the magnitude  of  this  derivative  instead.   For  3-D  interpolation,
              specify  the  three  components of the desired vector direction (the vector will be
              normalized before use).

       -R     Specify the  domain  for  an  equidistant  lattice  where  output  predictions  are
              required.  Requires -I and optionally -F.
              1-D:  Give xmin/xmax, the minimum and maximum x coordinates.
              2-D:  Give xmin/xmax/ymin/ymax, the minimum and maximum x and y coordinates.  These
              may be Cartesian or geographical.  If geographical, then  west,  east,  south,  and
              north  specify  the Region of interest, and you may specify them in decimal degrees
              or in [+-]dd:mm[:ss.xxx][W|E|S|N] format.  The two shorthands -Rg and -Rd stand for
              global  domain  (0/360  and  -180/+180  in  longitude respectively, with -90/+90 in
              latitude).
              3-D:  Give xmin/xmax/ymin/ymax/zmin/zmax, the  minimum  and  maximum  x,  y  and  z
              coordinates.   See the 2-D section if your horizontal coordinates are geographical;
              note the shorthands -Rg and -Rd cannot be used if a 3-D domain is specified.

       -S     Select one of five different splines.  The first two are used for 1-D, 2-D, or  3-D
              Cartesian  splines  (see  -D  for  discussion).   Note  that all tension values are
              expected to be normalized tension in the range 0 < t <  1:  (c)  Minimum  curvature
              spline  [Sandwell,  1987],  (t)  Continuous curvature spline in tension [Wessel and
              Bercovici, 1998];  append  tension[/scale]  with  tension  in  the  0-1  range  and
              optionally  supply  a length scale [Default is the average grid spacing].  The next
              is a 2-D or 3-D spline: (r) Regularized spline  in  tension  [Mitasova  and  Mitas,
              1993];  again,  append  tension  and  optional  scale.   The last two are spherical
              surface splines and both imply -D 4 and  geographic  data:  (p)  Minimum  curvature
              spline  [Parker,  1994],  (q)  Continuous  curvature  spline in tension [Wessel and
              Becker, 2008]; append tension.  The G(x; x') for  the  last  method  is  slower  to
              compute;  by  specifying -SQ you can speed up calculations by first pre-calculating
              G(x; x') for a dense set of x values (e.g., 100,001 nodes between  -1  to  +1)  and
              store them in look-up tables.  Optionally append /N (an odd integer) to specify how
              many points in the spline to set [100001]

       -T     For 2-D interpolation only.  Only  evaluate  the  solution  at  the  nodes  in  the
              maskgrid  that  are  not  equal  to NaN. This option eliminates the need to specify
              options -R, -I, and -F.

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

       -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-4 input columns (x,w); the number
              depends on the chosen dimension].

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

       -bo    Selects  binary  output.   Append  s  for single precision [Default is d (double)].
              Uppercase S or D will force byte-swapping.  Optionally, append ncol, the number  of
              desired columns in your binary output file.

1-D EXAMPLES

       To  resample  the  x,y  Gaussian  random  data  created  by  gmtmath and stored in 1D.txt,
       requesting output every 0.1 step from 0 to 10, and using a minimum cubic spline, try

       gmtmath -T 0/10/1 0 1 NRAND = 1D.txt
       psxy -R0/10/-5/5 -JX 6i/3i -B 2f1/1 -Sc 0.1 -G black 1D.txt -K > 1D.ps
       greenspline 1D.txt -R 0/10 -I 0.1 -Sc -V | psxy -R -J -O -W thin >> 1D.ps

       To apply a spline in tension instead, using a tension of 0.7, try

       psxy -R0/10/-5/5 -JX 6i/3i -B 2f1/1 -Sc 0.1 -G black 1D.txt -K > 1Dt.ps
       greenspline 1D.txt -R 0/10 -I 0.1 -St 0.7 -V | psxy -R -J -O -W thin >> 1Dt.ps

2-D EXAMPLES

       To make a uniform grid using the minimum curvature spline for the same Cartesian data  set
       from Davis (1986) that is used in the GMT Cookbook example 16, try

       greenspline table_5.11 -R 0/6.5/-0.2/6.5 -I 0.1 -Sc -V -D 1 -G S1987.grd
       psxy -R0/6.5/-0.2/6.5 -JX 6i -B 2f1 -Sc 0.1 -G black table_5.11 -K > 2D.ps
       grdcontour -JX6i -B 2f1 -O -C 25 -A 50 S1987.grd >> 2D.ps

       To  use  Cartesian  splines in tension but only evaluate the solution where the input mask
       grid is not NaN, try

       greenspline table_5.11 -T mask.grd -St 0.5 -V -D 1 -G WB1998.grd

       To use Cartesian generalized splines in tension and return the magnitude  of  the  surface
       slope in the NW direction, try

       greenspline  table_5.11  -R  0/6.5/-0.2/6.5  -I  0.1  -Sr 0.95 -V -D 1 -Q-45 -G slopes.grd
       Finally, to use Cartesian minimum curvature splines in  recovering  a  surface  where  the
       input data is a single surface value (pt.d) and the remaining constraints specify only the
       surface slope and direction (slopes.d), use

       greenspline pt.d -R-3.2/3.2/-3.2/3.2 -I 0.1 -Sc -V -D 1 -A 1,slopes.d -G slopes.grd

3-D EXAMPLES

       To create a uniform 3-D Cartesian grid table based on the  data  in  table_5.23  in  Davis
       (1986)  that  contains  x,y,z  locations and a measure of uranium oxide concentrations (in
       percent), try

       greenspline table_5.23 -R 5/40/-5/10/5/16 -I 0.25 -Sr 0.85 -V -D 5 -G 3D_UO2.txt

2-D SPHERICAL SURFACE EXAMPLES

       To recreate Parker's [1994] example on a global 1x1 degree grid, assuming the data are  in
       file mag_obs_1990.d, try

       greenspline -V -Rg -Sp -D 3 -I 1 -G P1994.grd mag_obs_1990.d

       To do the same problem but applying tension and use pre-calculated Green functions, use

       greenspline -V -Rg -SQ 0.85 -D 3 -I 1 -G WB2008.grd mag_obs_1990.d

CONSIDERATIONS

       (1)  For  the  Cartesian  cases  we  use the free-space Green functions, hence no boundary
       conditions are applied at the edges of the specified domain.  For most  applications  this
       is  fine  as  the  region typically is arbitrarily set to reflect the extent of your data.
       However, if your application requires particular boundary conditions then you may consider
       using surface instead.
       (2)  In  all  cases, the solution is obtained by inverting a n x n double precision matrix
       for the Green function coefficients, where n is the number of  data  constraints.   Hence,
       your  computer's memory may place restrictions on how large data sets you can process with
       greenspline.  Pre-processing your  data  with  blockmean,  blockmedian,  or  blockmode  is
       recommended  to avoid aliasing and may also control the size of n. For information, if n =
       1024 then only 8 Mb memory is needed, but for  n  =  10240  we  need  800  Mb.  Note  that
       greenspline is fully 64-bit compliant if compiled as such.
       (3) The inversion for coefficients can become numerically unstable when data neighbors are
       very close compared to the overall span  of  the  data.   You  can  remedy  this  by  pre-
       processing  the data, e.g., by averaging closely spaced neighbors.  Alternatively, you can
       improve stability by using the SVD solution and discard information  associated  with  the
       smallest eigenvalues (see -C).

TENSION

       Tension  is  generally  used  to  suppress  spurious  oscillations  caused  by the minimum
       curvature requirement, in particular when rapid gradient changes are present in the  data.
       The  proper  amount of tension can only be determined by experimentation.  Generally, very
       smooth data (such as potential fields) do not require much, if any tension, while  rougher
       data  (such  as topography) will typically interpolate better with moderate tension.  Make
       sure you try a range of values before choosing your final result.  Note:  the  regularized
       spline  in  tension is only stable for a finite range of scale values; you must experiment
       to find the valid range and a useful setting.  For more information  on  tension  see  the
       references below.

REFERENCES

       Davis,  J. C., 1986, Statistics and Data Analysis in Geology, 2nd Edition, 646 pp., Wiley,
       New York,
       Mitasova, H., and L. Mitas, 1993, Interpolation by regularized  spline  with  tension:  I.
       Theory and implementation, Math. Geol., 25, 641-655.
       Parker,  R.  L.,  1994,  Geophysical  Inverse  Theory,  386  pp.,  Princeton  Univ. Press,
       Princeton, N.J.
       Sandwell, D. T., 1987, Biharmonic spline interpolation  of  Geos-3  and  Seasat  altimeter
       data, Geophys. Res. Lett., 14, 139-142.
       Wessel,  P.,  and  D.  Bercovici,  1998,  Interpolation with splines in tension: a Green's
       function approach, Math. Geol., 30, 77-93.
       Wessel, P., and J. M. Becker, 2008, Interpolation using a generalized Green's function for
       a spherical surface spline in tension, Geophys. J. Int, 174, 21-28.
       Wessel,   P.,   2009,   A  general-purpose  Green's  function  interpolator,  Computers  &
       Geosciences, 35, 1247-1254, doi:10.1016/j.cageo.2008.08.012.

SEE ALSO

       GMT(1), gmtmath(1), nearneighbor(1), psxy(1), surface(1), triangulate(1), xyz2grd(1)