Utiliser des données de trame avec Earth Engine dans BigQuery

Ce document explique comment combiner des données de trame et vectorielles à l'aide de la ST_REGIONSTATS fonction, qui utilise Google Earth Engine pour accéder aux données d'image et de trame dans BigQuery.

Présentation

Une trame est une grille bidimensionnelle de pixels, chacun étant associé à une ou plusieurs valeurs appelées bandes. Par exemple, chaque pixel peut correspondre à un kilomètre carré particulier à la surface de la Terre et comporter des bandes pour la température moyenne et les précipitations moyennes. Les données de trame incluent des images satellite et d'autres données continues basées sur une grille, telles que les prévisions météorologiques et la couverture terrestre. De nombreux formats d'image courants, tels que les fichiers PNG ou JPEG, sont mis en forme en tant que données de trame.

Les données de trame sont souvent opposées aux données vectorielles, dans lesquelles les données sont décrites par des lignes ou des courbes plutôt que par une grille rectangulaire fixe. Par exemple, vous pouvez utiliser le type de données GEOGRAPHY dans BigQuery pour décrire les limites des pays, des villes ou d'autres régions.

Les données géospatiales de trame et vectorielles sont souvent combinées à l'aide d'une opération de statistiques zonales, qui calcule un agrégat de toutes les valeurs de trame dans une région vectorielle donnée. Par exemple, vous pouvez calculer les éléments suivants :

  • Qualité de l'air moyenne dans un ensemble de villes.
  • Potentiel solaire pour un ensemble de polygones de bâtiments.
  • Risque d'incendie résumé le long des corridors de lignes électriques dans les zones boisées.

BigQuery excelle dans le traitement des données vectorielles, et Google Earth Engine dans le traitement des données de trame. Vous pouvez utiliser la ST_REGIONSTATS fonction géographique pour combiner des données de trame à l'aide d'Earth Engine avec vos données vectorielles stockées dans BigQuery.

Carte de la Terre avec des valeurs raster et des statistiques zonales calculées.

Avant de commencer

  1. Pour utiliser la fonction ST_REGIONSTATS dans vos requêtes, activez l'API Earth Engine.

    Activer l'API

  2. Facultatif : Pour vous abonner aux données publiées dans BigQuery Sharing (anciennement Analytics Hub) et les utiliser à l'aide de la fonction ST_REGIONSTATS, activez l'API Analytics Hub.

    Activer l'API

Autorisations requises

Pour obtenir les autorisations nécessaires pour appeler la fonction ST_REGIONSTATS, demandez à votre administrateur de vous attribuer les rôles IAM suivants dans votre projet :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour appeler la fonction ST_REGIONSTATS. Pour afficher les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour appeler la fonction ST_REGIONSTATS :

  • earthengine.computations.create
  • serviceusage.services.use
  • bigquery.datasets.create

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Rechercher des données de trame

Le paramètre raster_id de la fonction ST_REGIONSTATS est une chaîne qui spécifie la source de vos données de trame. Les sections suivantes expliquent comment trouver et mettre en forme l'ID de trame.

Tables d'images BigQuery

Vous pouvez utiliser BigQuery Sharing (anciennement Analytics Hub) pour découvrir des ensembles de données de trame dans BigQuery et y accéder. Pour utiliser BigQuery Sharing, vous devez activer l'API Analytics Hub et vous assurer que vous disposez des autorisations requises pour afficher les fiches et les échanges de données, et vous y abonner.

