Echantillon (ArcGIS Spatial Analyst)

Synthèse

Crée une table ou une classe d’entités ponctuelles indiquant les valeurs des cellules d’un raster ou d’un jeu de rasters, pour des localisations définies. Les localisations sont définies par cellules de raster, points, polylignes ou polygones.

Pour en savoir plus sur le Fonctionnement de l'outil Echantillon

Utilisation

  • Les valeurs de cellule seront extraites de tous les éléments Input rasters (Rasters en entrée) (in_rasters en Python) à chaque emplacement. Une table ou une classe d’entités ponctuelles est créée avec des champs contenant les valeurs de cellule pour chaque raster en entrée.

  • Les éventuels attributs supplémentaires de la table raster en entrée ne seront pas inclus dans la table en sortie.

  • Vous pouvez définir n’importe quelle combinaison de rasters (monocanal ou multicanal) comme rasters en entrée. La structure de la table en sortie change automatiquement lorsque les rasters en entrée sont multidimensionnels.

    Lorsqu’un raster multicanal est spécifié comme un des éléments Input rasters (Rasters en entrée), tous les canaux de cette entrée sont utilisés.

  • Les éléments suivants peuvent être utilisés comme valeurs de paramètre Input location raster or features (Raster de localisation ou entités en entrée) (in_location_data en Python) :

    • Raster : les cellules contenant des valeurs valides (pas NoData) sont utilisées pour extraire les valeurs de cellule de tous les rasters en entrée, et le centre de la cellule est utilisé en tant que localisation de points.
    • Point : les valeurs sont échantillonnées à chaque localisation de point.
    • Polyligne ou polygone : la valeur moyenne de toutes les cellules qui intersectent chaque polyligne ou polygone est calculée si l’entrée est un raster bidimensionnel ou plusieurs rasters. Des types de statistiques supplémentaires peuvent être spécifiés si l’entrée est un raster multidimensionnel et est traitée en tant que tel.

  • Les localisations qui extraient les valeurs des cellules NoData dans le raster en entrée ont la valeur <null> dans la table en sortie. Pour les shapefiles, étant donné que les champs Null ne sont pas pris en charge, des cellules NoData sont représentées à la place dans la table avec la valeur -9999.

  • Les éléments Input rasters (Rasters en entrée) sont échantillonnés dans leurs référence spatiale et résolution natives. S’il existe plusieurs rasters en entrée avec différentes références spatiales, les localisations en entrée sont d’abord projetées sur la référence spatiale de chaque raster individuellement ; les valeurs sont ensuite extraites. En effet, alors que les rasters en entrée ne respectent pas les paramètres d’environnement d’analyse, les environnements appropriés sont appliqués aux localisations en entrée.

  • Par défaut, la référence spatiale des coordonnées x,y dans le paramètre Output table or feature class (Table ou classe d’entités en sortie) (out_table en Python) est identique à celle des valeurs de paramètre Input location raster or features (Raster de localisation ou entités en entrée), sauf si une autre est spécifiée dans l’environnement Output Coordinate System (Système de coordonnées en sortie). Si la référence spatiale des données d’emplacements en entrée est inconnue, la référence spatiale des coordonnées x,y est également inconnue.

    La référence spatiale des coordonnées x,y est indiquée à la fin de l’exécution de l’outil sous forme de message de géotraitement.

  • Si le paramètre Input location raster or features (Raster de localisation ou entités en entrée) est une classe d’entités ponctuelles sans index spatial, un avertissement est émis. Pour améliorer les performances de l’outil d’une entrée comportant un nombre élevé de points, créez un index spatial. Pour plus d’informations, reportez-vous à la rubrique Ajouter un index spatial.

  • L’exécution de l’outil avec des entités multi-points échoue. Pour effectuer une analyse avec des entités multi-points, convertissez ces dernières en entités ponctuelles uniques avant de les utiliser dans l’outil d’extraction. Reportez-vous à la rubrique Traitement des données multi-points pour plus d’informations.

  • Lorsque le paramètre Resampling technique (Méthode de rééchantillonnage) est défini sur Nearest (Le plus proche) (resampling_type = "NEAREST" en Python), le type de champ dans la table en sortie correspond à celui du type raster. Lorsque l’option de rééchantillonnage est définie sur Bilinear (Bilinéaire) ou sur Cubic (Cubique), le champ est toujours de type virgule flottante afin de conserver la précision des valeurs interpolées.

  • Un champ est ajouté à la table en sortie afin de stocker les valeurs spécifiées dans le paramètre Unique ID field (Champ d’ID unique) (unique_id_field en Python). Par défaut, le nom du champ est identique au nom du jeu de données de localisation en entrée. Il est recommandé d’utiliser un champ qui contient des valeurs uniques comme identifiant de chaque localisation en vue d’une analyse future.

  • Si le paramètre Process as multidimensional (Traiter comme multidimensionnel) est désactivé (process_as_multidimensional = "CURRENT_SLICE" en Python), les conditions suivantes s’appliquent :

    • Si l’entrée est un raster multidimensionnel, seule la tranche actuelle est échantillonnée.
    • Si l’entrée est un raster multivarié, seule la variable actuelle est échantillonnée.

  • Si le paramètre Process as multidimensional (Traiter comme multidimensionnel) est activé (process_as_multidimensional = "ALL_SLICES" en Python), les conditions suivantes s’appliquent :

    • Si l’entrée est un raster multidimensionnel, toutes les tranches sont échantillonnées.
    • Si l’entrée est un raster multivarié, toutes les variables sont échantillonnées.
    • Si l’entrée est un raster multidimensionnel avec plusieurs variables, toutes les tranches de toutes les variables sont échantillonnées. Les variables doivent avoir les mêmes dimensions.

  • Si le paramètre Process as multidimensional (Traiter comme multidimensionnel) est désactivé (process_as_multidimensional = "ALL_SLICES" en Python), le scénario approprié parmi les suivants s’applique :

    • Le paramètre Acquisition information of location data (Informations d’acquisition des données de localisation) (acquisition_definition en Python) est utilisé pour spécifier le sous-ensemble du raster en entrée à utiliser pour l’échantillonnage.

      • Lorsque la dimension, la valeur de départ et la valeur de fin sont spécifiées, les tranches comprises entre les valeurs de départ et de fin sont traitées. La valeur de fin par défaut est la valeur de dimension maximale. Dans le cas d’une dimension temporelle, indiquez la valeur au format standard. Pour les autres dimensions, spécifiez la valeur dans la même unité que celle du raster en entrée.

      • Lorsque la dimension, le champ de début et le champ de fin sont spécifiés (le champ de début et le champ de fin proviennent des données de localisation), les valeurs de ces champs sont utilisées pour préciser un sous-ensemble du raster en entrée avec des valeurs d’échantillonnage à cette localisation.

      • Les valeurs de Relative value or days before (Valeur relative ou jours avant) et de Relative value or days after (Valeur relative ou jours après) permettent de spécifier un sous-ensemble relatif à la valeur de début, dans lequel la valeur avant indique le début du sous-ensemble et la valeur après la fin du sous-ensemble. Les valeurs temporelles sont indiquées en jours et les valeurs des autres dimensions sont spécifiées dans la même unité que celle du raster en entrée.

    • Le paramètre Statistic type (Type de statistique) (statistics_type en Python) agrège les valeurs du paramètre Input raster (Raster en entrée) tel qu’indiqué par le sous-ensemble dans le paramètre Acquisition information of location data (Informations d’acquisition des données de localisation).

    • Si le paramètre Column-wise layout (Mise en page en colonnes) est désactivé (layout = "ROW_WISE" en Python), les valeurs extraites sont stockées dans un champ portant le même nom que la variable. Des champs supplémentaires sont créés pour stocker les valeurs de dimensions non spatiales portant le même nom que la dimension.

    • Si le paramètre Column-wise layout (Mise en page en colonnes) est activé (layout = "COLUMN_WISE" en Python), les valeurs extraites sont stockées dans des champs portant des noms qui respectent une convention <variable_name>_<dimension_name>_<dimension_value>. Veuillez noter que le paramètre Column-wise layout (Mise en page en colonnes) est pris en charge lorsque le raster multidimensionnel contient une seule variable, que la variable n’a qu’une dimension et que chaque tranche est monocanale. Dans le cas contraire, un message d’erreur est généré.

    • Si le raster multidimensionnel contient plusieurs canaux, un champ supplémentaire est créé pour chaque canal, dans lequel est stockée la valeur extraite de ce canal.

    • La valeur NoData du raster multidimensionnel en entrée est affectée aux localisations qui extraient les valeurs des cellules NoData.

  • Un raster multidimensionnel peut être une couche raster netCDF, une couche raster multidimensionnelle, unjeu de données mosaïque multidimensionnel, un format CRF multidimensionnel, un service d’imagerie multidimensionnelle ou un fichier netCDF. Vous ne pouvez pas accéder à un fichier netCDF à partir de la boîte de dialogue d’un outil, mais vous pouvez spécifier le chemin d’accès au fichier.

  • Si le paramètre Generate Feature Class (Générer une classe d’entités) est activé (generate_feature_class = "FEATURE_CLASS" en Python), la sortie est une classe d’entités ponctuelles dont la table attributaire contient les valeurs échantillonnées. Voici les types de localisations possibles, ainsi que les descriptions du mode d’échantillonnage des valeurs :

    • Raster : des points sont créés avec la localisation du centre de cellule.
    • Point : un point est créé à chaque localisation de point.
    • Polyligne ou polygone : un point est créé à chaque centroïde de polygone ou de polyligne.

  • La référence spatiale de la classe d’entités en sortie est identique à celle des éléments Input location raster or features (Raster de localisation ou entités en entrée), sauf si elle est spécifiée dans l’environnement Output Coordinate System (Système de coordonnées en sortie).

  • L’environnement Parallel Processing Factor (Facteur de traitement parallèle) est seulement pris en charge si le paramètre Process as multidimensional (Traiter comme multidimensionnel) est activé.

  • Si une entité est spécifiée dans l’environnement Mask (Masque), un raster interne est créé avec la taille de cellule minimale des rasters en entrée. Lors de l’extraction, le raster de masque interne est à nouveau rééchantillonné sur la taille de cellule de chaque raster en entrée.

  • Pour plus d’informations sur les environnements de géotraitement qui s’appliquent à cet outil, reportez-vous à la rubrique Environnements d’analyse et Spatial Analyst.

