Trabaja con datos de trama usando Earth Engine en BigQuery

Combinar datos ráster y vectoriales con la función ST_REGIONSTATS te permite calcular estadísticas zonales, como la calidad promedio del aire o el riesgo de incendio, en regiones geográficas específicas. Puedes usar Google Earth Engine directamente en BigQuery para analizar imágenes satelitales y previsiones meteorológicas junto con tus límites vectoriales existentes.

Descripción general

Un ráster es una cuadrícula bidimensional de píxeles, a cada uno de los cuales se le asigna uno o más valores llamados bandas. Por ejemplo, cada píxel podría corresponder a un kilómetro cuadrado en particular de la superficie de la Tierra y tener bandas para la temperatura promedio y la precipitación promedio. Los datos de trama incluyen imágenes satelitales y otros datos continuos basados en cuadrículas, como las previsiones meteorológicas y la cobertura del suelo. Muchos formatos de imagen comunes, como los archivos PNG o JPEG, tienen el formato de datos de trama.

Los datos de trama suelen contrastarse con los datos vectoriales, en los que los datos se describen con líneas o curvas, en lugar de una cuadrícula rectangular fija. Por ejemplo, puedes usar el tipo de datos GEOGRAPHY en BigQuery para describir los límites de países, ciudades o de otras regiones.

Los datos geoespaciales de trama y vectoriales suelen combinarse con una operación de estadísticas zonales, que calcula un agregado de todos los valores de trama dentro de una región vectorial determinada. Por ejemplo, es posible que quieras calcular lo siguiente:

• Calidad del aire promedio en un conjunto de ciudades.
• Potencial solar de una colección de polígonos de edificios.
• Resumen del riesgo de incendio en los corredores de líneas eléctricas en áreas forestales.

BigQuery se destaca en el procesamiento de datos vectoriales, y Google Earth Engine, en el procesamiento de datos de trama. Puedes usar la función geográfica ST_REGIONSTATS para combinar datos de trama con Earth Engine y tus datos vectoriales almacenados en BigQuery.

Antes de comenzar

1. Para usar la función ST_REGIONSTATS en tus consultas, habilita la API de Earth Engine.

   Habilitar la API

2. Opcional: Para suscribirte a los datos publicados en el uso compartido de BigQuery (antes Analytics Hub) y usarlos con la función ST_REGIONSTATS, habilita la API de Analytics Hub.

   Habilitar la API

Permisos necesarios

Para obtener los permisos que necesitas para llamar a la función ST_REGIONSTATS, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

• Visualizador de recursos de Earth Engine (roles/earthengine.viewer)
• Consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer)
• Suscribirte a conjuntos de datos en el uso compartido de BigQuery: Editor de datos de BigQuery (roles/bigquery.dataEditor)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para llamar a la función ST_REGIONSTATS. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para llamar a la función ST_REGIONSTATS:

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

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Busca datos de trama

El parámetro raster_id de la función ST_REGIONSTATS es una cadena que especifica la fuente de tus datos de trama. En las siguientes secciones, se explica cómo buscar y dar formato al ID de ráster.

Tablas de imágenes de BigQuery

Puedes usar BigQuery sharing (anteriormente Analytics Hub) para descubrir y acceder a conjuntos de datos de ráster en BigQuery. Para usar BigQuery sharing, debes habilitar la API de Analytics Hub y asegurarte de tener los permisos necesarios para ver y suscribirte a fichas y exchanges de datos.

Google Earth Engine publica conjuntos de datos disponibles de forma pública que contienen datos de trama en las multirregiones US y EU. Para suscribirte a un conjunto de datos de Earth Engine con datos de ráster, sigue estos pasos:

1. Ve a la página Uso compartido (Analytics Hub).

   Ir a Uso compartido (Analytics Hub)

2. Haz clic en Buscar fichas.

3. En el campo Buscar fichas, ingresa "Google Earth Engine".

4. Haz clic en el conjunto de datos al que deseas suscribirte.

5. Haz clic en Suscribirse.

6. Opcional: Actualiza los campos Proyecto o Nombre del conjunto de datos vinculado.

