From 054390efe9df49ffb5dd6731ab2d164ea25c6288 Mon Sep 17 00:00:00 2001 From: rly Date: Fri, 19 Jul 2024 10:14:14 -0700 Subject: [PATCH 1/3] Improve docs around waveforms --- src/pynwb/misc.py | 45 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 38 insertions(+), 7 deletions(-) diff --git a/src/pynwb/misc.py b/src/pynwb/misc.py index 14c2e08d1..9989b3b5f 100644 --- a/src/pynwb/misc.py +++ b/src/pynwb/misc.py @@ -137,11 +137,42 @@ class Units(DynamicTable): 'resolution' ) - waveforms_desc = ('Individual waveforms for each spike. If the dataset is three-dimensional, the third dimension ' - 'shows the response from different electrodes that all observe this unit simultaneously. In this' - ' case, the `electrodes` column of this Units table should be used to indicate which electrodes ' - 'are associated with this unit, and the electrodes dimension here should be in the same order as' - ' the electrodes referenced in the `electrodes` column of this table.') + __waveforms_desc = ( + """ + Individual waveforms for each spike. If the dataset is three-dimensional, the third dimension + shows the response from different electrodes that all observe this unit simultaneously. In this + case, the ``electrodes`` column of this Units table should be used to indicate which electrodes + are associated with this unit, and the electrodes dimension here should be in the same order as + the electrodes referenced in the ``electrodes`` column of this table. + + Example usage:: + + waveforms_list = [ + [ # unit 1 + np.array([ # electrode 1 + [1, 2, 3, 4, 5], # spike time 1 [sample 1, sample 2, ...] + [2, 3, 4, 5, 6], # spike time 2 + ]), + np.array([ # electrode 2 + [3, 4, 5, 6, 7], # spike time 1 [sample 1, sample 2, ...] + ]), + ], + [ # unit 2 + np.array([ # electrode 1 + [10, 20, 30, 40, 50], # spike time 1 [sample 1, sample 2, ...] + ]), + ], + ] + electrodes_list = [[1, 2], [3]] + for unit_id in range(2): + nwbfile.add_unit( + id=unit_id, + electrodes=electrodes_list[unit_id], + waveforms=waveforms_list[unit_id] + ) + """ + ) + __columns__ = ( {'name': 'spike_times', 'description': 'the spike times for each unit', 'index': True}, {'name': 'obs_intervals', 'description': 'the observation intervals for each unit', @@ -151,7 +182,7 @@ class Units(DynamicTable): {'name': 'electrode_group', 'description': 'the electrode group that each spike unit came from'}, {'name': 'waveform_mean', 'description': 'the spike waveform mean for each spike unit'}, {'name': 'waveform_sd', 'description': 'the spike waveform standard deviation for each spike unit'}, - {'name': 'waveforms', 'description': waveforms_desc, 'index': 2} + {'name': 'waveforms', 'description': __waveforms_desc, 'index': 2} ) @docval({'name': 'name', 'type': str, 'doc': 'Name of this Units interface', 'default': 'Units'}, @@ -195,7 +226,7 @@ def __init__(self, **kwargs): 'default': None}, {'name': 'waveform_sd', 'type': 'array_data', 'default': None, 'doc': 'the spike waveform standard deviation for each unit. Shape is (time,) or (time, electrodes)'}, - {'name': 'waveforms', 'type': 'array_data', 'default': None, 'doc': waveforms_desc, + {'name': 'waveforms', 'type': 'array_data', 'default': None, 'doc': __waveforms_desc, 'shape': ((None, None), (None, None, None))}, {'name': 'id', 'type': int, 'default': None, 'doc': 'the id for each unit'}, allow_extra=True) From 291e89c78cd0f84f9abd0fe1e763e59fdc4c145d Mon Sep 17 00:00:00 2001 From: rly Date: Fri, 19 Jul 2024 10:17:10 -0700 Subject: [PATCH 2/3] Update changelog --- CHANGELOG.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3d3dae88c..d1daf1103 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,10 +3,11 @@ ## PyNWB 2.8.2 (Upcoming) ### Documentation and tutorial enhancements -- Added pre-release pull request instructions to release process documentation @stephprince [#1928](https://github.com/NeurodataWithoutBorders/pynwb/pull/1928) +- Added pre-release pull request instructions to release process documentation. @stephprince [#1928](https://github.com/NeurodataWithoutBorders/pynwb/pull/1928) +- Improve docs for specifying waveforms in the Units table. @rly [#1936](https://github.com/NeurodataWithoutBorders/pynwb/pull/1936) ### Bug fixes -- Fixed `can_read` method to return False if no nwbfile version can be found @stephprince [#1934](https://github.com/NeurodataWithoutBorders/pynwb/pull/1934) +- Fixed `can_read` method to return False if no nwbfile version can be found. @stephprince [#1934](https://github.com/NeurodataWithoutBorders/pynwb/pull/1934) - Changed `epoch_tags` to be a NWBFile property instead of constructor argument. @stephprince [#1935](https://github.com/NeurodataWithoutBorders/pynwb/pull/1935) ## PyNWB 2.8.1 (July 3, 2024) From da0e55a6d2e92977255a7508ea921c9442c8d008 Mon Sep 17 00:00:00 2001 From: rly Date: Tue, 23 Jul 2024 14:21:46 -0700 Subject: [PATCH 3/3] Improve doc --- src/pynwb/misc.py | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/src/pynwb/misc.py b/src/pynwb/misc.py index 9989b3b5f..b84b255d3 100644 --- a/src/pynwb/misc.py +++ b/src/pynwb/misc.py @@ -137,7 +137,7 @@ class Units(DynamicTable): 'resolution' ) - __waveforms_desc = ( + __add_unit_waveforms_desc = ( """ Individual waveforms for each spike. If the dataset is three-dimensional, the third dimension shows the response from different electrodes that all observe this unit simultaneously. In this @@ -148,20 +148,21 @@ class Units(DynamicTable): Example usage:: waveforms_list = [ - [ # unit 1 - np.array([ # electrode 1 - [1, 2, 3, 4, 5], # spike time 1 [sample 1, sample 2, ...] - [2, 3, 4, 5, 6], # spike time 2 - ]), - np.array([ # electrode 2 - [3, 4, 5, 6, 7], # spike time 1 [sample 1, sample 2, ...] - ]), - ], - [ # unit 2 - np.array([ # electrode 1 + np.array([ # unit 1 + [ # electrode 1 + [1, 2, 3, 4, 5], # spike 1 [sample 1, sample 2, ...] + [2, 3, 4, 5, 6], # spike 2 + ], + [ # electrode 2 + [3, 4, 5, 6, 7], # spike 1 [sample 1, sample 2, ...] + [2, 3, 4, 5, 6], # spike 2 + ], + ]), + np.array([ # unit 2 + [ # electrode 1 [10, 20, 30, 40, 50], # spike time 1 [sample 1, sample 2, ...] - ]), - ], + ], + ]), ] electrodes_list = [[1, 2], [3]] for unit_id in range(2): @@ -182,7 +183,7 @@ class Units(DynamicTable): {'name': 'electrode_group', 'description': 'the electrode group that each spike unit came from'}, {'name': 'waveform_mean', 'description': 'the spike waveform mean for each spike unit'}, {'name': 'waveform_sd', 'description': 'the spike waveform standard deviation for each spike unit'}, - {'name': 'waveforms', 'description': __waveforms_desc, 'index': 2} + {'name': 'waveforms', 'description': 'individual waveforms for each spike', 'index': 2} ) @docval({'name': 'name', 'type': str, 'doc': 'Name of this Units interface', 'default': 'Units'}, @@ -226,7 +227,7 @@ def __init__(self, **kwargs): 'default': None}, {'name': 'waveform_sd', 'type': 'array_data', 'default': None, 'doc': 'the spike waveform standard deviation for each unit. Shape is (time,) or (time, electrodes)'}, - {'name': 'waveforms', 'type': 'array_data', 'default': None, 'doc': __waveforms_desc, + {'name': 'waveforms', 'type': 'array_data', 'default': None, 'doc': __add_unit_waveforms_desc, 'shape': ((None, None), (None, None, None))}, {'name': 'id', 'type': int, 'default': None, 'doc': 'the id for each unit'}, allow_extra=True)