Paramètres

ÉtiquetteExplicationType de données
Rasters en entrée

Rasters dont les valeurs sont échantillonnées en fonction des données de localisation en entrée.

Le paramètre Process as multidimensional (Traiter comme multidimensionnel) est uniquement disponible lorsque l’entrée est un raster multidimensionnel unique.

Raster Layer
Raster de localisation ou entités en entrée

Données identifiant les positions où un échantillon sera prélevé.

L’entrée peut être un raster ou une classe d’entités.

Raster Layer; Feature Layer
Table ou classe d’entités en sortie

Table ou classe d’entités en sortie contenant les valeurs de cellules échantillonnées.

Le format en sortie est déterminé par l’emplacement et le chemin d’accès en sortie. Par défaut, la sortie est une table ou une classe d’entités de géodatabase dans un espace de travail de géodatabase, ou une table dBASE ou une classe d’entités de shapefile dans un espace de travail de dossier.

Le type de données en sortie pour générer une table ou une classe d’entités est contrôlé par le paramètre Generate feature class (Générer une classe d’entités).

Table; Point feature class
Méthode de rééchantillonnage
(Facultatif)

Algorithme de rééchantillonnage qui sera utilisé pour échantillonner un raster afin de déterminer la façon dont les valeurs seront obtenues à partir du raster.

  • Les plus prochesL’affectation par le voisin le plus proche est utilisée. Il s’agit de l’option par défaut.
  • BilinéaireL’interpolation bilinéaire est utilisée.
  • CubiqueLa convolution cubique est utilisée.
