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




NAME

       greenspline  -  Interpolate  using Green's functions for splines in 1-3
       dimensions


SYNOPSIS

       greenspline    [    table    ]    [     -Agradfile+f1|2|3|4|5    ]    [
       -C[n|r|v]value[+ffile] ] [  -Dmode ] [  -E[misfitfile] ] [  -Ggrdfile ]
       [  -Ixinc[/yinc[/zinc]] ] [  -L ] [  -Nnodefile ]  [   -Qaz|x/y/z  ]  [
       -Rwest/east/south/north[/zmin/zmax][+r]  ]  [   -Sc|t|l|r|p|q[pars] ] [
       -Tmaskgrid ] [  -V[level] ] [  -W[w]] [  -bbinary  ]  [  -dnodata  ]  [
       -eregexp ] [ -fflags ] [ -hheaders ] [ -oflags ] [ -x[[-]n] ] [ -:[i|o]
       ]

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


DESCRIPTION

       greenspline  uses  the  Greenas function G(x; xa) for the chosen spline
       and geometry to interpolate data at regular [or arbitrary] output loca-
       tions.  Mathematically,  the  solution  is composed as w(x) = sum {c(i)
       G(xa; x(i))}, for i = 1, n, the number of  data  points  {x(i),  w(i)}.
       Once  the  n coefficients c(i) have been found the sum can be evaluated
       at any output point x. Choose between 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.


REQUIRED ARGUMENTS

       None.


OPTIONAL ARGUMENTS

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

       -Agradfile+f1|2|3|4|5
              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 sepa-
              rately  or  gradient components v directly) or angles w.r.t. the
              coordinate axes. Append name of ASCII file with the surface gra-
              dients.   Use +f to select 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.

       -C[n|r|v]value[+ffile]
              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 value [Default uses Gauss-Jordan elimination to  solve  the
              linear  system  and  fit  the  data exactly]. Optionally, append
              +ffile to save the eigenvalue ratios to the specified  file  for
              further  analysis.   Finally,  if a negative value is given then
              +ffile is required and execution will stop after saving the  ei-
              genvalues,  i.e., no surface output is produced.  Specify -Cv to
              use the largest  eigenvalues  needed  to  explain  approximately
              value  %  of  the data variance.  Specify -Cr to use the largest
              eigenvalues needed to leave approximately  value  as  the  model
              misfit.   If  value is not given then -W is required and we com-
              pute value as the rms of the data uncertainties.  Alternatively,
              use  -Cn  to select the value largest eigenvalues.  If a file is
              given with -Cv then we  save  the  eigenvalues  instead  of  the
              ratios.

       -Dmode Sets  the  distance  flag  that determines how we calculate dis-
              tances between data points. Select  mode  0  for  Cartesian  1-D
              spline  interpolation:  -D0  means  (x) in user units, Cartesian
              distances, Select mode 1-3  for  Cartesian  2-D  surface  spline
              interpolation:  -D1  means  (x,y)  in user units, Cartesian dis-
              tances, -D2 for (x,y) in degrees, Flat Earth distances, and  -D3
              for  (x,y)  in  degrees,  Spherical  distances  in  km. Then, if
              PROJ_ELLIPSOID is spherical, we compute great circle arcs,  oth-
              erwise  geodesics.  Option mode = 4 applies to spherical surface
              spline interpolation only: -D4 for (x,y) in degrees, use  cosine
              of  great circle (or geodesic) arcs. Select mode 5 for Cartesian
              3-D surface spline interpolation:  -D5  means  (x,y,z)  in  user
              units, Cartesian distances.

       E[misfitfile]
          Evaluate  the  spline exactly at the input data locations and report
          statistics of  the  misfit  (mean,  standard  deviation,  and  rms).
          Optionally, append a filename and we will write the data table, aug-
          mented by two extra columns holding the spline estimate and the mis-
          fit.

       -Ggrdfile
              Name of resulting output file. (1) If options -R, -I, and possi-
              bly -r 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 -C0 is given.

       -Ixinc[/yinc[/zinc]]
              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).

       -Nnodefile
              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 elim-
              inates the need to specify options -R, -I, and -r.

       -Qaz|x/y/z
              Rather  than  evaluate the surface, take the directional deriva-
              tive in the az azimuth and return the magnitude of this  deriva-
              tive  instead.  For  3-D interpolation, specify the three compo-
              nents of the desired vector direction (the vector will  be  nor-
              malized before use).

       -Rxmin/xmax[/ymin/ymax[/zmin/zmax]]
              Specify  the domain for an equidistant lattice where output pre-
              dictions are required. Requires -I and optionally -r.

              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 geo-
              graphical, then west, east, south, and north specify the  Region
              of  interest,  and you may specify them in decimal degrees or in
              [A+-]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.

       -Sc|t|l|r|p|q[pars]
              Select  one of six 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 aver-
              age grid spacing]. The next is a 1-D or 2-D spline:  (l)  Linear
              (1-D) or Bilinear (2-D) spline; these produce output that do not
              exceed the range of the given data.  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 -D4: (p) Minimum
              curvature spline [Parker, 1994], (q) Continuous curvature spline
              in  tension [Wessel and Becker, 2008]; append tension. The G(xa;
              xa) for the last method is slower to compute (a series solution)
              so  we  pre-calculate  values and use cubic spline interpolation
              lookup instead.  Optionally  append  +nN  (an  odd  integer)  to
              change  how many points to use in the spline setup [10001].  The
              finite Legendre sum has a truncation error [1e-6]; you can lower
              that by appending +elimit at the expense of longer run-time.

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

       -V[level] (more a|)
              Select verbosity level [c].

       -W[w]  Data  one-sigma  uncertainties  are provided in the last column.
              We then compute weights that are inversely proportional  to  the
              uncertainties.   Append w if weights are given instead of uncer-
              tainties.  This results in a weighted least squares  fit.   Note
              that  this  only  has an effect if -C is used.  [Default uses no
              weights or uncertainties].

       -bi[ncols][t] (more a|)
              Select native binary input. [Default is 2-4 input columns (x,w);
              the number depends on the chosen dimension].

       -bo[ncols][type] (more a|)
              Select native binary output.

       -d[i|o]nodata (more a|)
              Replace  input  columns  that  equal  nodata with NaN and do the
              reverse on output.

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

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

       -r (more a|)
              Set pixel node registration [gridline].

       -x[[-]n] (more a|)
              Limit number of cores used in multi-threaded algorithms  (OpenMP
              required).

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


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

              gmt math -T0/10/1 0 1 NRAND = 1D.txt
              gmt psxy -R0/10/-5/5 -JX6i/3i -B2f1/1 -Sc0.1 -Gblack 1D.txt -K > 1D.ps
              gmt greenspline 1D.txt -R0/10 -I0.1 -Sc -V | psxy -R -J -O -Wthin >> 1D.ps

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

              gmt psxy -R0/10/-5/5 -JX6i/3i -B2f1/1 -Sc0.1 -Gblack 1D.txt -K > 1Dt.ps
              gmt greenspline 1D.txt -R0/10 -I0.1 -St0.7 -V | psxy -R -J -O -Wthin >> 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  Technical
       Reference and Cookbook example 16, try

              gmt greenspline table_5.11 -R0/6.5/-0.2/6.5 -I0.1 -Sc -V -D1 -GS1987.nc
              gmt psxy -R0/6.5/-0.2/6.5 -JX6i -B2f1 -Sc0.1 -Gblack table_5.11 -K > 2D.ps
              gmt grdcontour -JX6i -B2f1 -O -C25 -A50 S1987.nc >> 2D.ps

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

              gmt greenspline table_5.11 -Tmask.nc -St0.5 -V -D1 -GWB1998.nc

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

              gmt greenspline table_5.11 -R0/6.5/-0.2/6.5 -I0.1 -Sr0.95 -V -D1 -Q-45 -Gslopes.nc

       Finally,  to  use  Cartesian  minimum curvature splines in recovering a
       surface where the input data is a single surface value (pt.txt) and the
       remaining  constraints  specify  only  the  surface slope and direction
       (slopes.txt), use

              gmt greenspline pt.txt -R-3.2/3.2/-3.2/3.2 -I0.1 -Sc -V -D1 -Aslopes.txt+f1 -Gslopes.nc


