Apportion Polygon (Analysis)

Summary

Summarizes the attributes of an input polygon layer based on the spatial overlay of a target polygon layer and assigns the summarized attributes to the target polygons. The target polygons have summed numeric attributes derived from the input polygons that each target overlaps. This process is typically known as apportioning or apportionment.

This tool can be used to estimate the population of one feature based on the percentage of that feature that overlays another feature with a known population.

Illustration

Apportion Polygon tool illustration
The partial sum of input attributes within the target is shown.

Usage

  • By default, the percentage of overlapping area determines the percentage of the attributes transferred.

  • A weight field from the input polygon will be normalized and used to adjust how much the attributes are transferred. A weight field of 0 will set the apportioned attributes from the input to the targets to 0.

  • If specified, the Estimation Features parameter value is used to determine how attributes will be transferred, instead of using the area. The estimation features must intersect the Input Polygons parameter value to be counted. If the estimation features also intersect the Target Polygons parameter value, the attributes will be transferred to the target from the input feature.

  • The Maintain target geometry parameter is used to include either the target geometry or the intersection of the input and target geometries in the output geometry.

  • This tool honors the Parallel Processing Factor environment. If the environment is not set (the default) or is set to 100, full parallel processing will be enabled and the tool will attempt to distribute the work to all the logical cores on the machine. Setting the environment to 0 will disable parallel processing. Specifying a factor between 1 and 99 will cause the tool to identify the percentage of logical cores to use by applying the formula (Parallel Processing Factor / 100 * Logical Cores) rounded up to the nearest integer. If the result of this formula is 0 or 1, parallel processing will not be enabled.

Parameters

LabelExplanationData Type
Input Polygons

The polygon features with numeric attributes that will be summarized into the target polygon geometries.

Feature Layer
Fields to Apportion

The numeric fields from the input polygons that will be summarized by each target polygon and recorded in the output feature class.

Field
Target Polygons

The polygon features and their apportioned fields that will be copied to the output feature class.

Feature Layer
Output Feature Class

The output feature class containing the attribute and geometries of the target polygons as well as the specified apportion fields from the input polygons.

Feature Class
Apportion Method

Specifies the method that will be used to apportion the fields from the input polygons to the target polygons.

  • Area — The amount that each input polygon contributes to the summarized values for each target feature will be determined by the area of overlap between the two features. If an input feature overlaps two target features by the same amount, the apportioned fields will be divided in two and contribute to both target features by half of the total value. This is the default.
  • Length —The attributes from the input features will be divided based on the percentage of how much of a line is within each target feature. Only the line intersecting the input feature is included in the calculation. The line outside the input feature is excluded. For example, if one target feature covers 750 meters of a line, and another target feature covers 250 meters of a line, 75% (750 / 1000) of the input feature's attribute values will be aggregated to the first target feature, and 25% (250 / 1000) of the input feature's attribute values will be aggregated to the second target feature.
  • Points —The attributes from the input features will be divided based on the number of points inside each target feature overlapping an input feature. Points outside of the input feature are excluded. Optionally, a weight field can be specified so that the total weight of all points within each target feature will be used to determine how the input features' attribute values are divided. For example, if two target features overlap one input feature, and there are two points inside the first target feature and eight points inside the second target feature, 20% (2 / 10) of the input feature's attribute values will be aggregated to the first target feature, and 80% (8 / 10) of the input feature's attribute values will be aggregated to the second target feature.
String
Estimation Features
(Optional)

The input point or polyline features that will be used to estimate the percent of the input polygon apportion fields to apportion to the target polygon. This is the amount of the point or line within the intersection divided by the amount within the input feature to create a percentage.

Feature Layer
Weight Field
(Optional)

A numeric field from the target polygons layer that will be used to adjust which target polygons receive larger apportioned values from the input polygons' fields to apportion. Targets with higher weight are apportioned a higher ratio of the field values.

If estimation features are specified, the weight field is a numeric field from the estimation features that will adjust the values apportioned to the target polygons intersecting the estimation features.

Field
Maintain target geometry
(Optional)

Specifies whether the output feature class will maintain the original geometries from the target polygon layer.

  • Checked—The output feature class will maintain the original geometries of the target polygon layer. This is the default.
  • Unchecked—The output feature class will be a geometric intersection of the target polygons and the input polygons. Only areas of the target polygons that overlap an input polygon will be included in the output.

Boolean

arcpy.analysis.ApportionPolygon(in_features, apportion_fields, target_features, out_features, method, {estimation_features}, {weight_field}, {maintain_geometries})
NameExplanationData Type
in_features

