SpatialSeries bounds field

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Enhancements and minor changes
 - Added support for python 3.12 and upgraded dependency versions. This also includes infrastructure updates for developers. @mavaylon1 [#1853](https://github.com/NeurodataWithoutBorders/pynwb/pull/1853)
+- Added `bounds` to `SpatialSeries` as an optional field to set (unenforced) boundary range, i.e.,  (min, max), for each dimension of ``data``. @mavaylon1 [#1866](https://github.com/NeurodataWithoutBorders/pynwb/pull/1866)
 
 ### Bug fixes
 - Fix bug with reading file with linked `TimeSeriesReferenceVectorData` @rly [#1865](https://github.com/NeurodataWithoutBorders/pynwb/pull/1865)

docs/gallery/domain/plot_behavior.py

@@ -105,13 +105,17 @@
 #
 # For position data ``reference_frame`` indicates the zero-position, e.g.
 # the 0,0 point might be the bottom-left corner of an enclosure, as viewed from the tracking camera.
+# In :py:class:`~pynwb.behavior.SpatialSeries`, the ``bounds`` field allows the user to set
+# the boundary range, i.e.,  (min, max), for each dimension of ``data``. The units are the same as in ``data``.
+# This field does not enforce a boundary on the dataset itself.
 
 timestamps = np.linspace(0, 50) / 200
 
 position_spatial_series = SpatialSeries(
     name="SpatialSeries",
     description="Position (x, y) in an open field.",
     data=position_data,
+    bounds=[(0,50), (0,50)],
     timestamps=timestamps,
     reference_frame="(0,0) is bottom left corner",
 )

src/pynwb/behavior.py

@@ -23,9 +23,11 @@ class SpatialSeries(TimeSeries):
     __nwbfields__ = ('reference_frame',)
 
     @docval(*get_docval(TimeSeries.__init__, 'name'),  # required
-            {'name': 'data', 'type': ('array_data', 'data', TimeSeries), 'shape': ((None, ), (None, None)),  # required
+            {'name': 'data', 'type': ('array_data', 'data', TimeSeries), 'shape': ((None, ), (None, None)), # required
              'doc': ('The data values. Can be 1D or 2D. The first dimension must be time. If 2D, there can be 1, 2, '
                      'or 3 columns, which represent x, y, and z.')},
+            {'name': 'bounds', 'type': list, 'shape': ((None, ), (None, None), (None, None, None)), 'default': None,
+             'doc': 'The boundary range (min, max) for each dimension of data.'},
             {'name': 'reference_frame', 'type': str,   # required
              'doc': 'description defining what the zero-position is'},
             {'name': 'unit', 'type': str, 'doc': 'The base unit of measurement (should be SI unit)',
@@ -36,7 +38,7 @@ def __init__(self, **kwargs):
         """
         Create a SpatialSeries TimeSeries dataset
         """
-        name, data, reference_frame, unit = popargs('name', 'data', 'reference_frame', 'unit', kwargs)
+        name, data, bounds, reference_frame, unit = popargs('name', 'data', 'bounds', 'reference_frame', 'unit', kwargs)
         super().__init__(name, data, unit, **kwargs)
 
         # NWB 2.5 restricts length of second dimension to be <= 3
@@ -47,6 +49,7 @@ def __init__(self, **kwargs):
                           "The second dimension should have length <= 3 to represent at most x, y, z." %
                           (name, str(data_shape)))
 
+        self.bounds = bounds
         self.reference_frame = reference_frame
 
     @staticmethod

tests/unit/test_behavior.py

@@ -12,11 +12,13 @@ def test_init(self):
         sS = SpatialSeries(
             name='test_sS',
             data=np.ones((3, 2)),
+            bounds=[(-1,1),(-1,1),(-1,1)],
             reference_frame='reference_frame',
             timestamps=[1., 2., 3.]
         )
         self.assertEqual(sS.name, 'test_sS')
         self.assertEqual(sS.unit, 'meters')
+        self.assertEqual(sS.bounds, [(-1,1),(-1,1),(-1,1)])
         self.assertEqual(sS.reference_frame, 'reference_frame')
 
     def test_set_unit(self):