עבודה עם נתוני רסטר באמצעות Earth Engine ב-BigQuery

במאמר הזה מוסבר איך לשלב נתוני רסטר ונתוני וקטור באמצעות הפונקציה ST_REGIONSTATS, שמשתמשת ב-Google Earth Engine כדי לקבל גישה לנתוני תמונה ורסטר ב-BigQuery.

סקירה כללית

רסטר הוא רשת דו-ממדית של פיקסלים, שלכל אחד מהם מוקצה ערך אחד או יותר שנקראים פסים. לדוגמה, כל פיקסל יכול להתאים לקילומטר רבוע מסוים על פני כדור הארץ, ולהכיל נתונים על טמפרטורה ממוצעת וכמות גשם ממוצעת. נתוני רסטר כוללים צילומי לוויין ונתונים רציפים אחרים שמבוססים על רשת, כמו תחזיות מזג אוויר וכיסוי פני השטח. פורמטים נפוצים רבים של תמונות, כמו קובצי PNG או JPEG, מעוצבים כנתוני רסטר.

נתוני רסטר מנוגדים לרוב לנתוני וקטור, שבהם הנתונים מתוארים באמצעות קווים או עקומות ולא באמצעות רשת מלבנית קבועה. לדוגמה, אפשר להשתמש בסוג הנתונים GEOGRAPHY ב-BigQuery כדי לתאר את הגבולות של מדינות, ערים או אזורים אחרים.

לעתים קרובות משלבים נתונים של רסטר ושל וקטור גיאוגרפיים באמצעות פעולה של סטטיסטיקה אזורית, שמחשבת את סכום כל ערכי הרסטר באזור וקטורי נתון. לדוגמה, יכול להיות שתרצו לחשב את הנתונים הבאים:

  • איכות האוויר הממוצעת בקבוצת ערים.
  • פוטנציאל ליצירת אנרגיה סולארית לקבוצה של פוליגונים של מבנים.
  • סיכום של סיכון לשריפה לאורך מסדרונות של קווי מתח גבוה באזורים מיוערים.

‫BigQuery מצטיין בעיבוד נתוני וקטור, ו-Google Earth Engine מצטיין בעיבוד נתוני רסטר. אתם יכולים להשתמש בST_REGIONSTATSפונקציית הגיאוגרפיה כדי לשלב נתוני רסטר באמצעות Earth Engine עם נתוני הווקטור שאוחסנו ב-BigQuery.

מפה של כדור הארץ עם ערכי רסטר ונתונים סטטיסטיים אזוריים מחושבים.

לפני שמתחילים

  1. כדי להשתמש בפונקציה ST_REGIONSTATS בשאילתות, צריך להפעיל את Earth Engine API.

    הפעלה של ה-API

  2. אופציונלי: כדי להירשם לנתונים שפורסמו ב-BigQuery sharing (לשעבר Analytics Hub) ולהשתמש בהם באמצעות הפונקציה ST_REGIONSTATS, צריך להפעיל את Analytics Hub API.

    הפעלה של ה-API

ההרשאות הנדרשות

כדי לקבל את ההרשאות שדרושות להפעלת הפונקציה ST_REGIONSTATS, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

התפקידים המוגדרים מראש האלה כוללים את ההרשאות שנדרשות להפעלת הפונקציה ST_REGIONSTATS. כדי לראות בדיוק אילו הרשאות נדרשות, אפשר להרחיב את הקטע ההרשאות הנדרשות:

ההרשאות הנדרשות

כדי להפעיל את הפונקציה ST_REGIONSTATS, נדרשות ההרשאות הבאות:

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

יכול להיות שתקבלו את ההרשאות האלה באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.

חיפוש נתוני רסטר

הפרמטר raster_id בפונקציה ST_REGIONSTATS הוא מחרוזת שמציינת את המקור של נתוני הרסטר. בקטעים הבאים מוסבר איך למצוא את מזהה הרסטר ואיך להגדיר את הפורמט שלו.

