feat: add option to keep file object open (#90)

Author: tsutterley

icesat2_toolkit/io/ATL03.py

@@ -49,7 +49,7 @@
 h5py = import_dependency('h5py')
 
 # PURPOSE: read ICESat-2 ATL03 HDF5 data files
-def read_granule(FILENAME, ATTRIBUTES=False, **kwargs):
+def read_granule(FILENAME, ATTRIBUTES=False, KEEP=False, **kwargs):
     """
     Reads ICESat-2 ATL03 Global Geolocated Photons data files
 
@@ -59,6 +59,8 @@ def read_granule(FILENAME, ATTRIBUTES=False, **kwargs):
         full path to ATL03 file
     ATTRIBUTES: bool, default False
         read file, group and variable attributes
+    KEEP: bool, default False
+        keep file object open
 
     Returns
     -------
@@ -270,12 +272,14 @@ def read_granule(FILENAME, ATTRIBUTES=False, **kwargs):
                 IS2_atl03_attrs[att_name] = att_val
 
     # Closing the HDF5 file
-    fileID.close()
+    if not KEEP:
+        fileID.close()
     # Return the datasets and variables
     return (IS2_atl03_mds, IS2_atl03_attrs, IS2_atl03_beams)
 
 # PURPOSE: read ICESat-2 ATL09 HDF5 data file for specific variables
-def interpolate_ATL09(FILENAME, pfl, dtime, ATTRIBUTES=True, **kwargs):
+def interpolate_ATL09(FILENAME, pfl, dtime,
+    ATTRIBUTES=True, KEEP=False, **kwargs):
     """
     Reads ICESat-2 ATL09 Atmospheric Characteristics data files
     and interpolates a subset of variables to ATL03 segment lengths
@@ -288,8 +292,10 @@ def interpolate_ATL09(FILENAME, pfl, dtime, ATTRIBUTES=True, **kwargs):
         profile for a given beam
     dtime: float
         ATL03 reference photon delta_time
-    ATTRIBUTES: bool, default False
+    ATTRIBUTES: bool, default True
         read file, group and variable attributes
+    KEEP: bool, default False
+        keep file object open
 
     Returns
     -------
@@ -349,12 +355,13 @@ def interpolate_ATL09(FILENAME, pfl, dtime, ATTRIBUTES=True, **kwargs):
                 IS2_atl09_attrs[att_name] = att_val
 
     # Closing the HDF5 file
-    fileID.close()
+    if not KEEP:
+        fileID.close()
     # Return the datasets and variables
     return (IS2_atl09_mds, IS2_atl09_attrs)
 
 # PURPOSE: find valid beam groups within ICESat-2 ATL03 HDF5 data files
-def find_beams(FILENAME, **kwargs):
+def find_beams(FILENAME, KEEP=False ,**kwargs):
     """
     Find valid beam groups within ICESat-2 ATL03 Global Geolocated Photons
     data files
@@ -363,6 +370,8 @@ def find_beams(FILENAME, **kwargs):
     ----------
     FILENAME: str
         full path to ATL03 file
+    KEEP: bool, default False
+        keep file object open
 
     Returns
     -------
@@ -391,12 +400,13 @@ def find_beams(FILENAME, **kwargs):
         else:
             IS2_atl03_beams.append(gtx)
     # Closing the HDF5 file
-    fileID.close()
+    if not KEEP:
+        fileID.close()
     # return the list of beams
     return IS2_atl03_beams
 
 # PURPOSE: read ICESat-2 ATL03 HDF5 data files for main level variables
-def read_main(FILENAME, ATTRIBUTES=False, **kwargs):
+def read_main(FILENAME, ATTRIBUTES=False, KEEP=False, **kwargs):
     """
     Reads ICESat-2 ATL03 Global Geolocated Photons data files
     for only the main-level variables and not the beam-level data
@@ -407,6 +417,8 @@ def read_main(FILENAME, ATTRIBUTES=False, **kwargs):
         full path to ATL03 file
     ATTRIBUTES: bool, default False
         read file, group and variable attributes
+    KEEP: bool, default False
+        keep file object open
 
     Returns
     -------
@@ -558,12 +570,13 @@ def read_main(FILENAME, ATTRIBUTES=False, **kwargs):
                 IS2_atl03_attrs[att_name] = att_val
 
     # Closing the HDF5 file
-    fileID.close()
+    if not KEEP:
+        fileID.close()
     # Return the datasets and variables
     return (IS2_atl03_mds, IS2_atl03_attrs, IS2_atl03_beams)
 
 # PURPOSE: read ICESat-2 ATL03 HDF5 data files for beam variables
-def read_beam(FILENAME, gtx, ATTRIBUTES=False, **kwargs):
+def read_beam(FILENAME, gtx, ATTRIBUTES=False, KEEP=False, **kwargs):
     """
     Reads ICESat-2 ATL03 Global Geolocated Photons data files
     for a specific beam
@@ -583,6 +596,8 @@ def read_beam(FILENAME, gtx, ATTRIBUTES=False, **kwargs):
             - ``'gt3r'``
     ATTRIBUTES: bool, default False
         read file, group and variable attributes
+    KEEP: bool, default False
+        keep file object open
 
     Returns
     -------
@@ -666,6 +681,7 @@ def read_beam(FILENAME, gtx, ATTRIBUTES=False, **kwargs):
                     IS2_atl03_attrs['geophys_corr'][key][att_name]=att_val
 
     # Closing the HDF5 file
-    fileID.close()
+    if not KEEP:
+        fileID.close()
     # Return the datasets and variables
     return (IS2_atl03_mds, IS2_atl03_attrs)

icesat2_toolkit/io/ATL06.py

@@ -48,7 +48,7 @@
 
 # PURPOSE: read ICESat-2 ATL06 HDF5 data files
 def read_granule(FILENAME, ATTRIBUTES=False, HISTOGRAM=False,
-    QUALITY=False, **kwargs):
+    QUALITY=False, KEEP=False, **kwargs):
     """
     Reads ICESat-2 ATL06 (Land Ice Along-Track Height Product) data files
 
@@ -62,6 +62,8 @@ def read_granule(FILENAME, ATTRIBUTES=False, HISTOGRAM=False,
         read ATL06 residual_histogram variables
     QUALITY: bool, default False
         read ATL06 segment_quality variables
+    KEEP: bool, default False
+        keep file object open
 
     Returns
     -------
@@ -266,12 +268,13 @@ def read_granule(FILENAME, ATTRIBUTES=False, HISTOGRAM=False,
                             IS2_atl06_attrs['quality_assessment'][key][k][att_name]= att_val
 
     # Closing the HDF5 file
-    fileID.close()
+    if not KEEP:
+        fileID.close()
     # Return the datasets and variables
     return (IS2_atl06_mds, IS2_atl06_attrs, IS2_atl06_beams)
 
 # PURPOSE: find valid beam groups within ICESat-2 ATL06 HDF5 data files
-def find_beams(FILENAME, **kwargs):
+def find_beams(FILENAME, KEEP=False, **kwargs):
     """
     Find valid beam groups within ICESat-2 ATL06 (Land Ice Along-Track
     Height Product) data files
@@ -280,6 +283,8 @@ def find_beams(FILENAME, **kwargs):
     ----------
     FILENAME: str
         full path to ATL06 file
+    KEEP: bool, default False
+        keep file object open
 
     Returns
     -------
@@ -306,12 +311,13 @@ def find_beams(FILENAME, **kwargs):
         else:
                 IS2_atl06_beams.append(gtx)
     # Closing the HDF5 file
-    fileID.close()
+    if not KEEP:
+        fileID.close()
     # return the list of beams
     return IS2_atl06_beams
 
 # PURPOSE: read ICESat-2 ATL06 HDF5 data files for beam variables
-def read_beam(FILENAME, gtx, ATTRIBUTES=False, **kwargs):
+def read_beam(FILENAME, gtx, ATTRIBUTES=False, KEEP=False, **kwargs):
     """
     Reads ICESat-2 ATL06 (Land Ice Along-Track Height Product) data files
     for a specific beam
@@ -335,6 +341,8 @@ def read_beam(FILENAME, gtx, ATTRIBUTES=False, **kwargs):
         read ATL06 residual_histogram variables
     QUALITY: bool, default False
         read ATL06 segment_quality variables
+    KEEP: bool, default False
+        keep file object open
 
     Returns
     -------
@@ -404,6 +412,7 @@ def read_beam(FILENAME, gtx, ATTRIBUTES=False, **kwargs):
                             IS2_atl06_attrs[gtx]['land_ice_segments'][key][k][att_name] = att_val
 
     # Closing the HDF5 file
-    fileID.close()
+    if not KEEP:
+        fileID.close()
     # Return the datasets and variables
     return (IS2_atl06_mds, IS2_atl06_attrs)

icesat2_toolkit/io/ATL07.py

@@ -40,7 +40,7 @@
 h5py = import_dependency('h5py')
 
 # PURPOSE: read ICESat-2 ATL07 HDF5 data files
-def read_granule(FILENAME, ATTRIBUTES=False, **kwargs):
+def read_granule(FILENAME, ATTRIBUTES=False, KEEP=False, **kwargs):
     """
     Reads ICESat-2 ATL07 (Sea Ice Height) data files
 
@@ -50,6 +50,8 @@ def read_granule(FILENAME, ATTRIBUTES=False, **kwargs):
         full path to ATL07 file
     ATTRIBUTES: bool, default False
         read HDF5 attributes for groups and variables
+    KEEP: bool, default False
+        keep file object open
 
     Returns
     -------
@@ -210,19 +212,22 @@ def read_granule(FILENAME, ATTRIBUTES=False, **kwargs):
                             IS2_atl07_attrs['quality_assessment'][key][k][att_name]= att_val
 
     # Closing the HDF5 file
-    fileID.close()
+    if not KEEP:
+        fileID.close()
     # Return the datasets and variables
     return (IS2_atl07_mds, IS2_atl07_attrs, IS2_atl07_beams)
 
 # PURPOSE: find valid beam groups within ICESat-2 ATL07 HDF5 data files
-def find_beams(FILENAME, **kwargs):
+def find_beams(FILENAME, KEEP=False, **kwargs):
     """
     Find valid beam groups within ICESat-2 ATL07 (Sea Ice Height) data files
 
     Parameters
     ----------
     FILENAME: str
         full path to ATL07 file
+    KEEP: bool, default False
+        keep file object open
 
     Returns
     -------
@@ -249,12 +254,13 @@ def find_beams(FILENAME, **kwargs):
         else:
             IS2_atl07_beams.append(gtx)
     # Closing the HDF5 file
-    fileID.close()
+    if not KEEP:
+        fileID.close()
     # return the list of beams
     return IS2_atl07_beams
 
 # PURPOSE: read ICESat-2 ATL07 HDF5 data files for beam variables
-def read_beam(FILENAME, gtx, ATTRIBUTES=False, **kwargs):
+def read_beam(FILENAME, gtx, ATTRIBUTES=False, KEEP=False, **kwargs):
     """
     Reads ICESat-2 ATL07 (Sea Ice Height) data files for a specific beam
 
@@ -273,6 +279,8 @@ def read_beam(FILENAME, gtx, ATTRIBUTES=False, **kwargs):
             - ``'gt3r'``
     ATTRIBUTES: bool, default False
         read HDF5 attributes for groups and variables
+    KEEP: bool, default False
+        keep file object open
 
     Returns
     -------
@@ -340,6 +348,7 @@ def read_beam(FILENAME, gtx, ATTRIBUTES=False, **kwargs):
                             IS2_atl07_attrs[gtx]['sea_ice_segments'][key][k][att_name] = att_val
 
     # Closing the HDF5 file
-    fileID.close()
+    if not KEEP:
+        fileID.close()
     # Return the datasets and variables
     return (IS2_atl07_mds, IS2_atl07_attrs)

icesat2_toolkit/io/ATL10.py

@@ -35,7 +35,7 @@
 h5py = import_dependency('h5py')
 
 # PURPOSE: read ICESat-2 ATL10 HDF5 data files
-def read_granule(FILENAME, ATTRIBUTES=False, **kwargs):
+def read_granule(FILENAME, ATTRIBUTES=False, KEEP=False, **kwargs):
     """
     Reads ICESat-2 ATL10 (Sea Ice Freeboard) data files
 
@@ -45,6 +45,8 @@ def read_granule(FILENAME, ATTRIBUTES=False, **kwargs):
         full path to ATL10 file
     ATTRIBUTES: bool, default False
         read HDF5 attributes for groups and variables
+    KEEP: bool, default False
+        keep file object open
 
     Returns
     -------
@@ -208,19 +210,22 @@ def read_granule(FILENAME, ATTRIBUTES=False, **kwargs):
                             IS2_atl10_attrs['quality_assessment'][key][k][att_name]= att_val
 
     # Closing the HDF5 file
-    fileID.close()
+    if not KEEP:
+        fileID.close()
     # Return the datasets and variables
     return (IS2_atl10_mds, IS2_atl10_attrs, IS2_atl10_beams)
 
 # PURPOSE: find valid beam groups within ICESat-2 ATL10 HDF5 data files
-def find_beams(FILENAME, **kwargs):
+def find_beams(FILENAME, KEEP=False, **kwargs):
     """
     Find valid beam groups within ICESat-2 ATL10 (Sea Ice Freeboard) data files
 
     Parameters
     ----------
     FILENAME: str
         full path to ATL10 file
+    KEEP: bool, default False
+        keep file object open
 
     Returns
     -------
@@ -248,12 +253,13 @@ def find_beams(FILENAME, **kwargs):
         else:
             IS2_atl10_beams.append(gtx)
     # Closing the HDF5 file
-    fileID.close()
+    if not KEEP:
+        fileID.close()
     # return the list of beams
     return IS2_atl10_beams
 
 # PURPOSE: read ICESat-2 ATL10 HDF5 data files for beam variables
-def read_beam(FILENAME, gtx, ATTRIBUTES=False, **kwargs):
+def read_beam(FILENAME, gtx, ATTRIBUTES=False, KEEP=False, **kwargs):
     """
     Reads ICESat-2 ATL10 (Sea Ice Freeboard) data files for a specific beam
 
@@ -272,6 +278,8 @@ def read_beam(FILENAME, gtx, ATTRIBUTES=False, **kwargs):
             - ``'gt3r'``
     ATTRIBUTES: bool, default False
         read HDF5 attributes for groups and variables
+    KEEP: bool, default False
+        keep file object open
 
     Returns
     -------
@@ -341,6 +349,7 @@ def read_beam(FILENAME, gtx, ATTRIBUTES=False, **kwargs):
                                 IS2_atl10_attrs[gtx][group][key][k][att_name] = att_val
 
     # Closing the HDF5 file
-    fileID.close()
+    if not KEEP:
+        fileID.close()
     # Return the datasets and variables
     return (IS2_atl10_mds, IS2_atl10_attrs)