AI-generated Key Takeaways
-
Saving joins in Earth Engine represent one-to-many relationships and store matches from a secondary collection as a named property in the primary collection.
-
The
ee.Join.saveAll()method is used to save all matching features from the secondary collection as anee.Listwithin the primary collection. -
Unmatched elements in the primary collection are dropped when using a
saveAll()join. -
An example demonstrates using
ee.Join.saveAll()to find MODIS imagery acquired within two days of each Landsat image.
Saving joins are one way of representing one-to-many relationships in Earth Engine.
Unlike an inner join, a saving join stores matches from the
secondary collection as a named property of the features in the
primary collection. To save all such matches, use an
ee.Join.saveAll(). If there is a one-to-many relationship, a
saveAll() join stores all matching features as an
ee.List. Unmatched elements in the primary collection are
dropped. For example, suppose there is a need to get all MODIS imagery acquired
within two days of each Landsat image in a collection. This example uses a
saveAll() join for that purpose:
Code Editor (JavaScript)
// Load a primary collection: Landsat imagery. var 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. var modSecondary = ee.ImageCollection('MODIS/006/MOD09GA') .filterDate('2014-03-01', '2014-07-01'); // Define an allowable time difference: two days in milliseconds. var twoDaysMillis = 2 * 24 * 60 * 60 * 1000; // Create a time filter to define a match as overlapping timestamps. var timeFilter = ee.Filter.or( ee.Filter.maxDifference({ difference: twoDaysMillis, leftField: 'system:time_start', rightField: 'system:time_end' }), ee.Filter.maxDifference({ difference: twoDaysMillis, leftField: 'system:time_end', rightField: 'system:time_start' }) ); // Define the join. var saveAllJoin = ee.Join.saveAll({ matchesKey: 'terra', ordering: 'system:time_start', ascending: true }); // Apply the join. var landsatModis = saveAllJoin.apply(primary, modSecondary, timeFilter); // Display the result. print('Join.saveAll:', landsatModis);
import ee import geemap.core as geemap
Colab (Python)
# 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)
In this example, note that the secondary MODIS collection is pre-filtered to be
chronologically similar to the primary Landsat collection for efficiency. To
compare the Landsat acquisition time to the MODIS composite time, which has a daily range,
the filter compares the endpoints of the image timestamps. The join is defined with the
name of the property used to store the list of matches for each Landsat image
(‘terra’) and optional parameter to sort the list of matches by the
system:time_start property
Inspection of the result indicates that images within the primary collection have the
added terra property which stores a list of the matching MODIS images.