String
Champ d'ID unique
(Facultatif)

Champ qui contient une valeur différente pour chaque localisation ou entité du raster de localisation ou des entités en entrée.

Field
Traiter comme multidimensionnel
(Facultatif)

Spécifie le mode de traitement des rasters en entrée.

Ce paramètre est uniquement disponible lorsque l’entrée est un raster multidimensionnel unique.

  • Désactivé : les échantillons seront traités à partir de la tranche actuelle d’un jeu de données multidimensionnelles. Il s’agit de l’option par défaut.
  • Activé : les échantillons seront traités pour toutes les dimensions (temps ou profondeur, par exemple) d’un jeu de données multidimensionnelles.
Boolean
Informations d’acquisition des données d’emplacement
(Facultatif)

Spécifie la durée, la profondeur ou d’autres données d’acquisition associées aux entités de localisation.

Seules les combinaisons suivantes sont prises en charge :

  • Dimension + Champ ou valeur de début
  • Dimension + Champ ou valeur de début + Champ ou valeur de fin
  • Dimension + Champ ou valeur de début + Valeur relative ou nombre de jours avant + Valeur relative ou nombre de jours après

Les paramètres Relative value or days before (Valeur relative ou jours avant) et Relative value or days after (Valeur relative ou jours après) prennent uniquement en charge les valeurs non négatives.

