Locate Regions (Spatial Analyst)

Available with Spatial Analyst license.

Summary

Identifies the best regions, or groups of contiguous cells, from an input utility (suitability) raster that satisfy a specified evaluation criterion and that meet identified shape, size, number, and interregion distance constraints.

This tool uses a parameterized region-growing (PRG) algorithm to grow candidate regions from seed cells by adding neighboring cells to the region that best preserves the specified shape but also maximizes utility for the region. Using a selection algorithm and an evaluation criterion—such as the highest average value—the best region or regions are selected from the candidate regions that meet identified size and spatial constraints. An example of a spatial constraint would be maintaining a certain minimum distance between regions.

Learn more about how the Locate Regions tool works

Usage

• The input utility raster is often the output from a suitability model. A suitability model identifies how suitable each location is based on the desired attributes actually found at the location. Suitability modeling is one of the most common applications for Spatial Analyst. For additional information on suitability modeling, see Understanding overlay analysis.

• The higher the input values in the utility raster, the greater the utility.

• The settings for Minimum distance between regions and Maximum distance between regions take precedent over Total area. For example, if five regions are desired, but due to the specified minimum and maximum distances only four regions can be located, then only four regions will be selected. As a result, the Total area will not be met. When possible, a warning will be issued, but this is not the case for all situations.

• The parameterized region-growing (PRG) algorithm grows based on utility values within the input raster—the higher value cells are more preferred in the growth. The Evaluation method determines which of the candidate regions are selected; it has no influence on the region growth.

• The Locate Regions tool is very computationally intensive. There are steps you can take with how you set up your input data and the settings of certain parameters to influence this.

• To speed up processing, locations that should not be considered in the selection processing should be set to NoData as a preprocessing step or eliminated using the Mask. No regions will grow from these excluded locations or be allocated in the selection process. Unlike Input raster or feature of existing regions, excluded areas have no effect on the Minimum distance between regions and Maximum distance between regions in the parameterized region-growing (PRG) algorithm or in the selection of the candidate regions.

• The options that are selected for the Number of seeds to grow from and Resolution of the growth parameters can greatly affect the processing time.

  Selecting the Small and Low options for these parameters, respectively, will provide the best performance. Selecting Small, Medium, or Large for Number of seeds to grow from and Low, Medium, or High for Resolution of the growth produces the most reliable results within a reasonable amount of time.

• If the Number of seeds to grow from or the Resolution of the growth are specified to any option other than Maximum, data will be lost due to not growing regions from every cell and resampling to a coarser resolution. However, depending on the size of the input raster, the Maximum option may be very slow; therefore, the other options may be more practical.

• Depending on the size of the input raster, selecting Maximum for Number of seeds to grow from or Resolution of the growth can take a long time. The Locate Regions algorithm implements a two-step process. It first grows candidate regions and it then selects the best regions from the candidate regions. The growing of the regions for large input rasters can take a long time. However, in the selecting regions step, a distance matrix is first loaded. If the matrix cannot be loaded due to memory limitations, the tool will end processing. If this occurs, either select a smaller number of seeds to grow from or specify a coarser resolution of growth.

• The default values for Number of seeds to grow from and Resolution of the growth are dependent on the number of cells in the input raster. The more cells in the input raster, the longer this tool takes to execute. To avoid extremely long execution times, these default values are set accordingly.

  Number of input cells	Number of seeds to grow from	Resolution of the growth
  <= 100,000	Maximum	Maximum
  100,000 - 500,000	Small	Maximum
  > 500,000	Small	Low

• When the Number of regions is greater than eight, it is recommended to use the Sequential option for the Region selection method. Using the Combinatorial method with more than eight regions selected may result in slow performance.

• Usually, the Number of seeds to grow from value has the greatest impact on the processing speed. The higher the number of seeds to grow from, the longer the tool takes to operate. However, in most cases the results are similar, regardless of the value specified.

• The Number of seeds to grow from are distributed within the input raster based on utility values—areas with higher utility values receive more seeds. The Evaluation method has no influence on their distribution.

• The Resolution of the growth sets the resolution on which the parameterized region growing will occur. The input raster is resampled to the defined resolution using the bilinear resampling method. Once the regions are selected, before the final output raster is created, the results are resampled to the environment Cell Size using the nearest neighbor resampling method.

