Menggunakan data raster dengan Earth Engine di BigQuery

Dokumen ini menjelaskan cara menggabungkan data raster dan vektor menggunakan fungsi ST_REGIONSTATS, yang menggunakan Google Earth Engine untuk mendapatkan akses ke data gambar dan raster di BigQuery.

Ringkasan

Raster adalah kisi dua dimensi piksel, yang masing-masing diberi satu atau beberapa nilai yang disebut band. Misalnya, setiap piksel dapat sesuai dengan satu kilometer persegi tertentu di permukaan bumi dan memiliki band untuk suhu rata-rata dan curah hujan rata-rata. Data raster mencakup citra satelit dan data berbasis kisi berkelanjutan lainnya seperti prakiraan cuaca dan penutup lahan. Banyak format gambar umum, seperti file PNG atau JPEG, diformat sebagai data raster.

Data raster sering kali dikontraskan dengan data vektor , yang datanya dijelaskan oleh garis atau kurva, bukan kisi persegi panjang tetap. Misalnya, Anda dapat menggunakan jenis data GEOGRAPHY di BigQuery untuk menjelaskan batas negara, kota, atau wilayah lainnya.

Data raster dan vektor geospasial sering kali digabungkan menggunakan operasi statistik zonal, yang menghitung agregat semua nilai raster dalam wilayah vektor tertentu. Misalnya, Anda mungkin ingin menghitung hal berikut:

• Kualitas udara rata-rata di kumpulan kota.
• Potensi tenaga surya untuk kumpulan poligon bangunan.
• Ringkasan risiko kebakaran di sepanjang koridor saluran listrik di area berhutan.

BigQuery unggul dalam memproses data vektor, dan Google Earth Engine unggul dalam memproses data raster. Anda dapat menggunakan fungsi geografi ST_REGIONSTATS untuk menggabungkan data raster menggunakan Earth Engine dengan data vektor yang disimpan di BigQuery.

Sebelum memulai

1. Untuk menggunakan fungsi ST_REGIONSTATS dalam kueri, aktifkan Earth Engine API.

   Mengaktifkan API

2. Opsional: Untuk berlangganan dan menggunakan data yang dipublikasikan ke BigQuery sharing (sebelumnya Analytics Hub) menggunakan fungsi ST_REGIONSTATS, aktifkan Analytics Hub API.

   Mengaktifkan API

Izin yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk memanggil fungsi ST_REGIONSTATS, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda:

• Earth Engine Resource Viewer (roles/earthengine.viewer)
• Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
• Berlangganan set data di BigQuery sharing: BigQuery Data Editor (roles/bigquery.dataEditor)

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran yang telah ditetapkan ini berisi izin yang diperlukan untuk memanggil fungsi ST_REGIONSTATS. Untuk melihat izin yang pasti diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk memanggil fungsi ST_REGIONSTATS:

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

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Menemukan data raster

Parameter raster_id dalam fungsi ST_REGIONSTATS adalah string yang menentukan sumber data raster Anda. Bagian berikut menjelaskan cara menemukan dan memformat ID raster.

Tabel gambar BigQuery

Anda dapat menggunakan BigQuery sharing (sebelumnya Analytics Hub) untuk menemukan dan mengakses set data raster di BigQuery. Untuk menggunakan BigQuery sharing, Anda harus mengaktifkan Analytics Hub API dan memastikan bahwa Anda memiliki izin yang diperlukan untuk melihat dan berlangganan listingan dan pertukaran data.

Google Earth Engine memublikasikan set data yang tersedia untuk umum yang berisi data raster di multi-region US dan EU. Untuk berlangganan set data Earth Engine dengan data raster, ikuti langkah-langkah berikut:

1. Buka halaman Sharing (Analytics Hub).

   Buka Sharing (Analytics Hub)

2. Klik Search listings.

3. Di kolom Search for listings, masukkan "Google Earth Engine".

4. Klik set data yang ingin Anda langgani.

5. Klik Subscribe.

6. Opsional: Perbarui kolom Project atau Linked dataset name.

7. Klik Save. Set data tertaut akan ditambahkan ke project Anda.

