Add optional link to Device in ImageSeries (#1265)

* Add optional link to Device in ImageSeries

* Add support for device in ImageSeries subclasses

* Update ImageMaskSeries docstring

* Update schema

src/pynwb/image.py

@@ -5,6 +5,7 @@
 
 from . import register_class, CORE_NAMESPACE
 from .base import TimeSeries, Image
+from .device import Device
 
 
 @register_class('ImageSeries', CORE_NAMESPACE)
@@ -17,7 +18,8 @@ class ImageSeries(TimeSeries):
     __nwbfields__ = ('dimension',
                      'external_file',
                      'starting_frame',
-                     'format')
+                     'format',
+                     'device')
 
     @docval(*get_docval(TimeSeries.__init__, 'name'),  # required
             {'name': 'data', 'type': ('array_data', 'data', TimeSeries), 'shape': ([None] * 3, [None] * 4),
@@ -40,10 +42,12 @@ class ImageSeries(TimeSeries):
             {'name': 'dimension', 'type': Iterable,
              'doc': 'Number of pixels on x, y, (and z) axes.', 'default': None},
             *get_docval(TimeSeries.__init__, 'resolution', 'conversion', 'timestamps', 'starting_time', 'rate',
-                        'comments', 'description', 'control', 'control_description'))
+                        'comments', 'description', 'control', 'control_description'),
+            {'name': 'device', 'type': Device,
+             'doc': 'Device used to capture the images/video.', 'default': None},)
     def __init__(self, **kwargs):
-        bits_per_pixel, dimension, external_file, starting_frame, format = popargs(
-            'bits_per_pixel', 'dimension', 'external_file', 'starting_frame', 'format', kwargs)
+        bits_per_pixel, dimension, external_file, starting_frame, format, device = popargs(
+            'bits_per_pixel', 'dimension', 'external_file', 'starting_frame', 'format', 'device', kwargs)
         call_docval_func(super(ImageSeries, self).__init__, kwargs)
         if external_file is None and self.data is None:
             raise ValueError("Must supply either external_file or data to %s '%s'."
@@ -56,6 +60,7 @@ def __init__(self, **kwargs):
         else:
             self.starting_frame = None
         self.format = format
+        self.device = device
 
     @property
     def bits_per_pixel(self):
@@ -111,7 +116,11 @@ class ImageMaskSeries(ImageSeries):
              'doc': 'Link to ImageSeries that mask is applied to.'},
             *get_docval(ImageSeries.__init__, 'format', 'external_file', 'starting_frame', 'bits_per_pixel',
                         'dimension', 'resolution', 'conversion', 'timestamps', 'starting_time', 'rate', 'comments',
-                        'description', 'control', 'control_description'))
+                        'description', 'control', 'control_description'),
+            {'name': 'device', 'type': Device,
+             'doc': ('Device used to capture the mask data. This field will likely not be needed. '
+                     'The device used to capture the masked ImageSeries data should be stored in the ImageSeries.'),
+             'default': None},)
     def __init__(self, **kwargs):
         masked_imageseries = popargs('masked_imageseries', kwargs)
         super(ImageMaskSeries, self).__init__(**kwargs)
@@ -146,7 +155,7 @@ class OpticalSeries(ImageSeries):
                     'Must also specify frame of reference.'},
             *get_docval(ImageSeries.__init__, 'external_file', 'starting_frame', 'bits_per_pixel',
                         'dimension', 'resolution', 'conversion', 'timestamps', 'starting_time', 'rate', 'comments',
-                        'description', 'control', 'control_description'))
+                        'description', 'control', 'control_description', 'device'))
     def __init__(self, **kwargs):
         distance, field_of_view, orientation = popargs('distance', 'field_of_view', 'orientation', kwargs)
         super(OpticalSeries, self).__init__(**kwargs)

src/pynwb/ophys.py

@@ -142,7 +142,7 @@ class TwoPhotonSeries(ImageSeries):
              'default': None},
             *get_docval(ImageSeries.__init__, 'external_file', 'starting_frame', 'bits_per_pixel',
                         'dimension', 'resolution', 'conversion', 'timestamps', 'starting_time', 'rate',
-                        'comments', 'description', 'control', 'control_description'))
+                        'comments', 'description', 'control', 'control_description', 'device'))
     def __init__(self, **kwargs):
         field_of_view, imaging_plane, pmt_gain, scan_line_rate = popargs(
             'field_of_view', 'imaging_plane', 'pmt_gain', 'scan_line_rate', kwargs)

