Summarize Within (Analysis)

Summary

Overlays a polygon layer with another layer to summarize the number of points, length of the lines, or area of the polygons within each polygon, and calculate attribute field statistics about the features within the polygons.

The following are example scenarios using Summarize Within:

  • From a layer of watershed boundaries and a layer of land-use boundaries by land-use type, calculate total acreage of land-use type for each watershed.
  • From a layer of parcels in a county and a layer of city boundaries, summarize the average value of vacant parcels within each city boundary.
  • From a layer of counties and a layer of roads, summarize the total mileage of roads by road type in each county.

Illustration

Summarize Within tool illustration

Usage

  • Think of Summarize Within as taking two layers, the input polygons and the input summary features, and stacking them on top of each other. After stacking these layers, you can look down through the stack and count the number of input summary features that fall within the input polygons. You can also calculate simple statistics about the attributes of the input summary features, such as sum, mean, minimum, maximum, and so on.

  • The Summarize Within and Summarize Nearby tools are conceptually similar. Using the Summarize Within tool, you can summarize features within existing polygons. Using the Summarize Nearby tool, you can generate areas around points, lines, or polygons, and summarize features within those derived areas.

  • Polygon summary features are summarized using the areal proportions of the input features. Consider an input polygon that overlays a summary polygon by 1 square kilometer. If the summary polygon is 100 square kilometers, the tool will summarize 1/100 of the numeric values of the summary polygon. To ensure that proportional calculations are valid, use fields with counts and quantities rather than rates or ratios.

  • You can create groups by specifying a group field from the input points. For example, if you are summarizing crimes within neighborhood boundaries, you may have a Crime_type attribute with five crime types. Each unique crime type forms a group, and the statistics you choose will be calculated for each unique Crime_type value.

  • Null values are excluded from all statistical calculations. For example, the average of 10, 5, and a null value is 7.5 ((10+5)/2).

Parameters

LabelExplanationData Type
Input Polygons

The polygons that will be used to summarize the features, or portions of features, in the input summary layer.

Feature Layer
Input Summary Features

The point, line, or polygon features that will be summarized for each polygon in the input polygons.

Feature Layer
Output Feature Class

The output polygon feature class containing the same geometries and attributes as the input polygons. The feature class will include additional attributes for the number of points, length of lines, and area of polygons inside each input polygon and statistics about those features.

Feature Class
Keep all input polygons
(Optional)

Specifies whether all input polygons or only those intersecting or containing at least one input summary feature will be copied to the output feature class.

  • Checked—All input polygons will be copied to the output feature class. This is the default.
  • Unchecked—Only input polygons that intersect or contain at least one input summary feature will be copied to the output feature class.
Boolean
Summary Fields
(Optional)

A list of attribute field names from the input summary features, as well as statistical summary types that will be calculated for those attribute fields for all points in each polygon.

Summary fields must be numeric. Text and other attribute field types are not supported.

The following are the statistic types:

  • Sum—The total value of all the points in each polygon will be calculated.
  • Mean—The average or mean value of all the points in each polygon will be calculated.
  • Min—The smallest value of all the points in each polygon will be identified.
  • Max—The largest value of all the points in each polygon will be identified.
  • Stddev—The standard deviation of all the points in each polygon will be calculated.

Value Table
Add shape summary attributes
(Optional)

Specifies whether attributes for the number of points, length of lines, and area of polygon features summarized in each input polygon will be added to the output feature class.

  • Checked—Shape summary attributes will be added to the output feature class. This is the default.
  • Unchecked—Shape summary attributes will not be added to the output feature class.
Boolean
Shape Unit
(Optional)

Specifies the unit that will be used when calculating shape summary attributes. If the input summary features are points, no shape unit is necessary, since only the count of points in each input polygon is added.

If the input summary features are lines, specify a linear unit. If the input summary features are polygons, specify an areal unit.

  • MetersThe unit will be meters.
  • KilometersThe unit will be kilometers.
  • FeetThe unit will be feet.
  • YardsThe unit will be yards.
  • MilesThe unit will be miles.
  • AcresThe unit will be acres.
  • HectaresThe unit will be hectares.
  • Square metersThe unit will be square meters.
  • Square kilometersThe unit will be square kilometers.
  • Square feetThe unit will be square feet.
  • Square yardsThe unit will be square yards.
  • Square milesThe unit will be square miles.
String
Group Field
(Optional)

An attribute field from the input summary features that will be used for grouping. Features that have the same group field value will be combined and summarized with other features with the same group field value.

When a group field is provided, the Output Grouped Table parameter value is required.

Field
Add minority and majority attributes
(Optional)

Specifies whether minority and majority fields will be added to the output. This parameter allows you to determine which group field value is the minority (least dominant) and the majority (most dominant) within each input polygon.

This parameter is active if you provided a Group Field parameter value.

  • Unchecked—Minority and majority fields will not be added to the output. This is the default.
  • Checked—Minority and majority fields will be added to the output.
Boolean
Add group percentages
(Optional)

Specifies whether a percentage attribute field will be added to the output. This parameter allows you to determine the percentage of each attribute value in each group.

This parameter is active if you provided a Group Field parameter value.

  • Unchecked—A percentage attribute field will not be added to the output. This is the default.
  • Checked—A percentage attribute field will be added to the output.
Boolean
Output Grouped Table
(Optional)

An output table that includes summary fields for each group of summary features for each input polygon.

The table will have the following attribute fields:

  • Join_ID—An ID corresponding to an ID field added to the output feature class
  • The group field
  • A shape summary field
  • One field for each summary field
  • A percentage field

This parameter is required when the Group Field parameter value is provided.

Table

