עבודה עם נתוני רסטר באמצעות 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 sharing, צריך להפעיל את Analytics Hub API ולוודא שיש לכם את ההרשאות הנדרשות לצפייה בפרטי המוצרים ובאוספי הנתונים לשיתוף ולהרשמה אליהם.

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

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

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

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

  3. בשדה Search for listings (חיפוש כרטיסי מוצר), מזינים את הערך "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 באמצעות 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.

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

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

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

חיוב

כשמריצים שאילתה, השימוש בפונקציה ST_REGIONSTATS מחויב בנפרד משאר השאילתה, כי Earth Engine מחשב את התוצאות של קריאת הפונקציה. השימוש הזה יחויב בשעות שימוש ביחידות קיבולת (slot) במסגרת SKU של שירותי 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.

גורמי עלות

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

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

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

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

  • השימוש בנוסחאות בארגומנטים 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

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