From 80fc386c20d791208142f97e8cfacbce967b8aee Mon Sep 17 00:00:00 2001
From: Steph Prince <40640337+stephprince@users.noreply.github.com>
Date: Thu, 19 Dec 2024 10:12:53 -0800
Subject: [PATCH] update extracellular electrophysiology tutorial (#2012)

* update filteredephys, decomp, spikeevent examples

* update CHANGELOG
---
 CHANGELOG.md                   |  3 +++
 docs/gallery/domain/ecephys.py | 18 +++++++++---------
 2 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fc360b840..4fcdcb4ac 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,9 @@
   - Deprecated `ImageMaskSeries` neurodata type. @rly [#1941](https://github.com/NeurodataWithoutBorders/pynwb/pull/1941)
 - Removed python 3.8 support, added python 3.13 support. @stephprince [#2007](https://github.com/NeurodataWithoutBorders/pynwb/pull/2007)
 
+### Documentation and tutorial enhancements
+- Updated `SpikeEventSeries`, `DecompositionSeries`, and `FilteredEphys` examples. @stephprince [#2012](https://github.com/NeurodataWithoutBorders/pynwb/pull/2012)
+
 ## PyNWB 2.8.3 (November 19, 2024)
 
 ### Enhancements and minor changes
diff --git a/docs/gallery/domain/ecephys.py b/docs/gallery/domain/ecephys.py
index b66698044..11e39b44a 100644
--- a/docs/gallery/domain/ecephys.py
+++ b/docs/gallery/domain/ecephys.py
@@ -208,6 +208,7 @@
     name="ElectricalSeries",
     description="LFP data",
     data=lfp_data,
+    filtering='Low-pass filter at 300 Hz',
     electrodes=all_table_region,
     starting_time=0.0,
     rate=200.0,
@@ -237,8 +238,8 @@
 lfp = LFP(electrical_series=lfp_electrical_series)
 
 ####################
-# Unlike the raw data, which we put into the acquisition group of the :py:class:`~pynwb.file.NWBFile`,
-# LFP data is typically considered processed data because the raw data was filtered and downsampled to generate the LFP.
+# LFP refers to data that has been low-pass filtered, typically below 300 Hz. This data may also be downsampled. 
+# Because it is filtered and potentially resampled, it is categorized as processed data.
 #
 # Create a processing module named ``"ecephys"`` and add the :py:class:`~pynwb.ecephys.LFP` object to it.
 # This is analogous to how we can store the :py:class:`~pynwb.behavior.Position` object in a processing module
@@ -250,9 +251,9 @@
 ecephys_module.add(lfp)
 
 #######################
-# If the derived data is filtered but not downsampled, you can store the data in an
-# :py:class:`~pynwb.ecephys.ElectricalSeries` object in a :py:class:`~pynwb.ecephys.FilteredEphys` object
-# instead of a :py:class:`~pynwb.ecephys.LFP` object.
+# If your data is filtered for frequency ranges other than LFP — such as Gamma or Theta — you should store it in an
+# :py:class:`~pynwb.ecephys.ElectricalSeries` and encapsulate it within a 
+# :py:class:`~pynwb.ecephys.FilteredEphys` object.
 
 from pynwb.ecephys import FilteredEphys
 
@@ -261,6 +262,7 @@
     name="FilteredElectricalSeries",
     description="Filtered data",
     data=filtered_data,
+    filtering='Band-pass filtered between 4 and 8 Hz',
     electrodes=all_table_region,
     starting_time=0.0,
     rate=200.0,
@@ -300,8 +302,6 @@
     decomp_series.add_band(
         band_name=band_name,
         band_limits=band_limits,
-        band_mean=np.nan,
-        band_stdev=np.nan,
     )
 
 ecephys_module.add(decomp_series)
@@ -355,7 +355,7 @@
 # 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
+spike_snippets = np.random.rand(40, 3, 30)  # 40 events, 3 channels, 30 samples per event
 shank0 = nwbfile.create_electrode_table_region(
     region=[0, 1, 2],
     description="shank0",
@@ -365,7 +365,7 @@
     name='SpikeEvents_Shank0',
     description="events detected with 100uV threshold",
     data=spike_snippets,
-    timestamps=np.arange(20),
+    timestamps=np.arange(40).astype(float),
     electrodes=shank0,
 )
 nwbfile.add_acquisition(spike_events)