Trabaja con datos ráster usando Earth Engine en BigQuery

En este documento, se explica cómo combinar datos de ráster y vectoriales con la función ST_REGIONSTATS, que llama a Google Earth Engine para realizar análisis geoespaciales en BigQuery.

Descripción general

Un raster 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 particular en la superficie de la Tierra y tener bandas para la temperatura promedio y la lluvia promedio. Los datos ráster incluyen imágenes satelitales y otros datos continuos basados en cuadrículas, como pronósticos meteorológicos y cobertura terrestre. Muchos formatos de imagen comunes, como los archivos PNG o JPEG, se formatean como datos ráster.

Los datos ráster 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 regiones.

Los datos geoespaciales de trama y vector se suelen combinar 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 desees calcular lo siguiente:

• Calidad del aire promedio en cada condado de tu estado
• Potencial solar para una colección de polígonos de edificios.
• Se resume el riesgo de incendios a lo largo de los corredores de líneas eléctricas en áreas boscosas.

BigQuery se destaca en el procesamiento de datos vectoriales, y Google Earth Engine, en el procesamiento de datos ráster. Puedes usar la función de geografía ST_REGIONSTATS para combinar datos de ráster 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 BigQuery sharing (anteriormente 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)
• Suscribirse 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:

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

Cómo encontrar datos ráster

El parámetro raster_id en la función ST_REGIONSTATS es una cadena que especifica la fuente de tus datos ráster. En las siguientes secciones, se explica cómo encontrar 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 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 las fichas.

Google Earth Engine publica conjuntos de datos disponibles públicamente que contienen datos ráster. Para suscribirte a un conjunto de datos de Earth Engine con datos 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 search 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, a veces llamada tabla de imágenes, que almacena metadatos para una colección de imágenes ráster según 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 ráster. El ID de ráster de cada imagen se almacena en la columna assets.image.href. Para encontrar una imagen específica, puedes filtrar por propiedades de imagen en la columna properties. Puedes encontrar información sobre las bandas en la descripción de la tabla.

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. La siguiente consulta filtra la tabla de imágenes con la columna properties.start_datetime para obtener el ID de ráster de la imagen correspondiente al 1 de enero de 2025 y calcula la temperatura promedio de cada país con 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  properties.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 común para almacenar datos ráster geoespaciales. La función ST_REGIONSTATS admite datos ráster almacenados en formato GeoTIFF en buckets de Cloud Storage ubicados en las regiones US o us-central1. Proporciona el URI de Cloud Storage como el ID de ráster, por ejemplo, gs://bucket/folder/raster.tif.

Recursos de imagen de Earth Engine

La función ST_REGIONSTATS admite el paso de una ruta de acceso a un activo 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 colecciones de imágenes. Para encontrar el ID de ráster de una imagen, sigue estos pasos:

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

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 la forma ee.Image('IMAGE_PATH'), el ID del ráster es 'ee://IMAGE_PATH'.

   Si el fragmento de Earth Engine tiene la forma ee.ImageCollection('IMAGE_COLLECTION_PATH'), puedes usar el editor de código de Earth Engine para filtrar la colección de imágenes 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 del ráster 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 ponderar cada píxel en los cálculos. Los valores de peso deben estar 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. Por lo general, los píxeles no válidos representan datos faltantes o no confiables, como áreas oscurecidas por nubes, anomalías en los 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 un píxel que se cruza parcialmente 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 cruza 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 hasta en 1/256 (alrededor del 0.4%).

Puedes proporcionar una expresión con la sintaxis de expresión de imágenes 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 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 píxel y escala de 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 un factor crucial que se debe tener en cuenta. 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 demasiado detallado. Por el contrario, agregar datos de baja resolución en toda la región, como las parcelas de la ciudad, podría no proporcionar 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 encontrar 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 en el uso compartido de BigQuery.

Cambiar el tamaño del píxel modifica la cantidad de píxeles que se cruzan con una ubicación geográfica determinada, lo que afecta los resultados y su interpretación. No recomendamos cambiar el tamaño del 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 píxel puede reducir el tiempo de ejecución y el costo de la consulta, especialmente para los datos de alta resolución.

Para cambiar el tamaño de píxel, establece 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 Scale en la documentación de Google Earth Engine.

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 la función. Este uso se factura en horas de ranura según el SKU de los 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.

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.
• Es la imagen de trama que usas. Algunos rásteres son compuestos creados a partir de colecciones de imágenes fuente en el catálogo de datos de Earth Engine, y los recursos de procesamiento para producir el resultado compuesto varían.
• Resolución de la imagen.
• El tamaño y la complejidad de la geografía de entrada, la cantidad de píxeles que se intersecan con la geografía y la cantidad de mosaicos de imágenes y bytes que lee Earth Engine.

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

  • Las proyecciones de imágenes pueden distorsionar los píxeles, en especial 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, la cantidad de imágenes de origen que se intersecan con la geografía de entrada puede variar según la región y con 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.

• Almacenamiento en caché de 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 se le permite consumir a la función. El valor predeterminado es de 350 horas de ranura por día. Cuando consultes tus cuotas, filtra la lista de Métricas 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 las funciones ráster de BigQuery en la documentación de Google Earth Engine.

Limitaciones

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

• US
• us-central1
• us-central2

¿Qué sigue?

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