org.tinfour.gwr

Class GwrTinInterpolator

java.lang.Object

org.tinfour.gwr.GwrInterpolator

org.tinfour.gwr.GwrTinInterpolator

All Implemented Interfaces:

IProcessUsingTin, IInterpolatorOverTin

public class GwrTinInterpolator
extends GwrInterpolator
implements IInterpolatorOverTin

Provides methods and elements for performing interpolation over a surface using linear regression methods to develop a polynomial z = f(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.

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. While this approach violates well-known safe-coding practices advocated by many parties, it is useful as a way of improving throughput for data processing and should not be a problem for careful developers.

Nested Class Summary

Nested classes/interfaces inherited from class org.tinfour.gwr.GwrInterpolator

GwrInterpolator.BootstrapResult

Constructor Summary

Constructors

Constructor and Description
GwrTinInterpolator(IIncrementalTin tin) Construct an interpolator that operates on the specified TIN.
GwrTinInterpolator(IIncrementalTin tin, int maxDepth) Construct an interpolator that operates on the specified TIN.

Method Summary

Modifier and Type	Method and Description
String	getMethod()
int	getSampleCount() Gets the number of samples used in the most recent calculation.
double	getSampleDistanceMean() Gets the mean distance of the samples from the most recent interpolation point
Vertex[]	getSampleVertices() Get the samples used in the most recent interpolation.
double	interpolate(double qx, double qy, IVertexValuator valuator) Obtains an interpolated value at the specified coordinates using a Geographically Weighted Linear Regression.
double	interpolate(SurfaceModel model, BandwidthSelectionMethod bandwidthMethod, double bandwidthParameter, double qx, double qy, IVertexValuator valuator) Performs regression using the specified surface model and bandwidth-selection method.
double	interpolateUsingAutomaticModelAndBandwidth(double qx, double qy, IVertexValuator valuator) Perform regression using adaptive bandwidth selection and testing all available models using the AICc criterion.
boolean	isSurfaceNormalSupported()
void	resetForChangeToTin() Used by an application to reset the state data within the interpolator when the content of the TIN may have changed.
boolean	wasTargetExteriorToTin() Indicates that the most recent target coordinates were exterior to the TIN.

Methods inherited from class org.tinfour.gwr.GwrInterpolator

bootstrap, getAICc, getAutomaticBandwidthTestCount, getBandwidth, getBandwidthSelectionMethod, getCoefficients, getEffectiveDegreesOfFreedom, getLeungDelta1, getLeungDelta2, getPredictionInterval, getPredictionIntervalHalfRange, getResiduals, getResidualSumOfTheSquares, getSamples, getSigmaML, getSlope, getStandardDeviation, getSurfaceModel, getSurfaceNormal, getVariance, getWeights, interpolate, interpolateUsingAutomaticModelAndBandwidth

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.tinfour.interpolation.IInterpolatorOverTin

getSurfaceNormal

Constructor Detail

GwrTinInterpolator

public GwrTinInterpolator(IIncrementalTin tin)

Construct an interpolator that operates on the specified TIN. Because the interpolator will access the TIN on a read-only basis, it is possible to construct multiple instances of this class and allow them to operate in parallel threads.

Important Synchronization Issue

In order to provide maximum performance, the classes in this package do not implement any kind of Java synchronization or or even the relatively weak concurrent-modification testing provided by the Java collection classes. If an application modified the TIN, instances of this class will not be aware of the change. In such cases, interpolation methods may fail by either throwing an exception or, worse, returning an incorrect value. The onus is on the calling application to make sure that the reset() methods are called if the TIN has been modified.

Parameters:

tin - a valid instance of an incremental TIN.

GwrTinInterpolator

public GwrTinInterpolator(IIncrementalTin tin,
                          int maxDepth)

Construct an interpolator that operates on the specified TIN. Because the interpolator will access the TIN on a read-only basis, it is possible to construct multiple instances of this class and allow them to operate in parallel threads.

Important Synchronization Issue

In order to provide maximum performance, the classes in this package do not implement any kind of Java synchronization or or even the relatively weak concurrent-modification testing provided by the Java collection classes. If an application modified the TIN, instances of this class will not be aware of the change. In such cases, interpolation methods may fail by either throwing an exception or, worse, returning an incorrect value. The onus is on the calling application to make sure that the reset() methods are called if the TIN has been modified.

Parameters:

tin - a valid instance of an incremental TIN.

maxDepth - the maximum depth of the search for neighboring points

Method Detail

resetForChangeToTin

public void resetForChangeToTin()

Used by an application to reset the state data within the interpolator when the content of the TIN may have changed. Reseting the state data unnecessarily may result in a performance reduction when processing a large number of interpolations, but is otherwise harmless.

Specified by:

resetForChangeToTin in interface IProcessUsingTin

interpolate

public double interpolate(double qx,
                          double qy,
                          IVertexValuator valuator)

Obtains an interpolated value at the specified coordinates using a Geographically Weighted Linear Regression. The interpolation uses the default Cubic surface model and selecting a bandwidth parameter based on one half the average distance of all samples from the query point.

Please see the documentation for IInterpolatorOverTin for more detail.

Specified by:

interpolate in interface IInterpolatorOverTin

Parameters:

qx - the x coordinate for the interpolation point

qy - the y coordinate for the interpolation point

valuator - an optional valuator (supply null if none is required).

Returns:

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

interpolateUsingAutomaticModelAndBandwidth

public double interpolateUsingAutomaticModelAndBandwidth(double qx,
                                                         double qy,
                                                         IVertexValuator valuator)

Perform regression using adaptive 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

valuator - a valid valuator for interpreting the z value of each vertex or a null value to use the default.

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,
                          IVertexValuator valuator)

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 1.0. The model should be selected based on the anticipated behavior of the surface. SurfaceModel.Quadratic is usually a good choice for all but flat surfaces, though QuadraticWithCrossTerms is useful for curvature-related computations.

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

valuator - an optional valuator for interpolation

Returns:

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

getSampleCount

public int getSampleCount()

Gets the number of samples used in the most recent calculation. Intended for diagnostic and analysis purposes.

Returns:

if a valid calculation was performed, a value greater than the number of degrees of freedom for the model that was used.

getSampleVertices

public Vertex[] getSampleVertices()

Get the samples used in the most recent interpolation. Intended for diagnostic and analysis purposes.

Returns:

a valid array, zero sized if no interpolation has been performed.

isSurfaceNormalSupported

public boolean isSurfaceNormalSupported()

Specified by:

isSurfaceNormalSupported in interface IInterpolatorOverTin

getMethod

public String getMethod()

Specified by:

getMethod in interface IInterpolatorOverTin

getSampleDistanceMean

public double getSampleDistanceMean()

Gets the mean distance of the samples from the most recent interpolation point

Returns:

if available, a positive value; if not interpolation has been performed, Double.NaN.

wasTargetExteriorToTin

public boolean wasTargetExteriorToTin()

Indicates that the most recent target coordinates were exterior to the TIN. Set by the most recent interpolation.

Returns:

true if the most recent coordinates were exterior to the TIN; otherwise, false.