Summarize Within

Description

Summarize Within

The SummarizeWithin operation find 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 SummarizeWithin 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 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 summarizeLayer, such as sum, mean, minimum, maximum, and so on.

Request parameters

Parameter

Details

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 of hexagon bins that are generated when the tool runs.

Syntax: As described in Feature input, 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

REST Examples

//REST web example
{"url": "https://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/0", "filter": "Month = 'September'"}

//REST scripting example
"summaryPolygons": {"url": "https://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/0", "filter": "Month = 'September'"}
binType

(Required if summaryPolygons is not specified)

The type of bin that will be generated and summarizedLayer will be summarized into. 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)

NoteNote:

Either binType or sumWithinLayer must be specified. If binType is chosen, then binSize and binSizeUnit must be included.

REST Examples

//REST web example
Hexagon

//REST scripting example
"binType": Square
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.

REST Examples

//REST web example
108.3

//REST scripting example
"binSize": 100
binSizeUnit

(Required if binSize is specified)

The linear distance unit for the bins that summaryLayer will be summarized into. The default value is Meters.

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

REST Examples

//REST web example
Meters

//REST scripting example
"binSizeUnit": "Miles"
summarizeLayer

(Required)

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

Syntax: As described in Feature input, 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

REST Examples

//REST web example
{"url": "https://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/0", "filter": "Month = 'September'"}

//REST scripting example
"summaryPolygons": {"url": "https://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/0", "filter": "Month = 'September'"}
standardSummaryFields

(Optional)

A list of field names and statistical summary types you want to calculate. Note that the count is always returned. By default, all statistics are returned.

onStatisticField specifies the name of the fields in the target layer. statisticType is one of the following for numeric fields:

  • Count—For numeric fields, this totals the number of values of all the points in each polygon. For string fields, this totals the number of strings for all the points in each polygon.
  • Sum—Adds the total value of all the points in each polygon. For numeric fields.
  • Mean—Calculates the average of all the points in each polygon. For numeric fields.
  • Max—Calculates the largest value of all the points in each polygon. For numeric fields.
  • Range—Finds the difference between the Min and Max values. For numeric fields.
  • Stddev—Finds the standard deviation of all the points in each polygon. For numeric fields.
  • Var—Finds the variance of all the points in each polygon. For numeric fields.
  • Any—Returns a sample string of a point in each polygon. For string fields.

REST Examples

//REST web example
[{"statisticType": "Mean", "onStatisticField": "Annual_Sales"},{"statisticType": "Sum", "onStatisticField": "Annual_Sales"}]

//REST scripting example
"summaryFields": [{"statisticType": "Mean", "onStatisticField": "Annual_Sales"},{"statisticType": "Sum", "onStatisticField": "Annual_Sales"}]

//Only return Count
"summaryFields": []
weightedSummaryFields

(Optional)

A list of field names and the statistical summary types 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.

statisticType can be defined as one of the following:

  • Count—For numeric fields, this totals the number of features in each polygon. For string fields, this totals the number of strings for all the features in each polygon.
  • Sum—Adds the total value of all the features in each polygon. For numeric fields.
  • Mean—Calculates the average of all the features in each polygon. For numeric fields.
  • Min—Finds the smallest value of all the features in each polygon. For numeric fields.
  • Max—Finds the largest value of all the features in each polygon. For numeric fields.
  • Range—Finds the difference between Min and Max. For numeric fields.
  • Stddev—Finds the standard deviation of all the features in each polygon. For numeric fields. At 10.9.1 or later.
  • Var—Finds the variance of all the features in each polygon. For numeric fields. At 10.9.1 or later.

REST Examples

//REST web example
[{"statisticType": "Mean", "onStatisticField":"Annual_Sales"},{"statisticType":"Sum", "onStatisticField": "Annual_Sales"}]

//REST scripting example
"weightedSummaryFields": [{"statisticType": "Mean", "onStatisticField": "Annual_Sales"},{"statisticType": "Sum", "onStatisticField": "Annual_Sales"}]
sumShape

(Optional)

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

shapeUnits

(Optional)

The units used to calculate sumShape. The available values for this parameter vary depending on the whether the summaryLayer contains polygons or lines.

If summaryLayer contains polygons, available values are: Acres | Hectares | SquareMeters | SquareKilometers | SquareMiles | SquareYards | SquareFeet

If summaryLayer contains lines, available values are: Meters | Kilometers | Feet | Yards | Miles

REST Examples

//REST web example
SquareMeters

//REST scripting example
"shapeUnits": "Hectares"
groupByField

(Optional)

Introduced at 10.6.1. This is a field of the summarizedLayer features that you can use to calculate statistics separately for each unique attribute value. For example, suppose the sumWithinLayer contains city boundaries and the summaryPolygons features are parcels. One of the fields of the parcels is Status which contains two values: VACANT and OCCUPIED. To calculate the total area of vacant and occupied parcels within the boundaries of cities, use Status as the groupByField field. When a groupByField parameter is provided, the service returns a table containing the statistics in the groupBySummary output parameter.

REST Examples

//REST web example
Status

//REST scripting example
"groupsByField": "Status"
minorityMajority

(Optional)

Introduced at 10.6.1. This Boolean parameter is applicable only when a groupByField is specified. If true, the minority (least dominant) or the majority (most dominant) attribute values for each group field are calculated. Two new fields are added to the resultLayer prefixed with Majority_ and Minority_. The default value is false.

Values: true | false

percentShape

(Optional)

Introduced at 10.6.1. This Boolean parameter is applicable only when a groupByField is specified. If set to true, the percentage of each unique groupByField value is calculated for each sumWithinLayer polygon. The default is false.

Values: true | false

outputName

(Required)

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

REST Examples

//REST web example
myOutput

//REST scripting example
"outputName": "myOutput"
context

(Optional)

The context parameter contains additional settings that affect task execution. For this task, there are four 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.

Syntax:
{
"extent" : {extent},
"processSR" : {spatial reference},
"outSR" : {spatial reference},
"dataStore":{data store}
}

f

The response format. The default response format is html.

Values: html | json

Example usage

Below is a sample request URL for SummarizeWithin:

https://webadaptor.domain.com/server/rest/services/System/GeoAnalyticsTools/GPServer/SummarizeWithin/submitJob?summaryPolygons={"url": "https://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/0" "filter":"Month = 'Septemner'"}&binType=Hexagon&binSize=108.3&binSizeUnit=Meters&summarizeLayer={"url":"https://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/1" "filter":"City = 'Corpus Christi'"}&sumShape=true&shapeUnits=SquareMeters&outputName=myOutput&f=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 jobId to retrieve the results. To track the status, you can make a request of the following form:

https://<analysis url>/SummarizeWithin/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>/SummarizeWithin/jobs/<jobId>/results/<response type>?token=<your token>&f=json

Response

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.

{"url": "https://<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.

groupBySummary

If a groupByField field was provided as input, the result will have a groupBySummary table that contains the calculated statistics for each unique group. Tables are simply a subset of features; that is, they contain attributes but no geometry.

{"url": "https://<analysis-url>/SummarizeWithin/jobs/<jobId>/results/groupBySummary"}

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":" groupBySummary", 
  "dataType":"GPRecordSet",
  "value":{"url":"<hosted featureservice layer url>"}
}

Copyright © 1995-2021 Esri. All rights reserved.