Les statistiques sont calculées à l’aide du paramètre Statistics type (Type de statistiques) pour les variables incluses dans cette plage de dimensions.

Value Table
Type de statistique
(Facultatif)

Spécifie le type de statistique à calculer.

  • MinimumLa valeur minimale dans la plage spécifiée est calculée.
  • MaximumLa valeur maximale dans la plage spécifiée est calculée.
  • MédianeLa valeur médiane dans la plage spécifiée est calculée.
  • MoyenneLa moyenne pour la plage spécifiée est calculée.
  • SommeLa valeur totale des variables dans la plage spécifiée est calculée.
  • MajoritéLa valeur qui survient le plus fréquemment est calculée.
  • MinoritéLa valeur qui survient le moins souvent est calculée.
  • Écart typeL’écart type est calculé.
  • PourcentageUn centile défini dans la plage spécifiée est calculé.
String
Valeur du centile
(Facultatif)

Cette valeur peut être comprise entre 0 et 100. La valeur par défaut est 90.

Double
Champ ou valeur de distance de la zone tampon
(Facultatif)

Distance autour des entités de données d’emplacement. La distance de la zone tampon est exprimée dans l’unité linéaire de la référence spatiale de l’entité d’emplacement. Si l’entité utilise une référence géographique, l’unité sont les degrés.

Les statistiques sont calculées dans cette zone tampon.

Double; Field
Mise en page en colonnes
(Facultatif)

Spécifie si les valeurs échantillonnées apparaissent sur des lignes ou dans des colonnes dans la table en sortie.

  • Désactivé : les valeurs échantillonnées apparaissent sur des lignes distinctes dans la table en sortie. Il s’agit de l’option par défaut.
  • Activé : les valeurs échantillonnées apparaissent dans des colonnes distinctes dans la table en sortie. Cette option est uniquement valable lorsque le raster multidimensionnel en entrée contient une variable et une dimension, et que chaque tranche est un raster monocanal.
Boolean
Generate feature class (Générer une classe d’entités)
(Facultatif)

Indique si une classe d’entités ponctuelles est générée avec des valeurs échantillonnées dans sa table attributaire ou si une table avec des valeurs échantillonnées est générée.

  • Désactivé : une table avec des valeurs échantillonnées est générée. Il s’agit de l’option par défaut.
  • Activé : une classe d’entités ponctuelles avec des valeurs échantillonnées dans sa table attributaire est générée.
Boolean

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})
NomExplicationType de données
in_rasters
[in_raster,...]

Rasters dont les valeurs sont échantillonnées en fonction des données de localisation en entrée.

Le paramètre process_as_multidimensional est uniquement pris en charge lorsque l’entrée est un raster multidimensionnel unique.

Raster Layer
in_location_data

Données identifiant les positions où un échantillon sera prélevé.

L’entrée peut être un raster ou une classe d’entités.

Raster Layer; Feature Layer
out_table

Table ou classe d’entités en sortie contenant les valeurs de cellules échantillonnées.

Le format en sortie est déterminé par l’emplacement et le chemin d’accès en sortie. Par défaut, la sortie est une table ou une classe d’entités de géodatabase dans un espace de travail de géodatabase, ou une table dBASE ou une classe d’entités de shapefile dans un espace de travail de dossier.

Le type de données en sortie pour générer une table ou une classe d’entités est contrôlé par le paramètre generate_feature_class.

Table; Point feature class
resampling_type
(Facultatif)

Algorithme de rééchantillonnage qui sera utilisé pour échantillonner un raster afin de déterminer la façon dont les valeurs seront obtenues à partir du raster.

  • NEARESTL’affectation par le voisin le plus proche est utilisée. Il s’agit de l’option par défaut.
  • BILINEARL’interpolation bilinéaire est utilisée.
  • CUBICLa convolution cubique est utilisée.
String
unique_id_field
(Facultatif)

Champ qui contient une valeur différente pour chaque localisation ou entité du raster de localisation ou des entités en entrée.

Field
process_as_multidimensional
(Facultatif)

Spécifie le mode de traitement des rasters en entrée.

Ce paramètre est uniquement disponible lorsque l’entrée est un raster multidimensionnel unique.

  • ALL_SLICESLes échantillons seront traités pour toutes les dimensions (temps ou profondeur, par exemple) d’un jeu de données multidimensionnelles.
  • CURRENT_SLICELes échantillons seront traités à partir de la tranche actuelle d’un jeu de données multidimensionnelles. Il s’agit de l’option par défaut.
