Add a SweepTable for icephys data

For icephys a common data acquisition method is to acquire data from
multiple electrodes in one run. This "run" is commonly called a sweep.

Now at the moment there exists no way of grouping PatchClampSeries
together in a NWB file.

The SweepTable solves that problem. It is a table with two columns
"sweep_number" and a vector of links to PatchClampSeries.

Now whenever someone adds some TimeSeries via
NWBFile.add_acquisition/add_stimulus/add_stimulus_template we check if
the added element is a PatchClampSeries and has a valid sweep number. In
that case we add, or append, to the SweepTable.

The sweep table is located at `/general/intracellular_ephys/sweep_table`
and is a DynamicTable.

Author: t-b

src/pynwb/data/nwb.file.yaml

@@ -391,6 +391,10 @@ groups:
       - neurodata_type_inc: IntracellularElectrode
         doc: 'One of possibly many. COMMENT: Name should be informative.'
         quantity: '*'
+      - neurodata_type_inc: SweepTable
+        name: sweep_table
+        doc: The table which groups different PatchClampSeries together.
+        quantity: '?'
       quantity: '?'
     - name: optogenetics
       doc: Metadata describing optogenetic stimuluation

src/pynwb/data/nwb.icephys.yaml

@@ -230,3 +230,35 @@ groups:
   - name: device
     doc: the device that was used to record from this electrode
     target_type: Device
+- neurodata_type_def: SweepTable
+  neurodata_type_inc: DynamicTable
+  doc: The table which groups different PatchClampSeries together.
+  attributes:
+  - name: help
+    dtype: text
+    doc: Value is 'The table which groups different PatchClampSeries together'
+    value: The table which groups different PatchClampSeries together
+  datasets:
+  - neurodata_type_inc: TableColumn
+    name: sweep_number
+    dtype: uint64
+    doc: The sweep number of the PatchClampSeries in that row.
+    attributes:
+    - name: description
+      dtype: text
+      doc: value is 'The sweep number of the PatchClampSeries in that row'
+      value: The sweep number of the PatchClampSeries in that row
+  - neurodata_type_inc: VectorData
+    name: series
+    dtype:
+      target_type: PatchClampSeries
+      reftype: object
+    doc: The PatchClampSeries with the sweep number in that row
+    attributes:
+    - name: help
+      dtype: text
+      doc: Value is 'The PatchClampSeries with the sweep number in that row'
+      value: The PatchClampSeries with the sweep number in that row
+  - neurodata_type_inc: VectorIndex
+    name: series_index
+    doc: Index for series

src/pynwb/file.py

@@ -11,7 +11,7 @@
 from .base import TimeSeries, ProcessingModule
 from .epoch import TimeIntervals
 from .ecephys import ElectrodeGroup, Device
-from .icephys import IntracellularElectrode
+from .icephys import IntracellularElectrode, SweepTable, PatchClampSeries
 from .ophys import ImagingPlane
 from .ogen import OptogeneticStimulusSite
 from .misc import Units
@@ -70,7 +70,7 @@ class NWBFile(MultiContainerInterface):
     __clsconf__ = [
         {
             'attr': 'acquisition',
-            'add': 'add_acquisition',
+            'add': '_add_acquisition_internal',
             'type': NWBDataInterface,
             'get': 'get_acquisition'
         },
@@ -82,13 +82,13 @@ class NWBFile(MultiContainerInterface):
         },
         {
             'attr': 'stimulus',
-            'add': 'add_stimulus',
+            'add': '_add_stimulus_internal',
             'type': TimeSeries,
             'get': 'get_stimulus'
         },
         {
             'attr': 'stimulus_template',
-            'add': 'add_stimulus_template',
+            'add': '_add_stimulus_template_internal',
             'type': TimeSeries,
             'get': 'get_stimulus_template'
         },
@@ -166,6 +166,7 @@ class NWBFile(MultiContainerInterface):
                      {'name': 'trials', 'child': True, 'required_name': 'trials'},
                      {'name': 'units', 'child': True, 'required_name': 'units'},
                      {'name': 'subject', 'child': True, 'required_name': 'subject'},
