Summarize Within

Summarize Within

The Summarize Within task finds features (and portions of features) that are within the boundaries of areas in the first input layer. The following are examples:

You can think of Summarize Within as taking two layers and stacking them on top of each other. One of the layers, summaryPolygons, must be a polygon layer, and imagine that these polygon boundaries are all colored red. The other layer, summarizedLayer, can be any feature type—point, line, or polygon. After stacking these layers on top of each other, you peer down through the stack and count the number of features in summarizedLayer that fall within the polygons with the red boundaries (summaryPolygons). Not only can you count the number of features, you can calculate simple statistics about the attributes of the features in summarizedLayer, such as sum, mean, minimum, maximum, and so on.

Request URL

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

Request parameters

Parameter

Description

summaryPolygons

(Required if binType is not specified)

The polygon features. Features, or portions of features, in summarizedLayer (below) that fall within the boundaries of these polygons will be summarized. You can choose to summarize within a polygon layer that you provide or within square or hexagon bins that are generated when the tool runs.

Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:

  • A URL to a feature service layer with an optional filter to select specific features
  • A URL to a big data catalog service layer with an optional filter to select specific features
  • A feature collection

Examples:

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

summarizedLayer

(Required)

Point, line, or polygon features that will be summarized for each polygon in summaryPolygons or bins.

Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:

  • A URL to a feature service layer with an optional filter to select specific features
  • A URL to a big data catalog service layer with an optional filter to select specific features
  • A feature collection

binType

(Required if summaryPolygons is not specified)

The type of bin that will be generated and summarizedLayer will be summarized into. Bin options are the following:

  • Hexagon.
  • Square—This is the default.
Either binType or sumWithinLayer must be specified. If binType is chosen, then binSize and binSizeUnit—specifying the size of the bin—must be included.

Example: "binType": "Square"

NoteNote:

Analysis using square or hexagon bins requires a projected coordinate system. When aggregating layers into bins, it is required that the input layer or processing extent (processSR) has a projected coordinate system. At 10.5.1, if a projected coordinate system is not specified when running analysis the World Cylindrical Equal Area (wkid 54034) projection will be used.

binSize

(Required if binType is specified)

The distance for the bins of type binType. When generating bins, for Square, the number and units specified determine the height and length of the square, and for Hexagon, the number and units specified determine the distance between parallel sides.

Example: "binSize": 100

binSizeUnit

(Required if binSize is specified)

The linear distance unit for the bins that summaryLayer will be summarized into.

The default is Meters.

Values: Meters | Kilometers | Feet | Miles | NauticalMiles | Yards

Example: "binSizeUnit" : "Miles"

standardSummaryFields

A list of field names and statistical summary type that you want to calculate for all features in summaryLayer that are within each polygon in sumWithinLayer or bins. The standard statistics are calculated using the whole attribute values from any feature that is within summaryPolygon.

Syntax: [{"statisticType" : "<statistic type>", "onStatisticField" : "<field name>" }, ...]

fieldName is the name of the fields found in the input point layer.

statisticType is one of the following for numeric fields:

  • Count—Totals the number of features in each polygon.
  • Sum—Adds the total value of all the features in each polygon.
  • Mean—Calculates the average of all the features in each polygon.
  • Min—Finds the smallest value of all the features in each polygon.
  • Max—Finds the largest value of all the features in each polygon.
  • Range—Finds the difference between Min and Max.
  • Stddev—Finds the standard deviation of all the features in each polygon.
  • Var—Finds the variance of all the features in each polygon.

statisticType is one of the following for string fields:

  • Count—Totals the number of strings for all the features in each polygon.
  • Any—Returns a sample string of a feature in each polygon.

Example: "standardSummaryFields" : [{"statisticType" : "Mean", "onStatisticField" : "Annual_Sales"},{"statisticType": "Sum", "onStatisticField": "Annual_Sales"}]

weightedSummaryFields

A list of field names and statistical summary type that you want to calculate for all features in summarizedLayer that are within each polygon in summaryPolygon or bins. The weighted statistics are calculated using the geographically weighted attribute values from features that are within summaryPolygon. Resulting fields from proportional statistics will be denoted with a p. Weighted statistics can only be applied to summarizedLayer that are lines or polygons.

Syntax: [{"statisticType" : "<statistic type>", "onStatisticField" : "<field name>" }, ...]

fieldName is the name of the fields found in the input point layer.

statisticType is one of the following for numeric fields:

  • Count—The count of each field multiplied by the proportion of the summarized layer within the polygons.
  • Sum—The sum of weighted of values in each field. Where the weight applied is the proportion of the summarized layer within the polygons.
  • Mean—The weighted mean of values in each field. Where the weight applied is the proportion of the summarized layer within the polygons.
  • Min—The minimum of weighted values in each field. Where the weight applied is the proportion of the summarized layer within the polygons.
  • Max—The maximum of weighted values in each field. Where the weight applied is the proportion of the summarized layer within the polygons.
  • Range—Finds the difference between Min and Max.

Example: "weightedSummaryFields" : [{"statisticType" : "Mean", "onStatisticField" : "Annual_Sales"},{"statisticType": "Sum", "onStatisticField": "Annual_Sales"}]

sumShape

A Boolean value that instructs the task to calculate statistics based on the shape type of summaryLayer, such as the length of lines or areas of polygons of summaryLayer within each polygon in sumWithinLayer. The default is true.

Values: true | false

sumUnits

The units used to calculate sumShape.

Values:

  • When summaryLayer contains polygons: Acres | Hectares | SquareMeters | SquareKilometers | SquareMiles | SquareYards | SquareFeet
  • When summaryLayer contains lines: Meters | Kilometers | Feet | Yards | Miles

Example: "shapeUnits": "Hectares"

outputName

(Required)

The task will create a feature service of the results. You define the name of the service.

Example: "outputName" : "myOutput"

context

Context contains additional settings that affect task execution. For this task, there are three settings:

  • Extent (extent)—A bounding box that defines the analysis area. Only those features that intersect the bounding box will be analyzed.
  • Processing spatial reference (processSR)—The features will be projected into this coordinate system for analysis.
  • Output spatial reference (outSR)—The features will be projected into this coordinate system after the analysis to be saved. The output spatial reference for the spatiotemporal big data store is always WGS84.
  • Data store (dataStore)— Results will be saved to the specified data store. The default is the spatiotemporal big data store.

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 jobId to periodically check the status of the job and messages as described in Checking job status. Once the job has successfully completed, use the jobId to retrieve the results. To track the status, you can make a request of the following form:

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

Accessing 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:

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

Parameter

Description

output

The polygon features of summaryPolygon or the bins generated when running the tool with summary statistics and weighted summary statistics about the features in summarizedLayer that fall within each polygon. Proportional statistics fields are denoted with a p.

Example:
{"url": 
"http://<analysis url>/SummarizeWithin/jobs/<jobId>/results/output"}

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.

{
"paramName":"output", 
"dataType":"GPRecordSet",
"value":{"url":"<hosted featureservice layer url>"}
}

See Feature output for more information about how the result layer is accessed.

7/5/2017