Add best practices documentation and check for NWB file extension (#625)

* add file extension check

* add test for file extension check

* expose check to API and add docs

* update CHANGELOG

* update file documentation, changelog

* Update src/nwbinspector/checks/_nwbfile_metadata.py

Co-authored-by: Ryan Ly <[email protected]>

* Update src/nwbinspector/checks/_nwbfile_metadata.py

Co-authored-by: Ryan Ly <[email protected]>

* check file extension ends with valid extension

* Update src/nwbinspector/checks/_nwbfile_metadata.py

Co-authored-by: Ryan Ly <[email protected]>

---------

Co-authored-by: Ryan Ly <[email protected]>

Author: stephprince

CHANGELOG.md

@@ -1,5 +1,8 @@
 # v0.6.6 (Upcoming)
 
+### New Checks
+* Added `check_file_extension` for NWB file extension best practice recommendations (`.nwb`, `.nwb.h5`, or `.nwb.zarr`) [#625](https://github.com/NeurodataWithoutBorders/nwbinspector/pull/625)
+
 ### Improvements
 * Added documentation to API and CLI docs on how to use the dandi config option. [#624](https://github.com/NeurodataWithoutBorders/nwbinspector/pull/624)
 

docs/best_practices/nwbfile_metadata.rst

@@ -4,6 +4,21 @@ NWBFile Metadata
 An :ref:`nwb-schema:sec-NWBFile` object generally contains data from a single experimental session.
 
 
+.. _best_practice_file_extension:
+
+File Extensions
+---------------
+
+NWB file paths should contain `.nwb` in their file extension to indicate that they are NWB files.
+To further help tools and users quickly identify the underlying backend type, an additional option is to attach the backend as a second suffix.
+Recommended file extensions are:
+
+1. ``.nwb`` (minimum recommendation)
+2. ``.nwb.h5`` (also acceptable for NWB HDF5 files)
+3. ``.nwb.zarr`` (also acceptable for NWB Zarr stores)
+
+Check function: :py:meth:`~nwbinspector.checks._nwbfile_metadata.check_file_extension`
+
 
 File Organization
 -----------------

src/nwbinspector/checks/__init__.py

@@ -39,6 +39,7 @@
     check_experiment_description,
     check_experimenter_exists,
     check_experimenter_form,
+    check_file_extension,
     check_institution,
     check_keywords,
     check_processing_module_name,
@@ -120,6 +121,7 @@
     "check_subject_species_exists",
     "check_subject_species_form",
     "check_subject_proper_age_range",
+    "check_file_extension",
     "check_session_id_no_slashes",
     "check_session_start_time_future_date",
     "check_processing_module_name",

src/nwbinspector/checks/_nwbfile_metadata.py

@@ -2,13 +2,16 @@
 
 import re
 from datetime import datetime
+from pathlib import Path
 from typing import Iterable, Optional
 
+from hdmf_zarr import NWBZarrIO
 from isodate import Duration, parse_duration
-from pynwb import NWBFile, ProcessingModule
+from pynwb import NWBHDF5IO, NWBFile, ProcessingModule
 from pynwb.file import Subject
 
 from .._registration import Importance, InspectorMessage, register_check
+from ..tools import get_nwbfile_path_from_internal_object
 from ..utils import is_module_installed
 
 duration_regex = (
@@ -352,3 +355,48 @@ def check_subject_id_no_slashes(subject: Subject) -> Optional[InspectorMessage]:
         )
 
     return None
+
+
+@register_check(importance=Importance.BEST_PRACTICE_SUGGESTION, neurodata_type=NWBFile)
+def check_file_extension(nwbfile: NWBFile) -> Optional[InspectorMessage]:
+    """
+    Check if the file extension contains ".nwb".
+    If a backend storage type is specified, check that it matches the backend storage type.
+
+    NWB files should use appropriate extensions based on their backend:
+    - .nwb (minimum recommendation), .nwb.h5 (HDF5), or .nwb.zarr (Zarr)
+
+    Best Practice: :ref:`best_practice_file_extension`
+    """
+    file_path = get_nwbfile_path_from_internal_object(nwbfile)
+
+    # Only perform the check if we can determine the file path
+    if file_path is not None:
+        file_extension = "".join(Path(file_path).suffixes)  # Concatenate all suffixes for multi-part extensions
+        all_valid_extensions = [".nwb", ".nwb.h5", ".nwb.zarr"]
+
+        read_io = nwbfile.get_read_io()
+        if isinstance(read_io, NWBHDF5IO):
+            valid_extensions = [".nwb", ".nwb.h5"]
+            backend = "HDF5"
+        elif isinstance(read_io, NWBZarrIO):
+            valid_extensions = [".nwb", ".nwb.zarr"]
+            backend = "Zarr"
+        else:
+            valid_extensions = all_valid_extensions
+            backend = ""
+
+        # check the extension ends with .nwb or .nwb.h5/.nwb.zarr
+        msg = (
+            f"The file extension '{file_extension}' does not follow the recommended naming convention. "
+            f"{backend} NWB files should use one of the following file name extensions: {', '.join(valid_extensions)}."
+        )
+        if not any(file_extension.endswith(pattern) for pattern in valid_extensions):
+            return InspectorMessage(message=msg)
+
+        # check the extension matches the backend storage type
+        invalid_extensions = set(all_valid_extensions) - set(valid_extensions)
+        if any(file_extension.endswith(pattern) for pattern in invalid_extensions):
+            return InspectorMessage(message=msg)
+
+    return None

tests/unit_tests/test_nwbfile_metadata.py

@@ -1,7 +1,9 @@
+import tempfile
 from datetime import datetime, timezone
 from uuid import uuid4
 
-from pynwb import NWBFile, ProcessingModule
+from hdmf_zarr import NWBZarrIO
+from pynwb import NWBHDF5IO, NWBFile, ProcessingModule
 from pynwb.file import Subject
 
 from nwbinspector import Importance, InspectorMessage
@@ -10,6 +12,7 @@
     check_experiment_description,
     check_experimenter_exists,
     check_experimenter_form,
+    check_file_extension,
     check_institution,
     check_keywords,
     check_processing_module_name,
@@ -619,3 +622,43 @@ def test_check_subject_id_with_slashes():
         object_name="subject",
         location="/general/subject",
     )
+
+
+def test_check_file_extension_pass():
+    """Test that valid HDF5 extensions pass the check."""
+    extension_dict = {".nwb": NWBHDF5IO, ".nwb.h5": NWBHDF5IO, ".nwb.zarr": NWBZarrIO}
+
+    for ext, io_class in extension_dict.items():
+        if isinstance(io_class, NWBZarrIO):
+            tmp_path = tempfile.TemporaryDirectory(suffix=ext).name
+        else:
+            tmp_path = tempfile.NamedTemporaryFile(suffix=ext).name
+
+        nwbfile = make_minimal_nwbfile()
+        with io_class(str(tmp_path), mode="w") as io:
+            io.write(nwbfile)
+
+        with io_class(str(tmp_path), mode="r") as io:
+            read_nwbfile = io.read()
+            assert check_file_extension(read_nwbfile) is None
+
+
+def test_check_file_extension_fail():
+    """Test that invalid HDF5 extensions fail the check."""
+    invalid_extension_dict = {".txt": NWBHDF5IO, ".nwb.zarr": NWBHDF5IO, ".nwb.h5": NWBZarrIO}
+
+    for ext, io_class in invalid_extension_dict.items():
+        if isinstance(io_class, NWBZarrIO):
+            tmp_path = tempfile.TemporaryDirectory(suffix=ext).name
+        else:
+            tmp_path = tempfile.NamedTemporaryFile(suffix=ext).name
+
+        nwbfile = make_minimal_nwbfile()
+        with io_class(str(tmp_path), mode="w") as io:
+            io.write(nwbfile)
+
+        with io_class(str(tmp_path), mode="r") as io:
+            read_nwbfile = io.read()
+            result = check_file_extension(read_nwbfile)
+            msg = f"The file extension '{ext}' does not follow the recommended naming convention."
+            assert msg in result.message