Bekerja dengan data raster menggunakan 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 petak 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 petak lainnya yang berkelanjutan seperti prakiraan cuaca dan penutupan lahan. Banyak format gambar umum, seperti file PNG atau JPEG, diformat sebagai data raster.

Data raster sering kali dibandingkan dengan data vektor, yang datanya dijelaskan 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 digabungkan menggunakan operasi statistik zonal, yang menghitung gabungan semua nilai raster dalam wilayah vektor tertentu. Misalnya, Anda mungkin ingin menghitung hal berikut:

• Kualitas udara rata-rata di sekumpulan 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 Anda, 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 berbagi BigQuery: BigQuery Data Editor (roles/bigquery.dataEditor)

Untuk mengetahui informasi selengkapnya tentang cara memberikan 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 fitur berbagi BigQuery, Anda harus mengaktifkan Analytics Hub API dan memastikan bahwa Anda memiliki izin yang diperlukan untuk melihat dan berlangganan listingan.

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 Berbagi (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 Nama set data tertaut.

7. Klik Simpan. Set data tertaut 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 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 Detail gambar.

Setiap tabel gambar menyertakan tabel *_metadata terkait 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 bagi gambar yang sesuai dengan 1 Januari 2025 dan menghitung suhu rata-rata untuk setiap negara menggunakan band 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 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 berada 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 kumpulan 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 inginkan.

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

   Jika cuplikan Earth Engine berbentuk ee.Image('IMAGE_PATH'), maka ID raster adalah 'ee://IMAGE_PATH'.

   Jika cuplikan Earth Engine berbentuk 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 raster 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 penghitungan. Nilai bobot harus berkisar dari 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 tidak valid biasanya merepresentasikan 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 zonal. Jika geometri kurang dari 1/256 ukuran piksel, bobot piksel adalah 0. Dalam kasus ini, null ditampilkan untuk semua statistik kecuali count dan area, yang bernilai 0.

Jika piksel yang beririsan sebagian memiliki bobot dari argumen include hingga ST_REGIONSTATS, BigQuery akan menggunakan bobot minimum dan fraksi piksel yang beririsan dengan wilayah.

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 sintaks ekspresi gambar Earth Engine dalam argumen include untuk memberi bobot secara dinamis pada piksel berdasarkan kriteria tertentu dalam band raster. Misalnya, ekspresi berikut membatasi penghitungan ke piksel dengan rentang probability melebihi 70%:

include => 'probability > 0.7'

Jika set data menyertakan rentang 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, 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 x 10 meter. Ukuran piksel yang dilaporkan asli dapat sangat bervariasi di antara 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 beresolusi tinggi di seluruh wilayah suatu negara dapat memerlukan banyak komputasi dan tidak perlu terlalu terperinci. Sebaliknya, menggabungkan data beresolusi 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 dalam berbagi BigQuery.

Mengubah ukuran piksel akan mengubah jumlah piksel yang berpotongan dengan geografi tertentu, yang akan 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 beresolusi 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 melakukan resampling gambar pada skala yang diminta. Untuk mempelajari lebih lanjut cara Earth Engine menangani penskalaan ulang, lihat Skala dalam dokumentasi Google Earth Engine.

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

Penagihan

Saat Anda menjalankan kueri, penggunaan fungsi ST_REGIONSTATS 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 sesuai permintaan atau reservasi. Untuk melihat jumlah yang ditagih untuk panggilan BigQuery ke Earth Engine, lihat laporan penagihan Anda dan gunakan label untuk memfilter menurut 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 menampilkan 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 milidetik slot yang digunakan oleh semua layanan eksternal BigQuery yang ditagih pada 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 koleksi gambar sumber dalam 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 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 mengubah piksel, terutama piksel pada lintang tinggi atau jauh di luar area cakupan yang dimaksudkan untuk 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 mungkin tidak menyertakan gambar bergantung pada perubahan kondisi atmosfer.

• Penggunaan formula dalam argumen include atau band_name, dan jumlah rentang 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 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 pembelanjaan berlebih, tetapi tidak dirancang untuk membatasi waktu slot secara ketat. BigQuery terkadang menjalankan kueri yang melebihi batas kuota, dan Anda mungkin kehabisan kuota tanpa ditagih untuk seluruh jumlah yang digunakan.

Region yang didukung

Kueri yang memanggil fungsi ST_REGIONSTATS harus dijalankan 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.