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

dist_s1_enumerator/asf.py

@@ -135,7 +135,7 @@ def get_rtc_s1_ts_metadata_by_burst_ids(
     properties_f = [
         {
             'opera_id': p['sceneName'],
-            'acq_dt': pd.to_datetime(p['startTime']),
+            'acq_dt': pd.Timestamp(p['startTime'], tz='UTC'),
             'track_number': p['pathNumber'],
             'polarizations': p['polarization'],
             'all_urls': [p['url']] + p['additionalUrls'],

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':
@@ -231,10 +232,10 @@ def enumerate_dist_s1_products(
     df_rtc_ts: gpd.GeoDataFrame,
     mgrs_tile_ids: list[str],
     lookback_strategy: str = 'multi_window',
-    max_pre_imgs_per_burst: int = (5, 5, 5),
+    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

@@ -32,10 +32,10 @@ def enumerate_dist_s1_workflow_inputs(
     start_acq_dt: datetime | pd.Timestamp | str | None = None,
     stop_acq_dt: datetime | pd.Timestamp | str | None = None,
     lookback_strategy: str = 'multi_window',
-    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),
     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.
@@ -60,11 +60,13 @@ def enumerate_dist_s1_workflow_inputs(
         Lookback strategy to use, by default 'multi_window'. Options are
         'immediate_lookback' or 'multi_window'.
     max_pre_imgs_per_burst : int | list[int] | tuple[int, ...], optional
-        Maximum number of pre-images per burst to include, by default 10.
+        Maximum number of pre-images per burst to include, by default (4, 3, 3).
         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/tabular_models.py

@@ -27,7 +27,7 @@ rtc_s1_resp_schema = DataFrameSchema(
     {
         'opera_id': Column(str, required=True),
         'jpl_burst_id': Column(str, required=True),
-        'acq_dt': Column(DateTime(tz='UTC'), required=True),
+        'acq_dt': Column(DateTime(tz='UTC'), coerce=True, required=True),
         'acq_date_for_mgrs_pass': Column(str, required=False),
         'polarizations': Column(str, required=True),
         'track_number': Column(int, required=True),

{dist_s1_enumerator-1.0.10.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.10
+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
@@ -99,7 +99,8 @@ Yields:
 <details>
   <summary>Output</summary>
 
-```[{'mgrs_tile_id': '19HBD',
+```
+[{'mgrs_tile_id': '19HBD',
   'post_acq_date': '2023-11-05',
   'track_number': 91,
   'post_acq_timestamp': '2023-11-05 23:36:49+00:00'},
@@ -342,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.10.dist-info → dist_s1_enumerator-1.0.12.dist-info}/RECORD

@@ -1,19 +1,19 @@
 dist_s1_enumerator/__init__.py,sha256=L89uOLGobmF-ZsBA767RiGpKCDKVx6KOK6wJkjGQ69M,1766
-dist_s1_enumerator/asf.py,sha256=m0LHIBM6OSeoNi2Htin5oeeyGjsWecFgyKeqUXNcbDo,13850
+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=pQn5646hyeks8ZYxTKGb7lwOXAKkS6sijiWRFXF2Gro,21412
-dist_s1_enumerator/dist_enum_inputs.py,sha256=RG8URUyXqjyOUzq7MtBGeJhwHyfM8tjmv5gD2buu5Zs,6792
+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
 dist_s1_enumerator/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 dist_s1_enumerator/rtc_s1_io.py,sha256=TPlgMdyjRYnGWCt7J1nQ1AY90lAPQoMy2BN0oFMw4gg,5267
-dist_s1_enumerator/tabular_models.py,sha256=OjsTg6fN9Mq-LHVKuz9klFD3DsG0WkfPmfDfdZYUJOw,3189
+dist_s1_enumerator/tabular_models.py,sha256=v1XBDiDtMvRix7HKJMvmPDO3HtD7ipE-Sol405YF2pY,3202
 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.10.dist-info/licenses/LICENSE,sha256=qsoT0jnoSQSgSzA-sywESwmVxC3XcugfW-3vctvz2aM,11346
-dist_s1_enumerator-1.0.10.dist-info/METADATA,sha256=I8wF9HlLcM60_nSxsNbFryzsZWWeIgu-XBv_bcH6ss8,20543
-dist_s1_enumerator-1.0.10.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-dist_s1_enumerator-1.0.10.dist-info/top_level.txt,sha256=5-RGu6oxsKKyhybZZSuUImALhcQT8ZOAnVv2MmrESDE,19
-dist_s1_enumerator-1.0.10.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,,

{dist_s1_enumerator-1.0.10.dist-info → dist_s1_enumerator-1.0.12.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any