Fix up scratch API

CHANGELOG.md

@@ -1,5 +1,17 @@
 # PyNWB Changelog
 
+## PyNWB 2.0.0 (Upcoming)
+
+### Breaking changes:
+- The 'notes' and 'table_description' arguments of `NWBFile.add_scratch(...)` are now replaced by a 'description'
+  argument that is required when a scalar, numpy.ndarray, list, tuple, or pandas.DataFrame is added to scratch. The
+  'notes' argument of `ScratchData.__init__(...)` is now replaced by the required 'description' argument for
+  consistency. Previously, 'notes' had a default value of empty string, which is not recommended. @rly (#1309)
+
+### New features:
+- `NWBFile.add_scratch(...)` and `ScratchData.__init__(...)` now accept scalar data in addition to the currently
+  accepted types. @rly (#1309)
+
 ## PyNWB 1.4.0 (August 12, 2020)
 
 Users can now add/remove containers from a written NWB file and export the modified NWBFile to a new file path.

docs/gallery/general/scratch.py

@@ -138,7 +138,7 @@
 
 fft = np.fft.fft(filt_ts.data)
 
-nwb_scratch.add_scratch(fft, name='dft_filtered', notes='discrete Fourier transform from filtered data')
+nwb_scratch.add_scratch(fft, name='dft_filtered', description='discrete Fourier transform from filtered data')
 
 
 ####################

requirements-dev.txt

@@ -3,4 +3,5 @@ coverage==5.2
 flake8==3.8.3
 flake8-debugger==3.1.0
 flake8-print==3.1.4
+importlib-metadata<2
 tox==3.17.1

src/pynwb/core.py

@@ -51,7 +51,7 @@ class NWBDataInterface(NWBContainer):
 class NWBData(NWBMixin, Data):
 
     @docval({'name': 'name', 'type': str, 'doc': 'the name of this container'},
-            {'name': 'data', 'type': ('array_data', 'data', Data), 'doc': 'the source of the data'})
+            {'name': 'data', 'type': ('scalar_data', 'array_data', 'data', Data), 'doc': 'the source of the data'})
     def __init__(self, **kwargs):
         call_docval_func(super(NWBData, self).__init__, kwargs)
         self.__data = getargs('data', kwargs)
@@ -90,14 +90,14 @@ def extend(self, arg):
 @register_class('ScratchData', CORE_NAMESPACE)
 class ScratchData(NWBData):
 
-    __nwbfields__ = ('notes',)
+    __nwbfields__ = ('description',)
 
     @docval({'name': 'name', 'type': str, 'doc': 'the name of this container'},
-            {'name': 'data', 'type': ('array_data', 'data', Data), 'doc': 'the source of the data'},
-            {'name': 'notes', 'type': str, 'doc': 'notes about the data', 'default': ''})
+            {'name': 'data', 'type': ('scalar_data', 'array_data', 'data', Data), 'doc': 'the source of the data'},
+            {'name': 'description', 'type': str, 'doc': 'description of the data'})
     def __init__(self, **kwargs):
-        call_docval_func(super(ScratchData, self).__init__, kwargs)
-        self.notes = getargs('notes', kwargs)
+        call_docval_func(super().__init__, kwargs)
+        self.description = getargs('description', kwargs)
 
 
 class NWBTable(NWBData):

src/pynwb/file.py

@@ -18,8 +18,7 @@
 from .ophys import ImagingPlane
 from .ogen import OptogeneticStimulusSite
 from .misc import Units
-from .core import NWBContainer, NWBDataInterface, MultiContainerInterface, \
-                  ScratchData, LabelledDict
+from .core import NWBContainer, NWBDataInterface, MultiContainerInterface, ScratchData, LabelledDict
 from hdmf.common import DynamicTableRegion, DynamicTable
 
 
@@ -669,36 +668,42 @@ def add_stimulus_template(self, timeseries):
         self._add_stimulus_template_internal(timeseries)
         self._update_sweep_table(timeseries)
 
-    @docval({'name': 'data', 'type': (np.ndarray, list, tuple, pd.DataFrame, DynamicTable, NWBContainer, ScratchData),
-             'help': 'the data to add to the scratch space'},
+    @docval({'name': 'data',
+             'type': ('scalar_data', np.ndarray, list, tuple, pd.DataFrame, DynamicTable, NWBContainer, ScratchData),
+             'doc': 'The data to add to the scratch space.'},
             {'name': 'name', 'type': str,
-             'help': 'the name of the data. Only used when passing in numpy.ndarray, list, or tuple',
+             'doc': ('The name of the data. Required only when passing in a scalar, numpy.ndarray, '
+                     'list, tuple, or pandas.DataFrame'),
              'default': None},
-            {'name': 'notes', 'type': str,
-             'help': 'notes to add to the data. Only used when passing in numpy.ndarray, list, or tuple',
-             'default': None},
-            {'name': 'table_description', 'type': str,
-             'help': 'description for the internal DynamicTable used to store a pandas.DataFrame',
-             'default': ''})
+            {'name': 'description', 'type': str,
+             'doc': ('Description of the data. Required only when passing in a scalar, numpy.ndarray, '
+                     'list, tuple, or pandas.DataFrame. Ignored when passing in an NWBContainer, '
+                     'DynamicTable, or ScratchData object.'),
+             'default': None})
     def add_scratch(self, **kwargs):
