feat: can use regions to filter sea ice products in cmr queries

fix: use CMR queries to find granules in each download test

icesat2_toolkit/convert.py

@@ -1,6 +1,6 @@
 """
 convert.py
-Written by Tyler Sutterley (12/2022)
+Written by Tyler Sutterley (03/2024)
 Utilities for converting ICESat-2 HDF5 files into different formats
 
 PYTHON DEPENDENCIES:
@@ -17,6 +17,7 @@
         https://pandas.pydata.org/
 
 UPDATE HISTORY:
+    Updated 03/2024: use pathlib to define and operate on paths
     Updated 12/2022: place some imports behind try/except statements
     Updated 06/2022: place zarr and pandas imports behind try/except statements
     Updated 04/2022: updated docstrings to numpy documentation format

icesat2_toolkit/io/ATL03.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 u"""
-ATL03.py (11/2023)
+ATL03.py (03/2024)
 Read ICESat-2 ATL03 and ATL09 data files to calculate average segment surfaces
     ATL03 datasets: Global Geolocated Photons
     ATL09 datasets: Atmospheric Characteristics
@@ -15,6 +15,7 @@
         https://www.h5py.org/
 
 UPDATE HISTORY:
+    Updated 03/2024: use pathlib to define and operate on paths
     Updated 11/2023: drop DIMENSION_LIST, CLASS and NAME attributes
     Updated 12/2022: place some imports behind try/except statements
         refactor ICESat-2 data product read programs under io

icesat2_toolkit/io/ATL06.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 u"""
-ATL06.py (11/2023)
+ATL06.py (03/2024)
 Read ICESat-2 ATL06 (Land Ice Along-Track Height Product) data files
 
 OPTIONS:
@@ -16,6 +16,7 @@
         https://www.h5py.org/
 
 UPDATE HISTORY:
+    Updated 03/2024: use pathlib to define and operate on paths
     Updated 11/2023: drop DIMENSION_LIST, CLASS and NAME attributes
     Updated 05/2023: extract more ancillary data from ATL06 files
     Updated 12/2022: place some imports behind try/except statements

icesat2_toolkit/io/ATL07.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 u"""
-ATL07.py (11/2023)
+ATL07.py (03/2024)
 Read ICESat-2 ATL07 (Sea Ice Height) data files
 
 PYTHON DEPENDENCIES:
@@ -11,6 +11,7 @@
         https://www.h5py.org/
 
 UPDATE HISTORY:
+    Updated 03/2024: use pathlib to define and operate on paths
     Updated 11/2023: drop DIMENSION_LIST, CLASS and NAME attributes
     Updated 05/2023: extract more ancillary data from ATL07 files
     Updated 12/2022: place some imports behind try/except statements

icesat2_toolkit/io/ATL10.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 u"""
-ATL10.py (11/2023)
+ATL10.py (03/2024)
 Read ICESat-2 ATL10 (Sea Ice Freeboard) data files
 
 PYTHON DEPENDENCIES:
@@ -11,6 +11,7 @@
         https://www.h5py.org/
 
 UPDATE HISTORY:
+    Updated 03/2024: use pathlib to define and operate on paths
     Updated 11/2023: drop DIMENSION_LIST, CLASS and NAME attributes
     Updated 05/2023: extract more ancillary data from ATL10 files
     Updated 12/2022: place some imports behind try/except statements

icesat2_toolkit/io/ATL11.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 u"""
-ATL11.py (11/2023)
+ATL11.py (03/2024)
 Read ICESat-2 ATL11 (Annual Land Ice Height) data files
 
 OPTIONS:
@@ -18,6 +18,7 @@
         https://www.h5py.org/
 
 UPDATE HISTORY:
+    Updated 03/2024: use pathlib to define and operate on paths
     Updated 11/2023: drop DIMENSION_LIST, CLASS and NAME attributes
     Updated 05/2023: extract more ancillary data from ATL11 files
     Updated 12/2022: place some imports behind try/except statements

