s.surf.rst manual page

s.surf.rst - interpolation and topographic analysis from given site data to GRASS raster format using regularized spline with tension

SYNOPSIS

s.surf.rst

s.surf.rst help

s.surf.rst [-d] [-h] input = name elev = name [ slope = name] [ aspect = name] [ pcurv = name] [ tcurv = name] [ mcurv = name] [ maskmap = name] [ dmin = val] [ zmult = val] [ tension = val] [ smooth = val] [ segmax = val] [ npmin = val] [ devi = name] [ treefile = name] [ overfile = name]

DESCRIPTION

s.surf.rst interpolates the z-values from point data (e.g., elevations, climatic stations, drill holes, etc.) given in a sites file named input as x|y|%z to grid cells in the output raster file elev representing surface. As an option, simultaneously with interpolation, topographic parameters slope, aspect, profile curvature (measured in the direction of steepest slope), tangential curvature (measured in the direction of a tangent to contour line) or mean curvature are computed and saved as raster files specified by the options slope, aspect, pcurv, tcurv, mcurv respectively. If -d flag is set the program outputs partial derivatives fx,fy,fxx,fyy,fxy instead of slope, aspect, profile, tangential and mean curvatures respectively. All output raster files have floating point values. If the input data have time stamp, the program creates time stamp for all output files. User can define a raster file named maskmap, which will be used as a mask. The interpolation is skipped for cells which have zero or NULL value in mask. Data points are checked for identical points and points that are closer to each other than the given dmin are removed. Parameter zmult allows user to rescale the z-values for sites (useful e.g. for transformation of elevations given in feet to meters, so that the proper values of slopes and curvatures can be computed).

Regularized spline with tension is used for the interpolation. The tension parameter tunes the character of the resulting surface from thin plate to membrane. Higher values of tension parameter reduce the overshoots that can appear in surfaces with rapid change of gradient (see suggested values for different types of surfaces given in notes). Very low tension can cause visible segments and/or overshoots - increase in tension is suggested for such cases. For noisy data, it is possible to define a either a constant smoothing parameter smooth which must be a positive number or a variable smoothing parameter by seting the parameter smooth to a negative number, e.g., smooth=-1and providing the variable smoothing parameter %s for each data point in the site file as a second floating point value, i.e. the each site will be given as x|y|%z %s. With the smoothing parameter set to zero (smooth=0) the resulting surface passes exactly through the data points. When smoothing is used, it is possible to output site file devi containing deviations of the resulting surface from the given data.

If the number of given points is greater than segmax, segmented processing is used. The region is split into rectangular segments, each having less than segmax points and interpolation is performed on each segment of the region. To ensure the smooth connection of segments the interpolation function for each segment is computed using the points in given segment and the points in its neighborhood which are in the rectangular window surrounding the given segment. The number of points taken for interpolation is controlled by npmin, the value of which must be larger than segmax. User can choose to output vector files treefile and overfile which represent quad tree used for segmentation and overlapping neighborhoods from which additional points for interpolation on each segment were taken. The program writes several important values to history file of raster map elev. When program is run with -h option, it displays the references which should be cited in publications where this program was used.

OPTIONS

The user can run this program either interactively or non-interactively. The program will be run non-interactively if the user specifies program arguments and flag settings on the command line using the form:

s.surf.rst [-dh] input = name elev = name [ slope = name] [ aspect = name] [ pcurv = name] [ tcurv = name] [ mcurv = name] [ maskmap = name] [ dmin = val] [ zmult = val] [ tension = val] [ smooth = val] [ segmax = val] [ npmin = val] [ devi = name] [ treefile = name] [ overfile = name]

Alternately, the user can simply type s.surf.rst on the command line without program arguments. In this case, the user will be prompted for parameter values and flag settings using the standard GRASS parser interface described in the manual entry for parser.

Parameters:

-d Output partial derivatives instead of aspect, slope and curvatures.

-h Display reference information

input = name
Use the existing site file name as input.

elev = name
Output elevation values to raster file name.

slope = name
Output slope or dx values to raster file name.

aspect = name
Output aspect or dy values to raster file name.

pcurv = name
Output profile curvature or dxx values to raster file name.

tcurv = name
Output tangential curvature or dyy values to raster file name.

mcurv = name
Output mean curvature or dxy values to raster file name.

maskmap = name
Use the existing raster file name as a mask.

dmin = val
Set min distance between points to val. Default value is set to 0.5 grid cell size.