-        '''Add data to the scratch space'''
-        data, name, notes = getargs('data', 'name', 'notes', kwargs)
-        if isinstance(data, (np.ndarray, pd.DataFrame, list, tuple)):
+        '''Add data to the scratch space.'''
+        data, name, description = getargs('data', 'name', 'description', kwargs)
+        if isinstance(data, (str, int, float, bytes, np.ndarray, list, tuple, pd.DataFrame)):
             if name is None:
-                raise ValueError('please provide a name for scratch data')
+                msg = ('A name is required for NWBFile.add_scratch when adding a scalar, numpy.ndarray, '
+                       'list, tuple, or pandas.DataFrame as scratch data.')
+                raise ValueError(msg)
+            if description is None:
+                msg = ('A description is required for NWBFile.add_scratch when adding a scalar, numpy.ndarray, '
+                       'list, tuple, or pandas.DataFrame as scratch data.')
+                raise ValueError(msg)
             if isinstance(data, pd.DataFrame):
-                table_description = getargs('table_description', kwargs)
-                data = DynamicTable.from_dataframe(df=data, name=name, table_description=table_description)
-                if notes is not None:
-                    warn('Notes argument is ignored when adding a pandas DataFrame to scratch')
+                data = DynamicTable.from_dataframe(df=data, name=name, table_description=description)
             else:
-                data = ScratchData(name=name, data=data, notes=notes)
+                data = ScratchData(name=name, data=data, description=description)
         else:
-            if notes is not None:
-                warn('Notes argument is ignored when adding an NWBContainer to scratch')
             if name is not None:
-                warn('Name argument is ignored when adding an NWBContainer to scratch')
-        self._add_scratch(data)
+                warn('The name argument is ignored when adding an NWBContainer, ScratchData, or '
+                     'DynamicTable to scratch.')
+            if description is not None:
+                warn('The description argument is ignored when adding an NWBContainer, ScratchData, or '
+                     'DynamicTable to scratch.')
+        return self._add_scratch(data)
 
     @docval({'name': 'name', 'type': str, 'help': 'the name of the object to get'},
             {'name': 'convert', 'type': bool, 'help': 'return the original data, not the NWB object', 'default': True})

src/pynwb/io/core.py

@@ -7,7 +7,7 @@
 from .. import register_map
 
 from pynwb.file import NWBFile
-from pynwb.core import NWBData, NWBContainer
+from pynwb.core import NWBData, NWBContainer, ScratchData
 from pynwb.misc import Units
 
 
@@ -39,6 +39,14 @@ def carg_data(self, builder, manager):
         return builder.data
 
 
+@register_map(ScratchData)
+class ScratchDataMap(NWBContainerMapper):
+
+    def __init__(self, spec):
+        super().__init__(spec)
+        self.map_spec('description', spec.get_attribute('notes'))
+
+
 class NWBTableRegionMap(NWBDataMap):
 
     @ObjectMapper.constructor_arg('table')

tests/integration/hdf5/test_scratch.py

@@ -11,7 +11,7 @@ class TestScratchDataIO(NWBH5IOMixin, TestCase):
 
     def setUpContainer(self):
         """ Return the test ScratchData to read/write """
-        return ScratchData(name='foo', data=[1, 2, 3, 4], notes='test scratch')
+        return ScratchData(name='foo', data=[1, 2, 3, 4], description='test scratch')
 
     def addContainer(self, nwbfile):
         """ Add the test ScratchData to the given NWBFile """
@@ -29,7 +29,7 @@ def roundtrip_scratch(self, data, case, **kwargs):
                           identifier=identifier,
                           session_start_time=self.start_time,
                           file_create_date=self.create_date)
-        nwbfile.add_scratch(data, name='foo', notes='test scratch', **kwargs)
+        nwbfile.add_scratch(data, name='foo', **kwargs)
 
         self.writer = NWBHDF5IO(self.filename, mode='w')
         self.writer.write(nwbfile)
@@ -39,61 +39,49 @@ def roundtrip_scratch(self, data, case, **kwargs):
         self.read_nwbfile = self.reader.read()
         return self.read_nwbfile.get_scratch('foo')
 
