Échantillon (Image Analyst)

Disponible avec une licence Spatial Analyst.

Disponible avec une licence Image 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 cellules sont extraites de tous les Rasters en entrée (in_rasters en Python) à chaque localisation. Une table ou une classe d’entités ponctuelles est créée avec des champs contenant les valeurs de cellule de 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 spécifier n’importe quelle combinaison de rasters (monocanal ou multicanal) pour les 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 l’un des rasters en entrée, tous les canaux de cette entrée sont utilisés.

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

    • Raster : les cellules contenant des valeurs valides (différentes de 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é comme emplacement des points.
    • Point : les valeurs sont échantillonnées à chaque emplacement 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 à deux dimensions, ou plusieurs rasters. D’autres types de statistiques peuvent être spécifiés si l’entrée est un raster multidimensionnel et qu’elle est traitée comme telle.

  • 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 rasters en entrée sont échantillonnés avec leur référence spatiale et leur résolution natives. S’il existe plusieurs rasters en entrée avec des références spatiales différentes, les emplacements en entrée sont d’abord projetés dans la référence spatiale de chaque raster individuel, puis les valeurs sont extraites. Ainsi, bien que les rasters en entrée ne respectent pas les paramètres d’environnement d’analyse, les environnements appropriés sont appliqués aux emplacements en entrée.

  • Par défaut, la référence spatiale des coordonnées x,y du paramètre Table ou classe d’entités en sortie (out_table en Python) est la même que celle des valeurs du paramètre Raster de localisation ou entités points en entrée, sauf si une valeur différente est spécifiée dans l’environnement 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 champ Input location raster or features (Raster d’emplacement 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 pour une entrée comportant de nombreux points, créez un index spatial. Reportez-vous à la rubrique Ajouter un index spatial pour plus d’informations.

  • 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 Technique de rééchantillonnage est défini sur Les plus proches (resampling_type = "NEAREST" en Python), le type de champ de la table en sortie correspond à celui du type de raster. Lorsque l’option de rééchantillonnage est Bilinear (Bilinéaire) ou Cubic (Cubique), le type de champ est toujours à virgule flottante afin de préserver la précision des valeurs interpolées.

  • Un champ est ajouté à la table en sortie pour stocker les valeurs spécifiées dans le paramètre Champ d’ID unique (unique_id_field en Python). Par défaut, le nom du champ est identique à celui du jeu de données d’emplacement en entrée. Il est recommandé d’utiliser un champ contenant des valeurs uniques pour identifier chaque emplacement pour une analyse approfondie.

  • Si le paramètre 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 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 à plusieurs variables, toutes les tranches de toutes les variables sont échantillonnées. Les variables doivent avoir les mêmes dimensions.

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

    • Le paramètre 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. Pour une dimension temporelle, spécifiez 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épart et le champ de fin sont spécifiés (les champs de départ et de fin proviennent des données d’emplacement), les valeurs de ces champs sont utilisées pour spécifier un sous-ensemble du raster en entrée lors de l’échantillonnage des valeurs pour cet emplacement.

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

    • Le paramètre Type de statistique (statistics_type en Python) agrège les valeurs du paramètre Raster en entrée comme indiqué par le sous-ensemble du paramètre Informations d’acquisition des données de localisation.

    • Si le paramètre Mise en page en colonnes est désactivé (layout = "ROW_WISE" en Python), les valeurs extraites sont stockées dans un champ ayant 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 Mise en page en colonnes est activé (layout = "COLUMN_WISE" en Python), les valeurs extraites sont stockées dans des champs dont les noms suivent la convention <variable_name>_<dimension_name>_<dimension_value>. Notez 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 attribuée aux emplacements qui extraient des valeurs des cellules NoData.

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

  • Si le paramètre 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 points dont la table attributaire contient les valeurs échantillonnées. Les types d’emplacements possibles, ainsi qu’une description du mode d’échantillonnage des valeurs, sont décrits ci-dessous.

    • Raster : les points sont créés à partir de l’emplacement du centre de la cellule.
    • Point : un point est créé à chaque emplacement 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 du paramètre Input location raster or features (Raster d’emplacement ou entités en entrée), sauf si elle est spécifiée dans le paramètre d’environnement 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 d’emplacement 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 d’emplacement 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 cellule échantillonnées.

Le format de sortie est déterminé par l’emplacement et le chemin d’accès en sortie. Par défaut, la sortie est une table de géodatabase 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 la génération d’une table ou d’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 à utiliser pour échantillonner un raster afin de déterminer comment obtenir les valeurs de celui-ci.

  • 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 emplacement ou entité du raster d’emplacement ou des entités en entrée.

Field
Traiter comme multidimensionnel
(Facultatif)

Indique comment les rasters en entrée sont traités.

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

  • Désactivé : les échantillons sont 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 sont 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 l’heure, la profondeur ou les autres données d’acquisition liées aux entités d’emplacement.

Seules les associations suivantes sont prises en charge :

  • Dimension + Start field or value (Champ ou valeur de début)
  • Dimension + Start field or value (Champ ou valeur de début) + End field or value (Champ ou valeur de fin)
  • Dimension + Start field or value (Champ ou valeur de début) + Relative value or days before (Valeur relative ou nombre de jours avant) + Relative value or days after (Valeur relative ou nombre de jours après)

Les options Relative value or days before (Valeur relative ou nombre de jours avant) et Relative value or days after (Valeur relative ou nombre de jours après) acceptent uniquement les valeurs non négatives.

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

Value Table
Type de statistique
(Facultatif)

Spécifie le type de statistique à calculer.

  • MinimumCalcule la valeur minimale dans la plage spécifiée.
  • MaximumCalcule la valeur maximale dans la plage spécifiée.
  • MédianeCalcule la valeur médiane dans la plage spécifiée.
  • MoyenneCalcule la valeur moyenne dans la plage spécifiée.
  • SommeCalcule la valeur totale des variables dans la plage spécifiée.
  • MajoritéCalcule la valeur la plus fréquente.
  • MinoritéCalcule la valeur la moins fréquente.
  • Écart typeCalcule l’écart type.
  • CentileCalcule un centile défini dans la plage spécifiée.
String
Valeur du pourcentage
(Facultatif)

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

Double
Buffer distance field or value (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é utilisée est le degré.

Les statistiques sont calculées dans cette zone tampon.

Double; Field
Column-wise layout (Mise en page en colonnes)
(Facultatif)

Indique si les valeurs échantillonnées apparaissent en lignes ou en colonnes dans la table en sortie.

  • Désactivé : les valeurs échantillonnées apparaissent sur des lignes séparées dans la table en sortie. Il s’agit de l’option par défaut.
  • Activé : les valeurs échantillonnées apparaissent dans des colonnes séparées 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
Générer une classe d’entités
(Facultatif)

Spécifie si une classe d’entités ponctuelles comportant les valeurs échantillonnées dans sa table attributaire ou une table comportant les valeurs échantillonnées, sera créée.

  • Désactivé : une table comportant les valeurs échantillonnées est générée. Il s’agit de l’option par défaut.
  • Activé : une classe d’entités ponctuelles comportant les 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 d’emplacement 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 cellule échantillonnées.

Le format de sortie est déterminé par l’emplacement et le chemin d’accès en sortie. Par défaut, la sortie est une table de géodatabase 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 la génération d’une table ou d’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 à utiliser pour échantillonner un raster afin de déterminer comment obtenir les valeurs de celui-ci.

  • 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 emplacement ou entité du raster d’emplacement ou des entités en entrée.

Field
process_as_multidimensional
(Facultatif)

Indique comment les rasters en entrée sont traités.

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

  • ALL_SLICESLes échantillons sont traités pour toutes les dimensions (temps ou profondeur, par exemple) d’un jeu de données multidimensionnelles.
  • CURRENT_SLICELes échantillons sont 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 l’heure, la profondeur ou les autres données d’acquisition liées aux entités d’emplacement.

Seules les associations suivantes sont prises en charge :

  • Dimension + Start field or value (Champ ou valeur de début)
  • Dimension + Start field or value (Champ ou valeur de début) + End field or value (Champ ou valeur de fin)
  • Dimension + Start field or value (Champ ou valeur de début) + Relative value or days before (Valeur relative ou nombre de jours avant) + Relative value or days after (Valeur relative ou nombre de jours après)

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

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

Value Table
statistics_type
(Facultatif)

Spécifie le type de statistique à calculer.

  • MINIMUMCalcule la valeur minimale dans la plage spécifiée.
  • MAXIMUMCalcule la valeur maximale dans la plage spécifiée.
  • MEDIANCalcule la valeur médiane dans la plage spécifiée.
  • MEANCalcule la valeur moyenne dans la plage spécifiée.
  • SUMCalcule la valeur totale des variables dans la plage spécifiée.
  • MAJORITYCalcule la valeur la plus fréquente.
  • MINORITYCalcule la valeur la moins fréquente.
  • STDCalcule l’écart type.
  • PERCENTILECalcule un centile défini dans la plage spécifiée.
String
percentile_value
(Facultatif)

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

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é utilisée est le degré.

Les statistiques sont calculées dans cette zone tampon.

Double; Field
layout
(Facultatif)

Indique si les valeurs échantillonnées apparaissent en lignes ou en colonnes dans la table en sortie.

  • ROW_WISELes valeurs échantillonnées apparaissent sur des lignes séparées dans la table en sortie. Il s’agit de l’option par défaut.
  • COLUMN_WISELes valeurs échantillonnées apparaissent dans des colonnes séparées 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)

Spécifie si une classe d’entités ponctuelles comportant les valeurs échantillonnées dans sa table attributaire ou une table comportant les valeurs échantillonnées, sera créée.

  • TABLEUne table comportant les valeurs échantillonnées est générée. Il s’agit de l’option par défaut.
  • FEATURE_CLASSUne classe d’entités ponctuelles comportant les valeurs échantillonnées dans sa table attributaire est générée créé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.ia import *
env.workspace = "C:/iapyexamples/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 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: Image Analyst Extension

# Import system modules
import arcpy
from arcpy import env
from arcpy.ia import *

# Set environment settings
env.workspace = "C:/iapyexamples/data"

# Set local variables
inRasters = ["elevation",
             "costraster"]
locations = "observers.shp"
outTable = "c:/sapyexamples/output/samptable02"
sampMethod = "NEAREST"

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

# Execute Sample
Sample(inRasters, locations, outTable, sampMethod)
Exemple 3 d’utilisation de l’outil Échantillon (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: Image Analyst Extension

# Import system modules
import arcpy
from arcpy import env
from arcpy.ia import *

# Set environment settings
env.workspace = "C:/iapyexamples/data"

# Set local variables
inRasters = "temperature_1990_2019.nc"
locations = "observers.shp"
outTable = "C:/iapyexamples/output/samptable_03"
sampMethod = ""
uniqueIDField = "FID"
process_as_multidimensional = True

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

# 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 (Échantillonner) (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 average temperature value within the period [1999-01-01T00:00:00 , 2019-01-01-T00:00:00]
# Requirements: Image Analyst Extension

# Import system modules
import arcpy
from arcpy import env
from arcpy.ia import *

# Set environment settings
env.workspace = "C:/iapyexamples/data"

# Set local variables
inRasters = "temperature_1990_2019.nc"
locations = "observers_polygons.shp"
outTable = "C:/iapyexamples/output/samptable_04"
sampMethod = "BILINEAR"
uniqueIDField = "FID"
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 = ""

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

# Execute Sample
# for each polygon in locations, the average 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)

Informations de licence

  • Basic: Nécessite Image Analyst ou Spatial Analyst
  • Standard: Nécessite Image Analyst ou Spatial Analyst
  • Advanced: Nécessite Image Analyst ou Spatial Analyst

Rubriques connexes