7. Haz clic en Guardar. El conjunto de datos vinculado se agrega a tu proyecto.

El conjunto de datos contiene una tabla de imágenes que almacena metadatos para una colección de imágenes de trama que siguen la especificación de elementos de STAC. Una tabla de imágenes es análoga a una colección de imágenes de Earth Engine (ImageCollection).

Cada fila de la tabla corresponde a una sola imagen de trama, con columnas que contienen propiedades y metadatos de la imagen. El ID de ráster de cada imagen se almacena en la columna assets.image.href. Haz referencia a las imágenes en tus consultas con este ID como el valor del parámetro raster_id.

Filtra la tabla con las columnas de propiedades para seleccionar imágenes o subconjuntos de imágenes específicos que cumplan con tus criterios. Para obtener más información sobre las bandas disponibles, el tamaño de los píxeles y las definiciones de las propiedades, abre la tabla y haz clic en la pestaña Detalles de la imagen.

Cada tabla de imágenes incluye una tabla *_metadata correspondiente que proporciona información de respaldo para la tabla de imágenes.

Por ejemplo, el conjunto de datos de ERA5-Land proporciona estadísticas diarias de variables climáticas y está disponible de forma pública. La tabla climate contiene varios IDs de ráster. En la siguiente consulta, se filtra la tabla de imágenes con la columna start_datetime para obtener el ID de ráster de la imagen correspondiente al 1 de enero de 2025 y se calcula la temperatura promedio de cada país con la banda 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;

Permite trabajar con BigQuery DataFrames.

Antes de probar este ejemplo, sigue las instrucciones de configuración de BigQuery DataFrames en la guía de inicio rápido de BigQuery con BigQuery DataFrames. Para obtener más información, consulta la documentación de referencia de BigQuery DataFrames.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura ADC para un entorno de desarrollo 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 de Cloud Storage

GeoTIFF es un formato de archivo común para almacenar datos de trama geoespaciales. La función ST_REGIONSTATS admite datos de trama almacenados en el formato GeoTIFF optimizado para la nube (COG) en buckets de Cloud Storage que se encuentran en las siguientes regiones:

• Multirregión de US
• us-central1
• Multirregión de EU
• europe-west1

Proporciona el URI de Cloud Storage como el ID de ráster, como gs://bucket/folder/raster.tif.

Recursos de imagen de Earth Engine

La función ST_REGIONSTATS admite pasar una ruta de acceso de recurso de imagen de Earth Engine para el argumento raster_id. Los datos de trama de Earth Engine están disponibles como imágenes individuales o colecciones de imágenes. Estos datos existen en la región US y solo son compatibles con las consultas que se ejecutan en la región US. Para encontrar el ID de ráster de una imagen, sigue estos pasos:

1. Busca el conjunto de datos que te interesa en el catálogo de datos de Earth Engine.

2. Para abrir la página de descripción de esa entrada, haz clic en el nombre del conjunto de datos. El fragmento de Earth Engine describe una sola imagen o una colección de imágenes.

   Si el fragmento de Earth Engine tiene el formato ee.Image('IMAGE_PATH'), el ID de ráster es 'ee://IMAGE_PATH'.

   Si el fragmento de Earth Engine tiene el formato ee.ImageCollection('IMAGE_COLLECTION_PATH'), puedes usar el editor de código de Earth Engine para filtrar la ImageCollection en una sola imagen. Usa el método ee.Image.get('system:id') para imprimir el valor de IMAGE_PATH de esa imagen en la consola. El ID de la trama es 'ee://IMAGE_PATH'.

Pesos de píxeles

Puedes especificar un peso, a veces denominado valor de máscara, para el parámetro include en la función ST_REGIONSTATS que determina cuánto peso se debe asignar a cada píxel en los cálculos. Los valores de peso deben estar comprendidos entre 0 y 1. Los pesos fuera de este rango se establecen en el límite más cercano, ya sea 0 o 1.