+    def test_scratch_convert_int(self):
+        data = 2
+        ret = self.roundtrip_scratch(data, 'int', description='test scratch')
+        self.assertEqual(data, ret)
+        self.validate()
+
     def test_scratch_convert_list(self):
         data = [1, 2, 3, 4]
-        ret = self.roundtrip_scratch(data, 'list')
+        ret = self.roundtrip_scratch(data, 'list', description='test scratch')
         assert_array_equal(data, ret)
         self.validate()
 
     def test_scratch_convert_ndarray(self):
         data = np.array([1, 2, 3, 4])
-        ret = self.roundtrip_scratch(data, 'ndarray')
+        ret = self.roundtrip_scratch(data, 'ndarray', description='test scratch')
         assert_array_equal(data, ret)
         self.validate()
 
-    def test_scratch_convert_DataFrame(self):
-        data = pd.DataFrame(data={'col1': [1, 2, 3, 4], 'col2': ['a', 'b', 'c', 'd']})
-        warn_msg = 'Notes argument is ignored when adding a pandas DataFrame to scratch'
-        with self.assertWarnsWith(UserWarning, warn_msg):
-            ret = self.roundtrip_scratch(data, 'DataFrame')
-        assert_array_equal(data.values, ret.values)
-        assert_array_equal(data.index.values, ret.index.values)
-        self.validate()
-
     def test_scratch_convert_DataFrame_table_desc(self):
         """Test round trip convert of DataFrame with a table description"""
         data = pd.DataFrame(data={'col1': [1, 2, 3, 4], 'col2': ['a', 'b', 'c', 'd']})
-
-        case = 'dataframe_desc'
-        self.filename = 'test_scratch_%s.nwb' % case
-        description = 'a file to test writing and reading a scratch data of type %s' % case
-        identifier = 'TEST_scratch_%s' % case
-        nwbfile = NWBFile(session_description=description,
-                          identifier=identifier,
-                          session_start_time=self.start_time,
-                          file_create_date=self.create_date)
-        nwbfile.add_scratch(data, name='foo', table_description='my_table')
-
-        self.writer = NWBHDF5IO(self.filename, mode='w')
-        self.writer.write(nwbfile)
-        self.writer.close()
-
-        self.reader = NWBHDF5IO(self.filename, mode='r')
-        self.read_nwbfile = self.reader.read()
-
+        self.roundtrip_scratch(data, 'DataFrame', description='my_table')
         ret = self.read_nwbfile.get_scratch('foo', convert=False)
         ret_df = ret.to_dataframe()
         self.assertEqual(ret.description, 'my_table')
         assert_array_equal(data.values, ret_df.values)
         assert_array_equal(data.index.values, ret_df.index.values)
         self.validate()
 
-    def _test_scratch_container(self, validate=True, **kwargs):
-        data = TimeSeries(name='test_ts', data=[1, 2, 3, 4, 5], unit='unit', timestamps=[1.1, 1.2, 1.3, 1.4, 1.5])
-        nwbfile = NWBFile(session_description='test', identifier='test', session_start_time=self.start_time,
-                          file_create_date=self.create_date)
-
-        nwbfile.add_scratch(data, **kwargs)
+    def test_scratch_container(self):
+        data = TimeSeries(
+            name='test_ts',
+            data=[1, 2, 3, 4, 5],
+            unit='unit',
+            timestamps=[1.1, 1.2, 1.3, 1.4, 1.5]
+        )
+        nwbfile = NWBFile(
+            session_description='test',
+            identifier='test',
+            session_start_time=self.start_time,
+            file_create_date=self.create_date
+        )
+        nwbfile.add_scratch(data)
 
         self.writer = NWBHDF5IO(self.filename, mode='w')
         self.writer.write(nwbfile)
@@ -104,18 +92,4 @@ def _test_scratch_container(self, validate=True, **kwargs):
         ret = self.read_nwbfile.get_scratch('test_ts')
 
         self.assertContainerEqual(data, ret)
-        if validate:
-            self.validate()
-
-    def test_scratch_container(self):
-        self._test_scratch_container(validate=True)
-
-    def test_scratch_container_with_name(self):
-        warn_msg = 'Name argument is ignored when adding an NWBContainer to scratch'
-        with self.assertWarnsWith(UserWarning, warn_msg):
-            self._test_scratch_container(validate=False, name='foo')
-
-    def test_scratch_container_with_notes(self):
-        warn_msg = 'Notes argument is ignored when adding an NWBContainer to scratch'
-        with self.assertWarnsWith(UserWarning, warn_msg):
-            self._test_scratch_container(validate=False, notes='test scratch')
+        self.validate()