The polygon features with numeric attributes that will be summarized into the target polygon geometries.

Feature Layer
apportion_fields
[apportion_fields,...]

The numeric fields from the input polygons that will be summarized by each target polygon and recorded in the output feature class.

Field
target_features

The polygon features and their apportioned fields that will be copied to the output feature class.

Feature Layer
out_features

The output feature class containing the attribute and geometries of the target polygons as well as the specified apportion fields from the input polygons.

Feature Class
method

Specifies the method that will be used to apportion the fields from the input polygons to the target polygons.

  • AREAThe amount that each input polygon contributes to the summarized values for each target feature will be determined by the area of overlap between the two features. If an input feature overlaps two target features by the same amount, the apportioned fields will be divided in two and contribute to both target features by half of the total value. This is the default.
  • LENGTHThe attributes from the input features will be divided based on the percentage of how much of a line is within each target feature. Only the line intersecting the input feature is included in the calculation. The line outside the input feature is excluded. For example, if one target feature covers 750 meters of a line, and another target feature covers 250 meters of a line, 75% (750 / 1000) of the input feature's attribute values will be aggregated to the first target feature, and 25% (250 / 1000) of the input feature's attribute values will be aggregated to the second target feature.
  • POINTSThe attributes from the input features will be divided based on the number of points inside each target feature overlapping an input feature. Points outside of the input feature are excluded. Optionally, a weight field can be specified so that the total weight of all points within each target feature will be used to determine how the input features' attribute values are divided. For example, if two target features overlap one input feature, and there are two points inside the first target feature and eight points inside the second target feature, 20% (2 / 10) of the input feature's attribute values will be aggregated to the first target feature, and 80% (8 / 10) of the input feature's attribute values will be aggregated to the second target feature.
String
estimation_features
(Optional)

The input point or polyline features that will be used to estimate the percent of the input polygon apportion fields to apportion to the target polygon. This is the amount of the point or line within the intersection divided by the amount within the input feature to create a percentage.

Feature Layer
weight_field
(Optional)

A numeric field from the target polygons layer that will be used to adjust which target polygons receive larger apportioned values from the input polygons' fields to apportion. Targets with higher weight are apportioned a higher ratio of the field values.

If estimation features are specified, the weight field is a numeric field from the estimation features that will adjust the values apportioned to the target polygons intersecting the estimation features.

Field
maintain_geometries
(Optional)

Specifies whether the output feature class will maintain the original geometries from the target polygon layer.

  • MAINTAIN_GEOMETRIESThe output feature class will maintain the original geometries of the target polygon layer. This is the default.
  • INTERSECT_GEOMETRIESThe output feature class will be a geometric intersection of the target polygons and the input polygons. Only areas of the target polygons that overlap an input polygon will be included in the output.
Boolean

Code sample

ApportionPolygon example 1 (Python window)

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

import arcpy
arcpy.env.workspace = "C:/data/MyAnalysis.gdb"
arcpy.ApportionPolygon_analysis(
        "CensusBlockGroups", "Pop2020", "StoreServiceArea", 
        "StoreServiceArea_w_Population", "AREA", "", "", "MAINTAIN_GEOMETRIES")
ApportionPolygon example 2 (stand-alone script)

The following stand-alone script transfers area-weighted population from a Census Block Groups layer to a Store Service Area polygon.

# Name: Store Service Area Get Population.py
# Description: Use apportionment to transfer population figures to different 
#              geometry.

# Import system modules 
import arcpy

# Set environment settings
arcpy.env.workspace = "C:/data/MyAnalysis.gdb"

# Perform apportionment
inputDataWithPop = "CensusBlockGroups"
popField = "Pop2020"
targetServiceAreas = "Store_ServiceAreas"
outputApp = "Store_ServiceAreas_w_Population"
apportionMethod = "AREA"
keepTargetGeom = "MAINTAIN_GEOMETRIES"
arcpy.ApportionPolygon_analysis(inputDataWithPop, popField, targetServiceAreas, 
                                outputApp, apportionMethod, "", "", 
                                keepTargetGeom)

# Summarize store service area populations by store admin region
outStats = "PopulationPerSalesRegion_tlb"
statsFields = [["Pop2020", "SUM"]]
regionField = "SalesRegion" # Values like North, North-East, etc.
arcpy.Statistics_analysis(outputApp, outStats, statsFields, regionField)

Licensing information

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

Related topics