Set data berisi tabel gambar yang menyimpan metadata untuk kumpulan gambar raster yang mengikuti spesifikasi item STAC. Tabel gambar analog dengan kumpulan gambar Earth Engine (ImageCollection).

Setiap baris dalam tabel sesuai dengan satu gambar raster, dengan kolom yang berisi properti dan metadata gambar. ID raster untuk setiap gambar disimpan di kolom assets.image.href. Referensi gambar dalam kueri Anda menggunakan ID ini sebagai nilai parameter raster_id.

Filter tabel menggunakan kolom properti untuk memilih gambar atau subset gambar tertentu yang memenuhi kriteria Anda. Untuk mengetahui informasi selengkapnya tentang band, ukuran piksel, dan definisi properti yang tersedia, buka tabel dan klik tab Image details.

Setiap tabel gambar menyertakan tabel *_metadata yang sesuai yang memberikan informasi pendukung untuk tabel gambar.

Misalnya, set data ERA5-Land menyediakan statistik variabel iklim harian dan tersedia untuk umum. Tabel climate berisi beberapa ID raster. Kueri berikut memfilter tabel gambar menggunakan kolom start_datetime untuk mendapatkan ID raster untuk gambar yang sesuai dengan 1 Januari 2025 dan menghitung suhu rata-rata untuk setiap negara menggunakan band 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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan BigQuery DataFrames di Panduan memulai BigQuery menggunakan BigQuery DataFrames. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery DataFrames.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan ADC untuk lingkungan pengembangan lokal.

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 adalah format file umum untuk menyimpan data raster geospasial. Fungsi ST_REGIONSTATS mendukung data raster yang disimpan dalam format GeoTIFF yang Dioptimalkan Cloud (COG) di bucket Cloud Storage yang berlokasi di region berikut:

• Multi-region US
• us-central1
• Multi-region EU
• europe-west1

Berikan Cloud Storage URI sebagai ID raster, seperti gs://bucket/folder/raster.tif.

Aset gambar Earth Engine

Fungsi ST_REGIONSTATS mendukung penerusan jalur aset gambar Earth Engine untuk argumen raster_id. Data raster Earth Engine tersedia sebagai gambar individual atau kumpulan gambar. Data ini ada di region US dan hanya kompatibel dengan kueri yang berjalan di region US. Untuk menemukan ID raster untuk gambar, ikuti langkah-langkah berikut:

1. Telusuri katalog data Earth Engine untuk set data yang Anda minati.

2. Untuk membuka halaman deskripsi untuk entri tersebut, klik nama set data. Earth Engine Snippet menjelaskan satu gambar atau kumpulan gambar.

   Jika cuplikan Earth Engine memiliki bentuk ee.Image('IMAGE_PATH'), ID rasternya adalah 'ee://IMAGE_PATH'.

   Jika cuplikan Earth Engine memiliki bentuk ee.ImageCollection('IMAGE_COLLECTION_PATH'), Anda dapat menggunakan Editor Kode Earth Engine untuk memfilter ImageCollection ke satu gambar. Gunakan metode ee.Image.get('system:id') untuk mencetak nilai IMAGE_PATH untuk gambar tersebut ke konsol. ID rasternya adalah 'ee://IMAGE_PATH'.

Bobot piksel

Anda dapat menentukan bobot, yang terkadang disebut sebagai nilai mask, untuk parameter include dalam fungsi ST_REGIONSTATS yang menentukan seberapa besar bobot setiap piksel dalam perhitungan. Nilai bobot harus berkisar antara 0 hingga 1. Bobot di luar rentang ini ditetapkan ke batas terdekat, yaitu 0 atau 1.

Piksel dianggap valid jika memiliki bobot lebih besar dari 0. Bobot 0 menunjukkan piksel tidak valid. Piksel yang tidak valid biasanya mewakili data yang tidak ada atau tidak dapat diandalkan, seperti area yang terhalang awan, anomali sensor, error pemrosesan, atau lokasi di luar batas yang ditentukan.

Jika Anda tidak menentukan bobot, setiap piksel akan otomatis diberi bobot berdasarkan proporsi piksel yang berada dalam geometri, sehingga memungkinkan penyertaan proporsional dalam statistik zonal. Jika geometri kurang dari 1/256 ukuran piksel, bobot piksel adalah 0. Dalam kasus ini, null akan ditampilkan untuk semua statistik kecuali count dan area, yang bernilai 0.

