Interpolate Points

Interpolate Points

The Interpolate Points task allows you to predict values at new locations based on measurements from a collection of points. The task takes point data with values at each point and returns areas classified by predicted values. For example

  • An air quality management district has sensors that measure pollution levels. Interpolate Points can be used to predict pollution levels at locations that don't have sensors, such as locations with at-risk populations—schools or hospitals, for example.
  • Predict heavy metal concentrations in crops based on samples taken from individual plants.
  • Predict soil nutrient levels (nitrogen, phosphorus, potassium, and so on) and other indicators (such as electrical conductivity) in order to study their relationships to crop yield and prescribe precise amounts of fertilizer for each location in the field.
  • Meteorological applications include prediction of temperatures, rainfall, and associated variables (such as acid rain).

Interpolate Points uses the Empirical Bayesian Kriging geoprocessing tool to perform the interpolation. The parameters that are supplied to the Empirical Bayesian Kriging tool are controlled by the interpolateOption request parameter.

If a value of 1 is provided for interpolateOption, empirical Bayesian kriging will use the following parameters:

  • transformation_typeNONE
  • semivariogram_model_typePOWER
  • max_local_points—50
  • overlap_factor—1
  • number_semivariograms—30
  • nbrMin—8
  • nbrMax—8

If a value of 5 is provided for interpolateOption, empirical Bayesian kriging will use the following parameters:

  • transformation_typeNONE
  • semivariogram_model_typePOWER
  • max_local_points—75
  • overlap_factor—1.5
  • number_semivariograms—100
  • nbrMin—10
  • nbrMax—10

If a value of 9 is provided for interpolateOption, empirical Bayesian kriging will use the following parameters:

  • transformation_typeEMPIRICAL
  • semivariogram_model_typeK_BESSEL
  • max_local_points—200
  • overlap_factor—3
  • number_semivariograms—200
  • nbrMin—15
  • nbrMax—15

Request URL

http://<analysis url>/InterpolatePoints/submitJob

Request Parameters

ParameterDescription

inputLayer

(Required)

The point features that will be interpolated.

Syntax: As described in detail in the Feature Input topic, this parameter can be

  • a URL to a feature service layer with an optional filter to select specific features, or
  • a feature collection.

