add read_nwb_method

docs/gallery/general/plot_read_basics.py

@@ -30,7 +30,6 @@
 import matplotlib.pyplot as plt
 import numpy as np
 
-from pynwb import NWBHDF5IO
 
 ####################
 # We will access NWB data on the `DANDI Archive <https://gui.dandiarchive.org/>`_,
@@ -103,14 +102,16 @@
 # read the data into a :py:class:`~pynwb.file.NWBFile` object.
 
 filepath = "sub-P11HMH_ses-20061101_ecephys+image.nwb"
-# Open the file in read mode "r",
-io = NWBHDF5IO(filepath, mode="r")
-nwbfile = io.read()
+from pynwb import read_nwb
+
+nwbfile = read_nwb(filepath)
 nwbfile
 
 #######################################
-# :py:class:`~pynwb.NWBHDF5IO` can also be used as a context manager:
+# For more advance use, use the :py:class:`~pynwb.NWBHDF5IO`. Here, we show how it can be used as a context manager
+# to read data from an NWB file in a more controlled way:
 
+from pynwb import NWBHDF5IO
 with NWBHDF5IO(filepath, mode="r") as io2:
     nwbfile2 = io2.read()
 
@@ -291,4 +292,4 @@
 # -----------------------
 # It is good practice, especially on Windows, to close any files that you have opened.
 
-io.close()
+nwbfile.get_read_io().close()

requirements-opt.txt

@@ -6,3 +6,6 @@ oaklib==0.5.32; python_version >= "3.9"
 fsspec==2024.10.0
 requests==2.32.3
 aiohttp==3.10.10
+
+# For read_nwb tests
+hdmf-zarr

src/pynwb/__init__.py

@@ -535,6 +535,72 @@ def read_nwb(**kwargs):
 
         return nwbfile
 
+@docval({'name': 'path', 'type': (str, Path), 'doc': 'the path to the nwbfile'}, 
+        is_method=False)
+def read_nwb(**kwargs):
+    """Read an NWB file from a local path or remote URL.
+
+    Provides a simple, high-level interface for reading NWB files in the most 
+    common use cases. Automatically handles both HDF5 and Zarr formats.
+    For advanced use cases (parallel I/O, custom namespaces), use NWBHDF5IO or NWBZarrIO.
+
+    Parameters
+    ----------
+    path : str or pathlib.Path
+        Path to the NWB file. Can be either a local filesystem path to an HDF5 (.nwb) 
+        or Zarr (.zarr) file
+
+    Returns
+    -------
+    pynwb.NWBFile
+        The loaded NWB file object.
+
+    See Also
+    --------
+    pynwb.NWBHDF5IO : Core I/O class for HDF5 files with advanced options.
+    hdmf_zarr.nwb.NWBZarrIO : Core I/O class for Zarr files with advanced options.
+
+    Notes
+    -----
+    This function uses the following defaults:
+    * Always opens in read-only mode
+    * Automatically loads namespaces
+    * Detects file format based on extension
+    * Automatically handles local and remote paths
+
+    Advanced features requiring direct use of IO classes include:
+    * Streaming data from s3
+    * Custom namespace extensions
+    * Parallel I/O with MPI
+    * Custom build managers
+    * Write or append modes
+    * Pre-opened HDF5 file objects or Zarr stores
+    * Remote file access configuration
+
+    Examples
+    --------
+    Read a local NWB file:
+
+    >>> from pynwb import read_nwb
+    >>> nwbfile = read_nwb("path/to/file.nwb")
+
+    
+    """
+
+    path = popargs('path', kwargs)
+    backend_is_hdf5 = NWBHDF5IO.can_read(path=path)
+    if backend_is_hdf5:
+        return NWBHDF5IO.read_nwb(path=path)
+    else:
+        from hdmf_zarr import NWBZarrIO
+        backend_is_zarr = NWBZarrIO.can_read(path=path)
+        if backend_is_zarr:
+            return NWBZarrIO.read_nwb(path=path) 
+        else:
+            raise ValueError(f"Unsupported backend for file: {path}")    
+
+
+
 from . import io as __io  # noqa: F401,E402
 from .core import NWBContainer, NWBData  # noqa: F401,E402
 from .base import TimeSeries, ProcessingModule  # noqa: F401,E402

tests/integration/hdf5/test_io.py

@@ -613,7 +613,6 @@ def test_read_nwb_method_file(self):
             io.write(self.nwbfile)
 
         import h5py
-
         file = h5py.File(self.path, 'r')
 
         read_nwbfile = NWBHDF5IO.read_nwb(file=file)
@@ -627,4 +626,7 @@ def test_read_nwb_method_s3_path(self):
         read_nwbfile = NWBHDF5IO.read_nwb(path=s3_test_path)
         assert read_nwbfile.identifier == "3f77c586-6139-4777-a05d-f603e90b1330"
 
-        assert read_nwbfile.subject.subject_id == "1"
+        assert read_nwbfile.subject.subject_id == "1"
+
+
+