טבלאות תמונות ב-BigQuery

אתם יכולים להשתמש ב-BigQuery sharing (לשעבר Analytics Hub) כדי לגלות מערכי נתונים של רסטר ב-BigQuery ולגשת אליהם. כדי להשתמש בשיתוף ב-BigQuery, צריך להפעיל את Analytics Hub API ולוודא שיש לכם את ההרשאות הנדרשות כדי לצפות בכרטיסי מוצר ובמרכזי נתונים ולהירשם אליהם.

‫Google Earth Engine מפרסם קבוצות נתונים שזמינות לציבור ומכילות נתוני רסטר באזורים המרובים US ו-EU. כדי להירשם למערך נתונים של Earth Engine עם נתוני רסטר, פועלים לפי השלבים הבאים:

  1. עוברים לדף שיתוף (מרכז Analytics).

    מעבר אל 'שיתוף' (Analytics Hub)

  2. לוחצים על חיפוש כרטיסי מוצר.

  3. בשדה חיפוש כרטיסי מוצר, מזינים "Google Earth Engine".

  4. לוחצים על קבוצת הנתונים שרוצים להירשם אליה.

  5. לוחצים על הרשמה.

  6. אופציונלי: מעדכנים את השדות Project (פרויקט) או Linked dataset name (שם מערך הנתונים המקושר).

  7. לוחצים על Save. מערך הנתונים המקושר נוסף לפרויקט.

מערך הנתונים מכיל טבלת תמונות שבה מאוחסנים מטא-נתונים של אוסף תמונות רסטר בהתאם למפרט הפריטים של STAC. טבלת תמונות דומה לאוסף תמונות של Earth Engine (ImageCollection).

כל שורה בטבלה תואמת לתמונת רסטר יחידה, והעמודות מכילות את מאפייני התמונה והמטא-נתונים שלה. מזהה הרסטר של כל תמונה מאוחסן בעמודה assets.image.href. כדי להפנות לתמונות בשאילתות, משתמשים במזהה הזה כערך של הפרמטר raster_id.

מסננים את הטבלה באמצעות עמודות מאפיינים כדי לבחור תמונות ספציפיות או קבוצות משנה של תמונות שעומדות בקריטריונים. למידע נוסף על הפסים הזמינים, גודל הפיקסלים והגדרות המאפיינים, פותחים את הטבלה ולוחצים על הכרטיסייה פרטי התמונה.

כל טבלת תמונות כוללת טבלת *_metadata תואמת שמספקת מידע תומך לטבלת התמונות.

לדוגמה, מערך הנתונים ERA5-Land מספק נתונים סטטיסטיים יומיים של משתני אקלים והוא זמין לציבור. climate הטבלה מכילה כמה מזהי רסטר. השאילתה הבאה מסננת את טבלת התמונות באמצעות העמודה start_datetime כדי לקבל את מזהה הרסטר של התמונה שמתאימה ל-1 בינואר 2025, ומחשבת את הטמפרטורה הממוצעת לכל מדינה באמצעות פס 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

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של BigQuery DataFrames במאמר BigQuery quickstart using BigQuery DataFrames. מידע נוסף זמין במאמרי העזרה בנושא BigQuery DataFrames.

כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת ADC לסביבת פיתוח מקומית. 

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))

Cloud Storage GeoTIFF

‫GeoTIFF הוא פורמט קובץ נפוץ לאחסון נתוני רסטר גיאוספציאליים. הפונקציה ST_REGIONSTATS תומכת בנתוני רסטר שמאוחסנים בפורמט Cloud Optimized GeoTIFF‏ (COG) בקטגוריות של Cloud Storage שממוקמות באזורים הבאים:

  • US מספר אזורים
  • us-central1
  • EU מספר אזורים
  • europe-west1

