deafrica_tools.spatial#

Fonctions d’analyses spatiales pour les données de Digital Earth Africa.

Fonctions

`add_geobox`(ds[, crs])	Assurez-vous qu'un xarray DataArray dispose d'une GeoBox et d'un accesseur .odc.* en utilisant odc.geo.
`contours_to_arrays`(gdf, col)	Cette fonction convertit un shapefile de polyligne en un tableau avec trois colonnes donnant les coordonnées X, Y et Z de chaque sommet.
`interpolate_2d`(ds, x_coords, y_coords, z_coords)	Cette fonction prend des points avec des coordonnées X, Y et Z, et interpole les valeurs Z à travers l'étendue d'un jeu de données xarray existant.
`largest_region`(bool_array, **kwargs)	Prend un tableau booléen et identifie la plus grande région contiguë de valeurs True connectées.
`reverse_geocode`(coords[, site_classes, ...])	Prend une coordonnée de latitude et de longitude, et effectue un géocodage inversé pour renvoyer une description en texte brut de l'emplacement sous la forme :
`subpixel_contours`(da[, z_values, crs, ...])	Utilise skimage.measure.find_contours pour extraire plusieurs lignes de contour de valeur z d'un tableau bidimensionnel (par exemple, plusieurs élévations à partir d'un seul DEM), ou une valeur z pour chaque tableau le long d'une dimension spécifiée d'un tableau multidimensionnel (par exemple, pour cartographier les lignes d'eau au fil du temps en extrayant un contour NDWI 0 de chaque étape temporelle individuelle dans une série temporelle xarray).
`sun_angles`(dc, query)	Pour une requête spatio-temporelle donnée, calculer l'azimut et l'élévation moyens du soleil pour chaque observation satellite, et les retourner sous forme d'un nouveau xarray.Dataset avec les variables 'sun_elevation' et 'sun_azimuth'.
`transform_geojson_wgs_to_epsg`(geojson, EPSG)	Prend un dictionnaire geojson et le convertit de WGS84 (EPSG:4326) vers l'EPSG souhaité
`xr_rasterize`(gdf, da[, attribute_col, crs, ...])	Rasterise un `geopandas.GeoDataFrame` vectoriel en un `xarray.DataArray` raster.
`xr_vectorize`(da[, attribute_col, crs, ...])	Vectorise un `xarray.DataArray` raster en un `geopandas.GeoDataFrame` vectoriel.
`zonal_stats_parallel`(shp, raster, ...])	Synthétiser les jeux de données raster basés sur des géométries vectorielles en parallèle.

deafrica_tools.spatial.add_geobox(ds, crs=None)#

Assurez-vous qu’un xarray DataArray dispose d’une GeoBox et d’un accesseur .odc.* en utilisant odc.geo.

Si ds manque d’un système de référence de coordonnées (CRS), celui-ci peut être fourni en utilisant le paramètre crs.

Paramètres:

ds (xarray.Dataset or xarray.DataArray) – Objet xarray d’entrée qui doit être vérifié pour les informations spatiales.
crs (str, optional) – Informations sur le système de référence de coordonnées (CRS) pour le tableau ds d’entrée. Si ds a déjà un CRS, alors crs n’est pas requis. La valeur par défaut est None.

Renvoie:

L’objet xarray d’entrée avec des attributs .odc.x ajoutés pour accéder aux informations spatiales.

Type renvoyé:

xarray.Dataset or xarray.DataArray

deafrica_tools.spatial.contours_to_arrays(gdf, col)#

Cette fonction convertit un shapefile de polyligne en un tableau avec trois colonnes donnant les coordonnées X, Y et Z de chaque sommet. Ces données peuvent ensuite être utilisées comme entrée pour des procédures d’interpolation (par exemple, en utilisant une fonction comme interpolate_2d).

Dernière modification : octobre 2021

Paramètres:

gdf (Geopandas GeoDataFrame) – Un GeoPandas GeoDataFrame de lignes à convertir en coordonnées de points.
col (str) – Une chaîne donnant le nom du champ GeoDataFrame à utiliser comme valeurs Z.

Renvoie:

Un tableau numpy avec trois colonnes donnant les coordonnées X, Y et Z
de chaque sommet dans le GeoDataFrame d’entrée.

deafrica_tools.spatial.interpolate_2d(ds, x_coords, y_coords, z_coords, method='linear', factor=1, verbose=False, **kwargs)#

Cette fonction prend des points avec des coordonnées X, Y et Z, et interpole les valeurs Z sur toute l’étendue d’un jeu de données xarray existant. Cela peut être utile pour produire des surfaces lisses à partir de données ponctuelles qui peuvent être comparées directement aux données satellitaires dérivées d’une requête OpenDataCube.