• A shape adjustment is implemented for the regions at the edge of the input raster. If at least one cell should fall outside the input raster's boundary in order to maintain the shape, the utility of the region will be reduced by 50 percent. Because of this utility reduction, the region is less likely to be selected, but the reduction does not eliminate the region from the selection process.

• The area selected can be more than the specified total area if Islands not allowed in regions is checked. To determine if the discrepancy between the selected area and the specified total area is based on the no-island parameter, rerun the tool with this parameter unchecked. Add the number of cells from COUNT in the output raster attribute table from the original run; then rerun the tool, multiply the sum of each by the area of a cell, and compare the results to the specified area.

• If the Resolution of the growth is specified with any option other than Maximum, through a postprocess, the original utility values for each region can be identified using Zonal Statistics. Enter the output region raster from Locate Regions as the zone raster and the input utility raster as the value raster.

• See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.

Parameters

Dialog

Label	Explanation	Data Type
Input raster	The input utility raster from which the regions will be derived. The higher the value in the input raster, the greater the utility. The raster can be of either integer or floating-point type.	Raster Layer
Total area (Optional)	The total amount of area for all regions. The default is 10 percent of the input cells within the processing extent.	Double
Area units (Optional)	Defines the area units used for the Total area, Region minimum area, and Region maximum area parameters. Square map units —For the square of the linear units of the output spatial reference Square miles —For miles Square kilometers —For kilometers Hectares —For hectares Acres —For acres Square meters —For meters Square yards —For yards Square feet —For feet	String
Number of regions (Optional)	Determines how many regions the Total area will be distributed across. The maximum number of regions that can be specified is 30. The default is 1.	Long
Region shape (Optional)	Defines the shape characteristics for the output regions. Circle —Cells that maintain circular regions will receive a greater weight. This is the default. Ellipse —Cells that maintain elliptical-shaped regions will receive a greater weight. Equilateral triangle —Cells that maintain equilateral triangular-shaped regions will receive a greater weight. Square —Cells that maintain square-shaped regions will receive a greater weight. Pentagon —Cells that maintain pentagon-shaped regions will receive a greater weight. Hexagon —Cells that maintain hexagon-shaped regions will receive a greater weight. Octagon —Cells that maintain octagon-shaped regions will receive a greater weight.	String
Region orientation (Optional)	Defines the orientation of the defined shape. Regions are grown out from the seed locations with preference given to the cells that maintain the desired orientation of the region shapes. The orientation values are in compass degrees ranging from 0 to 360, increasing clockwise starting from north. The default is 0. The default of 0 orients the shapes in the following manner: Circle—no effect; Ellipse—the minor axis is orientated north-south; Triangle and Pentagon—one point is straight up; Square, Hexagon, and Octagon—one flat side is oriented east-west. If the Region shape is set to Circle, the Region orientation parameter is unavailable.	Double
Shape/Utility tradeoff (%) (Optional)	Identifies the weight for the cells when growing the candidate regions in the parameterized region-growing algorithm. The weighting is a tradeoff between a cell's contribution for maintaining the region shape relative to the utility contribution of the cell's attribute value. Higher values indicates maintaining the shape of the region is more important than selecting higher utility values. The acceptable percent values are 0 to 100, inclusively. The default is 50. This parameter is used to identify the feasible candidate regions. The candidate regions that will be selected by the algorithm are controlled by the Evaluation method parameter.	Double
Evaluation method (Optional)	The evaluation criteria to be used for determining which of the candidate regions identified in the parameterized region-growing algorithm are most preferred. The preference can be specified based on a particular statistic of the utility values, or spatial arrangement of the cells within the regions. Highest average value —Selects regions based on the highest average value. This is the default. Highest sum —Selects regions based on the highest sum. Highest median value —Selects regions based on the highest median value. Highest value —Selects regions based on the highest individual cell value contained within the region. This option ensures the best individual cells are selected. Lowest value —Selects regions based on the highest lowest individual cell value contained within the region. This option ensures the selected regions contain cells with really low utility. Greatest core area — Selects regions based on the greatest core area. Any cell that is farther than one cell from the edge of a region is considered to be part of the core. The edge distance can be controlled by the analysis cell size. Setting a smaller cell size can increase the core area. Highest sum of core utility values —Selects regions based on the highest cumulative sum of the utility values for the core area. The edge distance can be controlled by the analysis cell size. Greatest edge — Selects regions based on the greatest amount of edge using the P1 ratio, which is the ratio of the perimeter of the shape to the perimeter of a circle of the same area. The P1 ratio for a circle is 1.	String
Region minimum area (Optional)	Define the minimum area allowed for each region. The units specified by the Area units parameter will be used.	Double
Region maximum area (Optional)	Define the maximum area allowed for each region. The units specified by the Area units parameter will be used.	Double
Minimum distance between regions (Optional)	Define the minimum distance allowed between regions. No two regions can be within this distance. This parameter influences the parameterized region-growing (PRG) algorithm. If a cell has the potential of being added to a candidate region, but it is within this distance from any individual region in the dataset specified by the Input raster or feature of existing regions parameter, it will not be considered for the candidate region. The minimum distance setting is not applied to excluded locations (NoData cells). The units specified by the Distance units parameter will be used.	Double
Maximum distance between regions (Optional)	Define the maximum distance allowed between regions. No region can be farther apart than this distance from at least one other region. When sequentially selecting regions, if the next best region is farther than this distance from any of the already selected regions, it will not be considered at this time, but it may be selected later when more regions are selected. The maximum distance is applied to the dataset specified in the Input raster or feature of existing regions parameter, in that at least one of the selected regions must be within the maximum distance from existing regions. The maximum distance setting is not applied to excluded areas (NoData cells) and has no effect on the PRG algorithm. The units specified by the Distance units parameter will be used.	Double
Distance units (Optional)	Defines the distance units that will be used for the Minimum distance between regions and Maximum distance between regions parameters. Map units —For the linear units of the output spatial reference Miles —For miles Kilometers —For kilometers Meters —For meters Yards —For yards Feet —For feet	String
Input raster or feature of existing regions (Optional)	A dataset identifying where regions already exist. The input can be a raster or feature dataset. If the input is a raster, any location in the raster with a valid value is considered already allocated. All other locations are set to NoData. In the parameterized region-growing algorithm, no region will grow from any location identified as an existing region. Existing regions will be used in the growth and evaluation of the Minimum distance between regions and Maximum distance between regions parameters as described in the corresponding parameter descriptions above.	Raster Layer; Feature Layer
Number of neighbors to use in growth (Optional)	Defines which neighboring cells to use in the growth of the regions. Four —Only the four direct (orthogonal) neighbors of the region cells will be considered in the region growth. Eight —The eight nearest neighbors (orthogonal and diagonal) will be considered in the region growth. This is the default.	String
Islands not allowed in regions (Optional)	Defines whether or not islands will be allowed within the potential regions. Checked—The parameterized region-growing algorithm ensures there will be no islands within a region. This is the default. A flood field algorithm is implemented as a postprocess once the regions are created but before the regions are selected. If there are islands within a region, they will be filled in and the cells will join the region. Since the fill process occurs before the selection process, the utility of the island cells will be added to the region, and their values will be included in the selection process of the regions and in the statistics of the output regions. As a result of the fill process, it is likely that the total area allocated will exceed the target specified by the Total area parameter. Unchecked—Islands will be allowed.	Boolean
Number of seeds to grow from (Optional)	Defines the number of seeds from which to grow the potential regions. Based on input —The number of seeds will be based on the number of cells in the input raster. When the input raster has 100,000 cells or fewer, the default is Maximum. When the input raster has more than 100,000 cells, the default is Small. This is the default. Small —The number of seeds will be equal to 10 percent of the number of cells in the input raster, after NoData cells are excluded, but not to exceed 1,600 seeds. Medium —The number of seeds will be equal to 20 percent of the number of cells in the input raster, after NoData cells are excluded, but not to exceed 2,500 seeds. Large —The number of seeds will be equal to 30 percent of the number of cells in the input raster, after NoData cells are excluded, but not to exceed 3,600 seeds. Maximum —The region growth will occur at each available cell within the input raster. Available cells are all cells that are not NoData and not identified as an existing region.	String
Resolution of the growth (Optional)	Sets the resolution at which region growth occurs. Based on input —The resolution will be based on the number of cells in the input raster. When the input raster has 500,000 cells or fewer, the default is Maximum. When the input raster has more than 500,000 cells, the default is Low. This is the default. Low —The analysis will be performed on an intermediate raster containing 147,356 (384 x 384) cells distributed in the same x and y ratio as the input raster. Medium —The analysis will be performed on an intermediate raster containing 262,144 (512 x 512) cells distributed in the same x and y ratio as the input raster. High —The analysis will be performed on an intermediate raster containing 589,824 (768 x 768) cells distributed in the same x and y ratio as the input raster. Maximum —The analysis will be performed on all cells in the input raster.	String
Region selection method (Optional)	Identifies how the regions will be selected. Based on number of regions —The selection method is based on the Number of regions parameter. If the Number of regions is eight or less, the Combinatorial selection method is used. If the Number of regions parameter is greater than eight, the Sequential selection method is used. This is the default. Combinatorial —Selects the best regions based on the specified evaluation method, while honoring the spatial constraints, by testing all combinations of the desired number of regions within the candidate regions from the parameterized region-growing (PRG) algorithm. Sequential —Sequentially selects the best regions based on the evaluation method and that meets the spatial constraints until the desired number of regions is reached.	String

