עבודה עם נתוני רסטר באמצעות 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. נכנסים לדף Sharing (Analytics Hub)‎.

    מעבר אל Sharing (Analytics Hub)

  2. לוחצים על חיפוש דפי אפליקציות.

  3. בשדה Search for listings מזינים את הערך "Google Earth Engine".

  4. לוחצים על מערך הנתונים שאליו רוצים להירשם.

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

  6. אופציונלי: מעדכנים את השדות פרויקט או שם מערך הנתונים המקושר.

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

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

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

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

כל טבלת תמונות כוללת טבלת *_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 באמצעות 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 לתמונה אחת. משתמשים ב-method‏ 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 מטרים. גודל הפיקסל המקורי שדווח יכול להשתנות באופן משמעותי בין קבוצות נתונים, מפחות ממטר אחד ועד ליותר מ-20 קילומטרים.

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

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

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

כדי לשנות את גודל הפיקסלים, מגדירים את scale בארגומנט options לפונקציה ST_REGIONSTATS. לדוגמה, כדי לחשב נתונים סטטיסטיים על פיקסלים של 1,000 מטר, משתמשים ב-options => JSON '{"scale":1000}', שמורה ל-Earth Engine לדגום מחדש את התמונה בקנה המידה המבוקש. למידע נוסף על האופן שבו Earth Engine מטפל בשינוי קנה מידה, קראו את המאמר קנה מידה במסמכי התיעוד של 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, שבו מוצג המספר הכולל של אלפיות השנייה של שימוש ב-slot בכל השירותים החיצוניים של BigQuery שמחויבים במק"ט של שירותי BigQuery.

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

גורמי עלות

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

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

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

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

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

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

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

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

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

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

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

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