Convert API code snippets from JS to Py.

PiperOrigin-RevId: 709334774

samples/python/guides/README.md

@@ -0,0 +1,18 @@
+<!--
+  Copyright 2024 The Google Earth Engine Community Authors
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+
+This directory contains code snippets published in Earth Engine developer
+guides at https://developers.google.com/earth-engine.

samples/python/guides/joins01.py

@@ -0,0 +1,46 @@
+# Copyright 2024 The Google Earth Engine Community Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Earth Engine Developer's Guide examples from 'Joins - Simple' section."""
+
+# [START earthengine__joins01__simple_join]
+# Load a Landsat 8 image collection at a point of interest.
+collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA').filterBounds(
+    ee.Geometry.Point(-122.09, 37.42)
+)
+
+# Define start and end dates with which to filter the collections.
+april = '2014-04-01'
+may = '2014-05-01'
+june = '2014-06-01'
+july = '2014-07-01'
+
+# The primary collection is Landsat images from April to June.
+primary = collection.filterDate(april, june)
+
+# The secondary collection is Landsat images from May to July.
+secondary = collection.filterDate(may, july)
+
+# Use an equals filter to define how the collections match.
+filter = ee.Filter.equals(leftField='system:index', rightField='system:index')
+
+# Create the join.
+simple_join = ee.Join.simple()
+
+# Apply the join.
+simple_joined = simple_join.apply(primary, secondary, filter)
+
+# Display the result.
+display('Simple join:', simple_joined)
+# [END earthengine__joins01__simple_join]

samples/python/guides/joins02.py

@@ -0,0 +1,48 @@
+# Copyright 2024 The Google Earth Engine Community Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Earth Engine Developer's Guide examples from 'Joins - Inverted' section."""
+
+# [START earthengine__joins02__inverted_join]
+# Load a Landsat 8 image collection at a point of interest.
+collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA').filterBounds(
+    ee.Geometry.Point(-122.09, 37.42)
+)
+
+# Define start and end dates with which to filter the collections.
+april = '2014-04-01'
+may = '2014-05-01'
+june = '2014-06-01'
+july = '2014-07-01'
+
+# The primary collection is Landsat images from April to June.
+primary = collection.filterDate(april, june)
+
+# The secondary collection is Landsat images from May to July.
+secondary = collection.filterDate(may, july)
+
+# Use an equals filter to define how the collections match.
+filter = ee.Filter.equals(leftField='system:index', rightField='system:index')
+
+# [START earthengine__joins02__inverted]
+# Define the join.
+inverted_join = ee.Join.inverted()
+
+# Apply the join.
+inverted_joined = inverted_join.apply(primary, secondary, filter)
+# [END earthengine__joins02__inverted]
+
+# Print the result.
+display('Inverted join:', inverted_joined)
+# [END earthengine__joins02__inverted_join]

samples/python/guides/joins03.py

@@ -0,0 +1,45 @@
+# Copyright 2024 The Google Earth Engine Community Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Earth Engine Developer's Guide examples from 'Joins - Inner toy example' section."""
+
+# [START earthengine__joins03__toy_inner]
+# Create the primary collection.
+primary_features = ee.FeatureCollection([
+    ee.Feature(None, {'foo': 0, 'label': 'a'}),
+    ee.Feature(None, {'foo': 1, 'label': 'b'}),
+    ee.Feature(None, {'foo': 1, 'label': 'c'}),
+    ee.Feature(None, {'foo': 2, 'label': 'd'}),
+])
+
+# Create the secondary collection.
+secondary_features = ee.FeatureCollection([
+    ee.Feature(None, {'bar': 1, 'label': 'e'}),
+    ee.Feature(None, {'bar': 1, 'label': 'f'}),
+    ee.Feature(None, {'bar': 2, 'label': 'g'}),
+    ee.Feature(None, {'bar': 3, 'label': 'h'}),
+])
+
+# Use an equals filter to specify how the collections match.
+toy_filter = ee.Filter.equals(leftField='foo', rightField='bar')
+
+# Define the join.
+inner_join = ee.Join.inner('primary', 'secondary')
+
+# Apply the join.
+toy_join = inner_join.apply(primary_features, secondary_features, toy_filter)
+
+# Print the result.
+display('Inner join toy example:', toy_join)
+# [END earthengine__joins03__toy_inner]

samples/python/guides/joins04.py