Return Value

Label	Explanation	Data Type
Output raster	The output regions raster. Each region is uniquely numbered with values greater than zero. Cells that do not belong to any regions will be assigned zero. The output is always an integer raster. Additional fields are calculated for each region storing statistics of the selected regions. These fields are the following: AVERAGE —The average utility value of the region. TOTAL —The total sum of the utility values within the region. MEDIAN —The median utility value of the region. HIGHEST —The highest individual cell value contained within the region. LOWEST —The lowest individual cell value contained within the region. COREAREA —The core area. Any cell farther than one cell from the region's edge is considered to be part of the core. CORESUM —The cumulative sum of the utility values for the core area. EDGE —The amount of edge using the P1 ratio, which is the ratio of the perimeter of the shape to the perimeter of a circle of the same area. The P1 ratio for a circle is 1.	Raster

Python

LocateRegions(in_raster, {total_area}, {area_units}, {number_of_regions}, {region_shape}, {region_orientation}, {shape_tradeoff}, {evaluation_method}, {minimum_area}, {maximum_area}, {minimum_distance}, {maximum_distance}, {distance_units}, {in_existing_regions}, {number_of_neighbors}, {no_islands}, {region_seeds}, {region_resolution}, {selection_method})

Name	Explanation	Data Type
in_raster	The input utility raster from which the regions will be derived. The higher the value in the input raster, the greater the utility. The raster can be of either integer or floating-point type.	Raster Layer
total_area (Optional)	The total amount of area for all regions. The default is 10 percent of the input cells within the processing extent.	Double
area_units (Optional)	Defines the area units used for the total_area, minimum_area, and maximum_area parameters. The available options and their corresponding units are the following: SQUARE_MAP_UNITS —For the square of the linear units of the output spatial reference SQUARE_MILES —For miles SQUARE_KILOMETERS —For kilometers HECTARES —For hectares ACRES —For acres SQUARE_METERS —For meters SQUARE_YARDS —For yards SQUARE_FEET —For feet The default is based on the input raster dataset. If the input raster is in feet, yards, miles or any other imperial unit, Square miles will be used. If the input raster is in meters, kilometers, or any other metric unit, Square kilometers will be used.	String
number_of_regions (Optional)	Determines how many regions the total_area will be distributed across. The maximum number of regions that can be specified is 30. The default is 1.	Long
region_shape (Optional)	Defines the shape characteristics for the output regions. The regions start out from seed cell locations and grow outward with preference given to the cells that maintain the desired shape. The available shape options are the following: CIRCLE —Cells that maintain circular regions will receive a greater weight. This is the default. ELLIPSE —Cells that maintain elliptical-shaped regions will receive a greater weight. TRIANGLE —Cells that maintain equilateral triangular-shaped regions will receive a greater weight. SQUARE —Cells that maintain square-shaped regions will receive a greater weight. PENTAGON —Cells that maintain pentagon-shaped regions will receive a greater weight. HEXAGON —Cells that maintain hexagon-shaped regions will receive a greater weight. OCTAGON —Cells that maintain octagon-shaped regions will receive a greater weight.	String
region_orientation (Optional)	Defines the orientation of the defined shape. Regions are grown out from the seed locations with preference given to the cells that maintain the desired orientation of the region shapes. The orientation values are in compass degrees ranging from 0 to 360, increasing clockwise starting from north. The default is 0. The default of 0 orients the shapes in the following manner: Circle—no effect; Ellipse—the minor axis is orientated north-south; Triangle and Pentagon—one point is straight up; Square, Hexagon, and Octagon—one flat side is oriented east-west.	Double
shape_tradeoff (Optional)	Identifies the weight for the cells when growing the candidate regions in the parameterized region-growing algorithm. The weighting is a tradeoff between a cell's contribution for maintaining the region shape relative to the utility contribution of the cell's attribute value. Higher values indicates maintaining the shape of the region is more important than selecting higher utility values. The acceptable percent values are 0 to 100, inclusively. The default is 50. This parameter is used to identify the feasible candidate regions. The candidate regions that will be selected are controlled by the evaluation_method parameter.	Double
evaluation_method (Optional)	The evaluation criteria to be used for determining which of the candidate regions identified in the parameterized region-growing algorithm are most preferred. The preference can be specified based on a particular statistic of the utility values, or spatial arrangement of the cells within the regions. The available options are the following: HIGHEST_AVERAGE_VALUE —Selects regions based on the highest average value. This is the default. HIGHEST_SUM —Selects regions based on the highest sum. HIGHEST_MEDIAN_VALUE —Selects regions based on the highest median value. HIGHEST_VALUE —Selects regions based on the highest individual cell value contained within the region. This option ensures the best individual cells are selected. LOWEST_VALUE —Selects regions based on the highest lowest individual cell value contained within the region. This option ensures the selected regions contain cells with really low utility. GREATEST_CORE_AREA —Selects regions based on the greatest core area.Any cell that is farther than one cell from the edge of a region is considered to be part of the core. The edge distance can be controlled by the analysis cell size. Setting a smaller cell size can increase the core area. HIGHEST_CORE_SUM —Selects regions based on the highest cumulative sum of the utility values for the core area. The edge distance can be controlled by the analysis cell size. GREATEST_EDGE —Selects regions based on the greatest amount of edge using the P1 ratio, which is the ratio of the perimeter of the shape to the perimeter of a circle of the same area. The P1 ratio for a circle is 1.	String
minimum_area (Optional)	Define the minimum area allowed for each region. The units specified by area_units will be used. To learn more about how regions are created when the minimum and maximum areas are defined, see How regions are determined when a minimum and maximum area are specified.	Double
maximum_area (Optional)	Define the maximum area allowed for each region. The units specified by area_units will be used. To learn more about how regions are created when the minimum and maximum areas are defined, see How regions are determined when a minimum and maximum area are specified.	Double
minimum_distance (Optional)	Define the minimum distance allowed between regions. No two regions can be within this distance. This parameter influences the parameterized region-growing (PRG) algorithm. If a cell has the potential of being added to a candidate region, but it is within this distance from any individual region in the in_existing_regions, it will not be considered for the candidate region. The minimum distance setting is not applied to excluded locations (NoData cells). The units specified by distance_units will be used.	Double
maximum_distance (Optional)	Define the maximum distance allowed between regions. No region can be farther apart than this distance from at least one other region. When sequentially selecting regions, if the next best region is farther than this distance from any of the already selected regions, it will not be considered at this time, but it may be selected later when more regions are selected. The maximum distance is applied to in_existing_regions; that is, at least one of the selected regions must be within the maximum distance from existing regions. The maximum distance setting is not applied to excluded areas (NoData cells), and has no effect on the PRG algorithm. The units specified by distance_units will be used.	Double
distance_units (Optional)	Defines the distance units that will be used for the minimum_distance and maximum_distance parameters. The available options and their corresponding units are the following: MAP_UNITS —For the linear units of the output spatial reference MILES —For miles KILOMETERS —For kilometers METERS —For meters YARDS —For yards FEET —For feet The default is based on the input raster dataset. If the input raster is in feet, yards, miles, or any other imperial unit, Miles will be used. If the input raster is in meters, kilometers, or any other metric unit, Kilometers will be used.	String
in_existing_regions (Optional)	A dataset identifying where regions already exist. The input can be a raster or feature dataset. If the input is a raster, any location in the raster with a valid value is considered already allocated. All other locations are set to NoData. In the parameterized region-growing algorithm, no region will grow from any location containing an existing region. Existing regions will be used in the growth and evaluation of the minimum_distance and maximum_distance as described in the corresponding parameter descriptions above.	Raster Layer; Feature Layer
number_of_neighbors (Optional)	Defines which neighboring cells to use in the growth of the regions. The available options are the following: FOUR —Only the four direct (orthogonal) neighbors of the region cells will be considered in the region growth. EIGHT —The eight nearest neighbors (orthogonal and diagonal) will be considered in the region growth. This is the default.	String
no_islands (Optional)	Defines if islands will be allowed within the potential regions. NO_ISLANDS —The parameterized region-growing algorithm ensures there will be no islands within a region.A flood field algorithm is implemented as a postprocess once the regions are created but before the regions are selected. If there are islands within a region, they will be filled in and the cells will join the region. Since the fill process occurs before the selection process, the utility of the island cells will be added to the region, and their values will be included in the selection process of the regions and in the statistics of the output regions. As a result of the fill process, it is likely that the total area allocated will exceed the target total_area value.This is the default. ISLANDS_ALLOWED —Islands will be allowed.	Boolean
region_seeds (Optional)	Defines the number of seeds from which to grow the potential regions. To learn more about how the seeds influence the region growth algorithm, see How seeds are distributed. The available options are the following: AUTO —The number of seeds will be based on the number of cells in the input raster. When the input raster has 100,000 cells or fewer, the default is Maximum. When the input raster has more than 100,000 cells, the default is Small. This is the default. SMALL —The number of seeds will be equal to 10 percent of the number of cells in the input raster, after NoData cells are excluded, but not to exceed 1,600 seeds. MEDIUM —The number of seeds will be equal to 20 percent of the number of cells in the input raster, after NoData cells are excluded, but not to exceed 2,500 seeds. LARGE —The number of seeds will be equal to 30 percent of the number of cells in the input raster, after NoData cells are excluded, but not to exceed 3,600 seeds. MAXIMUM —The region growth will occur at each available cell within the input raster. Available cells are all cells that are not NoData and not identified as an existing region.	String
region_resolution (Optional)	Sets the resolution at which region growth occurs. The input raster will be resampled to the resolution determined by the number of cells identified by this parameter (see below). For example, for Low the input raster is resampled to 147,356 cells. The parameterized region-growing algorithm grows on the resampled intermediate raster. Once the regions are selected from the resampled intermediate raster, the selected regions will be resampled to the Cell Size. An adjustment to the target resolutions identified below may be implemented if the number of cells in the desired average region size is too small or too large. This adjustment makes sure there will be enough cells in each desired region or that unnecessary processing will not occur. As a result, the total cells for the intermediate resampled raster for each of the specified resolutions below can be lower or higher than the target number of cells. For more information on this adjustment and the thresholds used, see Adjusting the region growth resolution based on the size of the desired regions. If the input has less than 147,356 cells or Maximum is selected, no resampling will occur and the region growth will process on all cells in the input raster. If the input raster has less than 147,356 cells, the Low, Medium, or High options have no effect. The available options are the following: AUTO —The resolution will be based on the number of cells in the input raster. When the input raster has 500,000 cells or fewer, the default is Maximum. When the input raster has more than 500,000 cells, the default is Low. This is the default. LOW —The analysis will be performed on an intermediate raster containing 147,356 (384 x 384) cells distributed in the same x and y ratio as the input raster. MEDIUM —The analysis will be performed on an intermediate raster containing 262,144 (512 x 512) cells distributed in the same x and y ratio as the input raster. HIGH —The analysis will be performed on an intermediate raster containing 589,824 (768 x 768) cells distributed in the same x and y ratio as the input raster. MAXIMUM —The analysis will be performed on all cells in the input raster.	String
selection_method (Optional)	Identifies how the regions will be selected. The available options are the following: AUTO —The selection method is based on the Number of regions parameter. If the Number of regions is eight or less, the Combinatorial selection method is used. If the Number of regions parameter is greater than eight, the Sequential selection method is used. This is the default. COMBINATORIAL —Selects the best regions based on the specified evaluation method, while honoring the spatial constraints, by testing all combinations of the desired number of regions within the candidate regions from the parameterized region-growing (PRG) algorithm. SEQUENTIAL —Sequentially selects the best regions based on the evaluation method and that meets the spatial constraints until the desired number of regions is reached.	String

