From c4af2a52fedb283701c43b3f9b4b2e765e1b66a5 Mon Sep 17 00:00:00 2001
From: Favyen Bastani <favyenb@allenai.org>
Date: Fri, 7 Feb 2025 10:31:26 -0800
Subject: [PATCH] add doc string

---
 rslp/satlas/data_sources.py | 35 +++++++++++++++++++++++++++++------
 1 file changed, 29 insertions(+), 6 deletions(-)

diff --git a/rslp/satlas/data_sources.py b/rslp/satlas/data_sources.py
index e4f43bf..a20ab3d 100644
--- a/rslp/satlas/data_sources.py
+++ b/rslp/satlas/data_sources.py
@@ -20,12 +20,35 @@
 def _find_monthly_matches(
     geometry: STGeometry, item_list: list[Item], period_days: int, max_matches: int
 ) -> list[list[Item]]:
-    # Find matches across the periods.
-    # For each period, we create an STGeometry with modified time range
-    # matching the period, and obtain matching mosaic.
-    # We start from the end of the time range because we care more about recent
-    # periods and so we want to make sure that they align correctly with the
-    # end.
+    """Match items to the geometry with one mosaic per period.
+
+    We divide the time range of the geometry into shorter periods. Within each period,
+    we use the items corresponding to that period to create a mosaic. The returned item
+    groups include one group per period, starting from the most recent periods, up to
+    the provided max_matches.
+
+    This is used e.g. when a model should process three mosaics, where each mosaic
+    should come from a different month. This gives more diversity of images, since
+    simply searching for the least cloudy images could result in selecting all of the
+    images from the same month.
+
+    max_matches may be smaller than the total number of periods in the given time
+    range. In this case, we prefer to use mosaics of the most recent periods. However,
+    sometimes there may be no items in a period; in that case, the older periods are
+    used as a fallback.
+
+    Args:
+        geometry: the window geometry to match items to.
+        item_list: the list of items.
+        period_days: the length of one period in days.
+        max_matches: the number of per-period mosaics to create.
+
+    Returns:
+        the matched item groups, where each group contains items that yield a
+            per-period mosaic.
+    """
+    # For each period, we create an STGeometry with modified time range matching that
+    # period, and use it with match_candidate_items_to_window to get a mosaic.
     cur_groups: list[list[Item]] = []
     period_end = geometry.time_range[1]
     while period_end > geometry.time_range[0] and len(cur_groups) < max_matches: