feat: check if input filename is an open HDF5 file object (#89)

* feat: check if input filename is an open HDF5 file object

* refactor: use wrapper to importlib for optional dependencies

* Update environment.yml

doc/environment.yml

@@ -20,6 +20,7 @@ dependencies:
   - scp
   - sphinx
   - sphinx_rtd_theme
+  - timescale
   - pip:
     - sphinx-argparse>=0.4
     - ..

doc/source/api_reference/utilities.rst

@@ -19,6 +19,8 @@ General Methods
 
 .. autofunction:: icesat2_toolkit.utilities.get_data_path
 
+.. autofunction:: icesat2_toolkit.utilities.import_dependency
+
 .. autofunction:: icesat2_toolkit.utilities.get_hash
 
 .. autofunction:: icesat2_toolkit.utilities.get_git_revision_hash

icesat2_toolkit/convert.py

@@ -1,6 +1,6 @@
 """
 convert.py
-Written by Tyler Sutterley (03/2024)
+Written by Tyler Sutterley (05/2024)
 Utilities for converting ICESat-2 HDF5 files into different formats
 
 PYTHON DEPENDENCIES:
@@ -17,6 +17,7 @@
         https://pandas.pydata.org/
 
 UPDATE HISTORY:
+    Updated 05/2024: use wrapper to importlib for optional dependencies
     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
@@ -35,20 +36,12 @@
 import itertools
 import posixpath
 import numpy as np
+from icesat2_toolkit.utilities import import_dependency
 
 # attempt imports
-try:
-    import h5py
-except ModuleNotFoundError:
-    warnings.warn("h5py not available", ImportWarning)
-try:
-    import pandas
-except ModuleNotFoundError:
-    warnings.warn("pandas not available", ImportWarning)
-try:
-    import zarr
-except ModuleNotFoundError:
-    warnings.warn("zarr not available", ImportWarning)
+h5py = import_dependency('h5py')
+pandas = import_dependency('pandas')
+zarr = import_dependency('zarr')
 
 class convert():
     np.seterr(invalid='ignore')

icesat2_toolkit/convert_delta_time.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 u"""
-convert_delta_time.py (04/2022)
+convert_delta_time.py (04/2024)
 Converts time from delta seconds into Julian and year-decimal
 
 INPUTS:
@@ -21,6 +21,7 @@
         https://pypi.org/project/timescale/
 
 UPDATE HISTORY:
+    Updated 04/2024: use timescale for temporal operations
     Updated 04/2022: updated docstrings to numpy documentation format
     Updated 01/2021: time utilities for converting times from JD and to decimal
     Updated 08/2020: time utilities for counting leap seconds and JD conversion

icesat2_toolkit/fit.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 fit.py
-Written by Tyler Sutterley (12/2021)
+Written by Tyler Sutterley (05/2024)
 Utilities for calculating average fits from ATL03 Geolocated Photon Data
 
 PYTHON DEPENDENCIES:
@@ -15,6 +15,7 @@
         https://github.com/scikit-learn/scikit-learn
 
 UPDATE HISTORY:
+    Updated 05/2024: use wrapper to importlib for optional dependencies
     Updated 12/2022: place some imports behind try/except statements
     Updated 04/2022: updated docstrings to numpy documentation format
     Written 05/2021
@@ -26,12 +27,10 @@
 import scipy.stats
 import scipy.signal
 import scipy.optimize
+from icesat2_toolkit.utilities import import_dependency
 
 # attempt imports
-try:
-    import sklearn.neighbors
-except (AttributeError, ImportError, ModuleNotFoundError) as exc:
-    warnings.warn("scikit-learn not available", ImportWarning)
+neighbors = import_dependency('sklearn.neighbors')
 
 # PURPOSE: compress complete list of valid indices into a set of ranges
 def compress_list(i,n):
@@ -527,7 +526,7 @@ def reduce_histogram_fit(x, y, z, ind, dt, FIT_TYPE='gaussian',
     # using kernel density functions from scikit-learn neighbors
     # gaussian kernels will reflect more accurate distributions of the data
     # with less sensitivity to sampling width than histograms (tophat kernels)
-    kde = sklearn.neighbors.KernelDensity(bandwidth=dz,kernel='gaussian')
+    kde = neighbors.KernelDensity(bandwidth=dz, kernel='gaussian')
     kde.fit(z[:,None])
     # kde score_samples outputs are normalized log density functions
     hist = np.exp(kde.score_samples(z_full[:,None]) + np.log(n_max*dz))
@@ -655,7 +654,7 @@ def reduce_histogram_fit(x, y, z, ind, dt, FIT_TYPE='gaussian',
             # using kernel density functions from scikit-learn neighbors
             # gaussian kernels will reflect more accurate distributions of the data
             # with less sensitivity to sampling width than histograms (tophat kernels)
-            kde = sklearn.neighbors.KernelDensity(bandwidth=dz,kernel='gaussian')
+            kde = neighbors.KernelDensity(bandwidth=dz,kernel='gaussian')
             kde.fit(z_filt[:,None])
             # kde score_samples outputs are normalized log density functions
             hist = np.exp(kde.score_samples(z_full[:,None]) + np.log(nz*dz))
@@ -990,7 +989,7 @@ def calc_first_photon_bias(temporal_residuals,n_pulses,n_pixels,dead_time,dt,
     # using kernel density functions from scikit-learn neighbors
     # gaussian kernels will reflect more accurate distributions of the data
     # with less sensitivity to sampling width than histograms (tophat kernels)
-    kde = sklearn.neighbors.KernelDensity(bandwidth=dt,kernel='gaussian')
+    kde = neighbors.KernelDensity(bandwidth=dt,kernel='gaussian')
     kde.fit(temporal_residuals[:,None])
     # kde score_samples outputs are normalized log density functions
     hist = np.exp(kde.score_samples(t_full[:,None]) + np.log(cnt*dt))

icesat2_toolkit/io/ATL03.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 u"""
-ATL03.py (03/2024)
+ATL03.py (05/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,8 @@
         https://www.h5py.org/
 
 UPDATE HISTORY:
+    Updated 05/2024: use wrapper to importlib for optional dependencies
+        check if input filename is an open HDF5 file object
     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
@@ -41,12 +43,10 @@
 import warnings
 import numpy as np
 import scipy.interpolate
+from icesat2_toolkit.utilities import import_dependency
 
 # attempt imports
-try:
-    import h5py
-except ModuleNotFoundError:
-    warnings.warn("h5py not available", ImportWarning)
+h5py = import_dependency('h5py')
 
 # PURPOSE: read ICESat-2 ATL03 HDF5 data files
 def read_granule(FILENAME, ATTRIBUTES=False, **kwargs):
@@ -72,6 +72,8 @@ def read_granule(FILENAME, ATTRIBUTES=False, **kwargs):
     # Open the HDF5 file for reading
     if isinstance(FILENAME, io.IOBase):
         fileID = h5py.File(FILENAME, 'r')
+    elif isinstance(FILENAME, h5py.File):
+        fileID = FILENAME
     else:
         FILENAME = pathlib.Path(FILENAME).expanduser().absolute()
         fileID = h5py.File(FILENAME, 'r')
@@ -299,6 +301,8 @@ def interpolate_ATL09(FILENAME, pfl, dtime, ATTRIBUTES=True, **kwargs):
     # Open the HDF5 file for reading
     if isinstance(FILENAME, io.IOBase):
         fileID = h5py.File(FILENAME, 'r')
+    elif isinstance(FILENAME, h5py.File):
+        fileID = FILENAME
     else:
         FILENAME = pathlib.Path(FILENAME).expanduser().absolute()
         fileID = h5py.File(FILENAME, 'r')
@@ -368,6 +372,8 @@ def find_beams(FILENAME, **kwargs):
     # Open the HDF5 file for reading
     if isinstance(FILENAME, io.IOBase):
         fileID = h5py.File(FILENAME, 'r')
+    elif isinstance(FILENAME, h5py.File):
+        fileID = FILENAME
     else:
         FILENAME = pathlib.Path(FILENAME).expanduser().absolute()
         fileID = h5py.File(FILENAME, 'r')
@@ -414,6 +420,8 @@ def read_main(FILENAME, ATTRIBUTES=False, **kwargs):
     # Open the HDF5 file for reading
     if isinstance(FILENAME, io.IOBase):
         fileID = h5py.File(FILENAME, 'r')
+    elif isinstance(FILENAME, h5py.File):
+        fileID = FILENAME
     else:
         FILENAME = pathlib.Path(FILENAME).expanduser().absolute()
         fileID = h5py.File(FILENAME, 'r')
@@ -586,6 +594,8 @@ def read_beam(FILENAME, gtx, ATTRIBUTES=False, **kwargs):
     # Open the HDF5 file for reading
     if isinstance(FILENAME, io.IOBase):
         fileID = h5py.File(FILENAME, 'r')
+    elif isinstance(FILENAME, h5py.File):
+        fileID = FILENAME
     else:
         FILENAME = pathlib.Path(FILENAME).expanduser().absolute()
         fileID = h5py.File(FILENAME, 'r')

icesat2_toolkit/io/ATL06.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 u"""
-ATL06.py (03/2024)
+ATL06.py (05/2024)
 Read ICESat-2 ATL06 (Land Ice Along-Track Height Product) data files
 
 OPTIONS:
@@ -16,6 +16,8 @@
         https://www.h5py.org/
 
 UPDATE HISTORY:
+    Updated 05/2024: use wrapper to importlib for optional dependencies
+        check if input filename is an open HDF5 file object
     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
@@ -39,12 +41,10 @@
 import pathlib
 import warnings
 import numpy as np
+from icesat2_toolkit.utilities import import_dependency
 
 # attempt imports
-try:
-    import h5py
-except ModuleNotFoundError:
-    warnings.warn("h5py not available", ImportWarning)
+h5py = import_dependency('h5py')
 
 # PURPOSE: read ICESat-2 ATL06 HDF5 data files
 def read_granule(FILENAME, ATTRIBUTES=False, HISTOGRAM=False,
@@ -75,6 +75,8 @@ def read_granule(FILENAME, ATTRIBUTES=False, HISTOGRAM=False,
     # Open the HDF5 file for reading
     if isinstance(FILENAME, io.IOBase):
         fileID = h5py.File(FILENAME, 'r')
+    elif isinstance(FILENAME, h5py.File):
+        fileID = FILENAME
     else:
         FILENAME = pathlib.Path(FILENAME).expanduser().absolute()
         fileID = h5py.File(FILENAME, 'r')
@@ -287,6 +289,8 @@ def find_beams(FILENAME, **kwargs):
     # Open the HDF5 file for reading
     if isinstance(FILENAME, io.IOBase):
         fileID = h5py.File(FILENAME, 'r')
+    elif isinstance(FILENAME, h5py.File):
+        fileID = FILENAME
     else:
         FILENAME = pathlib.Path(FILENAME).expanduser().absolute()
         fileID = h5py.File(FILENAME, 'r')
@@ -342,6 +346,8 @@ def read_beam(FILENAME, gtx, ATTRIBUTES=False, **kwargs):
     # Open the HDF5 file for reading
     if isinstance(FILENAME, io.IOBase):
         fileID = h5py.File(FILENAME, 'r')
+    elif isinstance(FILENAME, h5py.File):
+        fileID = FILENAME
     else:
         FILENAME = pathlib.Path(FILENAME).expanduser().absolute()
         fileID = h5py.File(FILENAME, 'r')

icesat2_toolkit/io/ATL07.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 u"""
-ATL07.py (03/2024)
+ATL07.py (05/2024)
 Read ICESat-2 ATL07 (Sea Ice Height) data files
 
 PYTHON DEPENDENCIES:
@@ -11,6 +11,8 @@
         https://www.h5py.org/
 
 UPDATE HISTORY:
+    Updated 05/2024: use wrapper to importlib for optional dependencies
+        check if input filename is an open HDF5 file object
     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
@@ -32,12 +34,10 @@
 import pathlib
 import warnings
 import numpy as np
+from icesat2_toolkit.utilities import import_dependency
 
 # attempt imports
-try:
-    import h5py
-except ModuleNotFoundError:
-    warnings.warn("h5py not available", ImportWarning)
+h5py = import_dependency('h5py')
 
 # PURPOSE: read ICESat-2 ATL07 HDF5 data files
 def read_granule(FILENAME, ATTRIBUTES=False, **kwargs):
@@ -63,6 +63,8 @@ def read_granule(FILENAME, ATTRIBUTES=False, **kwargs):
     # Open the HDF5 file for reading
     if isinstance(FILENAME, io.IOBase):
         fileID = h5py.File(FILENAME, 'r')
+    elif isinstance(FILENAME, h5py.File):
+        fileID = FILENAME
     else:
         FILENAME = pathlib.Path(FILENAME).expanduser().absolute()
         fileID = h5py.File(FILENAME, 'r')
@@ -230,6 +232,8 @@ def find_beams(FILENAME, **kwargs):
     # Open the HDF5 file for reading
     if isinstance(FILENAME, io.IOBase):
         fileID = h5py.File(FILENAME, 'r')
+    elif isinstance(FILENAME, h5py.File):
+        fileID = FILENAME
     else:
         FILENAME = pathlib.Path(FILENAME).expanduser().absolute()
         fileID = h5py.File(FILENAME, 'r')
@@ -280,6 +284,8 @@ def read_beam(FILENAME, gtx, ATTRIBUTES=False, **kwargs):
     # Open the HDF5 file for reading
     if isinstance(FILENAME, io.IOBase):
         fileID = h5py.File(FILENAME, 'r')
+    elif isinstance(FILENAME, h5py.File):
+        fileID = FILENAME
     else:
         FILENAME = pathlib.Path(FILENAME).expanduser().absolute()
         fileID = h5py.File(FILENAME, 'r')

icesat2_toolkit/io/ATL10.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 u"""
-ATL10.py (03/2024)
+ATL10.py (05/2024)
 Read ICESat-2 ATL10 (Sea Ice Freeboard) data files
 
 PYTHON DEPENDENCIES:
@@ -11,6 +11,8 @@
         https://www.h5py.org/
 
 UPDATE HISTORY:
+    Updated 05/2024: use wrapper to importlib for optional dependencies
+        check if input filename is an open HDF5 file object
     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
@@ -27,12 +29,10 @@
 import pathlib
 import warnings
 import numpy as np
+from icesat2_toolkit.utilities import import_dependency
 
 # attempt imports
-try:
-    import h5py
-except ModuleNotFoundError:
-    warnings.warn("h5py not available", ImportWarning)
+h5py = import_dependency('h5py')
 
 # PURPOSE: read ICESat-2 ATL10 HDF5 data files
 def read_granule(FILENAME, ATTRIBUTES=False, **kwargs):
@@ -58,6 +58,8 @@ def read_granule(FILENAME, ATTRIBUTES=False, **kwargs):
     # Open the HDF5 file for reading
     if isinstance(FILENAME, io.IOBase):
         fileID = h5py.File(FILENAME, 'r')
+    elif isinstance(FILENAME, h5py.File):
+        fileID = FILENAME
     else:
         FILENAME = pathlib.Path(FILENAME).expanduser().absolute()
         fileID = h5py.File(FILENAME, 'r')
@@ -228,6 +230,8 @@ def find_beams(FILENAME, **kwargs):
     # Open the HDF5 file for reading
     if isinstance(FILENAME, io.IOBase):
         fileID = h5py.File(FILENAME, 'r')
+    elif isinstance(FILENAME, h5py.File):
+        fileID = FILENAME
     else:
         FILENAME = pathlib.Path(FILENAME).expanduser().absolute()
         fileID = h5py.File(FILENAME, 'r')
@@ -279,6 +283,8 @@ def read_beam(FILENAME, gtx, ATTRIBUTES=False, **kwargs):
     # Open the HDF5 file for reading
     if isinstance(FILENAME, io.IOBase):
         fileID = h5py.File(FILENAME, 'r')
+    elif isinstance(FILENAME, h5py.File):
+        fileID = FILENAME
     else:
         FILENAME = pathlib.Path(FILENAME).expanduser().absolute()
         fileID = h5py.File(FILENAME, 'r')