Google Earth Engine publie des ensembles de données accessibles au public qui contiennent des données de trame dans les multirégions US et EU. Pour vous abonner à un ensemble de données Earth Engine contenant des données de trame, procédez comme suit :

  1. Accédez à la page Sharing (Analytics Hub) (Partage (Analytics Hub)).

    Accéder à Sharing (Analytics Hub)

  2. Cliquez sur Search listings (Rechercher des fiches).

  3. Dans le champ Search for listings (Rechercher des fiches), saisissez "Google Earth Engine".

  4. Cliquez sur l'ensemble de données auquel vous souhaitez vous abonner.

  5. Cliquez sur Subscribe (S'abonner).

  6. Facultatif : Mettez à jour les champs Project (Projet) ou Linked dataset name (Nom de l'ensemble de données associé).

  7. Cliquez sur Save (Enregistrer). L'ensemble de données associé est ajouté à votre projet.

L'ensemble de données contient une table d'images qui stocke les métadonnées d'une collection d'images de trame suivant la spécification des éléments STAC. Une table d'images est analogue à une collection d'images Earth Engine (ImageCollection).

Chaque ligne du tableau correspond à une seule image de trame, avec des colonnes contenant les propriétés et les métadonnées de l'image. L'ID de trame de chaque image est stocké dans la colonne assets.image.href. Référencez les images dans vos requêtes à l'aide de cet ID comme valeur de paramètre raster_id.

Filtrez le tableau à l'aide des colonnes de propriétés pour sélectionner des images ou des sous-ensembles d'images spécifiques qui répondent à vos critères. Pour en savoir plus sur les bandes disponibles, la taille des pixels et les définitions des propriétés, ouvrez le tableau et cliquez sur l'onglet Image details (Détails de l'image).

Chaque table d'images inclut une table *_metadata correspondante qui fournit des informations complémentaires pour la table d'images.

Par exemple, l'ensemble de données ERA5-Land fournit des statistiques quotidiennes sur les variables climatiques et est accessible au public. La table climate contient plusieurs ID de trame. La requête suivante filtre la table d'images à l'aide de la colonne start_datetime pour obtenir l'ID de trame de l'image correspondant au 1er janvier 2025 et calcule la température moyenne pour chaque pays à l'aide de la bande temperature_2m :

SQL 

WITH SimplifiedCountries AS (
  SELECT
    ST_SIMPLIFY(geometry, 10000) AS simplified_geometry,
    names.primary AS name
  FROM
    `bigquery-public-data.overture_maps.division_area`
  WHERE
    subtype = 'country'
)
SELECT
  sc.simplified_geometry AS geometry,
  sc.name,
  ST_REGIONSTATS(
    sc.simplified_geometry,
    (SELECT assets.image.href
    FROM `LINKED_DATASET_NAME.climate`
    WHERE start_datetime = '2025-01-01 00:00:00'),
    'temperature_2m'
  ).mean - 273.15 AS mean_temperature
FROM
  SimplifiedCountries AS sc
ORDER BY
  mean_temperature DESC;

BigQuery DataFrames

Avant d'essayer cet exemple, suivez les instructions de configuration pour BigQuery DataFrames du guide de démarrage rapide de BigQuery DataFrames. Pour en savoir plus, consultez la documentation de référence sur BigQuery DataFrames.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer les identifiants par défaut de l'application pour un environnement de développement local. 

import datetime
from typing import cast

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# TODO: Set the project_id to your Google Cloud project ID.
# project_id = "your-project-id"
bpd.options.bigquery.project = project_id

# TODO: Set the dataset_id to the ID of the dataset that contains the
# `climate` table. This is likely a linked dataset to Earth Engine.
# See: https://cloud.google.com/bigquery/docs/link-earth-engine
linked_dataset = "era5_land_daily_aggregated"

# For the best efficiency, use partial ordering mode.
bpd.options.bigquery.ordering_mode = "partial"

# Load the table of country boundaries.
countries = bpd.read_gbq("bigquery-public-data.overture_maps.division_area")

# Filter to just the countries.
countries = countries[countries["subtype"] == "country"].copy()
countries["name"] = countries["names"].struct.field("primary")
countries["simplified_geometry"] = bbq.st_simplify(
    countries["geometry"],
    tolerance_meters=10_000,
)

# Get the reference to the temperature data from a linked dataset.
# Note: This sample assumes you have a linked dataset to Earth Engine.
image_href = (
    bpd.read_gbq(f"{project_id}.{linked_dataset}.climate")
    .set_index("start_datetime")
    .loc[[datetime.datetime(2025, 1, 1, tzinfo=datetime.timezone.utc)], :]
)
raster_id = image_href["assets"].struct.field("image").struct.field("href")
raster_id = raster_id.item()
stats = bbq.st_regionstats(
    countries["simplified_geometry"],
    raster_id=cast(str, raster_id),
    band="temperature_2m",
)

# Extract the mean and convert from Kelvin to Celsius.
countries["mean_temperature"] = stats.struct.field("mean") - 273.15

# Sort by the mean temperature to find the warmest countries.
result = countries[["name", "mean_temperature"]].sort_values(
    "mean_temperature", ascending=False
)
print(result.head(10))

GeoTIFF Cloud Storage

GeoTIFF est un format de fichier courant pour stocker des données de trame géospatiales. La fonction ST_REGIONSTATS est compatible avec les données de trame stockées au format Cloud Optimized GeoTIFF (COG) dans les buckets Cloud Storage situés dans les régions suivantes :

  • Multirégion US
  • us-central1
  • Multirégion EU
  • europe-west1

Fournissez l'URI Cloud Storage comme ID de trame, par exemple gs://bucket/folder/raster.tif.

Éléments d'image Earth Engine

La fonction ST_REGIONSTATS permet de transmettre un chemin d'accès à un composant Image Earth Engine pour l'argument raster_id. Les données de trame Earth Engine sont disponibles sous forme d'images individuelles ou de collections d'images. Ces données existent dans la région US et ne sont compatibles qu'avec les requêtes exécutées dans cette région.US Pour trouver l'ID de trame d'une image, procédez comme suit :

  1. Recherchez l' ensemble de données qui vous intéresse dans le catalogue de données Earth Engine.

  2. Pour ouvrir la page de description de cette entrée, cliquez sur le nom de l'ensemble de données. L'extrait Earth Engine décrit une seule image ou une collection d'images.

    Si l'extrait Earth Engine est au format ee.Image('IMAGE_PATH'), l'ID de trame est 'ee://IMAGE_PATH'.

    Si l'extrait Earth Engine est au format ee.ImageCollection('IMAGE_COLLECTION_PATH'), vous pouvez utiliser l' éditeur de code Earth Engine pour filtrer l'ImageCollection sur une seule image. Utilisez la méthode ee.Image.get('system:id') pour imprimer la valeur IMAGE_PATH de cette image dans la console. L'ID de trame est 'ee://IMAGE_PATH'.

Pondérations des pixels

Vous pouvez spécifier une pondération, parfois appelée valeur de masque, pour le paramètre include de la fonction ST_REGIONSTATS qui détermine le poids de chaque pixel dans les calculs. Les valeurs de pondération doivent être comprises entre 0 et 1. Les pondérations en dehors de cette plage sont définies sur la limite la plus proche, soit 0, soit 1.

Un pixel est considéré comme valide si sa pondération est supérieure à 0. Une pondération de 0 indique un pixel non valide. Les pixels non valides représentent généralement des données manquantes ou non fiables, telles que des zones masquées par des nuages, des anomalies de capteur, des erreurs de traitement ou des emplacements en dehors d'une limite définie.

Si vous ne spécifiez pas de pondération, chaque pixel est automatiquement pondéré par la proportion du pixel qui se trouve dans la géométrie, ce qui permet une inclusion proportionnelle dans les statistiques zonales. Si la géométrie est inférieure à 1/256 de la taille du pixel, la pondération du pixel est de 0. Dans ce cas, null est renvoyé pour toutes les statistiques, à l'exception de count et area, qui sont égales à 0.

Si un pixel partiellement intersecté a une pondération de l'argument include à ST_REGIONSTATS, BigQuery utilise le minimum de cette pondération et la fraction du pixel qui intersecte la région.

Les valeurs de pondération n'ont pas la même précision que les valeurs FLOAT64. En pratique, leur valeur réelle peut différer de la valeur utilisée dans les calculs jusqu'à 1/256 (environ 0,4%).

Vous pouvez fournir une expression à l'aide de la syntaxe d'expression d'image Earth Engine dans votre argument include pour pondérer dynamiquement les pixels en fonction de critères spécifiques dans les bandes de trame. Par exemple, l'expression suivante limite les calculs aux pixels où la bande probability dépasse 70%:

include => 'probability > 0.7'

Si l'ensemble de données inclut une bande de facteur de pondération, vous pouvez l'utiliser avec la syntaxe suivante :

include => 'weight_factor_band_name'

Taille des pixels et échelle d'analyse

Une image de trame géospatiale est une grille de pixels qui correspond à un emplacement à la surface de la Terre. La taille des pixels d'une trame, parfois appelée l' échelle, est la taille nominale d'un bord d'un pixel dans le système de référence de coordonnées de la grille. Par exemple, une trame avec une résolution de 10 mètres comporte des pixels de 10 mètres sur 10 mètres. La taille des pixels d'origine peut varier considérablement d'un ensemble de données à l'autre, allant de moins de 1 mètre à plus de 20 kilomètres.

Lorsque vous utilisez la fonction ST_REGIONSTATS pour calculer des statistiques zonales, la taille des pixels des données de trame est un élément essentiel à prendre en compte. Par exemple, l'agrégation de données de trame haute résolution sur la région d'un pays peut être gourmande en ressources de calcul et inutilement précise. À l'inverse, l'agrégation de données basse résolution sur la région, comme les parcelles de ville, peut ne pas fournir suffisamment de détails.

Pour obtenir des résultats pertinents et efficaces de votre analyse, nous vous recommandons de choisir une taille de pixel adaptée à la taille de vos polygones et à l'objectif de votre analyse. Vous trouverez la taille des pixels pour chaque ensemble de données de trame dans la section de description des tables d'images dans BigQuery Sharing.

La modification de la taille des pixels modifie le nombre de pixels qui intersectent une géographie donnée, ce qui affecte les résultats et leur interprétation. Nous vous déconseillons de modifier la taille des pixels pour les analyses de production. Toutefois, si vous créez un prototype de requête, l'augmentation de la taille des pixels peut réduire la durée et le coût de la requête, en particulier pour les données haute résolution.

Pour modifier la taille des pixels, définissez scale dans l'argument options de la fonction ST_REGIONSTATS. Par exemple, pour calculer des statistiques sur des pixels de 1 000 mètres, utilisez options => JSON '{"scale":1000}', ce qui indique à Earth Engine de rééchantillonner l'image à l'échelle demandée. Pour en savoir plus sur la façon dont Earth Engine gère le redimensionnement, consultez Échelle dans la documentation Google Earth Engine.

Le calcul de statistiques pour des polygones beaucoup plus petits que les pixels de la trame peut produire des résultats inexacts ou nuls. Dans ce cas, vous pouvez remplacer le polygone par son point centroïde à l'aide de ST_CENTROID.

Facturation

Lorsque vous exécutez une requête, l'utilisation de la fonction ST_REGIONSTATS est facturée séparément du reste de la requête, car Earth Engine calcule les résultats de l'appel de fonction. Cette utilisation vous est facturée en heures d'emplacement sous la référence SKU des services BigQuery, que vous utilisiez la facturation à la demande ou les réservations. Pour afficher le montant facturé pour les appels BigQuery à Earth Engine, consultez votre rapport sur la facturation et utilisez les étiquettes pour filtrer par la clé d'étiquette goog-bq-feature-type, avec la valeur EARTH_ENGINE. Si la fonction ST_REGIONSTATS échoue, vous n'êtes pas facturé pour les calculs Earth Engine utilisés.

Pour chaque requête, vous pouvez utiliser la jobs.get méthode de l'API BigQuery pour afficher les informations suivantes :

  • Le champ slotMs, qui indique le nombre de millisecondes d'emplacement consommées par Earth Engine lorsque le champ externalService est EARTH_ENGINE et le champ billingMethod est SERVICES_SKU.
  • Le champ totalServicesSkuSlotMs, qui indique le nombre total de millisecondes d'emplacement utilisées par tous les services externes BigQuery facturés sur la référence SKU des services BigQuery.

Vous pouvez également interroger le champ total_services_sku_slot_ms dans la vue INFORMATION_SCHEMA.JOBS pour trouver le nombre total de millisecondes d'emplacement consommées par les services externes facturés sur la référence SKU des services BigQuery.

Facteurs de coût

Les facteurs suivants ont un impact sur l'utilisation du calcul lorsque vous exécutez la fonction ST_REGIONSTATS :

  • Nombre de lignes d'entrée.
  • Image de trame que vous utilisez. Certaines trames sont des composites créés à partir de collections d'images sources dans le catalogue de données Earth Engine. Les ressources de calcul nécessaires pour produire le résultat composite varient.
  • Résolution de l'image.
  • Taille et complexité de la géographie d'entrée, nombre de pixels qui intersectent la géographie, et nombre de tuiles d'image et d'octets lus par Earth Engine.

  • Emplacement de la géographie d'entrée sur la Terre par rapport aux images sources, ainsi que projection et résolution de l'image.

    • Les projections d'image peuvent déformer les pixels, en particulier ceux situés à des latitudes élevées ou loin de la zone de couverture prévue de l'image.
    • Pour les trames composites, le nombre d'images sources intersectant la géographie d'entrée peut varier selon la région et au fil du temps. Par exemple, certains satellites produisent plus d'images à des latitudes basses ou élevées, en fonction de leur orbite et de leurs paramètres de collecte de données, ou peuvent omettre des images en fonction des conditions atmosphériques changeantes.

  • Utilisation de formules dans les arguments include ou band_name, et nombre de bandes impliquées.

  • Mise en cache des résultats précédents.

Contrôler les coûts

Pour contrôler les coûts associés à la fonction ST_REGIONSTATS, vous pouvez ajuster le quota qui contrôle la quantité de temps d'emplacement que la fonction est autorisée à consommer. La valeur par défaut est de 350 heures d'emplacement par jour. Lorsque vous affichez vos quotas, filtrez la liste Metric sur earthengine.googleapis.com/bigquery_slot_usage_time pour afficher le quota Earth Engine associé aux appels de BigQuery. Pour en savoir plus, consultez la section Quotas des fonctions de trame BigQuery dans la documentation Google Earth Engine.

Régions où le service est disponible

Les requêtes qui appellent la fonction ST_REGIONSTATS doivent s'exécuter dans l'une des régions suivantes :

  • Multirégion US
  • us-central1
  • us-central2
  • Multirégion EU
  • europe-west1

Étape suivante