SurfaceGwr (Analysis 2.1.2 API)

java.lang.Object
- org.tinfour.gwr.SurfaceGwr

```
public class SurfaceGwr
extends Object
```
Provides an implementation of a weighted polynomial regression for the surface z=p(x, y). A small set of models (cubic, quadradic, planar) are available for the surface of interest which may be elevation or some other phenomenon. Weights are computed using an inverse distance weighted calculation.
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.
Usage Notes: This class is optimized for the computation of values at specific points in which a set of irregularly spaced sample points are available in the vicinity of the point of interest. Each value calculation involves a separate regression operation.
Regression techniques are used as a way of dealing with uncertainty in the observed values passed into the calculation. As such, they provide methods for evaluating the uncertainty in the computed results. In terrain-based applications, it is common to treat points nearest a query position as more significant than those farther away (in accordance to the precept of "spatial autocorrelation"). In order to support that, a criterion for inverse-distance weighting of the regression is provided based on the Gaussian Kernel described in the references cited below.
Given a set of sample points in the vicinity of the point of interest,(x,y), the class solves for the coefficients treating (x,y) as the origin. Thus algebraic simplifications result in a case where the parameter b0 gives the surface height at point (x,y). Furthermore, the ordering of coefficients is specified for all models so that the coefficients b1 and b2 give the partial derivatives of the surface when evaluated at (x,y). Parameter b1 is the partial derivative with respect to x, b2 with respect to y. Applications requiring information about slope or surface normal may do so by using this construct.
The calculations used to derive regression coefficients are adapted from "Probability and Statistics for Engineers and Scientists (4th ed.)", 1989 by Ronald E. Walpole and Raymond H. Myers, Macmillan Publishing Company, New York City, NY Chapter 10, "Multiple Linear Regression". Walpole and Myers provide an excellent introduction to the problem of multiple linear regression, its general statistics (particularly the prediction interval), and their use. The calculations for weighted regression are not covered in their work, but were derived from the information they provided. Because these calculations are not taken from published literature, they have not been vetted by expert statisticians.
Details of the residual variance and other statistics specific to a weighted regression are taken from Leung, Yee; Mei, Chang-Lin; and Zhang, Wen-Xiu (2000). "Statistical tests for spatial nonstationarity based on the geographically weighted regression model", Environment and Planning A 2000, volumn 32, p. 9-32.
Information related to the AICc criteria as applied to a GWR was found in "Geographically Weighted Regression" by David C Wheeler and Antonio Paez, a white paper I found on the web. It appears to be a chapter from "Handbook of Applied Spatial Analysis: Software Tool, Methods, and Applications", Springer Verlag, Berlin (2010). I also found information in Charlton, M. and Fotheringham, A. (2009) "Geographically Weighted Regression -- White Paper", National Center for Geocomputation, National University of Ireland Maynooth, a white paper downloaded from the web. A number of other papers by Brunsdon, Fotheringham and Charlton (BRC) which provide slightly different perspectives on the same material can be found on the web.
A Note on Safe Coding: This class maintains references to its most recent inputs as member elements. For efficiency purposes, it does not make copies of the input arrays, but uses them directly. Therefore, it is imperative that the calling application not modify these elements until it is done with the results from a computation. Also, some of the getter methods in the class expose internal arrays. So the results obtained from these methods should not be modified by application code but are subject to modification by subsequent interpolation operations. While approach violates well-known safe-coding practices, it is necessary in this case for efficiency reasons. Instances of this class are often used in raster-processing operations that require millions of interpolations in tight loops where the overhead of repeatedly creating arrays would be detrimental to processing.
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 arbitrary models. Originally, I felt that users interested in other problems might be better served by R, GWR4, or even the Apache Commons Math GSLMultipleLinearRegression class. But this implementation has demonstrated sufficient utility, that it may be worth considering expanding its capabilities in future development.
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.

Constructor Summary

Constructors
Constructor and Description

SurfaceGwr()
Standard constructor.

