dist-s1-enumerator 1.0.10__tar.gz → 1.0.12__tar.gz

{dist_s1_enumerator-1.0.10 → dist_s1_enumerator-1.0.12}/CHANGELOG.md

@@ -6,6 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [PEP 440](https://www.python.org/dev/peps/pep-0440/)
 and uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.12] - 2026-01-27
+
+### Changed
+* Default for `enumerate_dist_s1_workflow_inputs` parameter `delta_window_days` goes from `365` to `60` as was expected in v1.0.9
+* Explicit tuple for `delta_lookback_days` default to ensure proper alignment with `max_pre_imgs_per_burst` and improve readability (also improved docstring for both)
+
+### Added
+* Discussion of parameters and defaults in README.md
+
+## [1.0.11] - 2026-01-27
+
+### Changed
+* Defaults for max_pre_img per burst set to defaults (4, 3, 3) in enumeration of many products and single product. This aligns with standard inputs for DIST-S1.
+
+### Fixed
+* Casting time strings into timestamps using pandas 2.0+ was attaching precision that was breaking schema validation with different precision (I believe pandas default is nano-second precision and ASF distributes with microsecond precision). Using `coerce=True` for the schema (forcing it to cast into the correct precision) and forcing data to have UTC time-zones fixes this issue with validation.
+
+
 ## [1.0.10] - 2026-01-07
 
 ### Added

{dist_s1_enumerator-1.0.10 → dist_s1_enumerator-1.0.12}/PKG-INFO

@@ -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_s1_enumerator-1.0.12}/README.md

@@ -76,7 +76,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'},
@@ -319,6 +320,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_s1_enumerator-1.0.12}/src/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-1.0.10 → dist_s1_enumerator-1.0.12}/src/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-1.0.10 → dist_s1_enumerator-1.0.12}/src/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-1.0.10 → dist_s1_enumerator-1.0.12}/src/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_s1_enumerator-1.0.12}/src/dist_s1_enumerator.egg-info/PKG-INFO

@@ -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_s1_enumerator-1.0.12}/src/dist_s1_enumerator.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ pyproject.toml
 .github/workflows/pypi-release.yml
 .github/workflows/static_analysis.yml
 .github/workflows/tests.yml
+assets/visualization_of_parameters.png
 notebooks/A__Staging_Inputs_for_One_MGRS_Tile.ipynb
 notebooks/B__Enumerate_MGRS_tile.ipynb
 src/dist_s1_enumerator/__init__.py