| Label | Explanation | Data Type |
Input Features | The feature class or feature layer that will be aggregated into zones. | Feature Layer |
Output Features | The output feature class indicating which features are aggregated into each zone. The feature class will be symbolized by the ZONE_ID field and will contain fields displaying the values of each criteria that you specify. | Feature Class |
Zone Creation Method | Specifies the method that will be used to create each zone. Zones grow until all specified criteria are satisfied.
| String |
Target Number of Zones (Optional) | The number of zones that will be created. | Long |
Zone Building Criteria With Target (Optional) | Specifies the variables that will be considered, as well as their target values and optional weights. The default weight is 1, and each variable contributes equally unless they are changed. | Value Table |
Zone Building Criteria (Optional) | Specifies the variables that will be considered and, optionally, their weights. The default weight is 1, and each variable contributes equally unless changed. | Value Table |
Spatial Constraints (Optional) | Specifies how neighbors will be defined while the zones grow. Zones can only grow into new features that are neighbors of at least one of the features already in the zone. If the input features are polygons, the default spatial constraint is Contiguity edges corners. If the input features are points, the default spatial constraint is Trimmed Delaunay triangulation.
| String |
Spatial Weight Matrix File (Optional) | The path to a file containing spatial weights that define spatial and, optionally, temporal relationships among features. | File |
Zone Characteristics (Optional) | Specifies the characteristics of the zones that will be created.
| String |
Attribute to Consider (Optional) | Specifies attributes and statistics to consider in the selection of final zones. You can homogenize attributes based on their sum, average, median, or variance. For example, if you are creating zones based on home values and want to balance the average total income within each zone, the solution with the most equal average income across zones will be preferred. | Value Table |
Distance to Consider (Optional) | The feature class that will be used to homogenize the total distance per zone. The distance is calculated from each of the input features to the closest feature provided in this parameter. This distance is then used as an additional attribute constraint when selecting the final zone solution. For example, you can create police patrol districts that are each approximately the same distance from the closest police station. | Feature Layer |
Categorical Variable to Maintain Proportions (Optional) | The categorical variable to be considered for zone proportions. | Field |
Proportion Method (Optional) | Specifies the type of proportion that will be maintained based on the chosen categorical variable.
| String |
Population Size (Optional) | The number of randomly generated initial seeds. For larger datasets, increasing this number will increase the search space and the probability of finding a better solution. The default is 100. | Long |
Number of Generations (Optional) | The number of times the zone search process will be repeated. For larger datasets, increasing the number is recommended to find an optimal solution. The default is 50 generations. | Long |
Mutation Factor (Optional) | The probability that an individual's seed values will be mutated to a new set of seeds. Mutation increases the search space by introducing variability of the possible solutions in every generation and allows for faster convergence to an optimal solution. The default is 0.1. | Double |
Output Convergence Table (Optional) | The table containing the total fitness score for the best solution found in every generation as well as the fitness score for the individual zone constraints. | Table |
Summary
Creates spatially contiguous zones in a study area using a genetic growth algorithm based on specified criteria.
You can create zones that contain an equal number of features, zones that are similar based on a set of attribute values, or both. You can also select zones with approximately equal areas, that are as compact as possible, and that maintain consistent summary statistics of other variables.
Usage
To create zones, choose Attribute target, Number of zones and attribute target, or Defined number of zones for the Zone Creation Method parameter. When you choose Attribute target, the tool will create zones based on the target values of one or more specified variables. The Number of zones and attribute target option balances the attributes over the specified number of zones. The Defined number of zones option creates zones based on feature counts.
This tool can take input points or polygons.
If multiple variables are specified for the Zone Building Criteria parameter, you can provide weights for each criteria. Weights are applied proportionally to the value specified in the weights field.
This tool supports parallel processing to create generations for the algorithm and uses 50 percent of available processors by default. The number of processors can be increased or decreased using the Parallel Processing Factor environment.
Parameters
arcpy.stats.BuildBalancedZones(in_features, output_features, zone_creation_method, {number_of_zones}, {zone_building_criteria_target}, {zone_building_criteria}, {spatial_constraints}, {weights_matrix_file}, {zone_characteristics}, {attribute_to_consider}, {distance_to_consider}, {categorial_variable}, {proportion_method}, {population_size}, {number_generations}, {mutation_factor}, {output_convergence_table})| Name | Explanation | Data Type |
in_features | The feature class or feature layer that will be aggregated into zones. | Feature Layer |
output_features | The output feature class indicating which features are aggregated into each zone. The feature class will be symbolized by the ZONE_ID field and will contain fields displaying the values of each criteria that you specify. | Feature Class |
zone_creation_method | Specifies the method that will be used to create each zone. Zones grow until all specified criteria are satisfied.
| String |
number_of_zones (Optional) | The number of zones that will be created. | Long |
zone_building_criteria_target [[variable, sum, weight],...] (Optional) | Specifies the variables that will be considered, as well as their target values and optional weights. The default weight is 1, and each variable contributes equally unless they are changed. | Value Table |
zone_building_criteria [[variable, weight],...] (Optional) | Specifies the variables that will be considered and, optionally, their weights. The default weight is 1, and each variable contributes equally unless changed. | Value Table |
spatial_constraints (Optional) | Specifies how neighbors will be defined while the zones grow. Zones can only grow into new features that are neighbors of at least one of the features already in the zone. If the input features are polygons, the default spatial constraint is Contiguity edges corners. If the input features are points, the default spatial constraint is Trimmed Delaunay triangulation.
| String |
weights_matrix_file (Optional) | The path to a file containing spatial weights that define spatial and, optionally, temporal relationships among features. | File |
zone_characteristics [zone_characteristics,...] (Optional) | Specifies the characteristics of the zones that will be created.
| String |
attribute_to_consider [[variable, function],...] (Optional) | Specifies attributes and statistics to consider in the selection of final zones. You can homogenize attributes based on their sum, average, median, or variance. For example, if you are creating zones based on home values and want to balance the average total income within each zone, the solution with the most equal average income across zones will be preferred. | Value Table |
distance_to_consider [distance_to_consider,...] (Optional) | The feature class that will be used to homogenize the total distance per zone. The distance is calculated from each of the input features to the closest feature provided in this parameter. This distance is then used as an additional attribute constraint when selecting the final zone solution. For example, you can create police patrol districts that are each approximately the same distance from the closest police station. | Feature Layer |
categorial_variable (Optional) | The categorical variable to be considered for zone proportions. | Field |
proportion_method (Optional) | Specifies the type of proportion that will be maintained based on the chosen categorical variable.
| String |
population_size (Optional) | The number of randomly generated initial seeds. For larger datasets, increasing this number will increase the search space and the probability of finding a better solution. The default is 100. | Long |
number_generations (Optional) | The number of times the zone search process will be repeated. For larger datasets, increasing the number is recommended to find an optimal solution. The default is 50 generations. | Long |
mutation_factor (Optional) | The probability that an individual's seed values will be mutated to a new set of seeds. Mutation increases the search space by introducing variability of the possible solutions in every generation and allows for faster convergence to an optimal solution. The default is 0.1. | Double |
output_convergence_table (Optional) | The table containing the total fitness score for the best solution found in every generation as well as the fitness score for the individual zone constraints. | Table |
Code sample
The following Python window script demonstrates how to use the BuildBalancedZones function.
import arcpy
arcpy.env.workspace = r"c:\data\project_data.gdb"
arcpy.stats.BuildBalancedZones("US_Counties", "out_features",
"NUMBER_OF_ZONES", 5, None, None, "TRIMMED_DELAUNAY_TRIANGULATION",
None, None, None, None, None, '', 100, 50, 0.1)The following stand-alone Python script demonstrates how to use the BuildBalancedZones function.
# Aggregate states into zones that have a target population of approximately
# 250,000 people. Make the zones of equal area and compact.
import arcpy
# Set the current workspace (to avoid having to specify the full path to
# the feature classes each time)
arcpy.env.workspace = r"c:\data\project_data.gdb"
arcpy.stats.BuildBalancedZones("states", "out_zones", "ATTRIBUTE_TARGET",
None, "POPULATION 250000 1", None, "TRIMMED_DELAUNAY_TRIANGULATION",
None, "EQUAL_AREA;COMPACTNESS", None, None, None, '', 100, 50, 0.1)