3-D EXAMPLES

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

              gmt greenspline table_5.23 -R5/40/-5/10/5/16 -I0.25 -Sr0.85 -V -D5 -G3D_UO2.txt


2-D SPHERICAL SURFACE EXAMPLES

       To recreate Parkeras [1994] example on a global 1x1 degree grid, assum-
       ing the data are in file mag_obs_1990.txt, try

              greenspline -V -Rg -Sp -D3 -I1 -GP1994.nc mag_obs_1990.txt

       To do the same problem but applying tension of 0.85, use

              greenspline -V -Rg -Sq0.85 -D3 -I1 -GWB2008.nc mag_obs_1990.txt


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 computeras memory may  place
          restrictions  on  how  large  data  sets you can process with green-
          spline. Pre-processing your data  with  doc:blockmean,  doc:blockme-
          dian, or doc: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 green-
          spline is fully 64-bit compliant if compiled as such.  For spherical
          data you may consider decimating using doc:gmtspatial nearest neigh-
          bor reduction.

       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  associ-
          ated with the smallest eigenvalues (see -C).

       4. The  series  solution implemented for -Sq was developed by Robert L.
          Parker, Scripps Institution of  Oceanography,  which  we  gratefully
          acknowledge.

       5. If you need to fit a certain 1-D spline through your data points you
          may wish to consider sample1d instead.  It  will  offer  traditional
          splines with standard boundary conditions (such as the natural cubic
          spline, which sets the curvatures at the ends  to  zero).   In  con-
          trast, greensplineas 1-D spline, as is explained in note 1, does not
          specify boundary conditions at the end of the data domain.


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 moder-
       ate 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  Edi-
       tion, 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  ten-
       sion: a Greenas function approach, Math. Geol., 30, 77-93.

       Wessel,  P.,  and J. M. Becker, 2008, Interpolation using a generalized
       Greenas function for a spherical surface spline in tension, Geophys. J.
       Int, 174, 21-28.

       Wessel, P., 2009, A general-purpose Greenas function interpolator, Com-
       puters & Geosciences, 35, 1247-1254, doi:10.1016/j.cageo.2008.08.012.


SEE ALSO

       gmt(1), gmtmath(1), nearneighbor(1), psxy(1), sample1d(1),
       sphtriangulate(1), surface(1), triangulate(1), xyz2grd(1)


COPYRIGHT

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



5.4.2                            Jun 24, 2017                   greenspline(1)

gmt5 5.4.2 - Generated Thu Jun 29 13:40:54 CDT 2017
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.