zmult = val
Convert z-values using conversion factor val. Default value is 1.

tension =val
Set tension to val. Default value is 40, appropriate for smooth surfaces at scales 1-100m distances/cell size.

smooth = val
Set smoothing parameter to val. If variable smoothing is given in a site file set val to a negative number. Default value is 0.1.

segmax = val
Set max number of points per segment to val. Default value is 40.

npmin =
Set min number of points for interpolation to val. Default value is 200, for data with heterogeneous spatial distribution higher value is suggested (see notes).

devi = name
Output deviations to a site file name. (Used for smoothed surfaces)

treefile = name
Output quad tree used for segmentation to vector file name

overfile = name
Output overlapping neighborhoods used for segmentation to vector file name.

NOTES

s.surf.rst uses regularized spline with tension for interpolation from point data. Point data should be in a new site format , that means format x|y|%value, instead of old format which confused categories with values (x|y|#value). If program detects the old format it will allow users to have the site file rewritten to a new format automatically. If variable smoothing is used the input will be x|y|%z %s.

The implementation has a segmentation procedure based on quadtrees which enhances the efficiency for large data sets. The GRASS4.2 version has enhanced segmentation which takes more points for the large segments, to reduce the potential for visibility of segmentens in areas with sparse data.

Special color tables are created by the program for output raster files. In the GRASS4.2 version, the output color table for raster elevation file with values only between 0-1 has reduced number of colors - this is a known bug.

Topographic parameters are computed directly from the interpolation function so that the important relationships between these parameters are preserved. The equations for computation of these parameters and their interpretation is described in (Mitasova and Hofierka 1993). Slopes and aspect are computed in degrees (0-90 and 1-360 respectively). The aspect raster file has value 0 assigned to flat areas (with slope less than 0.1%) and to singular points with undefined aspect. Aspect points downslope and is 90 to the North, 180 to the West, 270 to the South and 360 to the East, the values increase counterclockwise. Curvatures are positive for convex and negative for concave areas. Singular points with undefined curvatures have assigned zero values.

The program gives warning when significant overshoots appear and higher tension should be used. However, with tension too high the resulting surface changes its behavior to membrane (rubber sheet stretched over the data points resulting in a peak or pit in each given point and everywhere else the surface goes rapidly to trend). Also smoothing can be used to reduce the overshoots.

For data with values changing over several magnitudes (sometimes the concentration or density data) it is suggested to interpolate the log of the values rather than the original ones.

The program checks the numerical stability of the algorithm by computating the values in given points, and prints the root mean square deviation (rms) found into the history file of raster map elev. For computation with smoothing set to 0. rms should be 0. Significant increase in tension is suggested if the rms is unexpectedly high for this case. With smoothing parameter greater than zero the surface will not pass exactly through the data points and the higher the parameter the closer the surface will be to the trend. The rms then represents a measure of smoothing effect on data. More detailed analysis of smoothing effects can be performed using the output deviations option and running s.univar on the site file with deviations. For theory on smoothing with splines and their statistical interpretation see Talmi and Gilat, 1977, Wahba, 1990 and Hutchinson, 1993, where you can find also a comparison of smoothing splines with kriging.

The program writes the values of parameters used in computation into the comment part of history file elev as well as the following values which help to evaluate the results and choose the suitable parameters: minimum and maximum z values in the data file (zmin_data, zmax_data) and in the interpolated raster map (zmin_int, zmax_int), rescaling parameter used for normalization (dnorm), which influences the tension. However, tension does not change with changes in npmin or dmin as it used to be in the GRASS4.1 version.

If visible connection of segments appears, the program should be rerun with higher npmin to get more points from the neighborhood of given segment and/or with higher tension.

When the number of points in a site file is not too large (less than 800), the user can skip segmentation by setting segmax to the number of data points.

The program gives warning when user wants to interpolate outside the rectangle given by minimum and maximum coordinates in site file, zoom into the area where the points are is suggested in this case.

When a mask is used, the program takes all points in the given region for interpolation, including those in the area which is masked out, to ensure proper interpolation along the border of the mask. It therefore does not mask out the data points, if this is desirable, it must be done outside s.surf.rst (e.g. using r.mask.points).

For examples of applications see http://www.cecer.army.mil/grass/viz/VIZ.html

The user must run g.region before the program to set the region and resolution for interpolation.

KNOWN BUGS
maskmap, timestamp, colortable for 0-1