Add dict-based metadata pipeline for imaging (#1677)

Author: h-mayorquin

CHANGELOG.md

@@ -11,6 +11,7 @@
 * Fixed `get_json_schema_from_method_signature` to resolve PEP 563 string annotations (from `from __future__ import annotations`) before passing them to pydantic. This affected any interface defined in a module with deferred annotations (e.g. `MiniscopeConverter`, or external subclasses from SpikeInterface). [PR #1670](https://github.com/catalystneuro/neuroconv/pull/1670)
 
 ## Features
+* Added dict-based metadata pipeline for imaging in `roiextractors.py`, supporting the new `MicroscopySeries`, `ImagingPlanes`, and `Devices` metadata format keyed by `metadata_key`. Old list-based functions are preserved (renamed with `_old_list_format` suffix) and dispatched automatically when `metadata_key` is not provided. [PR #1677](https://github.com/catalystneuro/neuroconv/pull/1677)
 
 ## Improvements
 * Added column-first fast path for writing Units tables when the table is new (no append/merge). Uses `id.extend()` + `add_column()` instead of per-row `add_unit()` calls, reducing Python overhead for large sortings. [PR #1669](https://github.com/catalystneuro/neuroconv/pull/1669)

src/neuroconv/tools/nwb_helpers/__init__.py

@@ -25,6 +25,7 @@
 from ._configure_backend import configure_backend
 from ._dataset_configuration import get_default_dataset_io_configurations, get_existing_dataset_io_configurations
 from ._metadata_and_file_helpers import (
+    _add_device_to_nwbfile,
     add_device_from_metadata,
     configure_and_write_nwbfile,
     get_default_nwbfile_metadata,

src/neuroconv/tools/nwb_helpers/_metadata_and_file_helpers.py

@@ -189,6 +189,37 @@ def add_device_from_metadata(nwbfile: NWBFile, modality: str = "Ecephys", metada
             nwbfile.create_device(**dict(defaults, **device_metadata))
 
 
+def _add_device_to_nwbfile(
+    nwbfile: NWBFile,
+    device_metadata: dict,
+):
+    """
+    Add a device to an NWBFile.
+
+    If a device with the same name already exists, the existing device is
+    returned without creating a duplicate.
+
+    Parameters
+    ----------
+    nwbfile : NWBFile
+        The NWB file to add the device to.
+    device_metadata : dict
+        Dictionary describing the device. Must contain at least a ``"name"`` key.
+
+    Returns
+    -------
+    Device
+        The Device object (either newly created or existing).
+    """
+    device_name = device_metadata["name"]
+
+    if device_name in nwbfile.devices:
+        return nwbfile.devices[device_name]
+
+    device = nwbfile.create_device(**device_metadata)
+    return device
+
+
 def _attempt_cleanup_of_existing_nwbfile(nwbfile_path: Path) -> None:
     if not nwbfile_path.exists():
         return