Les méthodes d’interpolation prises en charge incluent “linear”, “nearest” et “cubic” (utilisant scipy.interpolate.griddata), et “rbf” (utilisant scipy.interpolate.Rbf).

Dernière modification : février 2020

Paramètres:

ds (xarray DataArray or Dataset) – Un tableau bidimensionnel ou multidimensionnel à partir duquel les dimensions x et y seront copiées et utilisées pour la zone dans laquelle interpoler les données ponctuelles.
x_coords (numpy array) – Tableaux contenant les coordonnées X et Y pour tous les points (par exemple, longitudes et latitudes).
y_coords (numpy array) – Tableaux contenant les coordonnées X et Y pour tous les points (par exemple, longitudes et latitudes).
z_coords (numpy array) – Un tableau contenant les coordonnées Z pour tous les points (par exemple, élévations). Ce sont les valeurs que vous souhaitez interpoler.
method (string, optional) – La méthode utilisée pour interpoler entre les valeurs ponctuelles. Cette chaîne est soit transmise à scipy.interpolate.griddata (pour les méthodes “linear”, “nearest” et “cubic”), soit utilisée pour spécifier l’interpolation par fonction de base radiale en utilisant scipy.interpolate.Rbf (“rbf”). Par défaut, “linear”.
factor (int, optional) – Un entier optionnel qui peut être utilisé pour sous-échantillonner l’étendue de l’interpolation spatiale afin d’obtenir des temps d’interpolation plus rapides, puis ré-échantillonner ce tableau aux dimensions originales des données comme étape finale. Par exemple, définir factor=10 interpolera les données dans une grille qui a un dixième de la résolution de ds. Cette approche sera nettement plus rapide que l’interpolation à pleine résolution, mais produira potentiellement des résultats moins précis ou fiables.
verbose (bool, optional) – Imprimer les messages de débogage. Par défaut, False.
**kwargs – Arguments nommés optionnels à passer soit à scipy.interpolate.griddata (si method est “linear”, “nearest” ou “cubic”), soit à scipy.interpolate.Rbf (si method est “rbf”).

Renvoie:

interp_2d_array – Un xarray DataArray avec des coordonnées x et y copiées depuis ds_array, et des valeurs Z interpolées à partir des données ponctuelles.

Type renvoyé:

xarray DataArray

deafrica_tools.spatial.largest_region(bool_array, **kwargs)#

Prend un tableau booléen et identifie la plus grande région contiguë de valeurs True connectées. Ceci est renvoyé sous forme de nouveau tableau avec les cellules de la plus grande région marquées comme True, et toutes les autres cellules marquées comme False.

Paramètres:

bool_array (boolean array) – Un tableau booléen (numpy ou xarray.DataArray) avec des valeurs True pour les zones qui seront inspectées pour trouver le plus grand groupe de cellules connectées.
**kwargs – Arguments nommés optionnels à passer à measure.label.

Renvoie:

largest_region – Un tableau booléen avec les cellules de la plus grande région marquées comme True, et toutes les autres cellules marquées comme False.

Type renvoyé:

boolean array

deafrica_tools.spatial.reverse_geocode(coords, site_classes=None, state_classes=None)#

Prend une coordonnée de latitude et de longitude, et effectue un géocodage inversé pour renvoyer une description en texte brut de l’emplacement sous la forme :

Site, État

Par ex. : reverse_geocode(coords=(-35.282163, 149.128835))

“Canberra, Territoire de la capitale australienne”

Paramètres:

coords (tuple of floats) – Un tuple de coordonnées (latitude, longitude) utilisé pour effectuer le géocodage inverse.
site_classes (list of strings, optional) – Une liste de chaînes utilisée pour définir la partie site de la description textuelle du lieu. Comme le contenu de l’adresse géocodée peut varier considérablement selon l’emplacement, ces chaînes sont testées par rapport à l’adresse une par une jusqu’à ce qu’une correspondance soit trouvée. Par défaut : [“city”, “town”, “village”, “suburb”, “hamlet”, “county”, “municipality”].
state_classes (list of strings, optional) – Une liste de chaînes utilisée pour définir la partie état de la description textuelle du lieu. Ces chaînes sont testées par rapport à l’adresse une par une jusqu’à ce qu’une correspondance soit trouvée. Par défaut : [“state”, “territory”].

Renvoie:

Si une adresse géocodée valide est trouvée, une description textuelle du lieu
sera renvoyée – “Site, État”
Si aucune adresse valide n’est trouvée, des coordonnées formatées seront renvoyées
à la place – “XX.XX S, XX.XX E”

deafrica_tools.spatial.subpixel_contours(da, z_values=[0.0], crs=None, attribute_df=None, output_path=None, min_vertices=2, dim='time', time_format='%Y-%m-%d', errors='ignore', verbose=True)#