icesat2_toolkit/io/ATL12.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 u"""
-ATL12.py (11/2023)
+ATL12.py (03/2024)
 Read ICESat-2 ATL12 (Ocean Surface Height) data files
 
 PYTHON DEPENDENCIES:
@@ -11,6 +11,7 @@
         https://www.h5py.org/
 
 UPDATE HISTORY:
+    Updated 03/2024: use pathlib to define and operate on paths
     Updated 11/2023: drop DIMENSION_LIST, CLASS and NAME attributes
     Updated 05/2023: extract more ancillary data from ATL12 files
     Updated 12/2022: place some imports behind try/except statements

icesat2_toolkit/tools.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 tools.py
-Written by Tyler Sutterley (04/2022)
+Written by Tyler Sutterley (03/2024)
 Plotting tools and utilities
 
 PYTHON DEPENDENCIES:
@@ -13,6 +13,7 @@
         https://github.com/matplotlib/matplotlib
 
 UPDATE HISTORY:
+    Updated 03/2024: use pathlib to define and operate on paths
     Updated 04/2022: updated docstrings to numpy documentation format
     Updated 12/2021: added custom colormap function for some common scales
     Written 09/2021

icesat2_toolkit/utilities.py

@@ -1,14 +1,15 @@
 #!/usr/bin/env python
 u"""
 utilities.py
-Written by Tyler Sutterley (11/2023)
+Written by Tyler Sutterley (03/2024)
 Download and management utilities for syncing time and auxiliary files
 
 PYTHON DEPENDENCIES:
     lxml: processing XML and HTML in Python
         https://pypi.python.org/pypi/lxml
 
 UPDATE HISTORY:
+    Updated 03/2024: can use regions to filter sea ice products in cmr queries
     Updated 11/2023: updated ssl context to fix deprecation error
     Updated 07/2023: add function for S3 filesystem
         add s3 and opendap endpoint options to cmr query functions
@@ -1608,36 +1609,44 @@ def cmr_granules(granule: str | int | list | None):
             logging.warning("Listed granule region is not presently available")
         return granule_list
 
-# PURPOSE: check if the submitted ATL14/ATL15 regions are valid
-def cmr_regions(region: str | list | None):
+# PURPOSE: check if the submitted regions are valid
+def cmr_regions(region: str | int | list | None):
     """
-    Check if the submitted ATL14/ATL15 regions are valid
+    Check if the submitted ATL07 or ATL14/ATL15 regions are valid
 
     Parameters
     ----------
-    region: str, list or NoneType
-        ICESat-2 ATL14/ATL15 region
+    region: str, int, list or NoneType
+        ICESat-2 ATL07 or ATL14/ATL15 region
 
     Returns
     -------
     region_list: list
-        formatted available ATL14/ATL15 regions
+        formatted available regions
     """
+    # all available ICESat-2 sea ice regions
+    ATL07_regions = ['01','02']
     # all available ICESat-2 ATL14/15 regions
-    all_regions = ['AA','AK','CN','CS','GL','IS','SV','RA']
+    ATL1415_regions = ['AA','A1','A2','A3','A4','AK',
+                       'CN','CS','GL','IS','SV','RA']
+    # combined regions
+    all_regions = ATL07_regions + ATL1415_regions
     if region is None:
         return ["??"]
     else:
         if isinstance(region, str):
             assert region in all_regions
             region_list = [str(region)]
+        elif isinstance(region, int):
+            assert int(region) > 0, "Sea ice hemisphere region must be positive"
+            region_list = [str(region).zfill(2)]
         elif isinstance(region, list):
             region_list = []
             for r in region:
                 assert r in all_regions
                 region_list.append(str(r))
         else:
-            raise TypeError("Please enter the region as a list or string")
+            raise TypeError("Please enter the region as a list, int or string")
         # check if user-entered region is currently not available
         if not set(all_regions) & set(region_list):
             logging.warning("Listed region is not presently available")
@@ -1693,7 +1702,7 @@ def cmr_readable_granules(product: str, **kwargs):
     granules: str, list or NoneType, default None
         ICESat-2 granule region strings to query
     regions: str, list or NoneType, default None
-        ICESat-2 ATL14/ATL15 region
+        ICESat-2 ATL07 or ATL14/ATL15 region
     resolutions: str, list or NoneType, default None
         ICESat-2 ATL14/ATL15 spatial resolution
 
@@ -1719,6 +1728,19 @@ def cmr_readable_granules(product: str, **kwargs):
                 # append the granule pattern
                 pattern = f"{product}_{r}_????_{s}_*"
                 readable_granule_list.append(pattern)