tests/integration/hdf5/test_image.py

@@ -1,25 +1,54 @@
 import numpy as np
 
-from pynwb.image import OpticalSeries
-from pynwb.testing import NWBH5IOMixin, TestCase
+from pynwb.device import Device
+from pynwb.image import ImageSeries, OpticalSeries
+from pynwb.testing import AcquisitionH5IOMixin, NWBH5IOMixin, TestCase
+
+
+class TestImageSeriesIO(AcquisitionH5IOMixin, TestCase):
+
+    def setUpContainer(self):
+        """ Return a test ImageSeries to read/write """
+        self.dev1 = Device('dev1')
+        iS = ImageSeries(
+            name='test_iS',
+            data=np.ones((3, 3, 3)),
+            unit='unit',
+            external_file=['external_file'],
+            starting_frame=[1, 2, 3],
+            format='tiff',
+            timestamps=list(),
+            device=self.dev1,
+        )
+        return iS
+
+    def addContainer(self, nwbfile):
+        """ Add the test ElectrodeGroup to the given NWBFile """
+        nwbfile.add_device(self.dev1)
+        super().addContainer(nwbfile)
 
 
 class TestOpticalSeriesIO(NWBH5IOMixin, TestCase):
 
     def setUpContainer(self):
         """ Return a test OpticalSeries to read/write """
-        self.optical_series = OpticalSeries(name='OpticalSeries',
-                                            distance=8.,
-                                            field_of_view=(4., 5.),
-                                            orientation='upper left',
-                                            data=np.ones((10, 3, 3)),
-                                            unit='m',
-                                            format='raw',
-                                            timestamps=np.arange(10.))
+        self.dev1 = Device('dev1')
+        self.optical_series = OpticalSeries(
+            name='OpticalSeries',
+            distance=8.,
+            field_of_view=(4., 5.),
+            orientation='upper left',
+            data=np.ones((10, 3, 3)),
+            unit='m',
+            format='raw',
+            timestamps=np.arange(10.),
+            device=self.dev1,
+        )
         return self.optical_series
 
     def addContainer(self, nwbfile):
         """ Add the test OpticalSeries to the given NWBFile """
+        nwbfile.add_device(self.dev1)
         nwbfile.add_stimulus(self.optical_series)
 
     def getContainer(self, nwbfile):

tests/unit/test_image.py

@@ -1,21 +1,31 @@
 import numpy as np
 
 from pynwb import TimeSeries
-from pynwb.image import ImageSeries, IndexSeries, ImageMaskSeries, OpticalSeries, \
-    GrayscaleImage, RGBImage, RGBAImage
+from pynwb.device import Device
+from pynwb.image import ImageSeries, IndexSeries, ImageMaskSeries, OpticalSeries, GrayscaleImage, RGBImage, RGBAImage
 from pynwb.testing import TestCase
 
 
 class ImageSeriesConstructor(TestCase):
 
     def test_init(self):
-        iS = ImageSeries(name='test_iS', data=np.ones((3, 3, 3)), unit='unit',
-                         external_file=['external_file'], starting_frame=[1, 2, 3], format='tiff', timestamps=list())
+        dev = Device('test_device')
+        iS = ImageSeries(
+            name='test_iS',
+            data=np.ones((3, 3, 3)),
+            unit='unit',
+            external_file=['external_file'],
+            starting_frame=[1, 2, 3],
+            format='tiff',
+            timestamps=list(),
+            device=dev,
+        )
         self.assertEqual(iS.name, 'test_iS')
         self.assertEqual(iS.unit, 'unit')
         self.assertEqual(iS.external_file, ['external_file'])
         self.assertEqual(iS.starting_frame, [1, 2, 3])
         self.assertEqual(iS.format, 'tiff')
+        self.assertIs(iS.device, dev)
         # self.assertEqual(iS.bits_per_pixel, np.nan)
 
     def test_no_data_no_file(self):