מזינים את ה-URI של Cloud Storage כמזהה הרסטר, למשל gs://bucket/folder/raster.tif.

נכסי תמונות ב-Earth Engine

הפונקציה ST_REGIONSTATS תומכת בהעברת נתיב של נכס תמונה ב-Earth Engine לארגומנט raster_id. נתוני רסטר של Earth Engine זמינים כתמונות נפרדות או כאוספים של תמונות. הנתונים האלה קיימים באזור US והם תואמים רק לשאילתות שמופעלות באזור US. כדי למצוא את מזהה הרסטר של תמונה, פועלים לפי השלבים הבאים:

  1. מחפשים בקטלוג הנתונים של Earth Engine את קבוצת הנתונים שמעניינת אתכם.

  2. כדי לפתוח את דף התיאור של הרשומה, לוחצים על שם מערך הנתונים. קטע הקוד ל-Earth Engine מתאר תמונה אחת או אוסף של תמונות.

    אם קטע הקוד ל-Earth Engine הוא מהצורה ee.Image('IMAGE_PATH'), אז מזהה הראסטר הוא 'ee://IMAGE_PATH'.

    אם קטע הקוד של Earth Engine הוא מהצורה ee.ImageCollection('IMAGE_COLLECTION_PATH'), אפשר להשתמש בעורך הקוד של Earth Engine כדי לסנן את ImageCollection לתמונה אחת. משתמשים בשיטה ee.Image.get('system:id') כדי להדפיס את הערך של התמונה במסוף.IMAGE_PATH מזהה הרסטר הוא 'ee://IMAGE_PATH'.

משקלים של פיקסלים

אפשר לציין משקל, שלפעמים נקרא ערך מסכה, לפרמטר include בפונקציה ST_REGIONSTATS. המשקל קובע את החשיבות של כל פיקסל בחישובים. הערכים של המשקל צריכים להיות בין 0 ל-1. משקלים מחוץ לטווח הזה מוגדרים למגבלה הקרובה ביותר, 0 או 1.

פיקסל נחשב תקין אם המשקל שלו גדול מ-0. משקל של 0 מציין פיקסל לא תקין. פיקסלים לא תקינים בדרך כלל מייצגים נתונים חסרים או לא מהימנים, כמו אזורים שמוסתרים על ידי עננים, חריגות בחיישנים, שגיאות עיבוד או מיקומים מחוץ לגבול מוגדר.

אם לא מציינים משקל, כל פיקסל מקבל משקל באופן אוטומטי לפי החלק היחסי של הפיקסל שנמצא בתוך הגיאומטריה, וכך הוא נכלל באופן יחסי בנתונים הסטטיסטיים של האזור. אם הגיאומטריה קטנה מ-1/256 מגודל הפיקסל, המשקל של הפיקסל הוא 0. במקרים האלה, הערך null מוחזר לכל הנתונים הסטטיסטיים מלבד count ו-area, שהערך שלהם הוא 0.

אם לפי הארגומנט include עד ST_REGIONSTATS, הפיקסל שחלק ממנו חופף לאזור הוא בעל משקל, אז BigQuery משתמש בערך המינימלי של המשקל הזה ושל החלק היחסי של הפיקסל שחופף לאזור.

ערכי המשקל לא זהים לערכי FLOAT64. בפועל, הערך האמיתי שלהם עשוי להיות שונה מהערך שמשמש בחישובים בשיעור של עד 1/256 (כ-0.4%).

אתם יכולים לספק ביטוי באמצעות תחביר של ביטוי תמונה ב-Earth Engine בארגומנט include כדי לשקלל באופן דינמי פיקסלים על סמך קריטריונים ספציפיים בתוך רצועות רסטר. לדוגמה, הביטוי הבא מגביל את החישובים לפיקסלים שבהם הערך של רצועת probability חורג מ-70%:

include => 'probability > 0.7'

