Bekerja dengan data raster menggunakan Earth Engine di BigQuery

Menggabungkan data raster dan vektor dengan fungsi ST_REGIONSTATS memungkinkan Anda menghitung statistik zona, seperti kualitas udara rata-rata atau risiko kebakaran, di seluruh wilayah geografis tertentu. Anda dapat menggunakan Google Earth Engine langsung di BigQuery untuk menganalisis citra satelit dan prakiraan cuaca bersama dengan batas vektor yang ada.

Ringkasan

Raster adalah petak piksel dua dimensi, 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 petak berkelanjutan lainnya seperti prakiraan cuaca dan tutupan lahan. Banyak format gambar umum, seperti file PNG atau JPEG, diformat sebagai data raster.

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

Data raster dan vektor geospasial sering kali digabungkan menggunakan operasi statistik zona, 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.
• Risiko kebakaran diringkas 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 Anda, aktifkan Earth Engine API.

   Mengaktifkan API

2. Opsional: Untuk berlangganan dan menggunakan data yang dipublikasikan ke fitur berbagi BigQuery (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 untuk memberi Anda peran IAM berikut pada project Anda:

• Earth Engine Resource Viewer (roles/earthengine.viewer)
• Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
• Berlangganan ke 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 bawaan 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 fitur berbagi BigQuery (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 Berbagi (Analytics Hub)

2. Klik Telusuri listingan.

3. Di kolom Telusuri listingan, masukkan "Google Earth Engine".

4. Klik set data yang ingin Anda jadikan langganan.

5. Klik Langganan.

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

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

Set data ini berisi tabel gambar yang menyimpan metadata untuk kumpulan gambar raster yang mengikuti spesifikasi item STAC. Tabel gambar serupa dengan koleksi 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 yang tersedia, ukuran piksel, dan definisi properti, 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 Cloud Optimized GeoTIFF (COG) di bucket Cloud Storage yang terletak di region berikut:

• US multi-region
• us-central1
• EU multi-region
• 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 koleksi gambar. Data ini ada di region US dan hanya kompatibel dengan kueri yang berjalan di region US. Untuk menemukan ID raster gambar, ikuti langkah-langkah berikut:

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

2. Untuk membuka halaman deskripsi entri tersebut, klik nama set data. Cuplikan Earth Engine mendeskripsikan satu gambar atau kumpulan gambar.

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

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

Bobot piksel

Anda dapat menentukan bobot, terkadang disebut sebagai nilai mask, untuk parameter include dalam fungsi ST_REGIONSTATS yang menentukan seberapa besar bobot setiap piksel dalam penghitungan. 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 menunjukkan data yang tidak ada atau tidak dapat diandalkan, seperti area yang tertutup 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 zona. Jika geometri kurang dari 1/256 ukuran piksel, bobot pikselnya adalah 0. Dalam kasus ini, null ditampilkan untuk semua statistik kecuali count dan area, yang bernilai 0.

Jika piksel yang berpotongan sebagian memiliki bobot dari argumen include hingga 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 komputasi hingga 1/256 (sekitar 0,4%).

Anda dapat memberikan ekspresi menggunakan sintaksis ekspresi gambar Earth Engine dalam argumen include untuk memberi bobot piksel secara dinamis berdasarkan kriteria tertentu dalam band raster. Misalnya, ekspresi berikut membatasi penghitungan ke piksel yang band probability-nya 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 petak piksel yang sesuai dengan beberapa lokasi di permukaan Bumi. Ukuran piksel raster, yang terkadang disebut skala, adalah ukuran nominal satu tepi piksel dalam sistem referensi koordinat petak. Misalnya, raster dengan resolusi 10 meter memiliki piksel berukuran 10 meter kali 10 meter. Ukuran piksel asli yang dilaporkan dapat sangat bervariasi antar-set data, dari kurang dari 1 meter hingga lebih dari 20 kilometer.

Saat menggunakan fungsi ST_REGIONSTATS untuk menghitung statistik zona, ukuran piksel data raster adalah pertimbangan yang penting. Misalnya, menggabungkan data raster resolusi tinggi di wilayah suatu negara dapat memerlukan komputasi yang intensif dan tingkat perincian yang tidak perlu. Sebaliknya, menggabungkan data beresolusi rendah di seluruh wilayah, seperti persil 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 pada 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 ini, salah satu alternatifnya adalah mengganti poligon dengan titik centroid-nya menggunakan ST_CENTROID.

Penagihan

Saat Anda menjalankan kueri, penggunaan fungsi ST_REGIONSTATS akan ditagih secara terpisah dari kueri lainnya karena Earth Engine menghitung hasil panggilan fungsi. Anda akan ditagih untuk penggunaan ini dalam jam slot berdasarkan SKU Layanan BigQuery, terlepas dari apakah Anda menggunakan penagihan on-demand 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, yang menunjukkan jumlah slot milidetik yang digunakan oleh Earth Engine saat kolom externalService adalah EARTH_ENGINE dan kolom billingMethod adalah SERVICES_SKU.
• Kolom totalServicesSkuSlotMs, yang menunjukkan jumlah total slot milidetik yang digunakan oleh semua layanan eksternal BigQuery yang ditagih di SKU Layanan BigQuery.

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

Faktor biaya

Faktor-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 koleksi gambar sumber di Data Catalog Earth Engine, dan resource komputasi untuk menghasilkan hasil komposit bervariasi.
• Resolusi gambar.
• Ukuran dan kompleksitas geografi input, jumlah piksel yang berpotongan dengan geografi, serta jumlah ubin 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 mendistorsi piksel, terutama piksel di lintang tinggi atau jauh di luar area cakupan gambar yang diinginkan.
  • Untuk raster komposit, jumlah gambar sumber yang berpotongan dengan geografi input dapat bervariasi secara regional dan seiring waktu. Misalnya, beberapa satelit menghasilkan lebih banyak gambar pada lintang rendah atau tinggi, bergantung pada orbit dan parameter pengumpulan datanya, atau dapat menghilangkan gambar bergantung pada perubahan kondisi atmosfer.

• 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 boleh digunakan oleh fungsi tersebut. Defaultnya adalah 350 slot-jam 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 kuota fungsi raster BigQuery dalam dokumentasi Google Earth Engine.

Catatan: Seperti kuota kueri kustom di BigQuery, kuota ini merupakan perkiraan. Fitur ini memberikan perlindungan terhadap pemakaian 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:

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

Langkah berikutnya

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