Summary
Creates spatially contiguous zones in your study area using a genetic growth algorithm based on criteria that you specify.
You can create zones that contain an equal number of features, zones that are similar based on a set of attribute values, or both. There are also options to select zones with approximately equal areas, are as compact as possible, and that maintain consistent summary statistics of other variables.
Usage
Zones can be created by choosing Attribute target, Number of zones and attribute target, or Defined number of zones in the Zone Creation Method parameter. When Attribute target is chosen, 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. You can also create zones based on feature counts using the Defined number of zones option.
This tool can take input points or polygons.
If multiple variables are specified for the Zone Building Criteria parameter, you have the option to 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.
License:
The Distance to Consider (distance_to_consider) parameter is only available with a Desktop Advanced license.Syntax
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})| Parameter | 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 grow 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, their target values, and optional weights. The default weights are set to 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, weights. The default weights are set to 1, and each variable contributes equally unless changed. | Value Table |
spatial_constraints (Optional) | Specifies how neighbors are 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 desired 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 choose to 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. License:This optional parameter is not available with a Desktop Basic or Desktop Standard license. | 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 is repeated. For larger datasets, increasing the number is recommended in order 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) | If specified, a table will be created 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 tool.
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 tool.
# 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)Licensing information
- Basic: Limited
- Standard: Limited
- Advanced: Yes