Examples:

  • {"url": <feature service layer url>, "filter": <where clause>}
  • {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

field

(Required)

Name of the numeric field containing the values you wish to interpolate.

interpolateOption

Integer value declaring your preference for speed versus accuracy, from 1 (fastest) to 9 (most accurate). More accurate predictions take longer to calculate.

The default is 5.

Values: 1 | 5 | 9

outputPredictionError

If True, a polygon layer of standard errors for the interpolation predictions will be returned in the predictionError output parameter.

Standard errors are useful because they provide information about the reliability of the predicted values. A simple rule of thumb is that the true value will fall within two standard errors of the predicted value 95 percent of the time. For example, suppose a new location gets a predicted value of 50 with a standard error of 5. This means that this task's best guess is that the true value at that location is 50, but it reasonably could be as low as 40 or as high as 60. To calculate this range of reasonable values, multiply the standard error by 2, add this value to the predicted value to get the upper end of the range, and subtract it from the predicted value to get the lower end of the range.

Values: True | False

classificationType

Determines how predicted values will be classified into areas:

  • EqualArea—Polygons are created such that the number of data values in each area is equal. For example, if the data has more large values than small values, more areas will be created for large values.
  • EqualInterval—Polygons are created such that the range of predicted values is equal for each area.
  • GeometricInterval—Polygons are based on class intervals that have a geometrical series. This method ensures that each class range has approximately the same number of values within each class and that the change between intervals is consistent.
  • Manual—You to define your own range of values for areas. These values will be entered in the classBreaks parameter below.

The default value is GeometricInterval.

Example: "classificationType": "EqualArea"

numClasses

This value is used to divide the range of interpolated values into distinct classes. The range of values in each class is determined by the classificationType parameter. Each class defines the boundaries of the result polygons.

The default is 10. The maximum value is 32.

Example: "numClasses": "20"

classBreaks

If classificationType is Manual, supply desired class break values as a list. These values define the upper limit of each class, so the number of classes will equal the number of entered values. Areas will not be created for any locations with predicted values above the largest entered break value. You must enter at least two values and no more than 32.

Example: "classBreaks": [0.5, 1.5, 3, 7]

boundingPolygonLayer

A layer specifying the polygon(s) where you want values to be interpolated. For example, if you are interpolating densities of fish within a lake, you can use the boundary of the lake in this parameter and the output will only contain polygons within the boundary of the lake.

Syntax: As described in detail in the Feature Input topic, this parameter can be

  • a URL to a feature service layer with an optional filter to select specific features, or
  • a feature collection.

predictAtPointLayer

An optional layer specifying point locations to calculate prediction values. This allows you to make predictions at specific locations of interest. For example, if the inputLayer represents measurements of pollution levels, you can use this parameter to predict the pollution levels of locations with large at-risk populations, such as schools or hospitals. You can then use this information to give recommendations to health officials in those locations.

If supplied, the output predictedPointLayer will contain predictions at the specified locations.

Syntax: As described in detail in the Feature Input topic, this parameter can be

  • a URL to a feature service layer with an optional filter to select specific features, or
  • a feature collection.

outputName

If provided, the task will create a feature service of the results. You define the name of the service. If outputName is not supplied, the task will return a feature collection.

Syntax:
{
  "serviceProperties": {
    "name": "<service name>"
  }
}

context

Context contains additional settings that affect task execution. For Interpolate Points, there are two settings.

  1. Extent (extent)—a bounding box that defines the analysis area. Only those points in the input inputLayer that intersect the bounding box will be analyzed.
  2. Output Spatial Reference (outSR)—the output features will be projected into the output spatial reference.

Syntax:
{
"extent" : {extent}
"outSR" : {spatial reference}
}

f

The response format. The default response format is html.

Values: html | json

Response

When you submit a request, the service assigns a unique job ID for the transaction.

Syntax:
{
"jobId": "<unique job identifier>",
"jobStatus": "<job status>"
}

After the initial request is submitted you can use the jobId to periodically check the status of the job and messages as described in the topic Checking job status. Once the job has successfully completed, you use the jobId to retrive the results. To track the status, you can make a request of the following form:

http://<analysis url>/InterpolatePoints/jobs/<jobId>

Accessing results

When the status of the job request is esriJobSucceded, you can access the results of the analysis by making a request of the following form:

http://<analysis url>/InterpolatePoints/jobs/<jobId>/results/<output parameter name>?token=<your token>&f=json

ParameterDescription

resultLayer

These are polygon features where each polygon surrounds interpolated values based on the classificationType and numClasses.

The result polygon features has the following attributes:

  • Classes—The class break of the polygon as defined by numClasses, zero based.
  • Value_Min—the minimum interpolated value of the polygon.
  • Value_Max—the maximum interpolated value of the polygon.
  • AnalysisArea—the area of the polygon in the units specified in your profile, which will either be square miles or square kilometers.

Request example:
{"url": 
"http://<analysis url>/InterpolatePoints/jobs/<jobId>/results/resultLayer"}

The result has properties for parameter name, data type, and value. The contents of value depends upon the outputName parameter provided in the initial request.

  • If outputName was provided, value contains the url to the feature service layer.
    {
    "paramName":"resultLayer", 
    "dataType":"GPString",
    "value":{"url":"<hosted featureservice layer url>"}
    }
  • If outputName was not provided, value contains a feature collection.
    {
    "paramName":"resultLayer",
    "dataType":"GPString",
    "value":{"layerDefinition": {}, "featureSet": {}  }
    }

See Feature Output for more information about how the result layer or collection is accessed.

predictionError

Contains the predicted error for each point in the inputLayer.

The output has the following fields:

  • Classes—The class break of the polygon as defined by numClasses, starting a zero.
  • Value_Min—The lower bound of the standard errors in the polygon.
  • Value_Max—The upper bound of the standard errors in the polygon.

Request example:

{"url": 
"http://<analysis url>/InterpolatePoints/jobs/<jobId>/results/predictionError
"}

The result has properties for parameter name, data type, and value. The contents of value depends upon the outputName parameter provided in the initial request.

  • If outputName was provided, value contains the url to the feature service layer.
    {
    "paramName":"predictionError", 
    "dataType":"GPString",
    "value":{"url":"<hosted featureservice table url>"}
    }
  • If outputName was not provided, value contains a feature collection.
    {
    "paramName":"predictionError",
    "dataType":"GPString",
    "value":{"layerDefinition": {}, "featureSet": {}  }
    }

See Feature Output for more information about how the group summary table is accessed.

predictedPointLayer

Point layer containing points from the predictAtPointLayer along with their predicted values.

Output fields are:

  • Included—contains "Yes" if a predicted value for the point could be found. If a value could not be found, the field value will be a string describing the issue.
  • Predicted—The interpolated value at the point.
  • StdError—The standard error of the interpolated value.

Request example:

{"url": 
"http://<analysis url>/InterpolatePoints/jobs/<jobId>/results/predictedPointLayer
"}

The result has properties for parameter name, data type, and value. The contents of value depends upon the outputName parameter provided in the initial request.

  • If outputName was provided, value contains the url to the feature service layer.
    {
    "paramName":"predictedPointLayer", 
    "dataType":"GPString",
    "value":{"url":"<hosted featureservice table url>"}
    }
  • If outputName was not provided, value contains a feature collection.
    {
    "paramName":"predictedPointLayer",
    "dataType":"GPString",
    "value":{"layerDefinition": {}, "featureSet": {}  }
    }

See Feature Output for more information about how the group summary table is accessed.