Available with Spatial Analyst license.
Summary
Creates a table that shows the values of cells from a raster, or set of rasters, for defined locations. The locations are defined by raster cells or by a set of points.
The input rasters can be two-dimensional or multidimensional. The structure of the output table changes when the input rasters are multidimensional.
Usage
Cell values will be extracted from all input rasters at each location. A table will be created with fields containing the cell values for each input raster.
Additional attributes from the input raster table, if any, will not be included in the output table.
The input rasters will not be resampled honoring the analysis environment. Instead, the cell values are extracted from all input rasters in their original resolution and spatial reference by the projecting input locations to the raster's spatial reference from which values are extracted.
However, the analysis environment is applied to the input locations.
Locations that extract values from NoData cells in the input raster will be given a <null> value in the output table. For shapefiles, because null fields are not supported, NoData cells are instead represented in the table with a value of -9999.
Any combination of rasters (single band or multiband) can be specified as Input rasters (in_rasters in Python).
When a multiband raster is specified as one of the Input Rasters (in_rasters in Python), all of the bands in that input will be used.
To process a selection of bands from an input multiband raster, first create a new raster dataset composed of those particular bands with the Composite Bands tool. Use the result in the list of input rasters.
When the input location data is a raster, the center of each cell containing valid values (not NoData) is used to extract the cell values from all input rasters for that location.
If the input location data is a point feature class and it does not have a spatial index, a warning will be issued. To improve tool performance for large input point features, create a spatial index.
The tool will fail to execute with multipoint features. To perform analysis with multipoint features, first convert them to single point features before using it in the extraction tool. See processing multipoint data for more information.
The spatial reference of the x,y coordinates in the output sample table are the same as that of the Input location raster or point features (in_location_data in Python), unless it is specified in the Output Coordinate System environment. If the spatial reference of the input locations data is unknown, the spatial reference of the x,y coordinates is also unknown.
The spatial reference of the x,y coordinates is identified at the end of tool execution as a geoprocessing message.
Resampling technique (resampling_type in Python) option determines how the values will be obtained from the raster. The default option is Nearest, which extracts the exact cell value at the input locations. To extract interpolated values, specify the Bilinear or Cubic option.
The field type containing the cell values matches the raster type for the nearest option. However, to retain the precision of the interpolated values, the field type will always be floating point for the Bilinear or Cubic option. When the resampling option is set to Nearest, the field in the output table will match that of the raster type. However, in order to retain the precision of the interpolated values, the field type will always be floating point for the Bilinear or Cubic option.
A field named Sample_point is added to the output table to store the values specified in the Unique ID field (unique_id_field in Python). It is recommended to use a field containing unique values as the identifier for each location for further analysis.
When a multidimensional raster is specified as an input raster, and the Process as multidimensional parameter is not checked (ALL_SLICES for the process_as_multidimensional parameter in Python), only the current slice of the multidimensional raster will be sampled.
To extract values from all slices of all variables from the input multidimensional dataset, check the Process as multidimensional parameter.
If the Process as multidimensional parameter is checked (ALL_SLICES for the process_as_multidimensional parameter in Python), see the following occur.
The tool will process only one multidimensional raster. If more than one multidimensional raster is specified, only the first raster will be processed.
The extracted values are stored in a field with the same name as the variable. Additional fields are created to store the nonspatial dimension values with the same name as the dimension.
If the multidimensional raster has multiple bands, additional fields are not created for each band. Instead, the values extracted for the bands are stored in the variable field. An additional field is created for the dimension that was used to specify the band, to store the dimension values.
The types of multidimensional raster currently supported by this tool for multidimensional processing are netCDF raster layers and multidimensional mosaic datasets. Image services of multidimensional data can also be used, provided that the image service has been set up to permit it.
If a feature is specified in the Mask environment, an internal raster is created using the minimum of cell size of the input rasters. During extraction, the internal mask raster is again resampled to the cell size of each input raster.
See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.
Syntax
Sample(in_rasters, in_location_data, out_table, {resampling_type}, {unique_id_field}, {process_as_multidimensional})| Parameter | Explanation | Data Type |
in_rasters [in_raster,...] | The list of rasters whose values will be sampled based on the input location data. | Raster Layer |
in_location_data | Data identifying positions at which you want a sample taken. This can be a raster or a point feature dataset. | Raster Layer; Feature Layer |
out_table | Output table holding the sampled cell values. The format of the table is determined by the output location and path. By default, the output will be a geodatabase table. If the path is not in a geodatabase, the format is determined by the extension. If the extension is .dbf, it will be in dBASE format. If no extension is specified, the output will be an INFO table. | Table |
resampling_type (Optional) | Resampling algorithm used when sampling a raster.
| String |
unique_id_field (Optional) | A field containing a different value for every location or feature in the input location raster or point features. | Field |
process_as_multidimensional (Optional) | Determines how the input rasters are processed.
| Boolean |
Code sample
Sample example 1 (Python window)
Extract the cell values from multiple rasters to a table based on input locations.
import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
Sample(["elevation", "costraster"], "observers.shp",
"c:/sapyexamples/output/samptable","NEAREST")
Sample example 2 (stand-alone script)
Extract the cell values from multiple rasters to a table based on input locations.
# Name: Sample_Ex_02.py
# Description: Creates a table that shows the values of cells from
# a raster, or set of rasters, for defined locations.
# The locations are defined by raster cells or by a set
# of points.
# 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
inRasters = ["elevation",
"costraster"]
locations = "observers.shp"
outTable = "c:/sapyexamples/output/samptable02"
sampMethod = "NEAREST"
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
# Execute Sample
Sample(inRasters, locations, outTable, sampMethod)
Environments
Licensing information
- Basic: Requires Spatial Analyst
- Standard: Requires Spatial Analyst
- Advanced: Requires Spatial Analyst