+    elif product in ("ATL07", "ATL10", "ATL20", "ATL21"):
+        # along-track sea ice products
+        # for each sea ice hemisphere flag
+        for r in cmr_regions(kwargs["regions"]):
+            # for each available cycle of interest
+            for c in cmr_cycles(kwargs["cycles"]):
+                # for each available track of interest
+                for t in cmr_tracks(kwargs["tracks"]):
+                    # use single character wildcards "?" for date strings,
+                    # unused granule numbers, and any unset parameters
+                    pattern = f"{product}-{r}_{14 * '?'}_{t}{c}??_*"
+                    # append the granule pattern
+                    readable_granule_list.append(pattern)
     else:
         # along-track products
         # for each available cycle of interest
@@ -1728,10 +1750,7 @@ def cmr_readable_granules(product: str, **kwargs):
                 # for each available granule region of interest
                 for g in cmr_granules(kwargs["granules"]):
                     # use single character wildcards "?" for date strings,
-                    # sea ice product hemispheres, and any unset parameters
-                    if product in ("ATL07", "ATL10", "ATL20", "ATL21"):
-                        pattern = f"{product}-??_{14 * '?'}_{t}{c}{g}_*"
-                    elif product in ("ATL11",):
+                    if product in ("ATL11",):
                         pattern = f"{product}_{t}{g}_*"
                     else:
                         pattern = f"{product}_{14 * '?'}_{t}{c}{g}_*"
