Trabajar con datos ráster mediante Earth Engine en BigQuery

En este documento se explica cómo combinar datos ráster y vectoriales mediante la función ST_REGIONSTATS, que usa Google Earth Engine para acceder a datos de imágenes y ráster en BigQuery.

Información general

Un raster es una cuadrícula bidimensional de píxeles, a cada uno de los cuales se le asigna uno o varios valores denominados bandas. Por ejemplo, cada píxel podría corresponder a un kilómetro cuadrado concreto de la superficie terrestre y tener bandas de temperatura media y precipitaciones medias. Los datos ráster incluyen imágenes de satélite y otros datos continuos basados en cuadrículas, como previsiones meteorológicas y cobertura del suelo. Muchos formatos de imagen habituales, como los archivos PNG o JPEG, tienen formato de datos rasterizados.

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

Los datos raster y vectoriales geoespaciales se suelen combinar mediante una operación de estadísticas zonales, que calcula un agregado de todos los valores raster de una región vectorial determinada. Por ejemplo, puede que quieras calcular lo siguiente:

• Calidad del aire media en un conjunto de ciudades.
• Potencial solar de una colección de polígonos de edificios.
• Resumen del riesgo de incendios a lo largo de los corredores de líneas eléctricas en zonas forestales.

BigQuery destaca en el procesamiento de datos vectoriales, mientras que Google Earth Engine lo hace en el procesamiento de datos ráster. Puedes usar la ST_REGIONSTATS función de geografía para combinar datos ráster con Earth Engine y tus datos vectoriales almacenados en BigQuery.

Antes de empezar

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

   Activar la API

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

   Activar la API

Permisos obligatorios

Para obtener los permisos que necesitas para llamar a la función ST_REGIONSTATS, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en tu proyecto:

• Lector de recursos de Earth Engine (roles/earthengine.viewer)
• Consumidor de uso del servicio (roles/serviceusage.serviceUsageConsumer)
• Suscribirse a conjuntos de datos en BigQuery Sharing: Editor de datos de BigQuery (roles/bigquery.dataEditor)

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar 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 se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

Para llamar a la función ST_REGIONSTATS, se necesitan los siguientes permisos:

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

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

Buscar datos ráster

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

Tablas de imágenes de BigQuery

Puede usar la función de compartir de BigQuery (antes Analytics Hub) para descubrir y acceder a conjuntos de datos ráster en BigQuery. Para usar la función de compartir de BigQuery, debe habilitar la API Analytics Hub y asegurarse de que tiene los permisos necesarios para ver y suscribirse a fichas.

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

1. Vaya a la página Compartir (Analytics Hub).

   Ir a Compartir (Analytics Hub)

2. Haz clic en Buscar fichas.

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

4. Haga clic en el conjunto de datos al que quiera suscribirse.

5. Haz clic en Suscribirme.

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

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

El conjunto de datos contiene una tabla de imágenes que almacena metadatos de una colección de imágenes ráster según la especificación de elementos 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 rasterizada, y las columnas contienen las propiedades y los 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 de tus consultas usando este ID como valor del parámetro raster_id.

Filtra la tabla usando las columnas de propiedades para seleccionar imágenes o subconjuntos de imágenes específicos que cumplan 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, abra la tabla y haga clic en la pestaña Detalles de la imagen.

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

Por ejemplo, el conjunto de datos ERA5-Land proporciona estadísticas diarias de variables climáticas y está disponible públicamente. La climate tabla contiene varios IDs de ráster. La siguiente consulta filtra la tabla de imágenes mediante la columna start_datetime para obtener el ID ráster de la imagen correspondiente al 1 de enero del 2025 y calcula la temperatura media de cada país mediante la banda temperature_2m:

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;

GeoTIFF de Cloud Storage

GeoTIFF es un formato de archivo habitual para almacenar datos ráster geoespaciales. La función ST_REGIONSTATS admite datos ráster almacenados en formato GeoTIFF optimizado para la nube (COG) en segmentos de Cloud Storage ubicados en las siguientes regiones:

• US multirregional
• us-central1
• EU multirregional
• europe-west1

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

Recursos de imagen de Earth Engine

