org.tinfour.gwr

Class GwrInterpolator

java.lang.Object

org.tinfour.gwr.GwrInterpolator

Direct Known Subclasses:

GwrTinInterpolator

public class GwrInterpolator
extends Object

Provides methods and elements for performing interpolation over a surface using linear regression methods to develop a polynomial z = p(x, y) describing the surface in the region of the interpolation coordinates.

A Note on the Suitability of This Implementation: Anyone who values his own time should respect the time of others. With that regard, I believe it appropriate to make this note about the current state of the Tinfour GWR implementation. While I believe that code is implemented correctly, it is not complete. Statistics such as R values and F scores are not yet available. The Tinfour GWR classes also lacks tools for detecting multi collinearities in model coefficients. These classes were developed with a specific application in mind: the modeling of terrain and bathymetry. And while they can be applied to many other problems, potential users should consider whether the tool is suitable to their particular requirements.

Development Notes
The current implementation of this class supports a family of surface models based on polynomials p(x, y) of order 3 or less. While this approach is appropriate for the original intent of this class, modeling terrain, there is no reason why the class cannot be adapted to support other models based on continuous, real-valued variables.

One of the special considerations in terrain modeling is "mass production". Creating a raster grid from unstructured data can involve literally millions of interpolation operations. The design of this class reflects that requirement. In particular, it featured the reuse of Java objects and arrays to avoid the cost of constructing or allocating new instances. However, recent improvements in Java's handling of short-persistence objects (through escape analysis) have made some of these considerations less pressing. So future work may not be coupled to the same approach as the existing implementation.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	GwrInterpolator.BootstrapResult A container for the results from a bootstrap analysis

Constructor Summary

Constructors

Constructor and Description
GwrInterpolator() Standard constructor.

Method Summary

Modifier and Type	Method and Description
GwrInterpolator.BootstrapResult	bootstrap(SurfaceModel model, BandwidthSelectionMethod bandwidthMethod, double bandwidthParameter, double qx, double qy, int nSamples, double[][] samples, int nRepetitions, double threshold) Perform a variation of a statistical bootstrap analysis in which the resampling is based on random selection of samples without repetition.
double	getAICc() Get the Akaike information criterion (corrected) organized so that the minimum value is preferred.
long	getAutomaticBandwidthTestCount() Gets the number of tests performed in selecting a bandwidth via the automatic selection method.
double	getBandwidth() Get the bandwidth setting used in the most recent interpolation.
BandwidthSelectionMethod	getBandwidthSelectionMethod() Gets the method used for the most recent bandwidth selection.
double[]	getCoefficients() Gets the coefficients computed by the most recent regression calculation, or a zero-length array if no results are available.
double	getEffectiveDegreesOfFreedom() Get the effective degrees of freedom for the a chi-squared distribution which approximates the distribution of the GWR.
double	getLeungDelta1() Get leung's delta parameter
double	getLeungDelta2() Get Leung's delta2 parameter.
double[]	getPredictionInterval(double alpha) Gets the prediction interval at the interpolation coordinates on the observed response for the most recent call to computeRegression.
double	getPredictionIntervalHalfRange(double alpha) Gets a value equal to one half of the range of the prediction interval on the observed response at the interpolation coordinates for the most recent call to computeRegression().
double[]	getResiduals() Gets the residuals from the most recent regression calculation.
double	getResidualSumOfTheSquares() Gets the residual sum of the squared errors (residuals) for the predicted versus the observed values at the sample locations.
double[][]	getSamples() Gets the samples from the most recent computation.
double	getSigmaML() Gets the ML Sigma value used in the AICc calculation.
double	getSlope() Gets the slope for the most recent computation expressed as the fraction change in elevation over a horizontal distance (i.e. rise-over-run).
double	getStandardDeviation() Gets an unbiased estimate of the the standard deviation of the residuals for the predicted values for all samples.
SurfaceModel	getSurfaceModel() Gets the surface model for the most recently performed interpolation.
double[]	getSurfaceNormal() Gets the unit normal to the surface at the position of the most recent interpolation.
double	getVariance() Gets an unbiased estimate of the variance of the residuals for the predicted values for all samples.
double[]	getWeights() Gets an array of weights from the most recent computation.
double	interpolate(SurfaceModel model, BandwidthSelectionMethod bandwidthMethod, double bandwidthParameter, double qx, double qy, int nSamples, double[][] samples) Performs regression using the specified surface model and bandwidth-selection method.
double	interpolateUsingAutomaticModelAndBandwidth(double qx, double qy, int nSamples, double[][] samples) Performs regression using automatic bandwidth selection and testing all available models using the AICc criterion.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GwrInterpolator