arcpy.analysis.SummarizeWithin(in_polygons, in_sum_features, out_feature_class, {keep_all_polygons}, {sum_fields}, {sum_shape}, {shape_unit}, {group_field}, {add_min_maj}, {add_group_percent}, {out_group_table})
NameExplanationData Type
in_polygons

The polygons that will be used to summarize the features, or portions of features, in the input summary layer.

Feature Layer
in_sum_features

The point, line, or polygon features that will be summarized for each polygon in the input polygons.

Feature Layer
out_feature_class

The output polygon feature class containing the same geometries and attributes as the input polygons. The feature class will include additional attributes for the number of points, length of lines, and area of polygons inside each input polygon and statistics about those features.

Feature Class
keep_all_polygons
(Optional)

Specifies whether all input polygons or only those intersecting or containing at least one input summary feature will be copied to the output feature class.

  • KEEP_ALLAll input polygons will be copied to the output feature class. This is the default.
  • ONLY_INTERSECTINGOnly input polygons that intersect or contain at least one input summary feature will be copied to the output feature class.
Boolean
sum_fields
[[summary_field, statistic_type],...]
(Optional)

A list of attribute field names from the input summary features, as well as statistical summary types that will be calculated for those attribute fields for all points in each polygon.

Summary fields must be numeric. Text and other attribute field types are not supported.

The following are the statistic types:

  • Sum—The total value of all the points in each polygon will be calculated.
  • Mean—The average or mean value of all the points in each polygon will be calculated.
  • Min—The smallest value of all the points in each polygon will be identified.
  • Max—The largest value of all the points in each polygon will be identified.
  • Stddev—The standard deviation of all the points in each polygon will be calculated.

Value Table
sum_shape
(Optional)

Specifies whether attributes for the number of points, length of lines, and area of polygon features summarized in each input polygon will be added to the output feature class.

  • ADD_SHAPE_SUMShape summary attributes will be added to the output feature class. This is the default.
  • NO_SHAPE_SUMShape summary attributes will not be added to the output feature class.
Boolean
shape_unit
(Optional)

Specifies the unit that will be used when calculating shape summary attributes. If the input summary features are points, no shape unit is necessary, since only the count of points in each input polygon is added.

If the input summary features are lines, specify a linear unit. If the input summary features are polygons, specify an areal unit.

  • METERSThe unit will be meters.
  • KILOMETERSThe unit will be kilometers.
  • FEETThe unit will be feet.
  • YARDSThe unit will be yards.
  • MILESThe unit will be miles.
  • ACRESThe unit will be acres.
  • HECTARESThe unit will be hectares.
  • SQUAREMETERSThe unit will be square meters.
  • SQUAREKILOMETERSThe unit will be square kilometers.
  • SQUAREFEETThe unit will be square feet.
  • SQUAREYARDSThe unit will be square yards.
  • SQUAREMILESThe unit will be square miles.
String
group_field
(Optional)

An attribute field from the input summary features that will be used for grouping. Features that have the same group field value will be combined and summarized with other features with the same group field value.

When a group field is provided, the out_grouped_table parameter value is required.

Field
add_min_maj
(Optional)

Specifies whether minority and majority fields will be added to the output. This parameter allows you to determine which group field value is the minority (least dominant) and the majority (most dominant) within each input polygon.

This parameter is enabled if you provided a group_field parameter value.

  • NO_MIN_MAJMinority and majority fields will not be added to the output. This is the default.
  • ADD_MIN_MAJMinority and majority fields will be added to the output.
Boolean
add_group_percent
(Optional)

Specifies whether a percentage attribute field will be added to the output. This parameter allows you to determine the percentage of each attribute value in each group.

This parameter is enabled if you provided a group_field parameter value.

  • NO_PERCENTA percentage attribute field will not be added to the output. This is the default.
  • ADD_PERCENTA percentage attribute field will be added to the output.
Boolean
out_group_table
(Optional)

An output table that includes summary fields for each group of summary features for each input polygon.

The table will have the following attribute fields:

  • Join_ID—An ID corresponding to an ID field added to the output feature class
  • The group field
  • A shape summary field
  • One field for each summary field
  • A percentage field

This parameter is required when the group_field parameter value is provided.

Table

Code sample

SummarizeWithin example 1 (Python window)

The following Python window script demonstrates how to use the SummarizeWithin function.

import arcpy
arcpy.env.workspace = 'C:/data/city.gdb'
arcpy.analysis.SummarizeWithin('neighborhoods', 'crimes', 'neighborhood_crimes')
SummarizeWithin example 2 (stand-alone script)

The following stand-alone script is an example of how to use the SummarizeWithin function in a scripting environment.

# Description: Use SummarizeWithin to summarize the crimes in each city neighborhood

# import system modules 
import arcpy

# Set environment settings
arcpy.env.workspace = 'C:/data/city.gdb'

#  Set local variables
polys = 'neighborhoods'
points = 'crimes'
outFeatureClass = 'crimes_aggregated'
keepAll = 'KEEP_ALL'
sumFields = [['Damages', 'SUM'], ['VICTIM_AGE', 'MEAN']]
addShapeSum = 'ADD_SHAPE_SUM'
groupField = 'Crime_type'
addMinMaj = 'ADD_MIN_MAJ'
addPercents = 'ADD_PERCENT'
outTable = 'crimes_aggregated_groups'

arcpy.analysis.SummarizeWithin(polys, points, outFeatureClass, keepAll, 
                               sumFields, addShapeSum, '', groupField, 
                               addMinMaj, addPercents, outTable)

Licensing information

  • Basic: Yes
  • Standard: Yes
  • Advanced: Yes

Related topics