Skip To Content

Sample

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.

Learn more about how Sample works

Usage

  • Any combination of rasters (single band or multiband) can be specified as input.

  • A cell value will be extracted for each input raster. 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 carried over to the output table.

  • 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 a multidimensional raster is specified as an input raster, if the Process as multidientional option (ALL_SLICES for the process_as_multidimensional parameter in Python) is not checked, 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 multidientional option.

  • The types of multidimensional raster currently supported by this tool for multidimensional processing arenetCDF raster layers, multidimensional raster layers and multidimensional mosaic datasets. Image services of multidimensional data are currently not supported.

  • When the input location is a raster, the set of location cells consists of all cells that have a value of zero or greater. Cells that have NoData values are not included in the location set. A location raster can be easily created using the extraction tools.

  • When the location input is raster, for best results, the cell size and registration of the input rasters and the location raster should be the same.

  • Locations that sample NoData cells in the input raster, or rasters, will be given a <null> value in an output geodatabase table. For output to INFO or .dbf, since the concept of null is not supported, a value of -9999 will be given.

  • When the input rasters are two-dimensional, the field type of the sampled values in the output table is always floating point. This is to ensure that the appropriate degree of precision is retained if the bilinear or cubic options for the resampling technique were to be selected.

  • Multipoint datasets are not supported as input.

  • 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})
ParameterExplanationData 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, but be aware that INFO tables are not supported as input in ArcGIS Pro, and cannot be displayed.

Table
resampling_type
(Optional)

Resampling algorithm used when sampling a raster.

  • NEAREST Nearest neighbor assignment
  • BILINEAR Bilinear interpolation
  • CUBIC Cubic convolution
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.

  • ALL_SLICES Samples will be taken for all dimensions (such as time or depth) of a multidimensional dataset.
  • CURRENT_SLICESamples will be taken from the current slice of a multidimensional dataset. This is the default.
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"

# Execute Sample
Sample(inRasters, locations, outTable, sampMethod)

Licensing information

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

Related topics