Merge branch 'dev' into fix/make-gain-optional

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)
 

docs/gallery/advanced_io/plot_editing.py

@@ -24,6 +24,9 @@
 
 First, let's create an NWB file with data:
 """
+
+# sphinx_gallery_thumbnail_path = "figures/gallery_thumbnails_editing.png"
+
 from pynwb import NWBHDF5IO, NWBFile, TimeSeries
 from datetime import datetime
 from dateutil.tz import tzlocal

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 <pynwb.ecephys>` 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 <basic_timeseries>` 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`

docs/gallery/general/plot_configurator.py

@@ -8,18 +8,18 @@
 Introduction
 -------------
 Users will create a configuration YAML file that outlines the fields (within a neurodata type)
-they want to be validated against a set of allowed terms. 
+they want to be validated against a set of allowed terms.
 After creating the configuration file, users will need to load the
 configuration file with the :py:func:`~pynwb.load_type_config` method.
 With the configuration loaded, every instance of the neurodata
 types defined in the configuration file will have the respective fields wrapped with a
 :py:class:`~hdmf.term_set.TermSetWrapper`.
 This automatic wrapping is what provides the term validation for the field value.
 For greater control on which datasets and attributes are validated
-against which sets of allowed terms, use the 
+against which sets of allowed terms, use the
 :py:class:`~hdmf.term_set.TermSetWrapper` on individual datasets and attributes instead.
-You can follow the 
-`TermSet tutorial in the HDMF documentation 
+You can follow the
+`TermSet tutorial in the HDMF documentation
 <https://hdmf.readthedocs.io/en/stable/tutorials/plot_term_set.html#sphx-glr-tutorials-plot-term-set-py>`_
 for more information.
 
@@ -42,6 +42,8 @@
 3. Each data type will have a list of fields associated with a :py:class:`~hdmf.term_set.TermSet`.
    The user can use the same or unique TermSet instances for each field.
 """
+# sphinx_gallery_thumbnail_path = 'figures/gallery_thumbnails_configurator.png'
+
 try:
     import linkml_runtime  # noqa: F401
 except ImportError as e: