Cost Allocation (Spatial Analyst)

License Level:BasicStandardAdvanced

Summary

Calculates for each cell its nearest source based on the least accumulative cost over a cost surface.

Learn more about how Cost distance tools work

Illustration

Cost Allocation illustration
Cost_Alloc = CostAllocation(Source_Ras, Cost_Ras)

Usage

Syntax

CostAllocation (in_source_data, in_cost_raster, {maximum_distance}, {in_value_raster}, {source_field}, {out_distance_raster}, {out_backlink_raster})
ParameterExplanationData 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.

Back-link positions
Raster Dataset

Return Value

NameExplanationData 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

Related Topics

Licensing Information

ArcGIS for Desktop Basic: Requires Spatial Analyst
ArcGIS for Desktop Standard: Requires Spatial Analyst
ArcGIS for Desktop Advanced: Requires Spatial Analyst
11/8/2012