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 those features within the polygons.

Example scenarios using Summarize Within:

  • Given 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.
  • Given a layer of parcels in a county and a layer of city boundaries, summarize the average value of vacant parcels within each city boundary.
  • Given a layer of counties and a layer of roads, summarize the total mileage of roads by road type within each county.

Illustration

Summarize Within

Usage

  • You can 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 peer down through the stack and count the number input summary features that fall within the input polygons. Not only can you count the number of features, you can 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 the same. With the Summarize Within tool you can summarize features within existing polygons, whereas with the Summarize Nearby tool you can generate areas around points, lines, or polygons, and summarize features within those derived areas.

  • 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 an attribute Crime_type with five different crime types. Each unique crime type forms a group, and the statistics you choose will be calculated for each unique value of Crime_type.

Syntax

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})
ParameterExplanationData Type
in_polygons

The polygons 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 with additional new attributes about the number points, length of lines, and area of polygons inside each input polygon and statistics about those features.

Feature Class
keep_all_polygons
(Optional)

Determines if all input polygons or only those containing at least one input point 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, and statistical summary types that you wish to calculate for those attribute fields for all points within each polygon.

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

Statistic types include:

  • Sum—Adds the total value of all the points in each polygon.
  • Mean—Calculates the average of all the points in each polygon.
  • Min—Finds the smallest value of all the points in each polygon.
  • Max—Finds the largest value of all the points in each polygon.
  • Stddev—Finds the standard deviation of all the points in each polygon.

Value Table
sum_shape
(Optional)

Determines if the output feature class will contain attributes for the number of points, length or lines, and area of polygon features summarized in each input polygon.

  • ADD_SHAPE_SUMAdd shape summary attributes to the output feature class. This is the default.
  • NO_SHAPE_SUMDo not add shape summary attributes to the output feature class.
Boolean
shape_unit
(Optional)

The unit in which to calculate shape summary attributes. If the input summary features are points no shape unit is necessary, since only the count of points within 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.

  • METERSMeters
  • KILOMETERSKilometers
  • FEETFeet
  • YARDSYards
  • MILESMiles
  • ACRESAcres
  • HECTARESHectares
  • SQUAREMETERSSquare meters
  • SQUAREKILOMETERSSquare kilometers
  • SQUAREFEETSquare feet
  • SQUAREYARDSSquare yards
  • SQUAREMILESSquare miles
String
group_field
(Optional)

Attribute field from the input summary features that is 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 you chose a group field, an additional output grouped table will be created and its location must be specified in the out_grouped_table parameter.

Field
add_min_maj
(Optional)

This option is only enabled if you have selected a group field. It allows you to determine which group field value is the minority (least dominant) and the majority (most dominant) within each input polygon.

  • NO_MIN_MAJDo not add minority and majority fields to the output. This is the default.
  • ADD_MIN_MAJAdd minority and majority fields to the output.
Boolean
add_group_percent
(Optional)

This option is only enabled if you have selected a group field. It allows you to determine the percentage of each attribute value within each group.

  • NO_PERCENTDo not add a percentage attribute field to the output. This is the default.
  • ADD_PERCENTAdd a percentage attribute field to the output.
Boolean
out_group_table
(Optional)

If a group field is specified, the output grouped table is required.

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 of the summary fields.
  • Percentage field.

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.SummarizeWithin_analysis('neighborhoods', 'crimes', 'neighborhood_crimes')
SummarizeWithin example 2 (stand-alone script)

The following standalone 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.SummarizeWithin_analysis(polys, points, outFeatureClass, keepAll, 
                               sumFields, addShapeSum, '', groupField, 
                               addMinMaj, addPercents, outTable)

Licensing information

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

Related topics