אם מערך הנתונים כולל פס של גורם משקל, אפשר להשתמש בו בתחביר הבא:

include => 'weight_factor_band_name'

גודל הפיקסל וקנה המידה של הניתוח

תמונת רסטר גיאוספציאלית היא רשת של פיקסלים שמתאימה למיקום מסוים על פני כדור הארץ. גודל הפיקסל של רסטר, שלפעמים נקרא קנה מידה, הוא הגודל הנומינלי של צלע אחת של פיקסל במערכת הפניות לקואורדינטות של הרשת. לדוגמה, לרסטר ברזולוציה של 10 מטרים יש פיקסלים בגודל 10 מטרים על 10 מטרים. הגודל המקורי של הפיקסלים שדווחו יכול להשתנות באופן משמעותי בין מערכי נתונים, מנתונים קטנים מ-1 מטר ועד לנתונים גדולים מ-20 קילומטרים.

כשמשתמשים בפונקציה ST_REGIONSTATS כדי לחשב נתונים סטטיסטיים של אזורים, גודל הפיקסל של נתוני הרסטר הוא שיקול חשוב. לדוגמה, צבירה של נתוני רסטר ברזולוציה גבוהה באזור של מדינה יכולה להיות עתירת משאבים וגרנולרית מדי. לעומת זאת, צבירה של נתונים ברזולוציה נמוכה באזור, כמו חבילות של ערים, עשויה שלא לספק מספיק פרטים.

כדי לקבל תוצאות משמעותיות ויעילות מהניתוח, מומלץ לבחור גודל פיקסל שמתאים לגודל של הפוליגונים ולמטרה של הניתוח. אפשר למצוא את גודל הפיקסל של כל מערך נתוני רסטר בקטע התיאור של טבלאות תמונות ב-BigQuery sharing.

שינוי גודל הפיקסל משנה את מספר הפיקסלים שחוצים אזור גיאוגרפי מסוים, ולכן משפיע על התוצאות ועל הפרשנות שלהן. אנחנו לא ממליצים לשנות את גודל הפיקסל לניתוחים של נתוני ייצור. עם זאת, אם אתם יוצרים אב טיפוס של שאילתה, הגדלת גודל הפיקסל יכולה לקצר את זמן הריצה של השאילתה ולהפחית את העלות שלה, במיוחד כשמדובר בנתונים ברזולוציה גבוהה.

כדי לשנות את גודל הפיקסלים, מגדירים את scale בארגומנט options של הפונקציה ST_REGIONSTATS. לדוגמה, כדי לחשב נתונים סטטיסטיים על פיקסלים של 1,000 מטרים, משתמשים ב-options => JSON '{"scale":1000}', שמורה ל-Earth Engine לבצע דגימה מחדש של התמונה בקנה המידה המבוקש. במאמר Scale בתיעוד של Google Earth Engine מוסבר איך המערכת מטפלת בשינוי קנה מידה.

חישוב נתונים סטטיסטיים עבור מצולעים שקטנים משמעותית מהפיקסלים של רסטר יכול להניב תוצאות לא מדויקות או תוצאות null. במקרה כזה, אפשר להחליף את הפוליגון בנקודת המרכז שלו באמצעות ST_CENTROID.

חיוב

כשמריצים שאילתה, השימוש בפונקציה ST_REGIONSTATS מחויב בנפרד משאר השאילתה, כי Earth Engine מחשב את התוצאות של בקשה להפעלת פונקציה. השימוש הזה יחויב בשעות שימוש ביחידות קיבולת (slot) במסגרת מק"ט שירותי BigQuery, ללא קשר לסוג החיוב שבו אתם משתמשים (חיוב לפי דרישה או הזמנות). כדי לראות את הסכום שחויב על קריאות ל-BigQuery מ-Earth Engine, תוכלו לצפות בדוח החיוב ולהשתמש בתוויות כדי לסנן לפי מפתח התווית goog-bq-feature-type עם הערך EARTH_ENGINE. אם הפונקציה ST_REGIONSTATS נכשלת, לא תחויבו על חישוב של Earth Engine שנעשה.