Return Value

Name	Explanation	Data Type
out_raster	The output regions raster. Each region is uniquely numbered with values greater than zero. Cells that do not belong to any regions will be assigned zero. The output is always an integer raster. Additional fields are calculated for each region storing statistics of the selected regions. These fields are the following: AVERAGE —The average utility value of the region. TOTAL —The total sum of the utility values within the region. MEDIAN —The median utility value of the region. HIGHEST —The highest individual cell value contained within the region. LOWEST —The lowest individual cell value contained within the region. COREAREA —The core area. Any cell farther than one cell from the region's edge is considered to be part of the core. CORESUM —The cumulative sum of the utility values for the core area. EDGE —The amount of edge using the P1 ratio, which is the ratio of the perimeter of the shape to the perimeter of a circle of the same area. The P1 ratio for a circle is 1.	Raster

Code sample

LocateRegions example 1 (Python window)

The following Python window script demonstrates how to use the LocateRegions tool.

import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
outRegions = LocateRegions("suitsurface", 13.5, "SQUARE_MILES", 5, "CIRCLE",
                           0, 50, "HIGHEST_AVERAGE_VALUE", 2, 5, 1, 3, "MILES",
                           "existingreg.shp", "EIGHT", "NO_ISLANDS", "SMALL", 
                           "LOW", "COMBINATORIAL")
