dist-s1-enumerator 1.0.11__py3-none-any.whl → 1.0.12__py3-none-any.whl

dist_s1_enumerator/dist_enum.py

@@ -16,9 +16,9 @@ def enumerate_one_dist_s1_product(
     post_date: datetime | pd.Timestamp | str,
     lookback_strategy: str = 'multi_window',
     post_date_buffer_days: int = 1,
-    max_pre_imgs_per_burst: int | list[int] | tuple[int, ...] = (5, 5, 5),
+    max_pre_imgs_per_burst: int | list[int] | tuple[int, ...] = (4, 3, 3),
     delta_window_days: int = 60,
-    delta_lookback_days: int | list[int] | tuple[int, ...] = 365,
+    delta_lookback_days: int | list[int] | tuple[int, ...] = (365, 730, 1095),
     min_pre_imgs_per_burst: int = 1,
     tqdm_enabled: bool = True,
 ) -> gpd.GeoDataFrame:
@@ -53,8 +53,9 @@ def enumerate_one_dist_s1_product(
         If lookback strategy is 'multi_window':
             - this is interpreted as the maximum number of pre-images on each anniversary date.
             - tuple/list of integers are provided, each int represents the maximum number of pre-images on each
-            anniversary date,
-            most recent last.
+            anniversary date. Each integer in tuple should be aligned with `delta_lookback_days`, if latter is a tuple.
+            If `delta_lookback_days` is an integer, then `max_pre_imgs_per_burst` will be interpreted with recent
+            coming first.
             - if a single integer is provided, this is interpreted as the maximum number of pre-images on 3
             anniversary dates.
         If the lookback strategy is 'immediate_lookback':
@@ -234,7 +235,7 @@ def enumerate_dist_s1_products(
     max_pre_imgs_per_burst: int = (4, 3, 3),
     min_pre_imgs_per_burst: int = 1,
     tqdm_enabled: bool = True,
-    delta_lookback_days: int = 365,
+    delta_lookback_days: int = (365, 730, 1095),
     delta_window_days: int = 60,
 ) -> gpd.GeoDataFrame:
     """
@@ -259,7 +260,9 @@ def enumerate_dist_s1_products(
         If lookback strategy is 'multi_window':
             - this is interpreted as the maximum number of pre-images on each anniversary date.
             - tuple/list of integers are provided, each int represents the maximum number of pre-images on each
-            anniversary date, most recent last.
+            anniversary date. Each integer in tuple should be aligned with `delta_lookback_days`, if latter is a tuple.
+            If `delta_lookback_days` is an integer, then `max_pre_imgs_per_burst` will be interpreted with recent
+            coming first.
             - if a single integer is provided, this is interpreted as the maximum number of pre-images on 3
             anniversary dates.
         If the lookback strategy is 'immediate_lookback':
@@ -270,7 +273,12 @@ def enumerate_dist_s1_products(
     tqdm_enabled : bool, optional
         Whether to enable tqdm progress bars, by default True.
     delta_lookback_days : int, optional
-        When to set the most recent pre-image date. Default is 365.
+        When to set the most recent pre-image date for a given lookback window in baseline.
+        Default is (365, 730, 1095). Explicitly set to a tuple to ensure proper alignment with `max_pre_imgs_per_burst`
+        and improve readability.
+        See `max_pre_imgs_per_burst` for how this parameter is aligned with that. Specifically, when they are both
+        tuples they should be the same length (i.e. if `delta_lookback_days` is a tuple, then `max_pre_imgs_per_burst`
+        should be the same length).
         If lookback strategy is 'multi_window', this means the maximum number of days to search for pre-images on each
         anniversary date where `post_date - n * lookback_days` are the anniversary dates for n = 1,....
         If lookback strategy is 'immediate_lookback', this must be set to 0.

dist_s1_enumerator/dist_enum_inputs.py

@@ -34,8 +34,8 @@ def enumerate_dist_s1_workflow_inputs(
     lookback_strategy: str = 'multi_window',
     max_pre_imgs_per_burst: int | list[int] | tuple[int, ...] = (4, 3, 3),
     min_pre_imgs_per_burst: int = 1,
-    delta_lookback_days: int | list[int] | tuple[int, ...] = 365,
-    delta_window_days: int = 365,
+    delta_lookback_days: int | list[int] | tuple[int, ...] = (365, 730, 1095),
+    delta_window_days: int = 60,
     df_ts: gpd.GeoDataFrame | None = None,
 ) -> list[dict]:
     """Enumerate the inputs for a DIST-S1 workflow.
@@ -64,7 +64,9 @@ def enumerate_dist_s1_workflow_inputs(
         If lookback strategy is 'multi_window':
             - this is interpreted as the maximum number of pre-images on each anniversary date.
             - tuple/list of integers are provided, each int represents the maximum number of pre-images on each
-            anniversary date, most recent last.
+            anniversary date. Each integer in tuple should be aligned with `delta_lookback_days`, if latter is a tuple.
+            If `delta_lookback_days` is an integer, then `max_pre_imgs_per_burst` will be interpreted with recent
+            coming first.
             - if a single integer is provided, this is interpreted as the maximum number of pre-images on 3
             anniversary dates.
         If the lookback strategy is 'immediate_lookback':
@@ -73,7 +75,7 @@ def enumerate_dist_s1_workflow_inputs(
     min_pre_imgs_per_burst : int, optional
         Minimum number of pre-images per burst to include, by default 1. This is for *all* the pre-images.
     delta_lookback_days : int | list[int] | tuple[int, ...], optional
-        When to set the most recent pre-image date. Default is 0.
+        When to set the most recent pre-image date. Default is (365, 730, 1095) days.
         If lookback strategy is 'multi_window', this means the maximum number of days to search for pre-images on each
         anniversary date where `post_date - n * lookback_days` are the anniversary dates for n = 1,....
         If lookback strategy is 'immediate_lookback', this must be set to 0.

{dist_s1_enumerator-1.0.11.dist-info → dist_s1_enumerator-1.0.12.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dist-s1-enumerator
-Version: 1.0.11
+Version: 1.0.12
 Summary: Enumeration and ops library for the OPERA DIST-S1 project
 Author-email: "Richard West, Charlie Marshak, Talib Oliver-Cabrera, and Jungkyo Jung" <charlie.z.marshak@jpl.nasa.gov>
 License: Apache-2.0
@@ -343,6 +343,21 @@ In theory, we could specify the exact time of acquisition, but we have elected t
 It is also important to note that we are assuming the selection of pre-images (once a post-image set is selected) is fixed.
 Although varying a baseline of pre-images to measure disturbance will alter the final DIST-S1 product, we assume with a fixed strategy to construct this baseline, the above 3 fields uniquely identify a DIST-S1 product.
 
+### Parameters for Enumeration of RTC-S1 Inputs
+
+We quickly discuss the primary parameters for enumerating the RTC-S1 inputs and provide a picture for the default parameters for clarity particularly for enumerating products.
+The primary paramters we discuss are $\Delta_w$ (`delta_window_days` in library), $\Delta_l$ (`delta_lookback_days` in library), and $m$ (`max_pre_imgs_per_burst` in library).
+These parameters operate on a per-burst curation as noted above.
+The parameter $\Delta_w$ constrains how many days between the anniversary date of a recent post-acquisition date and $\Delta_w$ days before that.
+By default it is set to 60 days.
+The parameter $\Delta_l$ explicitly defines the number of anniversary dates and their distance in days from the recent post-acquisition.
+It is by default set to (365, 730, 1095) days, which is 3 anniversary dates at 365 days apart.
+$m$ explicitly says the maximum amount in each window when constructing this baseline and by default it is set to (4, 3, 3).
+So for a post-date acquistion at $t_0$, the maximum number of RTC-S1 products to be used in the time range $[t_0 - 365 - \Delta_w, t_0 - 365]$ is $4$ and the next range $[t_0 - 730 - \Delta_w, t_0 - 730]$ is 3. A visualization of this is shown below.
+
+![params](assets/visualization_of_parameters.png)
+
+
 # About the Data Tables in this Library
 
 One of the purposes of this data is to provide easy access via standard lookups to a variety of tables associated with enumerating DIST-S1 products.

{dist_s1_enumerator-1.0.11.dist-info → dist_s1_enumerator-1.0.12.dist-info}/RECORD

@@ -1,8 +1,8 @@
 dist_s1_enumerator/__init__.py,sha256=L89uOLGobmF-ZsBA767RiGpKCDKVx6KOK6wJkjGQ69M,1766
 dist_s1_enumerator/asf.py,sha256=FflbykjtZDT8sn8a2g2PMpFejYXgbtyCaW7wuKnzcSE,13858
 dist_s1_enumerator/constants.py,sha256=Ve_aLWRqNduh7uEBaHbJNy1VfH2njzV57L4T_gBVNaE,727
-dist_s1_enumerator/dist_enum.py,sha256=196qAcsAscT0pNn4hK7hM0dI1j1aABSI5zpaxFjUGUI,21412
-dist_s1_enumerator/dist_enum_inputs.py,sha256=O930DPfubLVW47zw7QzVBokjtNk9Wy4nP_gDdBaEnn0,6799
+dist_s1_enumerator/dist_enum.py,sha256=AidZHEqB-vyJF-0N9Mvxj6aj4DqTg0MeII4NYzdDW7I,22297
+dist_s1_enumerator/dist_enum_inputs.py,sha256=mHwkQtgsK3gRoW52KJB5NzF6-JCa6P0K087vUGXPE4A,7043
 dist_s1_enumerator/exceptions.py,sha256=JhT8fIEmW3O2OvUQADkEJkL8ZrUN5pkKNzCCSt33goQ,82
 dist_s1_enumerator/mgrs_burst_data.py,sha256=vt9ubDUP3l2iNXK82OuvahX_WUq0MpHMkmTKOPvbRuw,7162
 dist_s1_enumerator/param_models.py,sha256=DI2MgSxiPo7HiRKtXX8bxZnQtuoYAmtAcdYYrnhMIho,4614
@@ -12,8 +12,8 @@ dist_s1_enumerator/tabular_models.py,sha256=v1XBDiDtMvRix7HKJMvmPDO3HtD7ipE-Sol4
 dist_s1_enumerator/data/jpl_burst_geo.parquet,sha256=EXpQcXhWt2T6RVBmvkh7vQb150ShftIsZWvN97wQP4g,30106843
 dist_s1_enumerator/data/mgrs.parquet,sha256=XB69HyNK502cJJ2Ry5wmnrbe-jepAdoMe7y35QUj_Gs,596933
 dist_s1_enumerator/data/mgrs_burst_lookup_table.parquet,sha256=m_r0E7yTet6Xwd_H-lg2qr6IpBYBksYn5C5nOaXY8pw,3029091
-dist_s1_enumerator-1.0.11.dist-info/licenses/LICENSE,sha256=qsoT0jnoSQSgSzA-sywESwmVxC3XcugfW-3vctvz2aM,11346
-dist_s1_enumerator-1.0.11.dist-info/METADATA,sha256=vufcaCwBJmK01Me8wAYo6dXfefkJ0EM-yLtRrf_jRVs,20544
-dist_s1_enumerator-1.0.11.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-dist_s1_enumerator-1.0.11.dist-info/top_level.txt,sha256=5-RGu6oxsKKyhybZZSuUImALhcQT8ZOAnVv2MmrESDE,19
-dist_s1_enumerator-1.0.11.dist-info/RECORD,,
+dist_s1_enumerator-1.0.12.dist-info/licenses/LICENSE,sha256=qsoT0jnoSQSgSzA-sywESwmVxC3XcugfW-3vctvz2aM,11346
+dist_s1_enumerator-1.0.12.dist-info/METADATA,sha256=nDC2iPBQE7J8v_hW_4FhpU6oQHq4xg_vI2dLMJpobtk,21850
+dist_s1_enumerator-1.0.12.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+dist_s1_enumerator-1.0.12.dist-info/top_level.txt,sha256=5-RGu6oxsKKyhybZZSuUImALhcQT8ZOAnVv2MmrESDE,19
+dist_s1_enumerator-1.0.12.dist-info/RECORD,,