La función ST_REGIONSTATS admite que se proporcione una ruta de acceso a un recurso de imagen de Earth Engine para el argumento raster_id. Los datos ráster de Earth Engine están disponibles como imágenes individuales o como colecciones de imágenes. Estos datos se encuentran 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 interese 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'), puede usar el editor de código de Earth Engine para filtrar la ImageCollection y obtener una sola imagen. Usa el método ee.Image.get('system:id') para imprimir el valor IMAGE_PATH de esa imagen en la consola. El ID de raster es 'ee://IMAGE_PATH'.

Pesos de píxeles

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

Un píxel se considera válido si tiene un peso superior a 0. Un peso de 0 indica que el píxel no es válido. Los píxeles no válidos suelen representar datos que faltan o que no son fiables, como zonas oscurecidas por nubes, anomalías de los sensores, errores de procesamiento o ubicaciones fuera de un límite definido.

Si no especifica 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 inferior a 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 parcialmente intersecado 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 se interseca con 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 utilizado en los cálculos en hasta 1/256 (aproximadamente un 0,4%).

Puedes proporcionar una expresión con la sintaxis de expresiones de imágenes de Earth Engine en el argumento include para ponderar dinámicamente los píxeles en función de criterios específicos de las bandas 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 peso, puedes usarla con la siguiente sintaxis:

include => 'weight_factor_band_name'

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

Una imagen ráster geoespacial es una cuadrícula de píxeles que corresponde a una ubicación en la superficie de la Tierra. El tamaño de píxel de un ráster, a veces denominado 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 notificado puede variar considerablemente 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 un factor crucial. Por ejemplo, agregar datos ráster de alta resolución en la región de un país puede ser un proceso computacionalmente intensivo y granular en exceso. Por el contrario, agregar datos de baja resolución de toda la región, como las parcelas de una ciudad, puede que no proporcione suficientes detalles.

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

Si cambias el tamaño de los píxeles, cambia el número de píxeles que se cruzan con una geografía determinada, lo que afecta a los resultados y a su interpretación. No recomendamos cambiar el tamaño de los píxeles en los análisis de producción. Sin embargo, si estás creando un prototipo de consulta, aumentar el tamaño de los píxeles puede reducir el tiempo de ejecución y el coste de la consulta, sobre todo en el caso de los datos de alta resolución.

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

Si se calculan estadísticas de polígonos que son significativamente más pequeños que los píxeles del ráster, se pueden obtener resultados imprecisos o nulos. En ese caso, una alternativa es sustituir el polígono por su punto centroide mediante 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 porque Earth Engine calcula los resultados de la llamada a la función. Se te facturará este uso en horas de ranura con la SKU de servicios de BigQuery, independientemente de si utilizas la facturación bajo demanda 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 cobrará por ningún cálculo de Earth Engine que se haya utilizado.

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

• El campo slotMs, que muestra el número de milisegundos de tiempo de CPU consumidos por Earth Engine cuando el campo externalService es EARTH_ENGINE y el campo billingMethod es SERVICES_SKU.
• El campo totalServicesSkuSlotMs, que muestra el número total de milisegundos de ranura usados por todos los servicios externos de BigQuery que se facturan con el SKU de servicios de BigQuery.

Factores de coste

Los siguientes factores influyen en el uso de recursos de computación cuando ejecutas la función ST_REGIONSTATS:

• Número de filas de entrada.
• La imagen rasterizada que usas. Algunos rásteres son compuestos creados a partir de colecciones de imágenes de origen del catálogo de datos de Earth Engine, y los recursos computacionales para producir el resultado compuesto varían.
• La resolución de la imagen.
• El tamaño y la complejidad de la geografía de entrada, el número de píxeles que se cruzan con la geografía y el número de mosaicos de imagen y bytes leídos por Earth Engine.

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

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

• El uso de fórmulas en los argumentos include o band_name, y el número de bandas que implican.

• Almacenamiento en caché de resultados anteriores.

Controla los costes

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

Nota: Al igual que las cuotas de consultas personalizadas de BigQuery, esta cuota es aproximada. Esta función es una medida de protección para no excederte en el gasto, pero no está diseñada para limitar estrictamente el tiempo de las franjas. Es posible que, a veces, BigQuery ejecute una consulta que supere el límite de la cuota y que agotes la cuota sin que se te facture el importe total consumido.

Regiones disponibles

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

• US multirregional
• us-central1
• us-central2
• EU multirregional
• europe-west1

Siguientes pasos

• Consulte el tutorial sobre cómo usar datos ráster para analizar la temperatura.
• Más información sobre las funciones geográficas de BigQuery
• Más información sobre cómo trabajar con datos geoespaciales