Un píxel se considera válido si tiene un peso mayor que 0. Un peso de 0 indica un píxel no válido. Los píxeles no válidos suelen representar datos faltantes o poco confiables, como áreas ocultas por nubes, anomalías de sensores, errores de procesamiento o ubicaciones fuera de un límite definido.

Si no especificas un peso, cada píxel se pondera automáticamente según la proporción del píxel que se encuentra dentro de la geometría, lo que permite la inclusión proporcional en las estadísticas zonales. Si la geometría es menor que 1/256 del tamaño del píxel, el peso del píxel es 0. En estos casos, se devuelve null para todas las estadísticas, excepto count y area, que son 0.

Si un píxel que se interseca de forma parcial tiene un peso del argumento include a ST_REGIONSTATS, BigQuery usa el mínimo de ese peso y la fracción del píxel que interseca la región.

Los valores de peso no tienen la misma precisión que los valores de FLOAT64. En la práctica, su valor real puede diferir del valor usado en los cálculos hasta en 1/256 (alrededor del 0.4%).

Puedes proporcionar una expresión con la sintaxis de expresión de imagen de Earth Engine en tu argumento include para ponderar de forma dinámica los píxeles según criterios específicos dentro de las bandas de ráster. Por ejemplo, la siguiente expresión restringe los cálculos a los píxeles en los que la banda probability supera el 70%:

include => 'probability > 0.7'

Si el conjunto de datos incluye una banda de factor de ponderación, puedes usarla con la siguiente sintaxis:

include => 'weight_factor_band_name'

Tamaño de los píxeles y escala del análisis

Una imagen ráster geoespacial es una cuadrícula de píxeles que corresponde a alguna ubicación en la superficie de la Tierra. El tamaño de píxel de un ráster, a veces llamado escala, es el tamaño nominal de un borde de un píxel en el sistema de referencia de coordenadas de la cuadrícula. Por ejemplo, un ráster con una resolución de 10 metros tiene píxeles de 10 metros por 10 metros. El tamaño de píxel original informado puede variar drásticamente entre los conjuntos de datos, desde menos de 1 metro hasta más de 20 kilómetros.

Cuando se usa la función ST_REGIONSTATS para calcular estadísticas zonales, el tamaño de píxel de los datos ráster es una consideración fundamental. Por ejemplo, agregar datos de ráster de alta resolución en la región de un país puede ser intensivo desde el punto de vista computacional y detallado de forma innecesaria. Por el contrario, agregar datos de baja resolución en la región, como parcelas de la ciudad, podría no proporcionar suficientes detalles.

Para obtener resultados significativos y eficientes de tu análisis, te recomendamos elegir un tamaño de píxel adecuado para el tamaño de tus polígonos y el objetivo de tu análisis. Puedes encontrar el tamaño de píxel de cada conjunto de datos de ráster en la sección de descripción de las tablas de imágenes en BigQuery sharing.

Cambiar el tamaño de los píxeles modifica la cantidad de píxeles que se cruzan con una geografía determinada, lo que afecta los resultados y su interpretación. No recomendamos cambiar el tamaño de píxel para los análisis de producción. Sin embargo, si estás creando un prototipo de una consulta, aumentar el tamaño de los píxeles puede reducir el tiempo de ejecución y el costo de la consulta, en especial para los datos de alta resolución.

Para cambiar el tamaño de los píxeles, establece el scale en el argumento options de la función ST_REGIONSTATS. Por ejemplo, para calcular estadísticas sobre píxeles de 1,000 metros, usa options => JSON '{"scale":1000}', que le indica a Earth Engine que vuelva a muestrear la imagen en la escala solicitada. Para obtener más información sobre cómo Earth Engine controla el cambio de escala, consulta Escala en la documentación de Google Earth Engine.

Calcular estadísticas para polígonos que son significativamente más pequeños que los píxeles del ráster puede producir resultados imprecisos o nulos. En ese caso, una alternativa es reemplazar el polígono por su punto centroide con ST_CENTROID.

Facturación

