Add model_number, model_name, and serial_number to Device (#1997)

Author: rly

CHANGELOG.md

@@ -6,6 +6,7 @@
 - Added support for NWB schema 2.8.0:
   - Removed `SpatialSeries.bounds` field that was not functional. This will be fixed in a future release. @rly [#1907](https://github.com/NeurodataWithoutBorders/pynwb/pull/1907), [#1996](https://github.com/NeurodataWithoutBorders/pynwb/pull/1996)
   - Added support for `NWBFile.was_generated_by` field. @stephprince [#1924](https://github.com/NeurodataWithoutBorders/pynwb/pull/1924)
+  - Added support for `model_number`, `model_name`, and `serial_number` fields to `Device`. @stephprince [#1997](https://github.com/NeurodataWithoutBorders/pynwb/pull/1997)
 
 ## PyNWB 2.8.3 (Upcoming)
 

docs/gallery/domain/ecephys.py

@@ -77,10 +77,16 @@
 #
 # 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`.
-
+# :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.
 device = nwbfile.create_device(
-    name="array", description="the best array", manufacturer="Probe Company 9000"
+    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",
 )
 
 #######################

docs/gallery/domain/ophys.py

@@ -86,12 +86,17 @@
 #     :align: center
 #
 # Create a :py:class:`~pynwb.device.Device` named ``"Microscope"`` in the :py:class:`~pynwb.file.NWBFile` object. Then
-# create an  :py:class:`~pynwb.ophys.OpticalChannel` named ``"OpticalChannel"``.
+# create an  :py:class:`~pynwb.ophys.OpticalChannel` named ``"OpticalChannel"``. The fields
+# ``description``, ``manufacturer``, ``model_number``, ``model_name``, and ``serial_number`` are optional, but
+# recommended.
 
 device = nwbfile.create_device(
     name="Microscope",
     description="My two-photon microscope",
-    manufacturer="The best microscope manufacturer",
+    manufacturer="Loki Labs",
+    model_number="ABC-123",
+    model_name="Loki 1.0",
+    serial_number="1234567890",
 )
 optical_channel = OpticalChannel(
     name="OpticalChannel",

src/pynwb/device.py

@@ -10,18 +10,41 @@ class Device(NWBContainer):
     Metadata about a data acquisition device, e.g., recording system, electrode, microscope.
     """
 
-    __nwbfields__ = ('name',
-                     'description',
-                     'manufacturer')
+    __nwbfields__ = (
+        'name',
+        'description',
+        'manufacturer',
+        'model_number',
+        'model_name',
+        'serial_number',
+    )
 
-    @docval({'name': 'name', 'type': str, 'doc': 'the name of this device'},
-            {'name': 'description', 'type': str,
-             'doc': 'Description of the device (e.g., model, firmware version, processing software version, etc.)',
-             'default': None},
-            {'name': 'manufacturer', 'type': str, 'doc': 'the name of the manufacturer of this device',
-            'default': None})
+    @docval(
+        {'name': 'name', 'type': str, 'doc': 'the name of this device'},
+        {'name': 'description', 'type': str,
+         'doc': ("Description of the device as free-form text. If there is any software/firmware associated "
+                 "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."),
+         '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.'),
+         '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.',
+         'default': None},
+    )
     def __init__(self, **kwargs):
-        description, manufacturer = popargs('description', 'manufacturer', kwargs)
+        description, manufacturer, model_number, model_name, serial_number = popargs(
+            'description', 'manufacturer', 'model_number', 'model_name', 'serial_number', kwargs)
         super().__init__(**kwargs)
         self.description = description
         self.manufacturer = manufacturer
+        self.model_number = model_number
+        self.model_name = model_name
+        self.serial_number = serial_number

tests/integration/hdf5/test_device.py

@@ -6,9 +6,14 @@ class TestDeviceIO(NWBH5IOMixin, TestCase):
 
     def setUpContainer(self):
         """ Return the test Device to read/write """
-        return Device(name='device_name',
-                      description='description',
-                      manufacturer='manufacturer')
+        return Device(
+            name='device_name',
+            description='description',
+            manufacturer='manufacturer',
+            model_number='model_number',
+            model_name='model_name',
+            serial_number='serial_number',
+        )
 
     def addContainer(self, nwbfile):
         """ Add the test Device to the given NWBFile """

tests/unit/test_device.py

@@ -5,10 +5,18 @@
 class TestDevice(TestCase):
 
     def test_init(self):
-        device = Device(name='device_name',
-                        description='description',
-                        manufacturer='manufacturer')
+        device = Device(
+            name='device_name',
+            description='description',
+            manufacturer='manufacturer',
+            model_number='model_number',
+            model_name='model_name',
+            serial_number='serial_number',
+        )
 
         self.assertEqual(device.name, 'device_name')
         self.assertEqual(device.description, 'description')
         self.assertEqual(device.manufacturer, 'manufacturer')
+        self.assertEqual(device.model_number, 'model_number')
+        self.assertEqual(device.model_name, 'model_name')
+        self.assertEqual(device.serial_number, 'serial_number')