From 3ad7aa370907c2cc177d033065dcba52140ca5a7 Mon Sep 17 00:00:00 2001
From: Ryan Ly <rly@lbl.gov>
Date: Thu, 25 Apr 2024 11:44:26 -0500
Subject: [PATCH] Make Units.waveform_mean and Units.waveform_sd ragged (#576)

---
 core/nwb.misc.yaml                          | 32 +++++++++++++++++----
 docs/format/source/format_release_notes.rst |  5 ++++
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/core/nwb.misc.yaml b/core/nwb.misc.yaml
index e743ac6b..40dd1fd8 100644
--- a/core/nwb.misc.yaml
+++ b/core/nwb.misc.yaml
@@ -242,7 +242,13 @@ groups:
     - - null
       - null
       - null
-    doc: Spike waveform mean for each spike unit.
+    doc: Spike waveform mean for each spike unit. The 'waveform_mean_index'
+      column indexes which waveforms in this column belong to a given unit, where each waveform
+      was recorded from a different electrode. The 'electrodes' column should be used to indicate which
+      electrodes are associated with each unit, and the order of the mean waveforms for a given unit 
+      in the 'waveform_mean' dataset should be the same as the order of the electrodes referenced in
+      the 'electrodes' column of this table. The number of samples for each waveform mean must be the
+      same.
     quantity: '?'
     attributes:
     - name: sampling_rate
@@ -254,6 +260,11 @@ groups:
       value: volts
       doc: Unit of measurement. This value is fixed to 'volts'.
       required: false
+  - name: waveform_mean_index
+    neurodata_type_inc: VectorIndex
+    doc: Optional index into the 'waveform_mean' dataset to allow each unit to have a different number of mean
+      waveforms, one per electrode. See 'waveform_mean' for more details.
+    quantity: '?'
   - name: waveform_sd
     neurodata_type_inc: VectorData
     dtype: float32
@@ -269,7 +280,13 @@ groups:
     - - null
       - null
       - null
-    doc: Spike waveform standard deviation for each spike unit.
+    doc: Spike waveform standard deviation for each spike unit. The 'waveform_sd_index'
+      column indexes which waveforms in this column belong to a given unit, where each waveform
+      was recorded from a different electrode. The 'electrodes' column should be used to indicate which
+      electrodes are associated with each unit, and the order of the waveform standard deviations for a
+      given unit in the 'waveform_sd' dataset should be the same as the order of the electrodes referenced
+      in the 'electrodes' column of this table. The number of samples for each waveform standard deviation
+      must be the same.
     quantity: '?'
     attributes:
     - name: sampling_rate
@@ -281,6 +298,11 @@ groups:
       value: volts
       doc: Unit of measurement. This value is fixed to 'volts'.
       required: false
+  - name: waveform_sd_index
+    neurodata_type_inc: VectorIndex
+    doc: Optional index into the 'waveform_sd' dataset to allow each unit to have a different number of
+      waveform standard deviations, one per electrode. See 'waveform_sd' for more details.
+    quantity: '?'
   - name: waveforms
     neurodata_type_inc: VectorData
     dtype: numeric
@@ -305,7 +327,7 @@ groups:
       associated with a single waveform), then the 'waveforms_index' column will have values 1, 2, ..., N, where N is
       the number of spike events. The number of electrodes for each spike event should be the same within a given unit.
       The 'electrodes' column should be used to indicate which electrodes are associated with each unit, and the order
-      of the waveforms within a given unit x spike event should be in the same order as the electrodes referenced in
+      of the waveforms within a given unit x spike event should be the same as the order of the electrodes referenced in
       the 'electrodes' column of this table. The number of samples for each waveform must be the same."
     quantity: '?'
     attributes:
@@ -320,10 +342,10 @@ groups:
         required: false
   - name: waveforms_index
     neurodata_type_inc: VectorIndex
-    doc: Index into the waveforms dataset. One value for every spike event. See 'waveforms' for more detail.
+    doc: Index into the 'waveforms' dataset. One value for every spike event. See 'waveforms' for more detail.
     quantity: '?'
   - name: waveforms_index_index
     neurodata_type_inc: VectorIndex
-    doc: Index into the waveforms_index dataset. One value for every unit (row in the table). See 'waveforms' for more
+    doc: Index into the 'waveforms_index' dataset. One value for every unit (row in the table). See 'waveforms' for more
       detail.
     quantity: '?'
diff --git a/docs/format/source/format_release_notes.rst b/docs/format/source/format_release_notes.rst
index 2d9805ff..b5b837e0 100644
--- a/docs/format/source/format_release_notes.rst
+++ b/docs/format/source/format_release_notes.rst
@@ -8,6 +8,11 @@ Release Notes
 Minor changes
 ^^^^^^^^^^^^^
 - Added support to set boundary metadata for ``SpatialSeries``. (#524)
+- Added columns ``waveform_mean_index`` and ``waveform_sd_index`` to ``Units`` to make the ``waveform_mean`` and
+  ``waveform_sd`` columns ragged. This allows for a different number of waveform means/SDs per unit which is useful
+  when each unit is associated with a different number of electrodes and there is a waveform mean/SD for each
+  electrode and unit. (#576)
+
 
 2.7.0 (February 7, 2024)
 ------------------------