public GwrInterpolator()

Standard constructor.

Method Detail

interpolateUsingAutomaticModelAndBandwidth

public double interpolateUsingAutomaticModelAndBandwidth(double qx,
                                                         double qy,
                                                         int nSamples,
                                                         double[][] samples)

Performs regression using automatic bandwidth selection and testing all available models using the AICc criterion. This method is intended to achieve a good solution under general circumstances, though it is also the most computationally expensive implementation.

Values are assigned to samples using the specified valuator, or by taking their z-values directly if no valuator (e.g. a null) is specified.

Parameters:

qx - the x coordinate for the interpolation point

qy - the y coordinate for the interpolation point

nSamples - the number of samples to process

samples - a nSamples-by-3 array giving the x, y, and z coordinates for input samples.

Returns:

if the interpolation is successful, a valid floating point value; otherwise, a NaN.

interpolate

public double interpolate(SurfaceModel model,
                          BandwidthSelectionMethod bandwidthMethod,
                          double bandwidthParameter,
                          double qx,
                          double qy,
                          int nSamples,
                          double[][] samples)

Performs regression using the specified surface model and bandwidth-selection method. The bandwidth parameter will be applied according to which bandwidth-selection method is supplied.

When in doubt, a good general specification for bandwidth-selection is to use BandwidthSelectionMethod.FixedProportionalBandwidth with a bandwidth parameter of 0.5. The model should be selected based on the anticipated behavior of the surface. SurfaceModel.Cubic is usually a good choice for all but flat surfaces.

Parameters:

model - a valid model specification

bandwidthMethod - a valid bandwidth-selection method specification

bandwidthParameter - a bandwidth parameter

qx - the x coordinate of the interpolation point

qy - the y coordinate of the interpolation point

nSamples - the number of samples for input processing

samples - an array of dimensions nSamples-by-3 giving x, y, and z coordinates for input samples.

Returns:

if successful, an valid floating-point number; otherwise a Double.NaN.

getAICc

public double getAICc()

Get the Akaike information criterion (corrected) organized so that the minimum value is preferred.

Returns:

a valid floating point number.

getCoefficients

public double[] getCoefficients()

Gets the coefficients computed by the most recent regression calculation, or a zero-length array if no results are available.

Returns:

if available, a valid array; otherwise a zero-length array.

getEffectiveDegreesOfFreedom

public double getEffectiveDegreesOfFreedom()

Get the effective degrees of freedom for the a chi-squared distribution which approximates the distribution of the GWR. Combined with the residual variance, this yields an unbiased estimator that can be used in the construction of confidence intervals and prediction intervals.

The definition of this method is based on Leung (2000).

Returns:

a positive, potentially non-integral value.

getLeungDelta1

public double getLeungDelta1()

Get leung's delta parameter

Returns:

a positive value

getLeungDelta2

public double getLeungDelta2()

Get Leung's delta2 parameter.

Returns:

a positive value

getPredictionInterval

public double[] getPredictionInterval(double alpha)

Gets the prediction interval at the interpolation coordinates on the observed response for the most recent call to computeRegression. According to Walpole (1995), the prediction interval "provides a bound within which we can say with a preselected degree of certainty that a new observed response will fall." For example, we do not know the true values of the surface at the interpolation points, but suppose observed values were to become available. Given a significance level (alpha) of 0.05, 95 percent of the observed values would occur within the prediction interval.

Parameters:

alpha - the significance level (typically 0..05, etc).

Returns:

an array of dimension two giving the lower and upper bound of the prediction interval.

getPredictionIntervalHalfRange

public double getPredictionIntervalHalfRange(double alpha)

Gets a value equal to one half of the range of the prediction interval on the observed response at the interpolation coordinates for the most recent call to computeRegression().

Parameters:

alpha - the significance level (typically 0..05, etc).

Returns:

a positive value.