Jika piksel yang berpotongan sebagian memiliki bobot dari argumen include ke ST_REGIONSTATS, BigQuery akan menggunakan bobot minimum dan pecahan piksel yang berpotongan dengan region.

Nilai bobot tidak memiliki presisi yang sama dengan nilai FLOAT64. Dalam praktiknya, nilai sebenarnya mungkin berbeda dari nilai yang digunakan dalam perhitungan hingga 1/256 (sekitar 0,4%).

Anda dapat memberikan ekspresi menggunakan Earth Engine sintaksis ekspresi gambar dalam argumen include untuk memberi bobot piksel secara dinamis berdasarkan kriteria tertentu dalam band raster. Misalnya, ekspresi berikut membatasi perhitungan ke piksel dengan band probability yang melebihi 70%:

include => 'probability > 0.7'

Jika set data menyertakan band faktor bobot, Anda dapat menggunakannya dengan sintaksis berikut:

include => 'weight_factor_band_name'

Ukuran piksel dan skala analisis

Gambar raster geospasial adalah kisi piksel yang sesuai dengan lokasi tertentu di permukaan Bumi. Ukuran piksel raster, yang terkadang disebut skala, adalah ukuran nominal satu tepi piksel dalam sistem referensi koordinat kisi. Misalnya, raster dengan resolusi 10 meter memiliki piksel berukuran 10 meter x 10 meter. Ukuran piksel yang dilaporkan asli dapat sangat bervariasi antar-set data, dari kurang dari 1 meter hingga lebih dari 20 kilometer.

Saat menggunakan fungsi ST_REGIONSTATS untuk menghitung statistik zonal, ukuran piksel data raster adalah pertimbangan penting. Misalnya, menggabungkan data raster resolusi tinggi di seluruh wilayah negara dapat memerlukan banyak komputasi dan tidak perlu terlalu mendetail. Sebaliknya, menggabungkan data resolusi rendah di seluruh wilayah, seperti petak kota, mungkin tidak memberikan detail yang memadai.

Untuk mendapatkan hasil yang bermakna dan efisien dari analisis Anda, sebaiknya pilih ukuran piksel yang sesuai dengan ukuran poligon dan tujuan analisis Anda. Anda dapat menemukan ukuran piksel untuk setiap set data raster di bagian deskripsi tabel gambar di BigQuery sharing.

Mengubah ukuran piksel akan mengubah jumlah piksel yang berpotongan dengan geografi tertentu, yang memengaruhi hasil dan interpretasinya. Sebaiknya jangan mengubah ukuran piksel untuk analisis produksi. Namun, jika Anda membuat prototipe kueri, meningkatkan ukuran piksel dapat mengurangi runtime dan biaya kueri, terutama untuk data resolusi tinggi.

Untuk mengubah ukuran piksel, tetapkan scale dalam argumen options ke fungsi ST_REGIONSTATS. Misalnya, untuk menghitung statistik atas piksel 1.000 meter, gunakan options => JSON '{"scale":1000}', yang memberi tahu Earth Engine untuk mengambil sampel ulang gambar pada skala yang diminta. Untuk mempelajari lebih lanjut cara Earth Engine menangani penskalaan ulang, lihat Skala dalam dokumentasi Google Earth Engine.

Menghitung statistik untuk poligon yang jauh lebih kecil daripada piksel raster dapat menghasilkan hasil yang tidak akurat atau null. Dalam kasus seperti itu, salah satu alternatifnya adalah mengganti poligon dengan titik centroid menggunakan ST_CENTROID.

Penagihan

Saat Anda menjalankan kueri, penggunaan fungsi ST_REGIONSTATS ditagih secara terpisah dari bagian kueri lainnya karena Earth Engine menghitung hasil panggilan fungsi. Anda akan ditagih untuk penggunaan ini dalam jam slot di bawah SKU Layanan BigQuery, terlepas dari apakah Anda menggunakan penagihan sesuai permintaan atau pemesanan. Untuk melihat jumlah yang ditagih untuk panggilan BigQuery ke Earth Engine, lihat laporan penagihan Anda dan gunakan label untuk memfilter berdasarkan kunci label goog-bq-feature-type, dengan nilai EARTH_ENGINE. Jika fungsi ST_REGIONSTATS gagal, Anda tidak akan ditagih untuk komputasi Earth Engine yang digunakan.

