google-earth-engine

Google Earth Engine

目的: GEE のサーバーサイドモデルを正しく使用すること。繰り返し発生する障害 パターンは、クライアント/サーバーの混同(ループ内での .getInfo() 呼び出し、 サーバーオブジェクトに対する Python の if)、無制限の計算(スケール調整されていない リダクションによるタイムアウト)、そして暗黙のデフォルトスケール(誤った解像度で 計算される統計)です。

これはそもそもここで実行すべきか? — Earth Engine とローカルの比較

ee. コードを書く前にこの問いに答えてください。判断は 6 つの事項にかかっており、 それらなしには判断できません。したがって、まずそれらを明確にしましょう — 暫定的な 推奨と並べて尋ねることはあっても、推奨の代わりに尋ねてはいけません:

1. アーカイブの範囲と期間 — 面積、および何年分をどの再訪頻度で扱うか。 これがサーバーサイドの制約に見合う価値をもたらすものであり、単一シーンでは そうなりません。
2. アルゴリズムの表現可能性 — その処理をマスク、リデューサー、バンド演算として 記述できるか? 任意のピクセル単位の反復、カスタムソルバー、または GEE がホスト していない Python ライブラリを必要とするものはローカルに属します。
3. データの所在と機密性 — 制限されたデータやオフラインデータはアップロード できず、規模に関係なく議論はそこで終わります。
4. インタラクティブの制限とバッチ — クォータとエチケット を参照してください。約 5 分を超えるインタラクティブリクエストは、最初から バッチエクスポートとして設計する必要があり、getInfo がタイムアウトしてから 後付けするものではありません。
5. エクスポート量 — 実際に何が返ってくるか: 少数のリダクション済み統計か、 ローカルに保存して再処理するフル解像度のピクセル単位スタックか。
6. 再現性のコスト — サーバーサイドへ移行する本当の代償。カタログのバージョンは 気づかないうちに変わり得て、計算はローカルに痕跡を残さないため、GEE を選ぶことは 来歴記録を提供する義務を負うことになります。GEE を推奨する 際にはこのコストを明示してください。これを欠いた推奨は不完全です。

Earth Engine を推奨するのは、1 と 2 がそれを支持し、3 がそれを許容する場合のみです。 答えが本当に拮抗している場合は、そう述べ、このスキルが対象とするプラットフォームを デフォルトにするのではなく、決め手となる問いを挙げてください。xee および STAC + stackstac / odc-stac は挙げる価値のある中間的な道です: ローカル計算による カタログアクセスです。

メンタルモデル — すべては遅延される

ee.Image、ee.ImageCollection、ee.FeatureCollection は サーバーサイドの 記述であり、データではありません。出力が要求される(getInfo、エクスポート、 マップタイル)まで何も計算されません。帰結:

• サーバー側の値に対して Python の if/for を決して使わないでください — ee.Algorithms.If は控えめに使い、.map() + フィルターを優先してください。 要素ごとに .getInfo() を呼び出す Python ループは、GEE のパフォーマンス上の バグ第 1 位です。
• .getInfo() はブロックして転送します。ごく小さなスカラーにのみ使ってください。 ある程度のサイズがあるもの → エクスポート(Drive/GCS/Asset へ)。
• デバッグには .aggregate_array()、.first()、.limit(3) のプローブを使い、 コレクション全体を出力しないでください。

標準パイプライン(Sentinel-2 クラウドフリーコンポジット)

import ee
ee.Initialize(project="my-project")

aoi = ee.Geometry.Rectangle([27.0, 38.3, 27.4, 38.6])

def mask_s2(img):
    # Cloud Score+ is the current best practice (threshold ~0.5-0.65)
    cs = img.linkCollection(csplus, ["cs_cdf"]).select("cs_cdf")
    return img.updateMask(cs.gte(0.6))

csplus = ee.ImageCollection("GOOGLE/CLOUD_SCORE_PLUS/V1/S2_HARMONIZED")
s2 = (ee.ImageCollection("COPERNICUS/S2_SR_HARMONIZED")
      .filterBounds(aoi)
      .filterDate("2025-05-01", "2025-09-30")
      .map(mask_s2))
composite = s2.median().clip(aoi)
ndvi = composite.normalizedDifference(["B8", "B4"]).rename("ndvi")

コレクションの選択: S2_SR_HARMONIZED(2022 年以降のオフセット補正済み)、 LANDSAT/LC08/C02/T1_L2 など(スケール係数を適用: 光学 *0.0000275 - 0.2)、日次/粗解像度には MODIS/061/...、気候には ERA5-Land。 コレクション ID と日付フィルターを成果物に記録してください。

リデューサーとゾーン統計 — スケールは省略できません

stats = ndvi.reduceRegions(
    collection=districts,
    reducer=ee.Reducer.mean().combine(ee.Reducer.stdDev(), sharedInputs=True),
    scale=10,                    # ALWAYS explicit — native resolution
    tileScale=4,                 # raise when "computation timed out"
)

• scale は一部のパスでマップのズームレベルがデフォルトになります — 気づかない うちに粗い統計になります。常にデータのネイティブ解像度に設定してください (または意図的な粗化であることを明示してください)。
• bestEffort=True は制限に収めるためにスケールを暗黙に低下させます — 分析では 避け、tileScale + エクスポートを優先してください。
• 大規模なリダクション → .getInfo() ではなく Export.table.toDrive。
• 加重リデューサーと非加重リデューサーはポリゴン境界で異なります (ピクセル全体のカウントには .unweighted())。どちらを使ったかを明示してください。

時系列