לכל שאילתה, אפשר להשתמש בשיטה jobs.get ב-BigQuery API כדי לראות את המידע הבא:

  • השדה slotMs, שבו מוצג מספר אלפיות השנייה של משבצות הזמן שנצרכו על ידי Earth Engine, כשהשדה externalService הוא EARTH_ENGINE והשדה billingMethod הוא SERVICES_SKU.
  • השדה totalServicesSkuSlotMs, שבו מוצג המספר הכולל של אלפיות השנייה של משבצות זמן שנעשה בהן שימוש על ידי כל השירותים החיצוניים של BigQuery שמחויבים לפי המק"ט של שירותי BigQuery.

אפשר גם להריץ שאילתה על השדה total_services_sku_slot_ms בתצוגה INFORMATION_SCHEMA.JOBS כדי למצוא את סך המילישניות של משבצות הזמן שנצרכו על ידי שירותים חיצוניים שמחויבים לפי מק"ט BigQuery Services.

גורמי עלות

הגורמים הבאים משפיעים על השימוש במחשוב כשמריצים את הפונקציה ST_REGIONSTATS:

  • מספר שורות הקלט.
  • תמונת הרסטר שבה אתם משתמשים. חלק מהרסטרים הם קומפוזיציות שנוצרו מאוספי תמונות מקור בקטלוג הנתונים של Earth Engine, ומשאבי החישוב שנדרשים כדי ליצור את תוצאת הקומפוזיציה משתנים.
  • הרזולוציה של התמונה.
  • הגודל והמורכבות של הגיאוגרפיה של הקלט, מספר הפיקסלים שחוצים את הגיאוגרפיה ומספר משבצות התמונה והבייטים שנקראו על ידי Earth Engine.

  • המיקום של הקלט הגיאוגרפי ב-Earth ביחס לתמונות המקוריות, להטלה ולרזולוציה של התמונה.

    • היטלי תמונות יכולים לעוות פיקסלים, במיוחד פיקסלים בקווי רוחב גבוהים או מחוץ להיקף הגיאוגרפי המיועד של התמונה.
    • בנתוני רסטר מורכבים, מספר תמונות המקור שחופפות למיקום הגיאוגרפי של הקלט יכול להשתנות לפי אזור ולפי זמן. לדוגמה, חלק מהלוויינים מייצרים יותר תמונות בקווי רוחב נמוכים או גבוהים, בהתאם למסלול שלהם ולפרמטרים של איסוף הנתונים, או שהם עשויים להשמיט תמונות בהתאם לתנאים האטמוספריים המשתנים.

  • השימוש בנוסחאות בארגומנטים include או band_name, ומספר הפסים שהן כוללות.

  • שמירה במטמון של תוצאות קודמות.

שליטה בעלויות

כדי לשלוט בעלויות שמשויכות לפונקציה ST_REGIONSTATS, אפשר לשנות את המכסה שקובעת את משך הזמן שהפונקציה יכולה להשתמש בו. ברירת המחדל היא 350 שעות שימוש במשבצת ליום. כשמציגים את המכסות, מסננים את רשימת המדדים לפי earthengine.googleapis.com/bigquery_slot_usage_time כדי לראות את המכסה של Earth Engine שמשויכת לקריאות מ-BigQuery. מידע נוסף זמין במאמר בנושא מכסות של פונקציות רסטר ב-BigQuery במאמרי העזרה של Google Earth Engine.

אזורים נתמכים

שאילתות שמפעילות את הפונקציה ST_REGIONSTATS חייבות לפעול באחד מהאזורים הבאים:

  • US מספר אזורים
  • us-central1
  • us-central2
  • EU מספר אזורים
  • europe-west1

המאמרים הבאים