Boolean
acquisition_definition
[acquisition_definition,...]
(Facultatif)

Spécifie la durée, la profondeur ou d’autres données d’acquisition associées aux entités de localisation.

Seules les combinaisons suivantes sont prises en charge :

  • Dimension + Champ ou valeur de début
  • Dimension + Champ ou valeur de début + Champ ou valeur de fin
  • Dimension + Champ ou valeur de début + Valeur relative ou nombre de jours avant + Valeur relative ou nombre de jours après

Relative value or days before et Relative value or days after prennent uniquement en charge les valeurs non négatives.

Les statistiques sont calculées à l’aide du paramètre statistics_type pour les variables incluses dans cette plage de dimensions.

Value Table
statistics_type
(Facultatif)

Spécifie le type de statistique à calculer.

  • MINIMUMLa valeur minimale dans la plage spécifiée est calculée.
  • MAXIMUMLa valeur maximale dans la plage spécifiée est calculée.
  • MEDIANLa valeur médiane dans la plage spécifiée est calculée.
  • MEANLa moyenne pour la plage spécifiée est calculée.
  • SUMLa valeur totale des variables dans la plage spécifiée est calculée.
  • MAJORITYLa valeur qui survient le plus fréquemment est calculée.
  • MINORITYLa valeur qui survient le moins souvent est calculée.
  • STDL’écart type est calculé.
  • PERCENTILEUn centile défini dans la plage spécifiée est calculé.
String
percentile_value
(Facultatif)

Pourcentage à calculer lorsque le paramètre Statistics Type (Type de statistique) est défini sur Percentile (Centile).

Centile à calculer lorsque le paramètre statistics_type est défini sur PERCENTILE.

Cette valeur peut être comprise entre 0 et 100. La valeur par défaut est 90.

Double
buffer_distance
(Facultatif)

Distance autour des entités de données d’emplacement. La distance de la zone tampon est exprimée dans l’unité linéaire de la référence spatiale de l’entité d’emplacement. Si l’entité utilise une référence géographique, l’unité sont les degrés.

Les statistiques sont calculées dans cette zone tampon.

Double; Field
layout
(Facultatif)

Spécifie si les valeurs échantillonnées apparaissent sur des lignes ou dans des colonnes dans la table en sortie.

  • ROW_WISELes valeurs échantillonnées apparaissent sur des lignes distinctes dans la table en sortie. Il s’agit de l’option par défaut.
  • COLUMN_WISELes valeurs échantillonnées apparaissent dans des colonnes distinctes dans la table en sortie. Cette option est uniquement valable lorsque le raster multidimensionnel en entrée contient une variable et une dimension, et que chaque tranche est un raster monocanal.
Boolean
generate_feature_class
(Facultatif)

Indique si une classe d’entités ponctuelles est générée avec des valeurs échantillonnées dans sa table attributaire ou si une table avec des valeurs échantillonnées est générée.

  • TABLEUne table avec des valeurs échantillonnées est générée. Il s’agit de l’option par défaut.
  • FEATURE_CLASSUne classe d’entités ponctuelles avec des valeurs échantillonnées dans sa table attributaire est générée.
Boolean

Exemple de code

Exemple 1 d'utilisation de l'outil Sample (fenêtre Python)

Extraire les valeurs de cellule de plusieurs rasters vers une table, en fonction de localisations en entrée.

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")
Exemple 2 d'utilisation de l'outil Sample (script autonome)

Extraire les valeurs de cellule de plusieurs rasters vers une table, en fonction de localisations en entrée.

# 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)
Exemple 3 d’utilisation de l’outil Sample (script autonome)

Extraire les valeurs de cellule de plusieurs rasters vers une table, en fonction de localisations en entrée.

# Name: Sample_Ex_03.py
# Description: Creates a table that shows the temperature values from 
#              a multidimensional raster, for defined locations. 
#              The locations are defined 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 = "temperature_1990_2019.nc"
locations = "observers.shp"
outTable = "C:/sapyexamples/output/samptable_03"
sampMethod = ""
uniqueIDField = "FID"
process_as_multidimensional = True

# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")

# 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)
Exemple 4 d’utilisation de l’outil Sample (script autonome)

Extraire les valeurs de cellule de plusieurs rasters vers une table, en fonction de localisations en entrée.

# 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)