Provided by: gmt_4.5.11-1build1_amd64

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

greensplineuses 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 asw(x) = sum {c(i) G(x;x(i))}, fori= 1,n, the number of data points {x(i),w(i)}. Once thencoefficientsc(i) have been found then the sum can be evaluated at any output pointx. 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 coefficientsc(i) is found by solving thenbynlinear systemw(j) = sum-over-i{c(i) G(x(j);x(i))}, forj= 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 thex,wdata points. If no file is given then we read standard input instead.-AThe solution will partly be constrained by surface gradientsv=v*n, wherevis the gradient magnitude andnits unit vector direction. The gradient direction may be specified either by Cartesian components (either unit vectornand magnitudevseparately or gradient componentsvdirectly) 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 isx,gradient. Options 1-2 are for 2-D data sets:1: records containx,y,azimuth,gradient(azimuthin degrees is measured clockwise from the vertical (north) [Default]).2: records containx,y,gradient,azimuth(azimuthin degrees is measured clockwise from the vertical (north)). Options 3-5 are for either 2-D or 3-D data:3: records containx,direction(s),v(direction(s)in degrees are measured counter-clockwise from the horizontal (and for 3-D the vertical axis).4: records containx,v.5: records containx,n,v. Append name of ASCII file with the surface gradients (following a comma if a format is specified).-CFind 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 thancut[Default uses Gauss-Jordan elimination to solve the linear system and fit the data exactly]. Optionally, append /fileto save the eigenvalue ratios to the specified file for further analysis. Finally, if a negativecutis given then /fileis required and execution will stop after saving the eigenvalues, i.e., no surface output is produced.-DSets the distance flag that determines how we calculate distances between data points. Selectmode0 for Cartesian 1-D spline interpolation:-D0 means (x) in user units, Cartesian distances, Selectmode1-3 for Cartesian 2-D surface spline interpolation:-D1 means (x,y) in user units, Cartesian distances,-D2 for (x,y) in degrees, flat Earth distances, and-D3 for (x,y) in degrees, spherical distances in km. Then, ifELLIPSOIDis spherical, we compute great circle arcs, otherwise geodesics. Optionmode= 4 applies to spherical surface spline interpolation only:-D4 for (x,y) in degrees, use cosine of great circle (or geodesic) arcs. Selectmode5 for Cartesian 3-D surface spline interpolation:-D5 means (x,y,z) in user units, Cartesian distances.-FForce pixel registration. [Default is gridline registration].-GName of resulting output file. (1) If options-R,-I, and possibly-Fare set we produce an equidistant output table. This will be written to stdout unless-Gis specified. Note: for 2-D grids the-Goption is required. (2) If option-Tis selected then-Gis required and the output file is a 2-D binary grid file. Applies to 2-D interpolation only. (3) If-Nis selected then the output is an ASCII (or binary; see-bo) table; if-Gis not given then this table is written to standard output. Ignored if-Cor-C0 is given.-HInput file(s) has header record(s). If used, the default number of header records isN_HEADER_RECS. Use-Hiif 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.-ISpecify equidistant sampling intervals, on for each dimension, separated by slashes.-LDonotremove a linear (1-D) or planer (2-D) trend when-Dselects 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).-NASCII file with coordinates of desired output locationsxin the first column(s). The resultingwvalues are appended to each record and written to the file given in-G[or stdout if not specified]; see-bofor binary output instead. This option eliminates the need to specify options-R,-I, and-F.-QRather than evaluate the surface, take the directional derivative in theazazimuth 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).-RSpecify the domain for an equidistant lattice where output predictions are required. Requires-Iand optionally-F.1-D:Givexmin/xmax, the minimum and maximumxcoordinates.2-D:Givexmin/xmax/ymin/ymax, the minimum and maximumxandycoordinates. These may be Cartesian or geographical. If geographical, thenwest,east,south,andnorthspecify 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-Rgand-Rdstand for global domain (0/360 and -180/+180 in longitude respectively, with -90/+90 in latitude).3-D:Givexmin/xmax/ymin/ymax/zmin/zmax, the minimum and maximumx,yandzcoordinates. See the 2-D section if your horizontal coordinates are geographical; note the shorthands-Rgand-Rdcannot be used if a 3-D domain is specified.-SSelect one of five different splines. The first two are used for 1-D, 2-D, or 3-D Cartesian splines (see-Dfor 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 [WesselandBercovici, 1998]; appendtension[/scale] withtensionin 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 [MitasovaandMitas, 1993]; again, appendtensionand optionalscale. The last two are spherical surface splines and both imply-D4 and geographic data: (p) Minimum curvature spline [Parker, 1994], (q) Continuous curvature spline in tension [WesselandBecker, 2008]; appendtension. The G(x;x') for the last method is slower to compute; by specifying-SQyou can speed up calculations by first pre-calculating G(x;x') for a dense set ofxvalues (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]-TFor 2-D interpolation only. Only evaluate the solution at the nodes in themaskgridthat are not equal to NaN. This option eliminates the need to specify options-R,-I, and-F.-VSelects verbose mode, which will send progress reports to stderr [Default runs "silently"].-biSelects binary input. Appendsfor single precision [Default isd(double)]. UppercaseSorDwill force byte-swapping. Optionally, appendncol, the number of columns in your binary input file if it exceeds the columns needed by the program. Or appendcif the input file is netCDF. Optionally, appendvar1/var2/...to specify the variables to be read. [Default is 2-4 input columns (x,w); the number depends on the chosen dimension].-fSpecial formatting of input and/or output columns (time or geographical data). Specifyioroto make this apply only to input or output [Default applies to both]. Give one or more columns (or column ranges) separated by commas. AppendT(absolute calendar time),t(relative time in chosenTIME_UNITsinceTIME_EPOCH),x(longitude),y(latitude), orf(floating point) to each column or column range item. Shorthand-f[i|o]gmeans-f[i|o]0x,1y(geographic coordinates).-boSelects binary output. Appendsfor single precision [Default isd(double)]. UppercaseSorDwill force byte-swapping. Optionally, appendncol, the number of desired columns in your binary output file.

**1-D** **EXAMPLES**

To resample thex,yGaussian random data created bygmtmathand stored in 1D.txt, requesting output every 0.1 step from 0 to 10, and using a minimum cubic spline, trygmtmath-T0/10/1 0 1NRAND= 1D.txtpsxy-R0/10/-5/5-JX6i/3i-B2f1/1-Sc0.1-Gblack 1D.txt-K> 1D.psgreenspline1D.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, trypsxy-R0/10/-5/5-JX6i/3i-B2f1/1-Sc0.1-Gblack 1D.txt-K> 1Dt.psgreenspline1D.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 Cookbook example 16, trygreensplinetable_5.11-R0/6.5/-0.2/6.5-I0.1-Sc-V-D1-GS1987.grdpsxy-R0/6.5/-0.2/6.5-JX6i-B2f1-Sc0.1-Gblack table_5.11-K> 2D.psgrdcontour-JX6i-B2f1-O-C25-A50 S1987.grd >> 2D.ps To use Cartesian splines in tension but only evaluate the solution where the input mask grid is not NaN, trygreensplinetable_5.11-Tmask.grd-St0.5-V-D1-GWB1998.grd To use Cartesian generalized splines in tension and return the magnitude of the surface slope in the NW direction, trygreensplinetable_5.11-R0/6.5/-0.2/6.5-I0.1-Sr0.95-V-D1-Q-45-Gslopes.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), usegreensplinept.d-R-3.2/3.2/-3.2/3.2-I0.1-Sc-V-D1-A1,slopes.d-Gslopes.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 containsx,y,zlocations and a measure of uranium oxide concentrations (in percent), trygreensplinetable_5.23-R5/40/-5/10/5/16-I0.25-Sr0.85-V-D5-G3D_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-D3-I1-GP1994.grd mag_obs_1990.d To do the same problem but applying tension and use pre-calculated Green functions, use greenspline-V-Rg-SQ0.85-D3-I1-GWB2008.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 usingsurfaceinstead. (2) In all cases, the solution is obtained by inverting anxndouble precision matrix for the Green function coefficients, wherenis the number of data constraints. Hence, your computer's memory may place restrictions on how large data sets you can process withgreenspline. Pre-processing your data withblockmean,blockmedian, orblockmodeis recommended to avoid aliasing and may also control the size ofn. For information, ifn= 1024 then only 8 Mb memory is needed, but forn= 10240 we need 800 Mb. Note thatgreensplineis 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 ofscalevalues; 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,StatisticsandDataAnalysisinGeology, 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,GeophysicalInverseTheory, 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)