outRegions.save("C:/sapyexamples/output/outregions")

LocateRegions example 2 (stand-alone script)

Identifies the optimum eight regions from a suitability surface while meeting the spatial requirements.

# Name: LocateRegions_Ex_02.py
# Description: Selects the best specified number of regions
# Requirements: Spatial Analyst Extension

# Import system modules
import arcpy
from arcpy import env
from arcpy.sa import *

# Set environment settings
env.workspace = "C:/sapyexamples/data"

# Set local variables
InRaster1 = "suitsurface"
InTotalArea2 = 13.5
InAreaUnits3 = "SQUARE_MILES"
InNumberofRegions4 = 5
InRegionShape5 = "CIRCLE"
InRegionOrientation6 = 0
InShapeTradeoff7 = 50
InEvaluationMethod8 = "HIGHEST_AVERAGE_VALUE"
InMinimumArea9 = 2
InMaximumArea10 = 5
InMinimumDistance11 = 1
InMaximumDistance12 = 3
InDistanceUnits13 = "MILES"
InExistingRegions14 = "existingreg.shp"
InRegionofNeighbors15 = "EIGHT"
InRegionNoIslands16 = "NO_ISLANDS"
InRegionSeeds17 = "SMALL"
InRegionResolution18 = "LOW"
InCombinatorialThreshold19 = "COMBINATORIAL"

# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")

# Execute Locate Regions
outRegions = LocateRegions(InRaster1, InTotalArea2, InAreaUnits3, InNumberofRegions4,
                           InRegionShape5, InRegionOrientation6, InShapeTradeoff7,
                           InEvaluationMethod8, InMinimumArea9, InMaximumArea10,
                           InMinimumDistance11, InMaximumDistance12, InDistanceUnits13,
                           InExistingRegions14, InRegionofNeighbors15, InRegionNoIslands16,
                           InRegionSeeds17, InRegionResolution18, InCombinatorialThreshold19)

# Save the output
outRegions.save("C:/sapyexamples/output/outregions")

Environments

Auto Commit, Cell Size, Cell Size Projection Method, Compression, Current Workspace, Extent, Geographic Transformations, Mask, Output CONFIG Keyword, Output Coordinate System, Raster Statistics, Scratch Workspace, Snap Raster, Tile Size

Licensing information

• Basic: Requires Spatial Analyst
• Standard: Requires Spatial Analyst
• Advanced: Requires Spatial Analyst