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 grow each zone. Zones grow until all specified criteria are satisfied. - Attribute target — Zones will be created based on target values of one or multiple variables. If this option is chosen, the desired sum of each attribute must be specified in the Zone Building Criteria With Target parameter, and each zone will grow until the sum of the attributes exceeds these values. For example, you can use this option to create zones that each have at least 100,000 residents and 20,000 family homes.
- Number of zones and attribute target — A specified number of zones will be created while keeping the sum of an attribute approximately equal within each zone. If this option is chosen, the desired number of zones must be specified in the Target Number of Zones parameter. The attribute sum within each zone is equal to the sum of the total attribute divided by the number of zones.
- Defined number of zones — A specified number of zones will be created that are each composed of approximately the same number of input features. If this option is chosen, the desired number of zones must be specified in the Target Number of Zones parameter.
| 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, 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 (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. - Contiguity edges only — For zones containing contiguous polygon features, only polygons that share an edge will be part of the same zone.
- Contiguity edges corners — For zones containing contiguous polygon features, only polygons that share an edge or a vertex will be part of the same zone.
- Trimmed Delaunay triangulation — Features in the same zone will have at least one natural neighbor in common with another feature in the zone. Natural neighbor relationships are based on a trimmed Delaunay Triangulation. Conceptually, Delaunay Triangulation creates a non-overlapping mesh of triangles from feature centroids. Each feature is a triangle node, and nodes that share edges are considered neighbors. These triangles are then clipped to a convex hull to ensure that features cannot be neighbors with any features outside of the convex hull. This is the default.
- Get spatial weights from file — Spatial, and, optionally, temporal relationships will be defined by a specified spatial weights file (.swm). Create the spatial weights matrix using the Generate Spatial Weights Matrix tool or the Generate Network Spatial Weights tool. The path to the spatial weights file is specified by the Spatial Weights Matrix File parameter.
| 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 desired characteristics of the zones that will be created. - Equal area — Zones with total area as similar as possible will be created.
- Compactness — Zones will be created with more closely-packed (compact) features.
- Equal number of features — Zones with an equal number of features will be created.
| String |

Attribute to Consider (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 (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 |

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. - Maintain within proportion — Each zone will maintain the same proportions as the overall study area for the given categorical variable. For example, given a categorical variable that is 60% Type A and 40% Type B, this method will prefer zones that are comprised of approximately 60% Type A features and 40% Type B features.
- Maintain overall proportion — Zones will be created so that the overall proportions of category predominance by zone matches the proportions of the given categorical variable for the entire dataset. For example, given a categorical variable that is 60% Type A and 40% Type B, this method will prefer solutions where 60% of the zones are predominantly Type A features and 40% of the zones are predominantly Type B features.
| 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 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 |

## 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.## 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 grow each zone. Zones grow until all specified criteria are satisfied. - ATTRIBUTE_TARGET —Zones will be created based on target values of one or multiple variables. If this option is chosen, the desired sum of each attribute must be specified in the Zone Building Criteria With Target parameter, and each zone will grow until the sum of the attributes exceeds these values. For example, you can use this option to create zones that each have at least 100,000 residents and 20,000 family homes.
- NUMBER_ZONES_AND_ATTRIBUTE —A specified number of zones will be created while keeping the sum of an attribute approximately equal within each zone. If this option is chosen, the desired number of zones must be specified in the Target Number of Zones parameter. The attribute sum within each zone is equal to the sum of the total attribute divided by the number of zones.
- NUMBER_OF_ZONES —A specified number of zones will be created that are each composed of approximately the same number of input features. If this option is chosen, the desired number of zones must be specified in the Target Number of Zones parameter.
| 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. - CONTIGUITY_EDGES_ONLY —For zones containing contiguous polygon features, only polygons that share an edge will be part of the same zone.
- CONTIGUITY_EDGES_CORNERS — For zones containing contiguous polygon features, only polygons that share an edge or a vertex will be part of the same zone.
- TRIMMED_DELAUNAY_TRIANGULATION — Features in the same zone will have at least one natural neighbor in common with another feature in the zone. Natural neighbor relationships are based on a trimmed Delaunay Triangulation. Conceptually, Delaunay Triangulation creates a non-overlapping mesh of triangles from feature centroids. Each feature is a triangle node, and nodes that share edges are considered neighbors. These triangles are then clipped to a convex hull to ensure that features cannot be neighbors with any features outside of the convex hull. This is the default.
- GET_SPATIAL_WEIGHTS_FROM_FILE — Spatial, and, optionally, temporal relationships will be defined by a specified spatial weights file (.swm). Create the spatial weights matrix using the Generate Spatial Weights Matrix tool or the Generate Network Spatial Weights tool. The path to the spatial weights file is specified by the Spatial Weights Matrix File parameter.
| 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. - EQUAL_AREA — Zones with total area as similar as possible will be created.
- COMPACTNESS —Zones will be created with more closely-packed (compact) features.
- EQUAL_NUMBER_OF_FEATURES —Zones with an equal number of features 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. - MAINTAIN_WITHIN_PROPORTION —Each zone will maintain the same proportions as the overall study area for the given categorical variable. For example, given a categorical variable that is 60% Type A and 40% Type B, this method will prefer zones that are comprised of approximately 60% Type A features and 40% Type B features.
- MAINTAIN_OVERALL_PROPORTION —Zones will be created so that the overall proportions of category predominance by zone matches the proportions of the given categorical variable for the entire dataset. For example, given a categorical variable that is 60% Type A and 40% Type B, this method will prefer solutions where 60% of the zones are predominantly Type A features and 40% of the zones are predominantly Type B features.
| 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