Handle Device conflicts between core schema and extensions (#2132)

* device model mapper - wip

* add device mapper for schema conflicts

* update warning stack levels

* update device mapping warnings for clarity

* add extension back compatibility test files

* add tests for reading old extension files with nwb schema 2.9.0

* update CHANGELOG

* fix test name

* bump hdmf minimum requirement

* update requirements.txt

* Update dandi download URL for testing data

* Update src/pynwb/io/device.py

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

* Update src/pynwb/io/device.py

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

* update test warning assertion

---------

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

Author: stephprince

.github/workflows/run_inspector_tests.yml

@@ -36,7 +36,7 @@ jobs:
           python -m pip install pytest
           python -m pip install ".[dandi]"  # this might install a pinned version of pynwb instead of the current one
           # Download testing data and set config path
-          dandi download "https://gui-staging.dandiarchive.org/#/dandiset/204919"
+          dandi download "https://sandbox.dandiarchive.org/dandiset/204919"
           cd ..
           python -m pip uninstall -y pynwb  # uninstall the pinned version of pynwb
           python -m pip install .  # reinstall current branch of pynwb

CHANGELOG.md

@@ -7,11 +7,12 @@
 
 ### Fixed
 - Fixed incorrect warning for path not ending in `.nwb` when no path argument was provided. @t-b [#2130](https://github.com/NeurodataWithoutBorders/pynwb/pull/2130)
+- Fixed inability to read files created with extensions that had schema conflicts with the DeviceModel type introduced in NWB Schema 2.9.0. @stephprince [#2132](https://github.com/NeurodataWithoutBorders/pynwb/pull/2132)
 - Fixed issue with setting `neurodata_type_inc` when reading NWB files with cached schema versions less than 2.2.0. @rly [#2135](https://github.com/NeurodataWithoutBorders/pynwb/pull/2135)
 - Fixed import structure test. @rly [#2136](https://github.com/NeurodataWithoutBorders/pynwb/pull/2136)
 
-### Documentation and tutorial enhancements
-- Change UI of assistant to be an accordion that is always visible. [#2124](https://github.com/NeurodataWithoutBorders/pynwb/pull/2124)
+### Changed
+- Change UI of documentation assistant to be an accordion that is always visible. @bendichter [#2124](https://github.com/NeurodataWithoutBorders/pynwb/pull/2124)
 
 
 ## PyNWB 3.1.2 (August 13, 2025)

requirements-min.txt

@@ -1,6 +1,6 @@
 # minimum versions of package dependencies for installing PyNWB
 h5py==3.2.0
-hdmf==4.1.0
+hdmf==4.1.1
 numpy==1.24.0
 pandas==1.2.0
 python-dateutil==2.8.2

requirements.txt

@@ -1,6 +1,6 @@
 # pinned dependencies to reproduce an entire development environment to use PyNWB
 h5py==3.12.1
-hdmf==4.1.0
+hdmf==4.1.1
 numpy==2.1.1; python_version > "3.9"  # numpy 2.1+ is not compatible with py3.9
 numpy==2.0.2; python_version == "3.9"
 pandas==2.2.3

src/pynwb/io/__init__.py

@@ -1,5 +1,6 @@
 from . import base as __base
 from . import core as __core
+from . import device as __device
 from . import file as __file
 from . import behavior as __behavior
 from . import ecephys as __ecephys

src/pynwb/io/device.py

@@ -0,0 +1,70 @@
+from warnings import warn
+
+from .. import register_map
+from ..device import Device, DeviceModel
+from .core import NWBContainerMapper
+
+
+@register_map(Device)
+class DeviceMapper(NWBContainerMapper):
+    """
+    Custom mapper for Device objects to handle known schema conflicts between core schema and extensions.
+    
+    This mapper detects when extensions define Device.model as a string attribute instead of 
+    a link to DeviceModel, or when extensions define their own DeviceModel type.
+    """
+
+    @NWBContainerMapper.constructor_arg("model")
+    def model_carg(self, builder, manager):
+        """
+        Handle different model mapping strategies based on detected schema conflicts.
+        
+        Args:
+            builder: The GroupBuilder for the Device
+            manager: The BuildManager
+            
+        Returns:
+            The appropriate model object or value based on the mapping strategy
+        """
+        model_builder = builder.get('model')
+        if isinstance(model_builder, str):
+            warn(
+                'Device.model was detected as a string, but NWB 2.9 specifies Device.model as a link to a DeviceModel. '
+                f'Remapping "{model_builder}" to a new DeviceModel.',
+                 stacklevel=3)
+
+            # replace the model string with a DeviceModel object using the model name and device attributes 
+            device_model_attributes = dict(name=model_builder,
+                                           description=builder.attributes.get('description'),
+                                           manufacturer=builder.attributes.get('manufacturer', ''),
+                                           model_number=builder.attributes.get('model_number'))
+            model = DeviceModel(**device_model_attributes)
+        
+            return model
+
+        return None
+    
+      
+    def __new_container__(self, cls, container_source, parent, object_id, **kwargs):
+        # Override ObjectMapper.__new_container__ to handle the case where the Device.model argument
+        # is not a DeviceModel, which can happen in extensions written to be compatible with NWB<2.9.
+        # The original Device.model object will be accessible under a new attribute name based on the
+        # extension namespace. 
+        model = kwargs.get('model', None)
+        
+        if model is None or isinstance(model, DeviceModel):
+            device_obj = super().__new_container__(cls, container_source, parent, object_id, **kwargs)
+        else:
+            # create device object without model
+            kwargs.pop('model')
+            device_obj = super().__new_container__(cls, container_source, parent, object_id, **kwargs)
+
+            # add the conflicting Device.model object as a new attribute on Device
+            # e.g. Device.model in the file -> Device.ndx_optogenetics_model in the python object
+            warn(f'The model attribute of the Device "{device_obj.name}" was detected as a non-DeviceModel '
+                 f'object. Data associated with this object can be accessed at '
+                 f'"nwbfile.devices["{device_obj.name}"].{model.namespace.replace("-", "_")}_model"',
+                 stacklevel=2)
+            setattr(device_obj, f"{model.namespace.replace('-', '_')}_model", model)
+
+        return device_obj

tests/back_compat/3.0.0_fiber_photometry_extension.nwb

@@ -4,6 +4,7 @@
 import warnings
 
 from pynwb import NWBHDF5IO, validate, TimeSeries
+from pynwb.device import DeviceModel
 from pynwb.ecephys import ElectrodesTable
 from pynwb.image import ImageSeries
 from pynwb.misc import FrequencyBandsTable
@@ -166,4 +167,55 @@ def test_read_bands_table_as_neurodata_type(self):
         f = Path(__file__).parent / '3.0.0_decompositionseries_bands_dynamic_table.nwb'
         with self.get_io(f) as io:
             read_nwbfile = io.read()
-            assert isinstance(read_nwbfile.processing['test_mod']['LFPSpectralAnalysis'].bands, FrequencyBandsTable)
+            assert isinstance(read_nwbfile.processing['test_mod']['LFPSpectralAnalysis'].bands, FrequencyBandsTable)
+    
+    def test_read_device_model_str_attribute(self):
+        """Test that a Device.model written as a string attribute is read and remapped to a DeviceModel object"""
+        f = Path(__file__).parent / '3.0.0_fiber_photometry_extension.nwb'
+        with self.get_io(f) as io:
+            # assert warning is issued to inform user the attribute is being remapped
+            with self.assertWarnsWith(UserWarning,
+                                      'Device.model was detected as a string, ' \
+                                      'but NWB 2.9 specifies Device.model as a link to a DeviceModel. '
+                                      'Remapping "dichroic mirror model" to a new DeviceModel.'):
+                read_nwbfile = io.read()
+
+            # assert data was remapped correctly
+            device = read_nwbfile.devices['dichroic_mirror_1']
+            self.assertIsInstance(device.model, DeviceModel)
+            self.assertEqual(device.model.name, 'dichroic mirror model')
+            self.assertEqual(device.model.description, 'Dichroic mirror for green indicator')
+            self.assertEqual(device.model.manufacturer, '')
+            self.assertEqual(device.model.model_number, None)
+    
+    def test_read_device_model_link_to_other_object(self):
+        """Test that a Device.model written as a link to another object is read and remapped to a new attribute"""
+        f = Path(__file__).parent / '3.0.0_optogenetics_extension.nwb'
+        with self.get_io(f) as io:
+            # assert warning is issued to inform user where old data is being remapped
+            with self.assertWarnsWith(UserWarning,
+                                      'The model attribute of the Device "Lambda" was detected as a non-DeviceModel '
+                                      'object. Data associated with this object can be accessed at '
+                                      '\"nwbfile.devices["Lambda"].ndx_optogenetics_model\"'):
+                read_nwbfile = io.read()
+
+            # assert data was remapped correctly
+            device = read_nwbfile.devices['Lambda']
+            self.assertIsNone(device.model)
+            self.assertIsNotNone(device.ndx_optogenetics_model)
+            self.assertEqual(device.ndx_optogenetics_model.name, 'Lambda Model')
+            self.assertEqual(device.ndx_optogenetics_model.description, 'Lambda fiber (tapered fiber) from Optogenix.')
+            self.assertEqual(device.ndx_optogenetics_model.numerical_aperture, 0.39)
+
+    def test_read_device_model_link_to_extension_device_model(self):
+        """Test that a Device.model written as a link to an extension DeviceModel object is read successfully"""
+        f = Path(__file__).parent / '3.0.0_ophys_devices_extension.nwb'
+        with self.get_io(f) as io:
+            read_nwbfile = io.read()
+
+            # assert model is read correct
+            band_optical_filter = read_nwbfile.devices['band_optical_filter']
+            self.assertIsInstance(band_optical_filter.model, DeviceModel)
+            self.assertEqual(band_optical_filter.model.name, 'band_optical_filter_model')
+            self.assertEqual(band_optical_filter.model.description, 'Band optical filter model for green indicator')
+            self.assertEqual(band_optical_filter.model.bandwidth_in_nm, 30.0)