@@ -1831,7 +1850,7 @@ def cmr(
     granules: str, list or NoneType, default None
         ICESat-2 granule region strings to query
     regions: str, list or NoneType, default None
-        ICESat-2 ATL14/15 region strings to query
+        ICESat-2 ATL07 or ATL14/15 region strings to query
     resolutions: str, list or NoneType, default None
         ICESat-2 ATL14/15 resolution strings to query
     bbox: list or NoneType, default None

scripts/MPI_DEM_ICESat2_ATL03.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 MPI_DEM_ICESat2_ATL03.py
-Written by Tyler Sutterley (12/2022)
+Written by Tyler Sutterley (03/2024)
 Determines which digital elevation model tiles to read for a given ATL03 file
 Reads 3x3 array of tiles for points within bounding box of central mosaic tile
 Interpolates digital elevation model to ICESat-2 ATL03 photon event locations
@@ -60,6 +60,7 @@
     https://nsidc.org/data/nsidc-0645/versions/1
 
 UPDATE HISTORY:
+    Updated 03/2024: use pathlib to define and operate on paths
     Updated 12/2022: single implicit import of altimetry tools
     Updated 11/2022: new ArcticDEM and REMA mosaic index shapefiles
         verify coordinate reference system attribute from shapefile

scripts/MPI_DEM_ICESat2_ATL06.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 MPI_DEM_ICESat2_ATL06.py
-Written by Tyler Sutterley (12/2022)
+Written by Tyler Sutterley (03/2024)
 Determines which digital elevation model tiles to read for a given ATL06 file
 Reads 3x3 array of tiles for points within bounding box of central mosaic tile
 Interpolates digital elevation model to locations of ICESat-2 ATL06 segments
@@ -60,6 +60,7 @@
     https://nsidc.org/data/nsidc-0645/versions/1
 
 UPDATE HISTORY:
+    Updated 03/2024: use pathlib to define and operate on paths
     Updated 12/2022: single implicit import of altimetry tools
     Updated 11/2022: new ArcticDEM and REMA mosaic index shapefiles
         verify coordinate reference system attribute from shapefile

scripts/MPI_DEM_ICESat2_ATL11.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 MPI_DEM_ICESat2_ATL11.py
-Written by Tyler Sutterley (12/2022)
+Written by Tyler Sutterley (03/2024)
 Determines which digital elevation model tiles to read for a given ATL11 file
 Reads 3x3 array of tiles for points within bounding box of central mosaic tile
 Interpolates digital elevation model to locations of ICESat-2 ATL11 segments
@@ -60,6 +60,7 @@
     https://nsidc.org/data/nsidc-0645/versions/1
 
 UPDATE HISTORY:
+    Updated 03/2024: use pathlib to define and operate on paths
     Updated 12/2022: single implicit import of altimetry tools
     Updated 11/2022: new ArcticDEM and REMA mosaic index shapefiles
         verify coordinate reference system attribute from shapefile

scripts/MPI_ICESat2_ATL03.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 u"""
-MPI_ICESat2_ATL03.py (12/2022)
+MPI_ICESat2_ATL03.py (03/2024)
 Read ICESat-2 ATL03 and ATL09 data files to calculate average segment surfaces
     ATL03 datasets: Global Geolocated Photons
     ATL09 datasets: Atmospheric Characteristics
@@ -42,6 +42,7 @@
     classify_photons.py: Yet Another Photon Classifier for Geolocated Photon Data
 
 UPDATE HISTORY:
+    Updated 03/2024: use pathlib to define and operate on paths
     Updated 12/2022: single implicit import of altimetry tools
     Updated 06/2022: update classify photons to match current GSFC version
     Updated 05/2022: use argparse descriptions within sphinx documentation

scripts/MPI_ICESat2_ATL03_histogram.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 u"""
-MPI_ICESat2_ATL03_histogram.py (12/2022)
+MPI_ICESat2_ATL03_histogram.py (03/2024)
 Read ICESat-2 ATL03 and ATL09 data files to calculate average segment surfaces
     ATL03 datasets: Global Geolocated Photons
     ATL09 datasets: Atmospheric Characteristics
@@ -75,6 +75,7 @@
         Geophysical Journal International (1997) 131, 267-280
 
 UPDATE HISTORY:
+    Updated 03/2024: use pathlib to define and operate on paths
     Updated 12/2022: single implicit import of altimetry tools
     Updated 06/2022: update classify photons to match current GSFC version
     Updated 05/2022: use argparse descriptions within sphinx documentation

scripts/MPI_reduce_ICESat2_ATL03_RGI.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 MPI_reduce_ICESat2_ATL03_RGI.py
-Written by Tyler Sutterley (12/2022)
+Written by Tyler Sutterley (03/2024)
 
 Create masks for reducing ICESat-2 data to the Randolph Glacier Inventory
     https://www.glims.org/RGI/rgi60_dl.html
@@ -57,6 +57,7 @@
     utilities.py: download and management utilities for syncing files
 
 UPDATE HISTORY:
+    Updated 03/2024: use pathlib to define and operate on paths
     Updated 12/2022: single implicit import of altimetry tools
     Updated 07/2022: place some imports behind try/except statements
     Updated 05/2022: use argparse descriptions within sphinx documentation

scripts/MPI_reduce_ICESat2_ATL06_RGI.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 MPI_reduce_ICESat2_ATL06_RGI.py
-Written by Tyler Sutterley (12/2022)
+Written by Tyler Sutterley (03/2024)
 
 Create masks for reducing ICESat-2 data to the Randolph Glacier Inventory
     https://www.glims.org/RGI/rgi60_dl.html
@@ -57,6 +57,7 @@
     utilities.py: download and management utilities for syncing files
 
 UPDATE HISTORY:
+    Updated 03/2024: use pathlib to define and operate on paths
     Updated 12/2022: single implicit import of altimetry tools
     Updated 07/2022: place some imports behind try/except statements
     Updated 05/2022: use argparse descriptions within sphinx documentation

scripts/MPI_reduce_ICESat2_ATL06_drainages.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 MPI_reduce_ICESat2_ATL06_drainages.py
-Written by Tyler Sutterley (12/2022)
+Written by Tyler Sutterley (03/2024)
 
 Create masks for reducing ICESat-2 data into IMBIE-2 drainage regions
 
@@ -38,6 +38,7 @@
     utilities.py: download and management utilities for syncing files
 
 UPDATE HISTORY:
+    Updated 03/2024: use pathlib to define and operate on paths
     Updated 12/2022: single implicit import of altimetry tools
     Updated 07/2022: place some imports behind try/except statements
     Updated 05/2022: use argparse descriptions within sphinx documentation

scripts/MPI_reduce_ICESat2_ATL06_grounded.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 MPI_reduce_ICESat2_ATL06_grounded.py
-Written by Tyler Sutterley (12/2022)
+Written by Tyler Sutterley (03/2024)
 
 Create masks for reducing ICESat-2 data into grounded ice regions
 
@@ -40,6 +40,7 @@
     utilities.py: download and management utilities for syncing files
 
 UPDATE HISTORY:
+    Updated 03/2024: use pathlib to define and operate on paths
     Updated 12/2022: single implicit import of altimetry tools
     Updated 07/2022: place some imports behind try/except statements
     Updated 05/2022: use argparse descriptions within sphinx documentation