diff --git a/CHANGELOG.md b/CHANGELOG.md index 25317ee8f..971c9d799 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,9 @@ ## PyNWB 2.8.3 (Upcoming) +### Documentation and tutorial enhancements +- Added documentation example for `SpikeEventSeries`. @stephprince [#1983](https://github.com/NeurodataWithoutBorders/pynwb/pull/1983) + ### Performance - Cache global type map to speed import 3X. @sneakers-the-rat [#1931](https://github.com/NeurodataWithoutBorders/pynwb/pull/1931) diff --git a/docs/gallery/domain/ecephys.py b/docs/gallery/domain/ecephys.py index 3f239eb77..48a979272 100644 --- a/docs/gallery/domain/ecephys.py +++ b/docs/gallery/domain/ecephys.py @@ -31,7 +31,7 @@ from dateutil.tz import tzlocal from pynwb import NWBHDF5IO, NWBFile -from pynwb.ecephys import LFP, ElectricalSeries +from pynwb.ecephys import LFP, ElectricalSeries, SpikeEventSeries ####################### # Creating and Writing NWB files @@ -244,8 +244,8 @@ #################### # .. _units_electrode: # -# Spike Times -# ^^^^^^^^^^^ +# Sorted spike times +# ^^^^^^^^^^^^^^^^^^ # # Spike times are stored in the :py:class:`~pynwb.misc.Units` table, which is a subclass of # :py:class:`~hdmf.common.table.DynamicTable`. Adding columns to the :py:class:`~pynwb.misc.Units` table is analogous @@ -272,6 +272,29 @@ nwbfile.units.to_dataframe() +#################### +# Unsorted spike times +# ^^^^^^^^^^^^^^^^^^^^ +# +# While the :py:class:`~pynwb.misc.Units` table is used to store spike times and waveform data for +# spike-sorted, single-unit activity, you may also want to store spike times and waveform snippets of +# unsorted spiking activity (e.g., multi-unit activity detected via threshold crossings during data acquisition). +# This information can be stored using :py:class:`~pynwb.ecephys.SpikeEventSeries` objects. + +spike_snippets = np.random.rand(20, 3, 40) # 20 events, 3 channels, 40 samples per event +shank0 = nwbfile.create_electrode_table_region( + region=[0, 1, 2], + description="shank0", +) + + +spike_events = SpikeEventSeries(name='SpikeEvents_Shank0', + description="events detected with 100uV threshold", + data=spike_snippets, + timestamps=np.arange(20), + electrodes=shank0) +nwbfile.add_acquisition(spike_events) + ####################### # Designating electrophysiology data # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -283,17 +306,17 @@ # :py:mod:`API documentation ` and :ref:`basics` for more details on # using these objects. # -# For storing spike data, there are two options. Which one you choose depends on what data you have available. -# If you need to store the complete, continuous raw voltage traces, you should store the traces with +# For storing unsorted spiking data, there are two options. Which one you choose depends on what data you +# have available. If you need to store the complete, continuous raw voltage traces, you should store the traces with # :py:class:`~pynwb.ecephys.ElectricalSeries` objects as :ref:`acquisition ` data, and use # the :py:class:`~pynwb.ecephys.EventDetection` class for identifying the spike events in your raw traces. # If you do not want to store the raw voltage traces and only the waveform 'snippets' surrounding spike events, -# you should use the :py:class:`~pynwb.ecephys.EventWaveform` class, which can store one or more -# :py:class:`~pynwb.ecephys.SpikeEventSeries` objects. +# you should use :py:class:`~pynwb.ecephys.SpikeEventSeries` objects. # # The results of spike sorting (or clustering) should be stored in the top-level :py:class:`~pynwb.misc.Units` table. -# Note that it is not required to store spike waveforms in order to store spike events or mean waveforms--if you only -# want to store the spike times of clustered units you can use only the Units table. +# The :py:class:`~pynwb.misc.Units` table can contain simply the spike times of sorted units, or you can also include +# individual and mean waveform information in some of the optional, predefined :py:class:`~pynwb.misc.Units` table +# columns: ``waveform_mean``, ``waveform_sd``, or ``waveforms``. # # For local field potential data, there are two options. Again, which one you choose depends on what data you # have available. With both options, you should store your traces with :py:class:`~pynwb.ecephys.ElectricalSeries`