Utilise skimage.measure.find_contours pour extraire plusieurs lignes de contour de valeur z d’un tableau bidimensionnel (par exemple, plusieurs élévations à partir d’un seul DEM), ou une valeur z pour chaque tableau le long d’une dimension spécifiée d’un tableau multidimensionnel (par exemple, pour cartographier les lignes d’eau au fil du temps en extrayant un contour NDWI 0 de chaque étape temporelle individuelle dans une série temporelle xarray).

Les contours sont renvoyés sous forme de geopandas.GeoDataFrame avec une ligne par valeur z ou une ligne par tableau le long d’une dimension spécifiée. Le paramètre attribute_df peut être utilisé pour passer des attributs personnalisés aux caractéristiques de contour de sortie.

Dernière modification : mai 2023

Paramètres:

da (xarray DataArray) – Un tableau bidimensionnel ou multidimensionnel à partir duquel les contours sont extraits. Si un tableau bidimensionnel est fourni, l’analyse s’exécutera en mode “tableau unique, valeurs z multiples”, ce qui vous permet de spécifier plusieurs z_values à extraire. Si un tableau multidimensionnel est fourni, l’analyse s’exécutera en mode “valeur z unique, tableaux multiples”, vous permettant d’extraire des contours pour chaque tableau le long de la dimension spécifiée par le paramètre dim.
z_values (int, float or list of ints, floats) – Une valeur z individuelle ou une liste de plusieurs valeurs z à extraire du tableau. Si vous opérez en mode “valeur z unique, tableaux multiples”, spécifiez une seule valeur z.
crs (string or CRS object, optional) – Si le système de référence de coordonnées (CRS) de da ne peut pas être déterminé, fournissez un CRS en utilisant ce paramètre. (par ex. “EPSG:3577”).
output_path (string, optional) – Le chemin et le nom de fichier pour le shapefile de sortie.
attribute_df (pandas.Dataframe, optional) – Un pandas.Dataframe contenant des attributs à passer aux caractéristiques de contour de sortie. Le dataframe doit contenir soit le même nombre de lignes que les z_values fournies (en mode “valeurs z multiples, tableau unique”), soit le même nombre de lignes que le nombre de tableaux le long de la dimension dim (en mode “valeur z unique, tableaux multiples”).
min_vertices (int, optional) – Le nombre minimum de sommets requis pour qu’un contour soit extrait. La valeur par défaut (et minimale) est 2, ce qui est le plus petit nombre requis pour produire une ligne de contour (c’est-à-dire un point de départ et de fin). Des valeurs plus élevées suppriment les contours plus petits, supprimant potentiellement le bruit du jeu de données de sortie.
dim (string, optional) – Le nom de la dimension le long de laquelle extraire les contours lors de l’utilisation en mode “valeur z unique, tableaux multiples”. La valeur par défaut est “time”, qui extrait les contours pour chaque tableau le long de la dimension temporelle.
time_format (string, optional) – Le format utilisé pour convertir les valeurs numpy.datetime64 en chaînes si elles sont appliquées à des données avec une dimension « time ». Par défaut « %Y-%m-%d ».
errors (string, optional) – Si “raise”, tout contour ayant échoué lèvera une exception. Si “ignore” (par défaut), une liste des contours ayant échoué sera imprimée. Si aucun contour n’est renvoyé, une exception sera toujours levée.
verbose (bool, optional) – Imprimer les messages de débogage. Par défaut est True.

Renvoie:

output_gdf – Un objet geopandas geodataframe avec une caractéristique par valeur z (mode “tableau unique, valeurs z multiples”), ou une ligne par tableau le long de la dimension spécifiée par le paramètre dim (mode “valeur z unique, tableaux multiples”). Si attribute_df a été fourni, ces valeurs seront incluses dans la table d’attributs du shapefile.

Type renvoyé:

geopandas geodataframe

deafrica_tools.spatial.sun_angles(dc, query)#

Pour une requête spatio-temporelle donnée, calculer l’azimut et l’élévation moyens du soleil pour chaque observation satellite, et les retourner sous forme d’un nouveau xarray.Dataset avec les variables “sun_elevation” et “sun_azimuth”.

Paramètres:#

dcobjet datacube.Datacube: Instance Datacube utilisée pour charger les données.
querydict: Un dictionnaire contenant les paramètres de requête utilisés pour identifier les observations satellitaires et charger les métadonnées.

Retours :#

sun_angles_dsxarray.Dataset: Un xarray.set contenant des variables “sun_elevation” et “sun_azimuth”.

deafrica_tools.spatial.transform_geojson_wgs_to_epsg(geojson, EPSG)#