Constructors
Constructor and Description
`SurfaceGwr()` Standard constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`clear()` Clear all state variables and external references that may have been set in previous operations.
`double[]`	`computeRegression(SurfaceModel model, double xQuery, double yQuery, int nSamples, double[][] samples, double[] weights, double[][] sampleWeightsMatrix)` Computes the elevation for a point at the specified query coordinates, by performing a multiple-linear regression using the observed values.
`void`	`computeVarianceAndHat()` Compute the variance and hat matrix for the sample data.
`org.apache.commons.math3.linear.RealMatrix`	`computeXWX(double xQuery, double yQuery, int nSamples, double[][] samples, double[] weights)`
`double`	`getAdjustedR2()` Gets the adjusted R2 value.
`double`	`getAICc()` Get the Akaike information criterion (corrected) organized so that the minimum value is preferred.
`double[]`	`getCoefficients()` Gets the computed polynomial coefficients from the regression (the "beta" parameters that).
`int`	`getDegreesOfFreedom()` Gets the number of degrees of freedom for the most recent computation based on a ordinary least squares treatment (weighting neglected)
`double`	`getEffectiveDegreesOfFreedom()` Get the effective degrees of freedom for the a chi-squared distribution which approximates the distribution of the GWR.
`double`	`getEstimatedValue(double xQuery, double yQuery)`
`double`	`getF()` Gets the F statistic for the regression result which may be used in hypothesis testing for evaluating the regression.
`org.apache.commons.math3.linear.RealMatrix`	`getHatMatrix()`
`double`	`getLeungDelta1()` Get leung's delta parameter
`double`	`getLeungDelta2()` Get Leung's delta2 parameter.
`int`	`getMinimumRequiredSamples(SurfaceModel sm)` Get the minimum number of samples required to perform a regression for the specified surface model
`SurfaceModel`	`getModel()` Get the surface model associated with this instance.
`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[]`	`getQueryCoordinates()` Get the coordinates used for the initial query
`double`	`getR2()` Get the r-squared value, the coefficient of multiple regression.
`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.
`int`	`getSampleCount()` Gets the number of samples from the most recent computation
`double[][]`	`getSamples()` Gets the samples from the most recent computation.
`double`	`getSigmaML()` Gets the ML Sigma value used in the AICc calculation.
`double`	`getStandardDeviation()` Gets an unbiased estimate of the the standard deviation of the residuals for the predicted values for all samples.
`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.
`void`	`initWeightsMatrixUsingGaussianKernel(double[][] samples, int nSamples, double bandwidth, double[][] matrix)` Initializes a square matrix of weights based on the distance between samples using the Gaussian kernel.
`void`	`initWeightsUsingGaussianKernel(double x, double y, double[][] samples, int nSamples, double bandwidth, double[] weights)` Initializes an array of weights based on the distance of samples from a specified pair of coordinates by using the Gaussian kernel.
`boolean`	`isSampleWeightsMatrixSet()` Indicates whether a sample weights matrix was set.
`void`	`printSummary(PrintStream ps)` Print a summary of the parameters and correlation results for the most recent interpolation.
`void`	`setSampleWeightsMatrix(double[][] sampleWeightsMatrix)` Allows an application to set the sample weights matrix.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - SurfaceGwr
```
public SurfaceGwr()
```
    Standard constructor.
- Method Detail
  - computeRegression
```
public double[] computeRegression(SurfaceModel model,
                                  double xQuery,
                                  double yQuery,
                                  int nSamples,
                                  double[][] samples,
                                  double[] weights,
                                  double[][] sampleWeightsMatrix)
```
    Computes the elevation for a point at the specified query coordinates, by performing a multiple-linear regression using the observed values. A number of statistics are simultaneously computed and may be obtained using access methods. The more heavy weight computations (such as the computation of a variance and covariance matrix) are deferred until actually requested by the calling application.
    Note: For efficiency purposes, the arrays for samples and weights passed to this method are stored in the class directly.
    The sample weights matrix is a two dimensional array giving weights based on the distance between samples. It is used when performing calculations for general statistics such as standard deviation, confidence intervals, etc. Because of the high cost of initializing this array, it can be treated as optional in cases where only the regression coefficients are required.
    A convenience routine for populating the sample weights matrix is supplied by the initWeightsUsingGaussianKernal method.
    
    Parameters:
    
    model - the model to be used for the regression
    
    xQuery - x coordinate of the query position
    
    yQuery - y coordinate of the query position
    
    nSamples - the number of sample points to be used for regression
    
    samples - an array of dimension [n][3] giving at least nSamples points with the x, y, and z values for the regression.
    
    weights - an array of weighting factors for samples
    
    sampleWeightsMatrix - an optional array of weights based on the distances between different samples; if general statistics are not required, pass a null value for this argument.
    
    Returns:
    
    an array of regression coefficients, or null if the computation failed.
  - computeXWX
```
public org.apache.commons.math3.linear.RealMatrix computeXWX(double xQuery,
                                                             double yQuery,
                                                             int nSamples,
                                                             double[][] samples,
                                                             double[] weights)
```
  - computeVarianceAndHat
```
public void computeVarianceAndHat()
```
    Compute the variance and hat matrix for the sample data.
    
    Throws:
    
    org.apache.commons.math3.linear.SingularMatrixException - if the data gives rise to an unsolvable or numerically ill-conditioned matrix.
  - printSummary
```
public void printSummary(PrintStream ps)
```
    Print a summary of the parameters and correlation results for the most recent interpolation.
    
    Parameters:
    
    ps - a valid print stream to receive the output of this method.
  - getCoefficients
```
public double[] getCoefficients()
```
    Gets the computed polynomial coefficients from the regression (the "beta" parameters that). These coefficients can be used for interpolation or surface modeling purposes. Developers are reminded that the interpolation is based on treating the query point as the origin, so x and y coordinates should be adjusted accordingly when used in calculations based on the return values of this method.
    
    Returns:
    
    a valid array of coefficients for the selected surface model.
  - getR2
```
public double getR2()
```
    Get the r-squared value, the coefficient of multiple regression. This value is basically the proportion of the variation in the data that is explained by the postulated model.
    
    Returns:
    
    a positive value between 0 and 1.0
  - getAdjustedR2