• 日付の ee.List.sequence に対してマップ関数を適用し、期間ごとのコンポジットを構築して（月次/季節ごとの中央値）、それからリデュースします — どうせ集約する日次のスタックをエクスポートしないでください。
• ピクセルごとのトレンドには: ee.Reducer.sensSlope()（ロバスト）または linearFit、フェノロジーには調和回帰（sin/cos 項の .addBands）を使用します。有効な観測数のカウントでマスクしてください — 200 回の可能な観測のうち 4 ピクセルから得たトレンドはノイズです。カウントバンドを報告してください。
• アーカイブ規模での変化点検出（GEE で利用可能な LandTrendr/CCDC）には、手法の選択は change-detection に従います。

GEE での分類

ee.Classifier.smileRandomForest がほとんどのケースをカバーします。トレーニングサンプルは image.sampleRegions で取得します。train/test は空間的に分割してください（グリッドセルの属性を追加してフィルタリングします — ランダムな randomColumn 分割はリークします。ml-experiment-standards → references/spatial-cv-protocol.md を参照）。クラスごとの精度は errorMatrix から報告してください。分類マップから得られた面積推定値には、依然として設計ベースの調整が必要です（change-detection / Olofsson）。

エクスポートとハンドオフ

• Export.image.toDrive/toCloudStorage を明示的な region、scale、crs、maxPixels とともに使用します。既存のラスターとのピクセルアラインメントが重要な場合は crsTransform を使用してください。
• 約 10⁸ ピクセルを超えるエクスポート: タイルごとに分割するか、中間として toAsset を使用してください。
• COG エクスポートを介してローカルの Python スタック（rasterio/xarray）へハンドオフするか、xarray ネイティブのアクセスには xee を使用してください。geemap でインタラクティブに可視化できます。

クォータとエチケット

バッチタスクはキューに入ります（タスクステータスを確認してください。何百も盲目的に投入しないでください）。インタラクティブリクエストは約 5 分でタイムアウトします — 長時間のジョブはバッチエクスポートに回してください。パイプラインが中間プロダクトを再利用する場合は、アセットとしてキャッシュしてください。

来歴記録

サーバーサイドの計算は事後に見えなくなります。カタログはあなたの下で変化し、リデューサーのデフォルトが数値を変え、エクスポートされたファイルにはどのアーカイブがそれを生成したかを示すものが何もありません。すべての Earth Engine 成果物には来歴記録を添付し、エクスポートの隣にサイドカー JSON として出力してください — ノートブックに残さないでください:

• バージョン接尾辞付きのカタログアセット ID（COPERNICUS/S2_SR_HARMONIZED および特定のコレクションバージョン）、適用された日付範囲とフィルターも併記します。
• マスク手法としきい値 — 雲確率のソース、しきい値、および形態学的バッファがあればそれも記載します。
• リデューサーとその引数（tileScale、bestEffort、および crsTransform があればそれも含む）。
• エクスポートパラメーター: region、scale、crs、maxPixels、およびタスク ID。
• 実行日と ee.__version__ / API クライアントバージョン。サーバーサイドのデフォルトは予告なく変更されるためです。

ローカルのワークフローではなく Earth Engine を推奨することは、これなしでは不完全です。ユーザーがサーバーサイドに移行することで手放す主なものは再現性のコストであるため、それがどのように回復されるかを明示してください。

検証プロトコル

1. プローブ: composite.select("B4").projection().nominalScale().getInfo() とバンド名 — リデュース前にスケール/CRS の仮定を確認します。
2. geemap で 2 つのズームレベルにおいてベースマップと比較しながら目視チェックします。
3. エクスポートされたクリップに対してローカル計算とゾーン統計を 1 つ照合します（スケール/マスキングの不一致を検出します）。
4. 報告: コレクション ID、日付範囲、マスク手法 + しきい値、スケール、リデューサーの種類。

落とし穴チェックリスト

• ループ内での .getInfo()（ロジックをサーバーサイドに移してください）。
• reduceRegion(s) で scale が欠落 → ズーム依存の統計。
• スケールファクターなしで Landsat C2 を使用 → 反射率 > 1。
• bestEffort=True が解像度の劣化を隠蔽。
• 雲のあるピクセルを含む中央値コンポジット（リデュースの前にマスクしてください）。
• サーバーサイドオブジェクトに対する Python の条件分岐（常に false になります）。
• 有効観測数マスキングのないトレンドマップ。

実行契約

• ワークフロー: コレクションと期間を定義し、サーバー側のマスクおよび変換パイプラインを構築し、小規模なリージョンでテストし、計算し、スケールと投影を検証し、再現可能な形でエクスポートします。
• 判断ルール: 惑星規模のアーカイブとスケーラブルな集計には Earth Engine を使用し、機密性の高いデータやオフラインデータにはローカルツールを使用し、対話型の限界を超える作業にはバッチエクスポートを使用します。
• 検証プロトコル: バンド、投影、スケール、マスク、観測数を調査し、空間サンプルを検査し、エクスポートされた統計値を 1 つローカルでクロスチェックし、コレクションのバージョンとパラメータを記録します。
• 障害モード: クライアント側のループ、暗黙的なスケール、マスクされたピクセルによるバイアス、クォータによるサイレントな劣化、期限切れのアセット、または無制限のリージョン操作が発生した場合は停止します。
• 成果物: 実行可能なスクリプト、コレクションと日付のマニフェスト、マスクとリデューサのパラメータ、タスク/エクスポート設定、検証エビデンス、エクスポートされたアセットのインベントリ。
• ソースの鮮度: 実行時に 信頼できるソースレジストリ を参照して、カタログ、API、クォータ、ポリシーの変更を確認してください。