Merge pull request #281 from nasa/feature/issue-82-expand-compatibili…

…ty-to-general-hdf-files

Feature/issue 82 expand compatibility to general hdf files

.gitattributes

@@ -0,0 +1,2 @@
+tests/data/icesat-2-ATL06/ATL06_20230816161508_08782002_006_02.h5 filter=lfs diff=lfs merge=lfs -text
+tests/data/icesat-2-ATL06/ATL06_20230816234629_08822013_006_01.h5 filter=lfs diff=lfs merge=lfs -text

.github/workflows/reusable_run_tests.yml

@@ -22,6 +22,8 @@ jobs:
     name: Python ${{ matrix.python-version }} tests
     steps:
       - uses: actions/checkout@v4
+        with:
+          lfs: 'true'
 
       - name: Set up Python
         uses: actions/setup-python@v5

CHANGELOG.md

@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - Code readability and CPU branching improvements [Time/Location stamp: Ursynow, Warsaw at 15:23 21/12/2024 UTC] ([#264](https://github.com/nasa/ncompare/pull/264)) ([**@kokroo**](https://github.com/kokroo))
 
+### Added
+- Enable comparison of HDF files ([#281](https://github.com/nasa/ncompare/pull/281)) ([**@danielfromearth**](https://github.com/danielfromearth))
+
 ## [1.12.0] - 2024-12-20
 
 ### Changed

README.md

@@ -32,8 +32,13 @@ _____
   <img src="https://joss.theoj.org/papers/10.21105/joss.06490/status.svg" alt="DOI badge" >
 </a>
 
-Compare the structure of two NetCDF files at the command line or via Python.
-`ncompare` generates a view of the matching and non-matching groups and variables between two NetCDF datasets.
+Compare the structure of two [netCDF](https://www.unidata.ucar.edu/software/netcdf) files 
+at the command line or via Python. `ncompare` generates a view of the matching and 
+non-matching groups and variables between two netCDF datasets.
+
+Allthough tailored for netCDF files, `ncompare`
+also works with some [HDF5](https://www.hdfgroup.org/solutions/hdf5/) files 
+(see [notes and known limitations](#notes-and-known-limitations)).
 
 
 ## Installing
@@ -75,13 +80,8 @@ ncompare S001G01.nc S001G01_SUBSET.nc --file-text subset_comparison.txt
 ```python
 from ncompare import compare
 
-total_number_of_differences = compare(
-    "<netcdf file 1>", 
-    "<netcdf file 2>", 
-    only_diffs=True,
-    show_attributes=True,
-    show_chunks=True,
-)
+total_number_of_differences = compare("<netcdf file 1>", "<netcdf file 2>", only_diffs=True,
+                                      show_chunks=True, show_attributes=True)
 ```
 
 
@@ -139,7 +139,7 @@ poetry run ncompare <netcdf file #1> <netcdf file #2>
 ## Why ncompare?
 
 The `cdo` (climate data operators) tool
-[does not support NetCDF4 groups](https://code.mpimet.mpg.de/boards/2/topics/12073).
+[does not support netCDF4 groups](https://code.mpimet.mpg.de/boards/2/topics/12073).
 Moreover, `nco` operators' `ncdiff` function computes value differences, but
 --- as far as the developers of this tool are aware ---
 `nco` does not have a simple function to show structural differences between NetCDF4 datasets.
@@ -150,8 +150,11 @@ and can generate report files formatted for other applications. However, note th
 `h5diff` provides comparison of some otherwise "hidden" hdf5 properties, such as _Netcdf4Dimid or _Netcdf4Coordinates,
 which are not currently assessed by `ncompare`.
 
-## Known limitations
+## Notes and known limitations
 
+- `ncompare` works successfully with select HDF5 files,
+  although it has not been tested extensively; therefore,
+  it would not be surprising to find additional limitations with other HDF files.
 - `ncompare` uses `xarray` to access the root-level dimensions.
 In some cases, `xarray` will miss dimensions whose names do not also exist as variable names in the dataset
   (also known as non-coordinate dimensions).

docs/example/ncompare-example-usage.ipynb

@@ -40,7 +40,7 @@
    "id": "6a145933-e57b-4e33-bed1-95b13800878d",
    "metadata": {},
    "source": [
-    "***✍️ Syntax Note:*** Commands preceeded by an exclamation point \"!\" \n",
+    "***✍️ Syntax Note:*** Commands are preceded by an exclamation point \"!\"\n",
     "(which is needed to [run shell commands in a Jupyter notebook](https://stackoverflow.com/a/48529220)) can be run from a terminal.  \n",
     "In a shell/terminal, the exclamation point should not be used."
    ]
@@ -785,8 +785,8 @@
     "    file_names[0],\n",
     "    file_names[2],\n",
     "    only_diffs=True,\n",
-    "    show_attributes=True,\n",
     "    show_chunks=True,\n",
+    "    show_attributes=True,\n",
     "    column_widths=[33, 30, 30],\n",
     ")"
    ]