```
public double getAdjustedR2()
```
    Gets the adjusted R2 value.
    
    Returns:
    
    a positive value between 0 and 1.0
  - getF
```
public double getF()
```
    Gets the F statistic for the regression result which may be used in hypothesis testing for evaluating the regression.
    
    Returns:
    
    if available, a valid floating point number; if the regression failed, NaN; if the regression was close to an exact match with the samples, positive infinity
  - 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.
  - 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.
  - 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.
  - 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
  - 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.
  - 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.
  - 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.
  - getDegreesOfFreedom
```
public int getDegreesOfFreedom()
```
    Gets the number of degrees of freedom for the most recent computation based on a ordinary least squares treatment (weighting neglected)
    
    Returns:
    
    if the most recent computation was successful, a positive integer; otherwise, a value <= 0.
  - getHatMatrix
```
public org.apache.commons.math3.linear.RealMatrix getHatMatrix()
```
  - getMinimumRequiredSamples
```
public final int getMinimumRequiredSamples(SurfaceModel sm)
```
    Get the minimum number of samples required to perform a regression for the specified surface model
    
    Parameters:
    
    sm - the surface model to be evaluated
    
    Returns:
    
    a positive integer
  - getQueryCoordinates
```
public double[] getQueryCoordinates()
```
    Get the coordinates used for the initial query
    
    Returns:
    
    an array of dimension 2 containing the x and y values of the most recently completed query.
  - getModel
```
public SurfaceModel getModel()
```
    Get the surface model associated with this instance.
    
    Returns:
    
    a valid surface model.
  - getAICc
```
public double getAICc()
```
    Get the Akaike information criterion (corrected) organized so that the minimum value is preferred.
    
    Returns:
    
    a valid floating point number.
  - getEstimatedValue
```
public double getEstimatedValue(double xQuery,
                                double yQuery)
```
  - clear
```
public void clear()
```
    Clear all state variables and external references that may have been set in previous operations.
  - 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.
  - 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
  - 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.
  - getSampleCount
```
public int getSampleCount()
```
    Gets the number of samples from the most recent computation
    
    Returns:
    
    a positive integer (zero if not available)
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - initWeightsUsingGaussianKernel
```
public void initWeightsUsingGaussianKernel(double x,
                                           double y,
                                           double[][] samples,
                                           int nSamples,
                                           double bandwidth,
                                           double[] weights)
```
    Initializes an array of weights based on the distance of samples from a specified pair of coordinates by using the Gaussian kernel. This method is intended to support the initialization of weights for a regression computation.
    If Double.POSITIVE_INFINITY is passed as the bandwidth parameter, all weights will be set uniformly to 1.0, which would be equivalent to an Ordinary Least Squares regression.
    
    Parameters:
    
    x - the coordinate of the query point
    
    y - the coordinate of the query point
    
    samples - a two dimensional array giving (x,y) coordinates of the samples
    
    nSamples - the number of samples
    
    bandwidth - the bandwidth parameter
    
    weights - an array to store the resulting weights
  - initWeightsMatrixUsingGaussianKernel
```
public void initWeightsMatrixUsingGaussianKernel(double[][] samples,
                                                 int nSamples,
                                                 double bandwidth,
                                                 double[][] matrix)
```
    Initializes a square matrix of weights based on the distance between samples using the Gaussian kernel. Each ith row of the matrix is set to the weights for samples based on their distance from the ith sample. Thus the main diagonal of the matrix is based on the distance of the sample from itself, and will be assigned a weight of 1.0
    
    Parameters:
    
    samples - a two dimensional array giving (x,y) coordinates of the samples
    
    nSamples - the number of samples
    
    bandwidth - the bandwidth parameter specification
    
    matrix - a square matrix of dimension nSamples to store the computed weights.
  - isSampleWeightsMatrixSet
```
public boolean isSampleWeightsMatrixSet()
```
    Indicates whether a sample weights matrix was set. Because the matrix is an optional argument of the computeRegression method, it could be set to a null value.
    
    Returns:
    
    true if the matrix is set; otherwise, false
  - setSampleWeightsMatrix
```
public void setSampleWeightsMatrix(double[][] sampleWeightsMatrix)
```
    Allows an application to set the sample weights matrix.
    
    Parameters:
    
    sampleWeightsMatrix - a valid two dimensional array dimensions to the same size as the number of samples.

Class SurfaceGwr

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

SurfaceGwr

Method Detail

computeRegression

computeXWX

computeVarianceAndHat

printSummary

getCoefficients

getR2

getAdjustedR2

getF

getVariance

getStandardDeviation

getSigmaML

getResidualSumOfTheSquares

getLeungDelta1

getLeungDelta2

getEffectiveDegreesOfFreedom

getPredictionIntervalHalfRange

getPredictionInterval

getDegreesOfFreedom

getHatMatrix

getMinimumRequiredSamples

getQueryCoordinates

getModel

getAICc

getEstimatedValue

clear

getResiduals

getSamples

getWeights

getSampleCount

toString

initWeightsUsingGaussianKernel

initWeightsMatrixUsingGaussianKernel

isSampleWeightsMatrixSet

setSampleWeightsMatrix