- URL:https://<geoanalytics-url>/BuildMultiVariableGrid
- Version Introduced:10.6.1
Description
The BuildMultiVariableGrid operation works with one or more layers of point, line, or polygon features. The task generates a grid of square or hexagonal bins and compiles information about each input layer into each bin. For each input layer, this information can include the following variables:
- DistanceToNearest—The distance from each bin to the nearest feature.
- AttributeOfNearest—An attribute value of the feature nearest to each bin.
- AttributeSummaryOfRelated—A statistical summary of all features within searchDistance of each bin.
Only variables you specify in variableCalculations will be included in the result layer. These variables can help you understand the proximity of your data throughout the extent of your analysis. The results can help you answer questions such as the following:
- Given multiple layers of public transportation infrastructure, what part of the city is least accessible by public transportation?
- Given layers of lakes and rivers, what is the name of the water body closest to each location in the United States?
- Given a layer of household income, where in the United States is the variation of income greatest in the surrounding 50 miles?
The result of BuildMultiVariableGrid can also be used in prediction and classification workflows. The task allows you to calculate and compile information from many different data sources into a single, spatially continuous layer in one step. This layer can then be used with the EnrichFromMultiVariableGrid operation to quickly enrich point features with the variables you have calculated, reducing the amount of effort required to build prediction and classification models from point data.
Request parameters
Parameter | Details |
---|---|
binType (Required) | The type of bin that will be used to generate the result grid. Analysis using Square or Hexagon bins requires a projected coordinate system. When aggregating layers into bins, the input layer or processing extent (processSR) must have a projected coordinate system. At 10.5.1, 10.6, and 10.6.1, if a projected coordinate system is not specified when running analysis, the World Cylindrical Equal Area (WKID 54034) projection will be used. At 10.7 or later, if a projected coordinate system is not specified when running analysis, a projection will be picked based on the extent of the data. Values: Hexagon | Square (default) REST examples
|
binSize (Required) | The distance for the bins of type binType in the output polygon layer. variableCalculations will be calculated at the center of each bin. When generating Square bins, the number and units specified determine the height and length of the square. For Hexagon bins, the number and units specified determine the distance between parallel sides. REST examples
|
binSizeUnit (Required) | The distance unit for the bins will be used to calculate variableCalculations. Values: Meters | Kilometers | Feet | FeetInt | FeetUS | Miles | MilesInt | MilesUS | NauticalMiles | NauticalMilesInt | NauticalMilesUS | Yards | YardsInt | YardsUS REST examples
|
inputLayers (Required) | A list of input layers that will be used in analysis. Each input layer follows the same formatting as described in the Feature Input topic. This can be one of the following:
In the REST web example for inputLayers below, two layers are being used in analysis. The layer at index 0 will be filtered to only use features where OID > 2. REST web example |
variableCalculations (Required) | A JSON array containing objects that describe the variables that will be calculated for each layer in inputLayers. |
outputName (Required) | The task will create a feature service of the results. You define the name of the service. REST examples
|
context (Optional) | The context parameter contains additional settings that affect task execution. For this task, there are four settings:
|
f | The response format. The default response format is html. Values: html | json |
variableCalculations syntax and examples
The following sections outline how to populate the variableCalculations parameter and examples.
variableCalculations syntax
In the syntax example below, layer is the index of the layer in inputLayers that will be used to calculate the specified variables; variables are an array of JSON objects that describe the variables you want to include in the result layer and must contain at least one variable for each layer; and type can be one of the following variable types:
- DistanceToNearest
- AttributeOfNearest
- AttributeSummaryOfRelated
Each type must be configured with a unique set of parameters, defined in the table below:
Parameter | Details |
---|---|
outFieldName | The name of the field that will be created in the result layer to store a variable. |
searchDistance | Defines the maximum distance that the tool will search from the center of each bin to find a feature in the layer for DistanceToNearest and AttributeOfNearest. If no feature is within the distance, null is returned. For AttributeOfSummaryRelated, searchDistance is optional and defines the radius of a circular neighborhood surrounding each bin. All features that intersect this neighborhood will be used to calculate statisticType. If a distance is not defined, only features that intersect a bin will be used to calculate statisticType. |
searchDistanceUnit | Defines the maximum distance unit that the tool will search from the center of each bin to find a feature in the layer for DistanceToNearest and AttributeOfNearest. If no feature is within the distance, null is returned. For AttributeOfSummaryRelated, searchDistance is optional and defines the radius of a circular neighborhood surrounding each bin. All features that intersect this neighborhood will be used to calculate statisticType. If a distance is not defined, only features that intersect a bin will be used to calculate statisticType. |
attributeField | The name of a field in the input layer. The value of this field in the closest feature to each bin will be included in the result layer. Required by AttributeOfNearest. |
statisticField | The name of a field in the input layer. The field's values will be used to calculate statisticType. Required by AttributeSummaryOfRelated. |
statisticType | Required by AttributeSummaryOfRelated. Can be defined as one of the following types:
|
filter | Optional for all variable types. This is formatted as described in the Feature Input topic. |
Syntax example
[
{
"layer":<index>,
"variables":[
{
"type":"DistanceToNearest",
"outFieldName":"<output field name>",
"searchDistance":<number>,
"searchDistanceUnit":"<unit>",
"filter":"<filter>"
},
{
"type":"AttributeOfNearest",
"outFieldName":"<output field name>",
"attributeField":"<field name>",
"searchDistance":<number>,
"searchDistanceUnit":"<unit>",
"filter":"<filter>"
},
{
"type":"AttributeSummaryOfRelated",
"outFieldName":"<output field name>",
"statisticType":"<statistic type>",
"statisticField":"<field name>",
"searchDistance":<number>,
"searchDistanceUnit":"<unit>",
"filter":"<filter>"
},
...
]
},
...
]
variableCalculations examples
In the REST web example for variableCalculations below, two variables are calculated for the layer at index 0 of the inputLayers list. distance_to_nearest_hurricane is the distance from each bin center to the nearest feature where type = "hurricane", and rating_of_nearest_hurricane is the value of field storm_rating in the nearest feature to each bin center. A variable named mean_wind_speed is calculated for the layer at index 1 of the inputLayers list; it is the mean value of field wind_speed in all features within a 20-mile radius of each bin center. All three variables are stored in the attribute table of the output layer.
REST web example for variableCalculations[
{
"layer":0,
"variables":[
{
"type":"DistanceToNearest",
"outFieldName":"distance_to_nearest_hurricane",
"searchDistance":100,
"searchDistanceUnit":"Miles",
"filter":"type = "hurricane""
},
{
"type":"AttributeOfNearest",
"outFieldName":"rating_of_nearest_hurricane",
"attributeField":"storm_rating",
"searchDistance":100,
"searchDistanceUnit":"Miles"
}
]
},
{
"layer":1,
"variables":[
{
"type":"AttributeSummaryOfRelated",
"outFieldName":"mean_wind_speed",
"statisticType":"mean",
"statisticField":"wind_speed",
"searchDistance":20,
"searchDistanceUnit":"Miles"
}
]
}
]
In the REST scripting example for variableCalculations below, two variables are calculated for the layer at index 0 of the inputLayers list. The variable distance_to_nearest_hurricane is the distance from each bin center to the nearest feature where type = "hurricane", and distance_to_nearest_trop_storm is the equivalent variable where type = "tropical storm". Both are stored in the attribute table of the output layer.
REST scripting example for variableCalculations"variableCalculations":"[
{
"layer":0,
"variables":[
{
"type":"DistanceToNearest",
"outFieldName":"distance_to_nearest_hurricane",
"searchDistance":100,
"searchDistanceUnit":"Miles",
"filter":"type = "hurricane""
},
{
"type":"DistanceToNearest",
"outFieldName":"distance_to_nearest_trop_storm",
"searchDistance":100,
"searchDistanceUnit":"Miles",
"filter":"type = "tropical storm""
}
]
}
]"
Example usage
Below is a sample request URL for BuildMultiVariableGrid:
https://hostname.domain.com/webadaptor/rest/services/System/GeoAnalyticsTools/GPServer/BuildMultiVariableGrid/submitJob?inputLayer={"url":"https://hostname.domain.com/webadaptor/rest/services/Hurricane/hurricaneTrack/0"}&bintype=Hexagon&binSize=108.3&binSizeUnit=Meters&variableCalculations=[{"layer":0,"variables":[{"type":"DistanceToNearest","outFieldName":"distance_to_nearest_hurricane","searchDistance":100,"searchDistanceUnit":"Miles","filter":"type = "hurricane""},{"type":"DistanceToNearest","outFieldName":"distance_to_nearest_trop_storm","searchDistance":100,"searchDistanceUnit":"Miles","filter":"type = "tropical storm""}]}]&outputName=myOutput&context={"extent":{"xmin":-122.68,"ymin":45.53,"xmax":-122.45,"ymax":45.6,"spatialReference":{"wkid":4326}}}&f=json
Response
When you submit a request, the service assigns a unique job ID for the transaction.
{
"jobId": "<unique job identifier>",
"jobStatus": "<job status>"
}
After the initial request is submitted, you can use jobId to periodically check the status of the job and messages as described in Check job status. Once the job has successfully completed, use jobId to retrieve the results. To track the status, you can make a request of the following form:
https://<analysis url>/BuildMultiVariableGrid/jobs/<jobId>
Access results
When the status of the job request is esriJobSucceeded, you can access the results of the analysis by making a request of the following form:
https://<analysis-url>/BuildMultiVariableGrid/jobs/<jobId>/results/output?token=<your token>&f=json
Response | Description |
---|---|
output |
The result output will always contain polygon features. The number of resulting polygons is based on binSize, variableCalculations, and the extent of the input data. The layer will only contain the variables specified in variableCalculations. The result has properties for parameter name, data type, and value. The contents of value depend on the outputName parameter provided in the initial request. The value contains the URL of the feature service layer. See Feature output for more information about how the result layer is accessed. |