Available with Spatial Analyst license.
Available with Image Analyst license.
Summary
Creates a table or a point feature class that shows the values of cells from a raster, or a set of rasters, for defined locations. The locations are defined by raster cells, points, polylines, or polygons.
Usage
Cell values will be extracted from all Input rasters (in_rasters in Python) at each location. A table or a point feature class 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.
Any combination of rasters (single band or multiband) can be specified for the input rasters. The structure of the output table changes automatically when the input rasters are multidimensional.
When a multiband raster is specified as one of the Input rasters, all of the bands in that input will be used.
The following can be used as Input location raster or features (in_location_data in Python) parameter values:
- Raster—Cells containing valid values (not NoData) will be used to extract the cell values from all input rasters, and the center of the cell will be used as point locations.
- Point—Values will be sampled at each point location.
- Polyline or polygon—The mean value of all cells that intersect each polyline or polygon will be calculated if the input is a two-dimensional raster or multiple rasters. Additional statistic types can be specified if the input is a multidimensional raster and is processed as multidimensional.
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.
The Input rasters are sampled in their native spatial reference and resolution. If there are multiple input rasters with different spatial references, the input locations are first projected to the spatial reference of each raster individually; then the values are extracted. This means that while the input rasters will not honor any analysis environment settings, the appropriate environments will be applied to the input locations.
By default, the spatial reference of the x,y coordinates in the Output table or feature class (out_table in Python) parameter will be the same as that of the Input location raster or features parameter values, unless a different one 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 reported at the end of tool execution as a geoprocessing message.
If the Input location raster or features is a point feature class with no spatial index, a warning will be issued. To improve tool performance for an input with a large number of points, create a spatial index. See Add spatial index for more information.
The tool will fail to execute with multipoint features. To perform analysis with multipoint features, convert them to single point features before using them in the extraction tool. See processing multipoint data for more information.
When the Resampling technique parameter is set to Nearest (resampling_type = "NEAREST" in Python), the field type in the output table will match that of the raster type. When the resampling option is Bilinear or Cubic, the field type will always be floating point to maintain the precision of the interpolated values.
A field will be added to the output table to store the values specified in the Unique ID field parameter (unique_id_field in Python). By default, the name of the field is the same as the input location dataset name. It is recommended that you use a field containing unique values as the identifier for each location for further analysis.
If the Process as multidimensional parameter is unchecked (process_as_multidimensional = "CURRENT_SLICE" in Python), the following conditions will apply:
- If the input is a multidimensional raster, only the current slice will be sampled.
- If the input is a multivariate raster, only the current variable will be sampled.
If the Process as multidimensional parameter is checked (process_as_multidimensional = "ALL_SLICES" in Python), the following conditions will apply:
- If the input is a multidimensional raster, all the slices will be sampled.
- If the input is a multivariate raster, all the variables will be sampled.
- If the input is a multidimensional raster with multiple variables, all slices from all variables will be sampled. The variables must have the same dimensions.
If the Process as multidimensional parameter is checked (process_as_multidimensional = "ALL_SLICES" in Python), the appropriate scenario from the following will apply:
The Acquisition information of location data parameter (acquisition_definition in Python) will be used to specify the subset of the input raster to use for sampling.
When dimension, start value, and end value are specified, the slices within the start and end values are processed. The default end value is the maximum dimension value. For a time dimension, specify the value in the standard format. For other dimensions, specify the value in the same unit as that of the input raster.
When dimension, start field, and end field are specified (start field and end field come from the location data), values from these fields are used to specify a subset of the input raster while sampling values at that location.
The Relative value or days before and Relative value or days after values can be used to specify a subset relative to the start value, in which the before value specifies the beginning of the subset and the after value specifies the end of the subset. The time values are specified in days and the other dimension values are specified in the same unit as that of the input raster.
The Statistic type parameter (statistics_type in Python) aggregates the values of the Input raster parameter as specified by the subset in the Acquisition information of location data parameter.
If the Column-wise layout parameter is unchecked (layout = "ROW_WISE" in Python), 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 Column-wise layout parameter is checked (layout = "COLUMN_WISE" in Python), the extracted values are stored in fields with names that follow a <variable_name>_<dimension_name>_<dimension_value> convention. Note that the Column-wise layout parameter is supported when the multidimensional raster contains only one variable, the variable has only one dimension, and each slice has a single band. Otherwise, an error message will be generated.
If the multidimensional raster has multiple bands, an additional field is created for each band, which stores the value extracted from that band.
Locations that extract values from NoData cells will be assigned the NoData value from the input multidimensional raster.
A multidimensional raster can be a netCDF raster layer, multidimensional raster layer, multidimensional mosaic dataset, multidimensional CRF, multidimensional image service, or netCDF file. You cannot browse to a netCDF file from the tool dialog box, but you can specify the path to file.
If the Generate Feature Class parameter is checked (generate_feature_class = "FEATURE_CLASS" in Python), the output is a point feature class with the sampled values in its attribute table. The following are the possible location types with descriptions of how the values will be sampled:
- Raster—Points will be created using the location of the cell center.
- Point—A point will be created at each of the point locations.
- Polyline or polygon—A point will be created at each polygon or polyline centroid.
The spatial reference of the output feature class is the same as that of the Input location raster or features, unless it is specified in the Output Coordinate System environment.
The Parallel Processing Factor environment is only supported when the Process as multidimensional parameter is checked.
If a feature is specified in the Mask environment, an internal raster is created using the minimum 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}, {acquisition_definition}, {statistics_type}, {percentile_value}, {buffer_distance}, {layout}, {generate_feature_class})| Parameter | Explanation | Data Type |
in_rasters [in_raster,...] | The rasters with values that will be sampled based on the input location data. The process_as_multidimensional parameter is only supported when the input is a single, multidimensional raster. | Raster Layer |
in_location_data | The data identifying positions where a sample will be taken. The input can be a raster or a feature class. | Raster Layer; Feature Layer |
out_table | The output table or feature class containing the sampled cell values. The output format is determined by the output location and path. By default, the output will be a geodatabase table or a geodatabase feature class in a geodatabase workspace or a dBASE table or a shapefile feature class in a folder workspace. The output data type to generate a table or a feature class is controlled by the generate_feature_class parameter. | Table; Point feature class |
resampling_type (Optional) | The resampling algorithm that will be used to sample a raster to determine how the values will be obtained from the raster.
| String |
unique_id_field (Optional) | A field containing a different value for every location or feature in the input location raster or features. | Field |
process_as_multidimensional (Optional) | Specifies how the input rasters will be processed. This parameter is only available when the input is a single, multidimensional raster.
| Boolean |
acquisition_definition [acquisition_definition,...] (Optional) | Specifies the time, depth, or other acquisition data associated with the location features. Only the following combinations are supported:
Relative value or days before and Relative value or days after only support nonnegative values. Statistics will be calculated using the statistics_type parameter for variables within this dimension range. | Value Table |
statistics_type (Optional) | Specifies the statistic type to be calculated.
| String |
percentile_value (Optional) | The percentile to calculate when the Statistics Type parameter is set to Percentile. The percentile to calculate when the statistics_type parameter is set to PERCENTILE. This value can range from 0 to 100. The default is 90. | Double |
buffer_distance (Optional) | The distance around the location data features. The buffer distance is specified in the linear unit of the location feature's spatial reference. If the feature uses a geographic reference, the unit will be degrees. Statistics will be calculated within this buffer area. | Double; Field |
layout (Optional) | Specifies whether sampled values will appear in rows or columns in the output table.
| Boolean |
generate_feature_class (Optional) | Specifies whether a point feature class with sampled values in its attribute table or a table with sampled values will be generated.
| Boolean |
Code sample
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.dbf")Extract the cell values from multiple rasters to a table based on input locations.
# Name: Sample_Ex_02.py
# Description: Creates a feature class that shows the values of cells from
# rasters, for defined locations.
# The locations are defined by a set of points.
# Sampling method is Bilinear.
# Requirements: Spatial Analyst Extension
# Import system modules
import arcpy
from arcpy import env
from arcpy.sa import *
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
# Set the analysis environments
env.workspace = "C:/sapyexamples/data"
# Set local variables
inRasters = ["elevation",
"costraster"]
locations = "observers.shp"
outFeatureClass = "c:/sapyexamples/output/samptable02.shp"
sampMethod = "BILINEAR"
generate_feature_class = "FEATURE_CLASS"
# Execute Sample
Sample(inRasters, locations, outFeatureClass, sampMethod, "", "", "", "", "", "", "", generate_feature_class)Extract the cell values from multiple rasters to a table based on input locations.
# Name: Sample_Ex_03.py
# Description: Creates a table that shows the temperature values from
# a multidimensional raster, for defined locations.
# Each temperature has a unique OBSERVATION_ID
# Sampling method is Bilinear
# Requirements: Spatial Analyst Extension
# Import system modules
import arcpy
from arcpy import env
from arcpy.sa import *
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
# Set the analysis environments
env.workspace = "C:/sapyexamples/data"
# Set local variables
inRasters = "temperature_1990_2019.nc"
locations = "observers.shp"
outTable = "C:/sapyexamples/output/samptable_03.dbf"
sampMethod = "BILINEAR"
uniqueIDField = "OBSERVATION_ID"
process_as_multidimensional = True
# Execute Sample
# the temperature value at each slice in temperature_1990_2019.nc will be extracted for each point
Sample(inRasters, locations, outTable, sampMethod, uniqueIDField, process_as_multidimensional)Extract the cell values from multiple rasters to a table based on input locations.
# Name: Sample_Ex_04.py
# Description: Creates a table that shows, for each polygon, the maximum temperature value within the period [1999-01-01T00:00:00 , 2019-01-01-T00:00:00]
# Requirements: Spatial Analyst Extension
# Import system modules
import arcpy
from arcpy import env
from arcpy.sa import *
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
# Set environment settings
env.workspace = "C:/sapyexamples/data"
# Set local variables
inRasters = "temperature_1990_2019.nc"
locations = "observers_polygons.shp"
outTable = "C:/sapyexamples/output/samptable_04.dbf"
sampMethod = "BILINEAR"
uniqueIDField = "OBSERVATIONID"
process_as_multidimensional = True
# StdTime in acquisition_definition is the name of the dimension in inRasters that are related with time
# 1999-01-01T00:00:00 in acquisition_definition is the start time of the period
# 2019-01-01-T00:00:00 in acquisition_definition is the end time of the period
acquisition_definition = "StdTime 1999-01-01T00:00:00 2019-01-01-T00:00:00"
statistic_method = "MAXIMUM"
# Execute Sample
# for each polygon in locations, the maximum temperature value within the period [1999-01-01T00:00:00 , 2019-01-01-T00:00:00] will be extracted
Sample(inRasters, locations, outTable, sampMethod, uniqueIDField, process_as_multidimensional, acquisition_definition, statistic_method)Environments
Licensing information
- Basic: Requires Spatial Analyst or Image Analyst or
- Standard: Requires Spatial Analyst or Image Analyst or
- Advanced: Requires Spatial Analyst or Image Analyst or