Prend un dictionnaire geojson et le convertit de WGS84 (EPSG:4326) vers l’EPSG souhaité

Paramètres:

geojson (dict) – un dictionnaire geojson contenant une clé “geometry”, en coordonnées WGS84
EPSG (int) – code numérique pour le système de référence de coordonnées EPSG vers lequel transformer

Renvoie:

transformed_geojson – un dictionnaire geojson contenant une clé “coordinates”, dans le CRS souhaité

Type renvoyé:

dict

deafrica_tools.spatial.xr_rasterize(gdf, da, attribute_col=None, crs=None, name=None, output_path=None, verbose=True, **rasterio_kwargs)#

Rasterise un geopandas.GeoDataFrame vectoriel en un xarray.DataArray raster.

Paramètres:

gdf (geopandas.GeoDataFrame) – Un objet geopandas.GeoDataFrame contenant les données vectorielles que vous souhaitez rastériser.
da (xarray.DataArray or xarray.Dataset) – La forme, les coordonnées, les dimensions et la transformation de cet objet sont utilisées pour définir le tableau dans lequel gdf est rastérisé. Il fournit efficacement un modèle spatial.
attribute_col (string, optional) – Nom de la colonne d’attribut dans gdf contenant des valeurs pour chaque caractéristique vectorielle qui sera rastérisée. Si None, la sortie sera un tableau booléen de 1 et 0.
crs (str or CRS object, optional) – Si le système de référence de coordonnées (CRS) de da ne peut pas être déterminé, fournissez un CRS en utilisant ce paramètre. (par ex. “EPSG:3577”).
name (str, optional) – Un nom optionnel utilisé pour le ``xarray.DataArray` de sortie.
output_path (string, optional) – Fournissez un chemin de fichier de chaîne optionnel pour exporter les données rastérisées sous forme de fichier GeoTIFF.
verbose (bool, optional) – Imprimer les messages de débogage. Par défaut True.
**rasterio_kwargs – Un ensemble d’arguments nommés pour rasterio.features.rasterize. Peut inclure : “all_touched”, “merge_alg”, “dtype”.

Renvoie:

da_rasterized – Les données vectorielles rastérisées.

Type renvoyé:

xarray.DataArray

deafrica_tools.spatial.xr_vectorize(da, attribute_col=None, crs=None, dtype='float32', output_path=None, verbose=True, **rasterio_kwargs)#

Vectorise un xarray.DataArray raster en un geopandas.GeoDataFrame vectoriel.

Paramètres:

da (xarray.DataArray) – Les données xarray.DataArray d’entrée à vectoriser.
attribute_col (str, optional) – Nom de la colonne d’attribut dans le geopandas.GeoDataFrame résultant. Les valeurs de da converties en polygones seront attribuées à cette colonne. Si None, le nom de la colonne sera par défaut “attribute”.
crs (str or CRS object, optional) – Si le système de référence de coordonnées (CRS) de da ne peut pas être déterminé, fournissez un CRS en utilisant ce paramètre. (par ex. “EPSG:3577”).
dtype (str, optional) – Le type de données doit être l’un des suivants : int16, int32, uint8, uint16 ou float32
output_path (string, optional) – Fournissez un chemin de fichier de chaîne optionnel pour exporter les données vectorisées vers un fichier. Prend en charge tous les formats de fichier vectoriel pris en charge par geopandas.GeoDataFrame.to_file().
verbose (bool, optional) – Imprimer les messages de débogage. Par défaut True.
**rasterio_kwargs – Un ensemble d’arguments nommés pour rasterio.features.shapes. Peut inclure mask et connectivity.

Renvoie:

gdf

Type renvoyé:

geopandas.GeoDataFrame

deafrica_tools.spatial.zonal_stats_parallel(shp, raster, statistics, out_shp, ncpus, **kwargs)#

Résumé des jeux de données raster basés sur des géométries vectorielles en parallèle. Chaque processeur reçoit un morceau égal du jeu de données. Utilise le package perrygeo/rasterstats.

Paramètres:

shp (str) – Chemin vers le shapefile qui contient les polygones sur lesquels les statistiques zonales sont calculées
raster (str) – Chemin vers le raster à partir duquel les statistiques sont calculées. Cela peut être un raster virtuel (.vrt).
statistics (list) – liste des statistiques à calculer. par ex. [“min”, “max”, “median”, “majority”, “sum”]
out_shp (str) – Chemin pour exporter le shapefile contenant les statistiques zonales.
ncpus (int) – nombre de cœurs sur lesquels paralléliser les opérations.
kwargs – Tout autre argument de mot-clé pour rasterstats.zonal_stats(). Voir perrygeo/python-rasterstats pour toutes les options

Type renvoyé:

Exports a shapefile to disk containing the zonal statistics requested