Available with Spatial Analyst license.
Summary
Calculates for each cell its nearest source based on the least accumulative cost over a cost surface.
Illustration
Usage
The input source data can be a feature class or raster.
When the input source data is a raster, the set of source cells consists of all cells in the source raster that have valid values. Cells that have NoData values are not included in the source set. The value 0 is considered a legitimate source. A source raster can be easily created using the extraction tools.
-
When the input source data is a feature class, the source locations are converted internally to a raster before performing the analysis. The resolution of the raster can be controlled 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 source 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 source output, and so will not be represented in the distance calculations. For example, if your sources 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 and set a Priority field, and use the resulting output as input to the Distance tool. Alternatively, you could select a small enough cell size to capture the appropriate amount of detail from the input features.
To calculate allocation, source locations can have an associated value, which can be specified by the Source field parameter. If the input source is an integer raster, the default field is VALUE. If it is a feature, it will be the first integer field in the attribute table. If the input source data is a floating point raster an integer value raster parameter must be specified.
When the source input is a feature, by default, the first valid available field will be used. If no valid fields exist, the ObjectID field (for example, OID or FID, depending on the type of feature input) will be used.
Cell locations with NoData in the Input cost raster act as barriers in the cost surface tools. Any cell location that is assigned NoData on the input cost surface will receive NoData on all output rasters (cost distance, allocation, and back link).
If the input source data and the cost raster are different extents, the default output extent is the intersection of the two. To get a cost distance surface for the entire extent, choose the Union of Inputs option on the output Extent environment settings.
If a Mask has been set in the environment, all masked cells will be treated as NoData values.
When a mask has been defined in the Raster Analysis window and the cells to be masked will mask a source, the calculations will occur on the remaining source cells. The source cells that are masked will not be considered in the computations. These cell locations will be assigned NoData on all outputs (distance, allocation, and back link) rasters.
The Input value raster is useful when alternative values or zones are to be used or if source was derived from a operation that results in a binary result of either 0 or 1, losing the original zone values that are associated with these locations. The value raster can restore these values or allow for analysis on additional combinations of zone values within the source locations.
If the value raster is used, it may change the configuration and results of the cost allocation output; it will not affect the optional cost distance or the back link results.
The Maximum distance is specified in the same cost units as those on the cost raster.
For the output distance raster, the least-cost distance (or minimum accumulative cost distance) of a cell to a set of source locations is the lower bound of the least-cost distances from the cell to all source locations.
See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.
Syntax
CostAllocation (in_source_data, in_cost_raster, {maximum_distance}, {in_value_raster}, {source_field}, {out_distance_raster}, {out_backlink_raster})| Parameter | Explanation | Data Type |
in_source_data |
The input source locations. This is a raster or feature dataset that identifies the cells or locations to which the least accumulated cost distance for every output cell location is calculated. For rasters, the input type can be integer or floating point. If the input source raster is floating point, the {in_value_raster} must be set, and it must be of integer type. The value raster will take precedence over any setting of the {source_field}. | 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 |
maximum_distance (Optional) | Defines the threshold that the accumulative cost values cannot exceed. If an accumulative cost distance value exceeds this value, the output value for the cell location will be NoData. The maximum distance defines the extent for which the accumulative cost distances are calculated. The default distance is to the edge of the output raster. | Double |
in_value_raster (Optional) |
The input integer raster that identifies the zone values that should be used for each input source location. For each source location (cell or feature), the value defined by the {in_value_raster} will be assigned to all cells allocated to the source location for the computation. The value raster will take precedence over any setting for the {source_field}. | Raster Layer |
source_field (Optional) | The field used to assign values to the source locations. It must be integer type. If the {in_value_raster} has been set, the values in that input will have precedence over any setting for the {source_field}. | Field |
out_distance_raster (Optional) | The output cost distance raster. The cost distance raster identifies, for each cell, the least accumulative cost distance over a cost surface to the identified source locations. A source can be a cell, a set of cells, or one or more feature locations. The output raster is of floating point type. | Raster Dataset |
out_backlink_raster (Optional) | The output cost back-link raster. The back-link raster contains values of 0 through 8, which define the direction or identify the next neighboring cell (the succeeding cell) along the least accumulative cost path from a cell to reach its least cost source. If the path is to pass into the right neighbor, the cell will be assigned the value 1, 2 for the lower right diagonal cell, and continuing clockwise. The value 0 is reserved for source cells.  | Raster Dataset |
Return Value
| Name | Explanation | Data Type |
| out_allocation_raster | The output cost allocation raster. This raster identifies the zone of each source location (cell or feature) that could be reached with the least accumulative cost. The output raster is of integer type. | Raster |
Code Sample
CostAllocation example 1 (Python window)
The following Python Window script demonstrates how to use the CostAllocation tool.
import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
out = ()
costAllocOut = CostAllocation("observers.shp", "costraster", 25000,"elevation",
"FID", "c:/sapyexamples/output/distout",
"c:/sapyexamples/output/backlinkout")
costAllocOut.save("c:/sapyexamples/output/costalloc")
CostAllocation example 2 (stand-alone script)
This script uses a cost raster, a feature layer of source points, and several optional parameter to calculate a raster of cells which contain the value of the nearest source.
# Name: CostAllocation_Ex_02.py
# Description: Calculates for each cell its nearest source
# based on the least accumulative cost over a
# cost surface.
# 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
inFeature = "observers.shp"
costRaster = "costraster"
maxDist = 25000
valRaster = "elevation"
featField = "FID"
outDistanceRaster = "c:/sapyexamples/output/distout"
outBacklink = "c:/sapyexamples/output/backlinkout"
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
# Execute CostAllocation
costAllocOut = CostAllocation(inFeature, costRaster, maxDist,
valRaster, featField, outDistanceRaster,
outBacklink)
# Save the output
costAllocOut.save("c:/sapyexamples/output/costalloc01")
Environments
Licensing Information
- ArcGIS for Desktop Basic: Requires Spatial Analyst
- ArcGIS for Desktop Standard: Requires Spatial Analyst
- ArcGIS for Desktop Advanced: Requires Spatial Analyst