Untuk setiap kueri, Anda dapat menggunakan metode jobs.get di BigQuery API untuk melihat informasi berikut:

• Kolom slotMs field, yang menampilkan jumlah milidetik slot yang digunakan oleh Earth Engine saat kolom externalService adalah EARTH_ENGINE dan kolom billingMethod adalah SERVICES_SKU.
• Kolom totalServicesSkuSlotMs field, yang menampilkan jumlah total milidetik slot yang digunakan oleh semua layanan eksternal BigQuery yang ditagih di SKU Layanan BigQuery.

Anda juga dapat membuat kueri kolom total_services_sku_slot_ms di tampilan INFORMATION_SCHEMA.JOBS untuk menemukan total milidetik slot yang digunakan oleh layanan eksternal yang ditagih di SKU Layanan BigQuery.

Faktor biaya

Faktor berikut memengaruhi penggunaan komputasi saat Anda menjalankan fungsi ST_REGIONSTATS:

• Jumlah baris input.
• Gambar raster yang Anda gunakan. Beberapa raster adalah komposit yang dibuat dari kumpulan gambar sumber di katalog data Earth Engine, dan resource komputasi untuk menghasilkan hasil komposit bervariasi.
• Resolusi gambar.
• Ukuran dan kompleksitas geografi input, jumlah piksel yang berpotongan dengan geografi, dan jumlah petak gambar dan byte yang dibaca oleh Earth Engine.

• Lokasi geografi input di Bumi relatif terhadap gambar sumber serta proyeksi dan resolusi gambar.

  • Proyeksi gambar dapat mengubah piksel, terutama piksel di lintang tinggi atau jauh di luar area cakupan yang dimaksudkan gambar.
  • Untuk raster komposit, jumlah gambar sumber yang berpotongan dengan geografi input dapat bervariasi secara regional dan dari waktu ke waktu. Misalnya, beberapa satelit menghasilkan lebih banyak gambar di lintang rendah atau tinggi, bergantung pada orbit dan parameter pengumpulan datanya, atau dapat menghilangkan gambar bergantung pada kondisi atmosfer yang berubah.

• Penggunaan formula dalam argumen include atau band_name, dan jumlah band yang terlibat.

• Caching hasil sebelumnya.

Kontrol biaya

Untuk mengontrol biaya yang terkait dengan fungsi ST_REGIONSTATS, Anda dapat menyesuaikan kuota yang mengontrol jumlah waktu slot yang diizinkan untuk digunakan oleh fungsi tersebut. Nilai defaultnya adalah 350 jam slot per hari. Saat Anda melihat kuota, filter daftar Metrik ke earthengine.googleapis.com/bigquery_slot_usage_time untuk melihat kuota Earth Engine yang terkait dengan panggilan dari BigQuery. Untuk mengetahui informasi selengkapnya, baca tentang BigQuery kuota fungsi raster dalam dokumentasi Google Earth Engine.

Catatan: Seperti kuota kueri kustom di BigQuery, kuota ini merupakan perkiraan. Kuota ini memberikan perlindungan terhadap pengeluaran berlebih, tetapi tidak dirancang untuk membatasi waktu slot secara ketat. BigQuery terkadang menjalankan kueri yang melebihi batas kuota, dan Anda mungkin menghabiskan kuota tanpa ditagih untuk seluruh jumlah yang digunakan.

Region yang didukung

Kueri yang memanggil fungsi ST_REGIONSTATS harus berjalan di salah satu region berikut:

• Multi-region US
• us-central1
• us-central2
• Multi-region EU
• europe-west1

Langkah berikutnya

• Coba tutorial yang menunjukkan cara menggunakan data raster untuk menganalisis suhu.
• Pelajari fungsi geografi lebih lanjut di BigQuery .
• Pelajari lebih lanjut cara menggunakan data geospasial.