Proposal: Add waveform Timing Context for Units Table #667
Description
From a discussion with @alejoe91
The current waveform_mean and waveform_sd datasets include a sampling_rate attribute (but see #664), which combined with the shape allows users to calculate the total duration of the waveform window. However, there is no way to determine where the spike peak (the alignment point) occurs within that window. This information is essential for proper interpretation of waveform data, as users need to know the temporal relationship between the waveform samples and the spike event itself.
I propose adding a new attribute waveform_peak_time_ms to specify the time in milliseconds from the start of the waveform to the peak. The peak is defined as the alignment point used during spike sorting, typically the point of maximum absolute amplitude. This attribute, combined with the existing sampling_rate (or waveform_rate in pynwb) and the number of samples from the shape, fully specifies the temporal structure of the waveform. See the diagram below for a visual representation.
I have chosen waveform_peak_time_ms because it follows the existing waveform_* naming pattern used by other waveform-related attributes (waveform_mean, waveform_sd, waveform_rate). The name is unambiguous and always positive, representing the time from the start of the waveform to the peak, unlike alternatives such as offset_to_peak_ms (unclear reference point and sign convention) or peak_offset_ms (ambiguous direction). Including _ms in the name makes the unit explicit, avoiding confusion about units.