Cuando ejecutas una consulta, el uso de la función ST_REGIONSTATS se factura por separado del resto de la consulta, ya que Earth Engine calcula los resultados de la llamada a función. Se te factura por este uso en horas de ranura con el SKU de servicios de BigQuery, independientemente de si usas la facturación a pedido o las reservas. Para ver el importe facturado por las llamadas de BigQuery a Earth Engine, consulta tu informe de facturación y usa etiquetas para filtrar por la clave de etiqueta goog-bq-feature-type, con el valor EARTH_ENGINE. Si la función ST_REGIONSTATS falla, no se te facturará ningún procesamiento de Earth Engine que se haya usado.

Para cada consulta, puedes usar el método jobs.get en la API de BigQuery para ver la siguiente información:

• El campo slotMs, que muestra la cantidad de milisegundos de ranura que consumió Earth Engine cuando el campo externalService es EARTH_ENGINE y el campo billingMethod es SERVICES_SKU.
• El campo totalServicesSkuSlotMs, que muestra la cantidad total de milisegundos de ranura que usan todos los servicios externos de BigQuery que se facturan en el SKU de servicios de BigQuery.

También puedes consultar el campo total_services_sku_slot_ms en la vista INFORMATION_SCHEMA.JOBS para encontrar el total de milisegundos de ranura consumidos por los servicios externos facturados en el SKU de servicios de BigQuery.

Factores de costo

Los siguientes factores afectan el uso de procesamiento cuando ejecutas la función ST_REGIONSTATS:

• Es la cantidad de filas de entrada.
• La imagen de trama que usas Algunas imágenes de trama son compuestos creados a partir de colecciones de imágenes de origen en el Data Catalog de Earth Engine, y los recursos de procesamiento para producir el resultado compuesto varían.
• Es la resolución de la imagen.
• El tamaño y la complejidad de la geografía de entrada, la cantidad de píxeles que se cruzan con la geografía y la cantidad de mosaicos de imágenes y bytes que lee Earth Engine.

• La ubicación de la geografía de entrada en la Tierra en relación con las imágenes de origen y la proyección y resolución de la imagen.

  • Las proyecciones de imágenes pueden deformar los píxeles, en especial los que se encuentran en latitudes altas o muy por fuera del área de cobertura prevista de la imagen.
  • En el caso de los rásteres compuestos, la cantidad de imágenes de origen que se cruzan con la geografía de entrada puede variar según la región y el tiempo. Por ejemplo, algunos satélites producen más imágenes en latitudes bajas o altas, según su órbita y los parámetros de recopilación de datos, o pueden omitir imágenes según las condiciones atmosféricas cambiantes.

• El uso de fórmulas en los argumentos include o band_name, y la cantidad de bandas que involucran.

• El almacenamiento en caché de los resultados anteriores

Controla los costos

Para controlar los costos asociados con la función ST_REGIONSTATS, puedes ajustar la cuota que controla la cantidad de tiempo de ranura que la función puede consumir. El valor predeterminado es de 350 horas de ranura por día. Cuando veas tus cuotas, filtra la lista Métrica por earthengine.googleapis.com/bigquery_slot_usage_time para ver la cuota de Earth Engine asociada con las llamadas de BigQuery. Para obtener más información, consulta las cuotas de funciones de ráster de BigQuery en la documentación de Google Earth Engine.

Nota: Al igual que las cuotas de consultas personalizadas en BigQuery, esta cuota es aproximada. Proporciona una protección contra el gasto excesivo, pero no está diseñado para limitar estrictamente el tiempo de las ranuras. En ocasiones, BigQuery podría ejecutar una consulta que exceda el límite de la cuota, y es posible que agotes tu cuota sin que se te facture por todo el importe consumido.

Regiones admitidas

Las consultas que llaman a la función ST_REGIONSTATS deben ejecutarse en una de las siguientes regiones:

• Multirregión de US
• us-central1
• us-central2
• Multirregión de EU
• europe-west1

¿Qué sigue?

• Prueba el instructivo que te muestra cómo usar datos de ráster para analizar la temperatura.
• Obtén más información sobre las funciones de ubicación geográfica en BigQuery.
• Obtén más información para trabajar con datos geoespaciales.