+                     {'name': 'sweep_table', 'child': True, 'required_name': 'sweep_table'},
                      'epoch_tags',)
 
     @docval({'name': 'session_description', 'type': str,
@@ -234,6 +235,8 @@ class NWBFile(MultiContainerInterface):
              'doc': 'the ElectrodeGroups that belong to this NWBFile', 'default': None},
             {'name': 'ic_electrodes', 'type': (list, tuple),
              'doc': 'IntracellularElectrodes that belong to this NWBFile', 'default': None},
+            {'name': 'sweep_table', 'type': SweepTable,
+             'doc': 'the SweepTable that belong to this NWBFile', 'default': None},
             {'name': 'imaging_planes', 'type': (list, tuple),
              'doc': 'ImagingPlanes that belong to this NWBFile', 'default': None},
             {'name': 'ogen_sites', 'type': (list, tuple),
@@ -288,6 +291,7 @@ def __init__(self, **kwargs):
         self.ogen_sites = getargs('ogen_sites', kwargs)
         self.time_intervals = getargs('time_intervals', kwargs)
         self.subject = getargs('subject', kwargs)
+        self.sweep_table = getargs('sweep_table', kwargs)
 
         recommended = [
             'experimenter',
@@ -500,6 +504,38 @@ def set_electrode_table(self, **kwargs):
         electrode_table = getargs('electrode_table', kwargs)
         self.electrodes = electrode_table
 
+    def _check_sweep_table(self):
+        """
+        Create a SweepTable if not yet done.
+        """
+        if self.sweep_table is None:
+            self.sweep_table = SweepTable(name='sweep_table')
+
+    def _update_sweep_table(self, nwbdata):
+        """
+        Add all PatchClampSeries with a valid sweep number to the sweep_table
+        """
+
+        if isinstance(nwbdata, PatchClampSeries):
+            if nwbdata.sweep_number is not None:
+                self._check_sweep_table()
+                self.sweep_table.add_entry(nwbdata)
+
+    @docval({'name': 'nwbdata', 'type': NWBDataInterface})
+    def add_acquisition(self, nwbdata):
+        self._add_acquisition_internal(nwbdata)
+        self._update_sweep_table(nwbdata)
+
+    @docval({'name': 'timeseries', 'type': TimeSeries})
+    def add_stimulus(self, timeseries):
+        self._add_stimulus_internal(timeseries)
+        self._update_sweep_table(timeseries)
+
+    @docval({'name': 'timeseries', 'type': TimeSeries})
+    def add_stimulus_template(self, timeseries):
+        self._add_stimulus_template_internal(timeseries)
+        self._update_sweep_table(timeseries)
+
 
 def _add_missing_timezone(date):
     """

src/pynwb/icephys.py

@@ -1,10 +1,10 @@
 from collections import Iterable
 
-from .form.utils import docval, popargs, fmt_docval_args
+from .form.utils import docval, popargs, fmt_docval_args, call_docval_func
 
 from . import register_class, CORE_NAMESPACE
 from .base import TimeSeries, _default_resolution, _default_conversion
-from .core import NWBContainer
+from .core import NWBContainer, DynamicTable, ElementIdentifiers
 from .device import Device
 
 
@@ -420,3 +420,65 @@ def __init__(self, **kwargs):
         name, data, unit = popargs('name', 'data', 'unit', kwargs)
         electrode, gain = popargs('electrode', 'gain', kwargs)
         super(VoltageClampStimulusSeries, self).__init__(name, data, unit, electrode, gain, **kwargs)
+
+
+@register_class('SweepTable', CORE_NAMESPACE)
+class SweepTable(DynamicTable):
+    """
+    A SweepTable allows to group PatchClampSeries together which stem from the same sweep.
+    """
+
+    __columns__ = (
+            {'name': 'series', 'description': 'PatchClampSeries with the same sweep number',
+             'required': True, 'vector_data': True},
+            {'name': 'sweep_number', 'description': 'Sweep number of the entries in that row', 'required': True}
+    )
+
+    @docval({'name': 'name', 'type': str, 'doc': 'name of this SweepTable', 'default': 'sweep_table'},
+            {'name': 'description', 'type': str, 'doc': 'Description of this SweepTable',
+             'default': "A sweep table groups different PatchClampSeries together."},
+            {'name': 'id', 'type': ('array_data', ElementIdentifiers), 'doc': 'the identifiers for this table',
+             'default': None},
+            {'name': 'columns', 'type': (tuple, list), 'doc': 'the columns in this table', 'default': None},
+            {'name': 'colnames', 'type': 'array_data', 'doc': 'the names of the columns in this table',
+             'default': None})
+    def __init__(self, **kwargs):
+        call_docval_func(super(SweepTable, self).__init__, kwargs)
+
+    @docval({'name': 'pcs', 'type': PatchClampSeries, 'doc': 'PatchClampSeries to add to the table ' +
+            'must have a valid sweep_number'})
+    def add_entry(self, pcs):
+        """
+        Add the passed PatchClampSeries to the sweep table.
+        """
+
+        kwargs = {'sweep_number': pcs.sweep_number, 'series': [pcs]}
+
+        # FIXME appending to an existing entry would be nicer
+        # but this seems to be not possible
+        self.add_row(**kwargs)
+
+    def get_series(self, sweep_number):
+        """
+        Return a list of PatchClampSeries for the given sweep number.
+        """
+
+        ids = self.__get_row_ids(sweep_number)
+
+        if len(ids) == 0:
+            return None
+
+        matches = []
+
+        for x in ids:
+            for y in self[(x, 'series')]:
+                matches.append(y)
+
+        return matches
+
+    def __get_row_ids(self, sweep_number):
+        """
+        Return the row ids for the given sweep number.
+        """
+
+        return [index for index, elem in enumerate(self['sweep_number'].data) if elem == sweep_number]

src/pynwb/io/file.py

@@ -28,6 +28,7 @@ def __init__(self, spec):
         icephys_spec = general_spec.get_group('intracellular_ephys')
         self.map_spec('ic_electrodes', icephys_spec.get_neurodata_type('IntracellularElectrode'))
         ecephys_spec = general_spec.get_group('extracellular_ephys')
+        self.map_spec('sweep_table', icephys_spec.get_neurodata_type('SweepTable'))
         self.map_spec('electrodes', ecephys_spec.get_group('electrodes'))
         self.map_spec('electrode_groups', ecephys_spec.get_neurodata_type('ElectrodeGroup'))
         self.map_spec(

src/pynwb/io/icephys.py

@@ -0,0 +1,9 @@
+from .. import register_map
+
+from pynwb.icephys import SweepTable
+from .core import DynamicTableMap
+
+
+@register_map(SweepTable)
+class SweepTableMap(DynamicTableMap):
+    pass