Add support for DeviceModel neurodata type (#2088)

Co-authored-by: Steph Prince <[email protected]>

Author: rly

CHANGELOG.md

@@ -11,6 +11,8 @@
   - Added new `ElectrodesTable` neurodata type. @mavaylon1 [#1890](https://github.com/NeurodataWithoutBorders/pynwb/pull/1890)
   - Formally defined and renamed `ElectrodeTable` as the `ElectrodesTable` neurodata type. @mavaylon1 [#1890](https://github.com/NeurodataWithoutBorders/pynwb/pull/1890)
   - Formally defined bands within `DecompositionSeries` as the neurodatatype `FrequencyBandsTable`. @mavaylon1 @rly [#2063](https://github.com/NeurodataWithoutBorders/pynwb/pull/2063)
+  - Added new `DeviceModel` neurodata type to store device model information. @rly [#2088](https://github.com/NeurodataWithoutBorders/pynwb/pull/2088)
+  - Deprecated `Device.model_name`, `Device.model_number`, and `Device.manufacturer` fields in favor of `DeviceModel`. @rly [#2088](https://github.com/NeurodataWithoutBorders/pynwb/pull/2088)
   - Added support for 2D `EventDetection.source_index` to indicate [time_index, channel_index]. @stephprince [#2091](https://github.com/NeurodataWithoutBorders/pynwb/pull/2091)
   - Made `EventDetection.times` optional. @stephprince [#2091](https://github.com/NeurodataWithoutBorders/pynwb/pull/2091)
 - Automatically add timezone information to timestamps reference time if no timezone information is specified. @stephprince [#2056](https://github.com/NeurodataWithoutBorders/pynwb/pull/2056)

docs/gallery/domain/ecephys.py

@@ -80,15 +80,21 @@
 # The electrodes table references a required :py:class:`~pynwb.ecephys.ElectrodeGroup`, which is used to represent a
 # group of electrodes. Before creating an :py:class:`~pynwb.ecephys.ElectrodeGroup`, you must define a
 # :py:class:`~pynwb.device.Device` object using the method :py:meth:`.NWBFile.create_device`. The fields
-# ``description``, ``manufacturer``, ``model_number``, ``model_name``, and ``serial_number`` are optional, but
-# recommended.
+# ``description``, ``serial_number``, and ``model`` are optional, but recommended. The
+# :py:class:`~pynwb.device.DeviceModel` object stores information about the device model, which can be useful
+# when searching a set of NWB files or a data archive for all files that use a specific device model
+# (e.g., Neuropixels probe).
+device_model = nwbfile.create_device_model(
+    name="Neurovoxels 0.99",
+    manufacturer="Array Technologies",
+    model_number="PRB_1_4_0480_123",
+    description="A 12-channel array with 4 shanks and 3 channels per shank",
+)
 device = nwbfile.create_device(
     name="array",
     description="A 12-channel array with 4 shanks and 3 channels per shank",
-    manufacturer="Array Technologies",
-    model_number="PRB_1_4_0480_123",
-    model_name="Neurovoxels 0.99",
     serial_number="1234567890",
+    model=device_model,
 )
 
 #######################
@@ -238,7 +244,7 @@
 lfp = LFP(electrical_series=lfp_electrical_series)
 
 ####################
-# LFP refers to data that has been low-pass filtered, typically below 300 Hz. This data may also be downsampled. 
+# LFP refers to data that has been low-pass filtered, typically below 300 Hz. This data may also be downsampled.
 # Because it is filtered and potentially resampled, it is categorized as processed data.
 #
 # Create a processing module named ``"ecephys"`` and add the :py:class:`~pynwb.ecephys.LFP` object to it.
@@ -252,7 +258,7 @@
 
 #######################
 # If your data is filtered for frequency ranges other than LFP — such as Gamma or Theta — you should store it in an
-# :py:class:`~pynwb.ecephys.ElectricalSeries` and encapsulate it within a 
+# :py:class:`~pynwb.ecephys.ElectricalSeries` and encapsulate it within a
 # :py:class:`~pynwb.ecephys.FilteredEphys` object.
 
 from pynwb.ecephys import FilteredEphys
@@ -272,21 +278,21 @@
 ecephys_module.add(filtered_ephys)
 
 ################################
-# In some cases, you may want to further process the LFP data and decompose the signal into different frequency bands 
+# In some cases, you may want to further process the LFP data and decompose the signal into different frequency bands
 # to use for other downstream analyses. You can store the processed data from these spectral analyses using a
 # :py:class:`~pynwb.misc.DecompositionSeries` object. This object allows you to include metadata about the frequency
-# bands and metric used (e.g., power, phase, amplitude), as well as link the decomposed data to the original 
+# bands and metric used (e.g., power, phase, amplitude), as well as link the decomposed data to the original
 # :py:class:`~pynwb.base.TimeSeries` signal the data was derived from.
 
 #######################
-# .. note:: When adding data to :py:class:`~pynwb.misc.DecompositionSeries`, the ``data`` argument is assumed to be 
+# .. note:: When adding data to :py:class:`~pynwb.misc.DecompositionSeries`, the ``data`` argument is assumed to be
 #           3D where the first dimension is time, the second dimension is channels, and the third dimension is bands.
 
 
-bands = dict(theta=(4.0, 12.0), 
-             beta=(12.0, 30.0), 
+bands = dict(theta=(4.0, 12.0),
+             beta=(12.0, 30.0),
              gamma=(30.0, 80.0))  # in Hz
-phase_data = np.random.randn(50, 12, len(bands))  # 50 samples, 12 channels, 3 frequency bands  
+phase_data = np.random.randn(50, 12, len(bands))  # 50 samples, 12 channels, 3 frequency bands
 
 decomp_series = DecompositionSeries(
     name="theta",
@@ -353,7 +359,7 @@
 # While the :py:class:`~pynwb.misc.Units` table is used to store spike times and waveform data for
 # spike-sorted, single-unit activity, you may also want to store spike times and waveform snippets of
 # unsorted spiking activity (e.g., multi-unit activity detected via threshold crossings during data acquisition).
-# This information can be stored using :py:class:`~pynwb.ecephys.SpikeEventSeries` objects. 
+# This information can be stored using :py:class:`~pynwb.ecephys.SpikeEventSeries` objects.
 
 spike_snippets = np.random.rand(40, 3, 30)  # 40 events, 3 channels, 30 samples per event
 shank0 = nwbfile.create_electrode_table_region(

src/pynwb/device.py

@@ -1,14 +1,16 @@
 from hdmf.utils import docval, popargs, AllowPositional
+import warnings
 
 from . import register_class, CORE_NAMESPACE
 from .core import NWBContainer
 
-__all__ = ['Device']
+__all__ = ['Device', 'DeviceModel']
 
 @register_class('Device', CORE_NAMESPACE)
 class Device(NWBContainer):
     """
     Metadata about a data acquisition device, e.g., recording system, electrode, microscope.
+    Link to a DeviceModel.model to represent information about the model of the device.
     """
 
     __nwbfields__ = (
@@ -18,6 +20,7 @@ class Device(NWBContainer):
         'model_number',
         'model_name',
         'serial_number',
+        'model',
     )
 
     @docval(
@@ -27,26 +30,86 @@ class Device(NWBContainer):
                  "with the device, the names and versions of those can be added to `NWBFile.was_generated_by`."),
          'default': None},
         {'name': 'manufacturer', 'type': str,
-         'doc': ("The name of the manufacturer of the device, e.g., Imec, Plexon, Thorlabs."),
+         'doc': ("DEPRECATED. The name of the manufacturer of the device, e.g., Imec, Plexon, Thorlabs. "
+                 "Instead of using this field, store the value in DeviceModel.manufacturer and link to that "
+                 "DeviceModel from this Device."),
          'default': None},
         {'name': 'model_number', 'type': str,
-         'doc': ('The model number (or part/product number) of the device, e.g., PRB_1_4_0480_1, '
-                 'PLX-VP-32-15SE(75)-(260-80)(460-10)-300-(1)CON/32m-V, BERGAMO.'),
+         'doc': ('DEPRECATED. The model number (or part/product number) of the device, e.g., PRB_1_4_0480_1, '
+                 'PLX-VP-32-15SE(75)-(260-80)(460-10)-300-(1)CON/32m-V, BERGAMO. '
+                 'Instead of using this field, store the value in DeviceModel.model_number and link to that '
+                 'DeviceModel from this Device. '),
          'default': None},
         {'name': 'model_name', 'type': str,
-         'doc': ('The model name of the device, e.g., Neuropixels 1.0, V-Probe, Bergamo III.'),
-         'default': None},
-        {'name': 'serial_number', 'type': str,
-         'doc': 'The serial number of the device.',
+         'doc': ('DEPRECATED. The model name of the device, e.g., Neuropixels 1.0, V-Probe, Bergamo III. '
+                 'Instead of using this field, storing the value in DeviceModel.name and link to that '
+                 'DeviceModel from this Device.'),
          'default': None},
+        {'name': 'serial_number', 'type': str, 'doc': 'The serial number of the device.', 'default': None},
+        {'name': 'model', 'type': 'DeviceModel', 'doc': 'The model of the device.', 'default': None},
          allow_positional=AllowPositional.WARNING,
     )
     def __init__(self, **kwargs):
-        description, manufacturer, model_number, model_name, serial_number = popargs(
-            'description', 'manufacturer', 'model_number', 'model_name', 'serial_number', kwargs)
+        description, manufacturer, model_number, model_name, serial_number, model = popargs(
+            'description', 'manufacturer', 'model_number', 'model_name', 'serial_number', 'model', kwargs)
+        if model_number is not None:
+            warnings.warn(
+                "The 'model_number' field is deprecated. Instead, use DeviceModel.model_number and link to that "
+                "DeviceModel from this Device.",
+                DeprecationWarning,
+                stacklevel=2
+            )
+        if manufacturer is not None:
+            warnings.warn(
+                "The 'manufacturer' field is deprecated. Instead, use DeviceModel.manufacturer and link to that "
+                "DeviceModel from this Device.",
+                DeprecationWarning,
+                stacklevel=2
+            )
+        if model_name is not None:
+            warnings.warn(
+                "The 'model_name' field is deprecated. Instead, use DeviceModel.name and link to that "
+                "DeviceModel from this Device.",
+                DeprecationWarning,
+                stacklevel=2
+            )
         super().__init__(**kwargs)
         self.description = description
         self.manufacturer = manufacturer
         self.model_number = model_number
         self.model_name = model_name
         self.serial_number = serial_number
+        self.model = model
+
+
+@register_class('DeviceModel', CORE_NAMESPACE)
+class DeviceModel(NWBContainer):
+    """
+    Model properties of a data acquisition device, e.g., recording system, electrode, microscope.
+    """
+
+    __nwbfields__ = (
+        'manufacturer',
+        'model_number',
+        'description',
+    )
+
+    @docval(
+        {'name': 'name', 'type': str, 'doc': 'The name of this device model'},
+        {'name': 'manufacturer', 'type': str,
+         'doc': ("The name of the manufacturer of the device, e.g., Imec, Plexon, Thorlabs.")},
+        {'name': 'model_number', 'type': str,
+         'doc': ('The model number (or part/product number) of the device, e.g., PRB_1_4_0480_1, '
+                 'PLX-VP-32-15SE(75)-(260-80)(460-10)-300-(1)CON/32m-V, BERGAMO.'),
+         'default': None},
+        {'name': 'description', 'type': str,
+         'doc': ("Description of the device model as free-form text."),
+         'default': None},
+         allow_positional=AllowPositional.ERROR,
+    )
+    def __init__(self, **kwargs):
+        manufacturer, model_number, description = popargs('manufacturer', 'model_number', 'description', kwargs)
+        super().__init__(**kwargs)
+        self.manufacturer = manufacturer
+        self.model_number = model_number
+        self.description = description

src/pynwb/file.py

@@ -13,7 +13,7 @@
 
 from . import register_class, CORE_NAMESPACE
 from .base import TimeSeries, ProcessingModule
-from .device import Device
+from .device import Device, DeviceModel
 from .epoch import TimeIntervals
 from .ecephys import ElectrodeGroup, ElectrodesTable
 from .icephys import (IntracellularElectrode, SweepTable, PatchClampSeries, IntracellularRecordingsTable,
@@ -208,6 +208,13 @@ class NWBFile(MultiContainerInterface, HERDManager):
             'create': 'create_device',
             'get': 'get_device'
         },
+        {
+            'attr': 'device_models',
+            'add': 'add_device_model',
+            'type': DeviceModel,
+            'create': 'create_device_model',
+            'get': 'get_device_model'
+        },
         {
             'attr': 'electrode_groups',
             'add': 'add_electrode_group',
@@ -401,6 +408,8 @@ class NWBFile(MultiContainerInterface, HERDManager):
              'doc': 'OptogeneticStimulusSites that belong to this NWBFile', 'default': None},
             {'name': 'devices', 'type': (list, tuple),
              'doc': 'Device objects belonging to this NWBFile', 'default': None},
+            {'name': 'device_models', 'type': (list, tuple),
+             'doc': ' Device models used in this NWBFile', 'default': None},
             {'name': 'subject', 'type': Subject,
              'doc': 'subject metadata', 'default': None},
             {'name': 'scratch', 'type': (list, tuple),
@@ -439,6 +448,7 @@ def __init__(self, **kwargs):
             'electrodes',
             'electrode_groups',
             'devices',
+            'device_models',
             'imaging_planes',
             'ogen_sites',
             'intervals',

src/pynwb/io/file.py

@@ -114,6 +114,10 @@ def __init__(self, spec):
         self.unmap(device_spec)
         self.map_spec('devices', device_spec.get_neurodata_type('Device'))
 
+        device_model_spec = general_spec.get_group('devices').get_group('models')
+        self.unmap(device_model_spec)
+        self.map_spec('device_models', device_model_spec.get_neurodata_type('DeviceModel'))
+
         self.map_spec('lab_meta_data', general_spec.get_neurodata_type('LabMetaData'))
 
         proc_spec = self.spec.get_group('processing')

src/pynwb/nwb-schema

@@ -220,7 +220,7 @@ def _make_electrodes_dynamic_table():
     nwbfile = NWBFile(session_description='ADDME',
                       identifier='ADDME',
                       session_start_time=datetime.now().astimezone())
-    device = nwbfile.create_device(name="array", description="an array", manufacturer="company")
+    device = nwbfile.create_device(name="array", description="an array")
     nwbfile.add_electrode_column(name="label", description="label of electrode")
 
     for i in range(4):

src/pynwb/testing/make_test_files.py

@@ -1,7 +1,7 @@
 from typing import Optional
 
 from ... import NWBFile
-from ...device import Device
+from ...device import Device, DeviceModel
 
 from .utils import name_generator
 
@@ -22,3 +22,23 @@ def mock_Device(
         nwbfile.add_device(device)
 
     return device
+
+
+def mock_DeviceModel(
+    name: Optional[str] = None,
+    manufacturer: str = None,
+    model_number: Optional[str] = None,
+    description: str = "description",
+    nwbfile: Optional[NWBFile] = None,
+) -> DeviceModel:
+    device = DeviceModel(
+        name=name or name_generator("DeviceModel"),
+        manufacturer=manufacturer,
+        model_number=model_number,
+        description=description,
+    )
+
+    if nwbfile is not None:
+        nwbfile.add_device_model(device)
+
+    return device

src/pynwb/testing/mock/device.py

@@ -1,24 +1,51 @@
-from pynwb.device import Device
+from pynwb.device import Device, DeviceModel
 from pynwb.testing import NWBH5IOMixin, TestCase
 
 
 class TestDeviceIO(NWBH5IOMixin, TestCase):
 
     def setUpContainer(self):
         """ Return the test Device to read/write """
-        return Device(
-            name='device_name',
-            description='description',
+        device_model = DeviceModel(
+            name='device_model_name',
             manufacturer='manufacturer',
             model_number='model_number',
-            model_name='model_name',
+            description='description',
+        )
+        device = Device(
+            name='device_name',
+            description='description',
             serial_number='serial_number',
+            model=device_model,
         )
+        return device
 
     def addContainer(self, nwbfile):
         """ Add the test Device to the given NWBFile """
         nwbfile.add_device(self.container)
+        nwbfile.add_device_model(self.container.model)
 
     def getContainer(self, nwbfile):
         """ Return the test Device from the given NWBFile """
         return nwbfile.get_device(self.container.name)
+
+
+class TestDeviceModelIO(NWBH5IOMixin, TestCase):
+
+    def setUpContainer(self):
+        """ Return the test DeviceModel to read/write """
+        device_model = DeviceModel(
+            name='device_model_name',
+            manufacturer='manufacturer',
+            model_number='model_number',
+            description='description',
+        )
+        return device_model
+
+    def addContainer(self, nwbfile):
+        """ Add the test DeviceModel to the given NWBFile """
+        nwbfile.add_device_model(self.container)
+
+    def getContainer(self, nwbfile):
+        """ Return the test DeviceModel from the given NWBFile """
+        return nwbfile.get_device_model(self.container.name)