getResiduals

public double[] getResiduals()

Gets the residuals from the most recent regression calculation. For this application, the residual the difference between the predicted result and the input sample.

Returns:

if computed, a valid array of double; otherwise, an empty array.

getResidualSumOfTheSquares

public double getResidualSumOfTheSquares()

Gets the residual sum of the squared errors (residuals) for the predicted versus the observed values at the sample locations.

Returns:

a positive number.

getSamples

public double[][] getSamples()

Gets the samples from the most recent computation. The array returned from this method is an n-by-3 array that may contain more than nSamples entries. Therefore it is important to call the getSampleCount() method to know how many samples are actually valid.

Returns:

if available, a valid array of samples ; otherwise an empty array

getSlope

public double getSlope()

Gets the slope for the most recent computation expressed as the fraction change in elevation over a horizontal distance (i.e. rise-over-run). This calculation is non directional. Note that this method assumes that the vertical and horizontal of the input sample points are isotropic

Returns:

if available, a valid, positive value; if the regression failed, NaN.

getStandardDeviation

public double getStandardDeviation()

Gets an unbiased estimate of the the standard deviation of the residuals for the predicted values for all samples.

Returns:

if available, a positive real value; otherwise NaN.

getSigmaML

public double getSigmaML()

Gets the ML Sigma value used in the AICc calculation. This value is the sqrt of the sum of the residuals squared divided by the number of samples.

Returns:

in available, a positive real value; otherwise NaN.

getSurfaceModel

public SurfaceModel getSurfaceModel()

Gets the surface model for the most recently performed interpolation. In the case where an optimization routine was used to perform the interpolation, this value will be the model selected by the optimization.

Returns:

if available a valid instance; if no interpolation has been performed, a null.

getSurfaceNormal

public double[] getSurfaceNormal()

Gets the unit normal to the surface at the position of the most recent interpolation. The unit normal is computed based on the partial derivatives of the surface polynomial evaluated at the coordinates of the query point. Note that this method assumes that the vertical and horizontal coordinates of the input sample points are isotropic.

Returns:

if defined, a valid array of dimension 3 giving the x, y, and z components of the normal, respectively; otherwise, a zero-sized array.

getVariance

public double getVariance()

Gets an unbiased estimate of the variance of the residuals for the predicted values for all samples.

Returns:

if available, a positive real value; otherwise NaN.

getWeights

public double[] getWeights()

Gets an array of weights from the most recent computation.

Returns:

if available, a valid array of weights; otherwise, an empty array.

bootstrap

public GwrInterpolator.BootstrapResult bootstrap(SurfaceModel model,
                                                 BandwidthSelectionMethod bandwidthMethod,
                                                 double bandwidthParameter,
                                                 double qx,
                                                 double qy,
                                                 int nSamples,
                                                 double[][] samples,
                                                 int nRepetitions,
                                                 double threshold)

Perform a variation of a statistical bootstrap analysis in which the resampling is based on random selection of samples without repetition. The result gives a mean and variance for the predicted value of the surface at the query point.

Parameters:

model - the model to be used to represent the surface

bandwidthMethod - the method used for selecting bandwidth

bandwidthParameter - the input parameter for the specified method

qx - X coordinate of query point

qy - Y coordinate of query point

nSamples - the number of samples for processing

samples - an nSamples-by-3 array of samples for processing

nRepetitions - number of sub-samples to evaluate for bootstrap analysis.

threshold - the probability of accepting any single sample into the subsample.

Returns:

if successful, a non-null result instance; otherwise, a null.

getBandwidth

public double getBandwidth()

Get the bandwidth setting used in the most recent interpolation. This value may have been specified as an argument to the interpolation method (when the FixedBandwidth option is used) or may have been computed dynamically.

Returns:

if set, a real value greater than or equal to zero

getAutomaticBandwidthTestCount

public long getAutomaticBandwidthTestCount()

Gets the number of tests performed in selecting a bandwidth via the automatic selection method. Intended for diagnostic purposes only.

Returns:

a positive value

getBandwidthSelectionMethod

public BandwidthSelectionMethod getBandwidthSelectionMethod()

Gets the method used for the most recent bandwidth selection.

Returns:

if a regression has been performed, a valid enumeration; otherwise, a null.