Cómo trabajar con datos ráster

En este documento, se explica cómo combinar datos vectoriales y rasterizados con la función ST_REGIONSTATS 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 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 pronósticos del clima y cobertura terrestre. Muchos formatos de imagen comunes, como los archivos PNG o JPEG, tienen formato de datos de trama.

Los datos de trama a menudo se contrastan con los datos de vector, 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 vectoriales y de trama geoespaciales a menudo se combinan 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:

  • La calidad del aire promedio en cada condado de tu estado
  • Es el potencial solar de un conjunto de polígonos de edificios.
  • Resumen del riesgo de incendio 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 se destaca en el procesamiento de datos de trama. Puedes usar la función geográfica ST_REGIONSTATS para combinar datos de trama con Earth Engine con 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 (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:

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.

Cómo encontrar datos de trama

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.

compartir tablas de imágenes

Puedes usar el uso compartido para descubrir y acceder a conjuntos de datos raster en BigQuery. Para usar la función de uso compartido, 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 de manera pública en el uso compartido que contienen datos de trama. Para suscribirte a un conjunto de datos de Earth Engine con datos ráster, sigue estos pasos:

  1. Ve a la página Analytics Hub.

    Ir a 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 Project o Linked dataset name.

  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 STAC. Una tabla de imágenes es similar a una colección de imágenes de Earth Engine (ImageCollection).

Cada fila de la tabla corresponde a una sola imagen raster. 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 ERA5-Land proporciona estadísticas diarias de las variables climáticas y está disponible para el público a través de la opción de compartir. La tabla climate contiene varios IDs de ráster. En la siguiente consulta, se filtra la tabla de imágenes con la columna properties.start_datetime para obtener el ID de trama 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:

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 de trama geoespaciales. La función ST_REGIONSTATS admite datos de trama almacenados en el formato GeoTIFF en buckets de Cloud Storage que se encuentran en las regiones US o us-central1. Proporciona el URI de Cloud Storage como el ID de trama, como gs://bucket/folder/raster.tif.

Recursos de imagen de Earth Engine

La función ST_REGIONSTATS admite pasar una ruta de acceso de activo 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. Para encontrar el ID de raster 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 recopilación de imágenes.

    Si el fragmento de Earth Engine tiene el formato ee.Image('IMAGE_PATH'), el ID del 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 IMAGE_PATH de esa imagen en la consola. El ID del ráster es 'ee://IMAGE_PATH'.

Grosores de píxeles

Puedes especificar un peso, que a veces se denomina valor de máscara, para el parámetro include en la función ST_REGIONSTATS que determina cuánto se debe ponderar cada píxel en los cálculos. Los valores de peso deben oscilar 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 superior a 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 valor de ponderación, 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 hasta en 1/256 (alrededor de un 0.4%) del valor que se usa en los cálculos.

Puedes proporcionar una expresión con la sintaxis de expresión de imagen de Earth Engine en tu argumento include para ponderar píxeles de forma dinámica en función de 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 píxeles y escala de análisis

Una imagen de trama 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íxeles informado original puede variar mucho entre los conjuntos de datos, de menos de 1 metro a más de 20 kilómetros.

Cuando se usa la función ST_REGIONSTATS para calcular estadísticas zonales, el tamaño de píxeles de los datos de ráster es una consideración fundamental. Por ejemplo, la agregación de datos de ráster de alta resolución en la región de un país puede ser intensiva en procesamiento y demasiado detallada. Por el contrario, la agregación de datos de baja resolución en la región, como parcelas de ciudades, podría no proporcionar detalles suficientes.

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

Cambiar el tamaño de los píxeles modifica la cantidad de píxeles que se cruzan en una ubicación geográfica determinada, lo que afecta los resultados y su interpretación. No recomendamos cambiar el tamaño de píxeles para los análisis de producción. Sin embargo, si estás prototipando 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 en la función ST_REGIONSTATS. Por ejemplo, para calcular estadísticas de más de 1,000 píxeles de 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.

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 función. Se te factura este uso 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 las etiquetas para filtrar según 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.
  • La imagen de trama que usas. Algunos rasteres son compuestos creados a partir de colecciones de imágenes de origen en el catálogo de datos 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

  • Es 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 píxeles en latitudes altas o muy fuera del área de cobertura prevista de la imagen.
    • En el caso de los rasteres 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 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

  • El 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 puede consumir la función. Cuando visualices tus cuotas, filtra la lista Métrica a 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 de trama 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?