@@ -0,0 +1,52 @@
+# Copyright 2024 The Google Earth Engine Community Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Earth Engine Developer's Guide examples from 'Joins - Inner MODIS example' section."""
+
+# [START earthengine__joins04__modis_inner]
+# Make a date filter to get images in this date range.
+date_filter = ee.Filter.date('2014-01-01', '2014-02-01')
+
+# Load a MODIS collection with EVI data.
+mcd43a4 = ee.ImageCollection('MODIS/MCD43A4_006_EVI').filter(date_filter)
+
+# Load a MODIS collection with quality data.
+mcd43a2 = ee.ImageCollection('MODIS/006/MCD43A2').filter(date_filter)
+
+# Define an inner join.
+inner_join = ee.Join.inner()
+
+# Specify an equals filter for image timestamps.
+filter_time_eq = ee.Filter.equals(
+    leftField='system:time_start', rightField='system:time_start'
+)
+
+# Apply the join.
+inner_joined_modis = inner_join.apply(mcd43a4, mcd43a2, filter_time_eq)
+
+# Display the join result: a FeatureCollection.
+display('Inner join output:', inner_joined_modis)
+# [END earthengine__joins04__modis_inner]
+
+# [START earthengine__joins04__inner_merge]
+# Map a function to merge the results in the output FeatureCollection.
+joined_modis = inner_joined_modis.map(
+    lambda feature: ee.Image.cat(
+        feature.get('primary'), feature.get('secondary')
+    )
+)
+
+# Print the result of merging.
+display("Inner join, merged 'bands':", joined_modis)
+# [END earthengine__joins04__inner_merge]

samples/python/guides/joins05.py

@@ -0,0 +1,57 @@
+# Copyright 2024 The Google Earth Engine Community Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Earth Engine Developer's Guide examples from 'Joins - Save All' section."""
+
+# [START earthengine__joins05__save_all]
+# Load a primary collection: Landsat imagery.
+primary = (
+    ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
+    .filterDate('2014-04-01', '2014-06-01')
+    .filterBounds(ee.Geometry.Point(-122.092, 37.42))
+)
+
+# Load a secondary collection: MODIS imagery.
+mod_secondary = ee.ImageCollection('MODIS/006/MOD09GA').filterDate(
+    '2014-03-01', '2014-07-01'
+)
+
+# Define an allowable time difference: two days in milliseconds.
+two_days_millis = 2 * 24 * 60 * 60 * 1000
+
+# Create a time filter to define a match as overlapping timestamps.
+time_filter = ee.Filter.Or(
+    ee.Filter.maxDifference(
+        difference=two_days_millis,
+        leftField='system:time_start',
+        rightField='system:time_end',
+    ),
+    ee.Filter.maxDifference(
+        difference=two_days_millis,
+        leftField='system:time_end',
+        rightField='system:time_start',
+    ),
+)
+
+# Define the join.
+save_all_join = ee.Join.saveAll(
+    matchesKey='terra', ordering='system:time_start', ascending=True
+)
+
+# Apply the join.
+landsat_modis = save_all_join.apply(primary, mod_secondary, time_filter)
+
+# Display the result.
+display('Join.saveAll:', landsat_modis)
+# [END earthengine__joins05__save_all]

samples/python/guides/joins06.py

@@ -0,0 +1,49 @@
+# Copyright 2024 The Google Earth Engine Community Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Earth Engine Developer's Guide examples from 'Joins - Save Best' section."""
+
+# [START earthengine__joins06__save_best]
+# Load a primary collection: Landsat imagery.
+primary = (
+    ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
+    .filterDate('2014-04-01', '2014-06-01')
+    .filterBounds(ee.Geometry.Point(-122.092, 37.42))
+)
+
+# Load a secondary collection: GRIDMET meteorological data
+gridmet = ee.ImageCollection('IDAHO_EPSCOR/GRIDMET')
+
+# Define a max difference filter to compare timestamps.
+max_diff_filter = ee.Filter.maxDifference(
+    difference=2 * 24 * 60 * 60 * 1000,
+    leftField='system:time_start',
+    rightField='system:time_start',
+)
+
+# Define the join.
+save_best_join = ee.Join.saveBest(matchKey='bestImage', measureKey='timeDiff')
+
+# Apply the join.
+landsat_met = save_best_join.apply(primary, gridmet, max_diff_filter)
+
+# Print the result.
+display(landsat_met)
+# [END earthengine__joins06__save_best]
+
+# check the dates (both UTC)
+first_left_match = ee.Image(landsat_met.first())
+first_right_match = ee.Image(first_left_match.get('bestImage'))
+display(ee.Date(first_left_match.get('system:time_start')))
+display(ee.Date(first_right_match.get('system:time_start')))

samples/python/guides/joins07.py

@@ -0,0 +1,39 @@
+# Copyright 2024 The Google Earth Engine Community Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Earth Engine Developer's Guide examples from 'Joins - Spatial joins' section."""
+
+# [START earthengine__joins07__spatial_save_all]
+# Load a primary collection: protected areas (Yosemite National Park).
+primary = ee.FeatureCollection('WCMC/WDPA/current/polygons').filter(
+    ee.Filter.eq('NAME', 'Yosemite National Park')
+)
+
+# Load a secondary collection: power plants.
+power_plants = ee.FeatureCollection('WRI/GPPD/power_plants')
+
+# Define a spatial filter, with distance 100 km.
+dist_filter = ee.Filter.withinDistance(
+    distance=100000, leftField='.geo', rightField='.geo', maxError=10
+)
+
+# Define a saveAll join.
+dist_save_all = ee.Join.saveAll(matchesKey='points', measureKey='distance')
+
+# Apply the join.
+spatial_joined = dist_save_all.apply(primary, power_plants, dist_filter)
+
+# Print the result.
+display(spatial_joined)
+# [END earthengine__joins07__spatial_save_all]