| Label | Explanation | Data Type |
Input raster or feature region data | The input regions that are to be connected by the least-cost network. Regions can be defined by either a raster or a feature dataset. If the region input is a raster, the regions are defined by groups of contiguous (adjacent) cells of the same value. Each region must be uniquely numbered. The cells that are not part of any region must be NoData. The raster type must be integer, and the values can be either positive or negative. If the region input is a feature dataset, it can be either polygons, lines, or points. Polygon feature regions cannot be composed of multipart polygons. | Raster Layer; Feature Layer |
Input cost raster | A raster defining the impedance or cost to move planimetrically through each cell. The value at each cell location represents the cost-per-unit distance for moving through the cell. Each cell location value is multiplied by the cell resolution while also compensating for diagonal movement to obtain the total cost of passing through the cell. The values of the cost raster can be integer or floating point, but they cannot be negative or zero (you cannot have a negative or zero cost). | Raster Layer |
Output feature class | The output polyline feature class of the optimum (least-cost) network of paths necessary to connect each of the input regions. Each path (or line) is uniquely numbered, and additional fields in the attribute table store specific information about the path. Those fields include the following:
This information provides you insight into the paths within the network. Since each path is represented by a unique line, there will be multiple lines in locations where paths travel the same route. | Feature Class |
Output feature class of neighboring connections (Optional) | The output polyline feature class identifying all paths from each region to each of its closest-cost neighbors. Each path (or line) is uniquely numbered, and additional fields in the attribute table store specific information about the path. Those fields include the following:
This information provides you insight into the paths within the network and is particularly useful when deciding which paths should be removed if necessary. Since each path is represented by a unique line, there will be multiple lines in locations where paths travel the same route. | Feature Class |
Available with Spatial Analyst license.
Summary
Produces the least-cost connectivity network between two or more input regions.
Legacy:
This tool is deprecated and will be removed in a future release.
The Optimal Region Connections tool provides enhanced functionality or performance.
Illustration
Usage
The input regions can be either raster or feature data.
In a raster, a region is a group of cells with the same value that are contiguous to one another (adjacent). When your input regions are identified by a raster, if any zones (cells with the same value) are composed of multiple regions, first run the Region Group tool as a preprocessing step to assign unique values to each region. Use the resulting raster as the input regions to the Cost Connectivity tool.
When input regions are identified by polygon, line, or point data, they are converted to raster using the feature ID to ensure the resulting regions have unique values. Therefore, multipart polygons cannot be input. When multipoint data is entered, Cost Connectivity randomly selects one of the points at the location as the region value.
You can control the resolution of the rasterized input feature regions with the Cell Size environment. By default, the resolution will be set to the resolution of the input cost raster.
When using polygon feature data for the input region data, care must be taken with how the output cell size is handled when it is coarse, relative to the detail present in the input. The internal rasterization process employs the same default Cell assignment type method as the Polygon to Raster tool, which is Cell center. This means that data not located at the center of the cell will not be included in the intermediate rasterized region and so will not be represented in the distance calculations. For example, if your regions are a series of small polygons, such as building footprints that are small relative to the output cell size, it is possible that only a few of them will fall under the centers of the output raster cells, seemingly causing most of the others to be lost in the analysis.
To avoid this situation, as an intermediate step, you could rasterize the input features directly with the Polygon to Raster tool, set a Priority field, and use the resulting output as input to the Cost Connectivity tool. Alternatively, you could select a small enough cell size to capture the appropriate amount of detail from the input features.
When the region input is a feature, the ObjectID field (for example, OID or FID, depending on the type of the feature input) will be used as the region identifier.
If the input regions are raster and the range of the row IDs is very large (even if there are only a few regions), the performance of the tool may be negatively impacted.
Cell locations with NoData in the Input cost raster act as barriers.
The default processing extent is the same as that of the Input cost raster.
The cost raster cannot contain values of zero since the algorithm is a multiplicative process. If your cost raster does contain values of zero, and these values represent areas of lowest cost, change values of zero to a small positive value (such as 0.01) before running Cost Connectivity, by first running the Con tool. If areas with a value of zero represent areas that should be excluded from the analysis, these values should be turned to NoData before running Cost Connectivity, by first running the Set Null tool.
For Output feature class of neighboring connections, the neighbors are not identified by Euclidean distance but instead are identified by cost distance. Therefore, a region's closest neighbor is the cheapest one to travel to, not the one that is closest in distance. A cost allocation operation is performed to identify which regions are neighbors to one another.
The optimum output network is created from the paths produced in the optional neighboring connections output. The paths in the optional neighboring connections output are converted to graph theory. The regions are the vertices, the paths are the edges, and the accumulative costs are the weights for the edges. The minimum spanning tree is calculated from the graph representation of the paths to determine the least-cost path network necessary to travel between the regions.
Each least-cost path first reaches the outer boundary of the polygon or multicell region. From the perimeter of the region, the tool then continues the paths with additional line segments, allowing for points of entry and exit between regions, and movement within them. There is no additional cost of movement along these line segments.
The Cost Distance and Cost Path tools can be used to connect regions that are not directly connected in the minimum spanning tree based on a priori information. For example, a particular region may need an alternative escape route for fire fighters to evacuate from the region. Since the resulting paths from Cost Path only reach the edge of a region, if you want to use these additional paths in the integrated network to perform subsequent network analysis, you will need to extend these paths within the region to connect them to the paths in the minimum spanning tree network.
The optional neighboring connections output can be used as an alternative network to the minimum spanning tree network. This output connects each region to its neighboring cost regions, thus producing a more complex network with many paths. The feature class can be used as is, or as the base from which to create your own desired network. To do that, you can select the specific paths you want within the network using the Select By Attributes button or the Select group on the Map tab, or the Select geoprocessing tool. Deciding which paths to select can be based on knowledge of the area and the statistics associated with the paths in the resulting attribute table.
The resulting network, either from the minimum spanning tree or the optional neighboring connections, can be converted to a Network Analyst network to perform additional network analysis.
See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.
Parameters
CostConnectivity(in_regions, in_cost_raster, out_feature_class, {out_neighbor_paths})| Name | Explanation | Data Type |
in_regions | The input regions that are to be connected by the least-cost network. Regions can be defined by either a raster or a feature dataset. If the region input is a raster, the regions are defined by groups of contiguous (adjacent) cells of the same value. Each region must be uniquely numbered. The cells that are not part of any region must be NoData. The raster type must be integer, and the values can be either positive or negative. If the region input is a feature dataset, it can be either polygons, lines, or points. Polygon feature regions cannot be composed of multipart polygons. | Raster Layer; Feature Layer |
in_cost_raster | A raster defining the impedance or cost to move planimetrically through each cell. The value at each cell location represents the cost-per-unit distance for moving through the cell. Each cell location value is multiplied by the cell resolution while also compensating for diagonal movement to obtain the total cost of passing through the cell. The values of the cost raster can be integer or floating point, but they cannot be negative or zero (you cannot have a negative or zero cost). | Raster Layer |
out_feature_class | The output polyline feature class of the optimum (least-cost) network of paths necessary to connect each of the input regions. Each path (or line) is uniquely numbered, and additional fields in the attribute table store specific information about the path. Those fields include the following:
This information provides you insight into the paths within the network. Since each path is represented by a unique line, there will be multiple lines in locations where paths travel the same route. | Feature Class |
out_neighbor_paths (Optional) | The output polyline feature class identifying all paths from each region to each of its closest-cost neighbors. Each path (or line) is uniquely numbered, and additional fields in the attribute table store specific information about the path. Those fields include the following:
This information provides you insight into the paths within the network and is particularly useful when deciding which paths should be removed if necessary. Since each path is represented by a unique line, there will be multiple lines in locations where paths travel the same route. | Feature Class |
Code sample
The following Python window script demonstrates how to use the CostConnectivity tool.
import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
outOptRegConnect = OptimalRegionConnections("sources.shp", "cost_surface.tif")
outOptRegConnect.save("C:/sapyexamples/output/optregconnect.tif")Produces the least-cost optimum network of paths connecting the input regions to one another.
# Name: CostConnectivity_Ex_02.py
# Description: Calculates for least-cost connectivity network between 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
inSourceData = "sources.shp"
inCostRaster = "cost_surface.tif"
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
# Execute the tool
outOptRegConnect = OptimalRegionConnections(inSourceData, inCostRaster)
# Save the output
outOptRegConnect.save("C:/sapyexamples/output/optregconnect.tif")Environments
Licensing information
- Basic: Requires Spatial Analyst
- Standard: Requires Spatial Analyst
- Advanced: Requires Spatial Analyst