Update ecephys and ophys tutorials (#1915)

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Documentation and tutorial enhancements
 - Simplified the introduction to NWB tutorial. @rly [#1914](https://github.com/NeurodataWithoutBorders/pynwb/pull/1914)
+- Simplified the ecephys and ophys tutorials. [#1915](https://github.com/NeurodataWithoutBorders/pynwb/pull/1915)
 
 
 ## PyNWB 2.8.0 (May 28, 2024)

docs/gallery/domain/ecephys.py

@@ -39,7 +39,6 @@
 #
 # When creating a NWB file, the first step is to create the :py:class:`~pynwb.file.NWBFile`.
 
-
 nwbfile = NWBFile(
     session_description="my first synthetic recording",
     identifier=str(uuid4()),
@@ -50,7 +49,8 @@
     lab="Bag End Laboratory",
     institution="University of Middle Earth at the Shire",
     experiment_description="I went on an adventure to reclaim vast treasures.",
-    session_id="LONELYMTN001",
+    keywords=["ecephys", "exploration", "wanderlust"],
+    related_publications="doi:10.1016/j.neuron.2016.12.011",
 )
 
 #######################
@@ -93,7 +93,6 @@
 # additional user-specified metadata as custom columns of the table. We will be adding a ``"label"`` column to the
 # table. Use the following code to add electrodes for an array with 4 shanks and 3 channels per shank.
 
-
 nwbfile.add_electrode_column(name="label", description="label of electrode")
 
 nshanks = 4
@@ -118,10 +117,9 @@
         electrode_counter += 1
 
 #######################
-# Similarly to the ``trials`` table, we can view the ``electrodes`` table in tabular form
+# Similarly to other tables in PyNWB, we can view the ``electrodes`` table in tabular form
 # by converting it to a pandas :py:class:`~pandas.DataFrame`.
 
-
 nwbfile.electrodes.to_dataframe()
 
 #######################
@@ -145,7 +143,6 @@
 # convenience function that creates a :py:class:`~hdmf.common.table.DynamicTableRegion` which references the
 # ``"electrodes"`` table.
 
-
 all_table_region = nwbfile.create_electrode_table_region(
     region=list(range(electrode_counter)),  # reference row indices 0 to N-1
     description="all electrodes",
@@ -156,7 +153,7 @@
 # ^^^^^^^^^^^^^^^^^
 #
 # Now create an :py:class:`~pynwb.ecephys.ElectricalSeries` object to store raw data collected
-# during the experiment, passing in this ``"all_table_region"`` :py:class:`~hdmf.common.table.DynamicTableRegion`
+# during the experiment, passing in this ``all_table_region`` :py:class:`~hdmf.common.table.DynamicTableRegion`
 # reference to all rows of the electrodes table.
 #
 # .. only:: html
@@ -174,10 +171,10 @@
 #     :align: center
 #
 
-
 raw_data = np.random.randn(50, 12)
 raw_electrical_series = ElectricalSeries(
     name="ElectricalSeries",
+    description="Raw acquisition traces",
     data=raw_data,
     electrodes=all_table_region,
     starting_time=0.0,  # timestamp of the first sample in seconds relative to the session start time
@@ -188,7 +185,6 @@
 # Since this :py:class:`~pynwb.ecephys.ElectricalSeries` represents raw data from the data acquisition system,
 # add it to the acquisition group of the :py:class:`~pynwb.file.NWBFile`.
 
-
 nwbfile.add_acquisition(raw_electrical_series)
 
 ####################
@@ -199,10 +195,10 @@
 # again passing in the :py:class:`~hdmf.common.table.DynamicTableRegion` reference to all rows of the ``"electrodes"``
 # table.
 
-
 lfp_data = np.random.randn(50, 12)
 lfp_electrical_series = ElectricalSeries(
     name="ElectricalSeries",
+    description="LFP data",
     data=lfp_data,
     electrodes=all_table_region,
     starting_time=0.0,
@@ -240,7 +236,6 @@
 # This is analogous to how we can store the :py:class:`~pynwb.behavior.Position` object in a processing module
 # created with the method :py:meth:`.NWBFile.create_processing_module`.
 
-
 ecephys_module = nwbfile.create_processing_module(
     name="ecephys", description="processed extracellular electrophysiology data"
 )
@@ -254,13 +249,16 @@
 #
 # 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
-# to how we can add columns to the ``"electrodes"`` and ``"trials"`` tables.
-#
-# Generate some random spike data and populate the :py:class:`~pynwb.misc.Units` table using the
-# method :py:meth:`.NWBFile.add_unit`.
+# to how we can add columns to the ``"electrodes"`` and ``"trials"`` tables. Use the convenience method
+# :py:meth:`.NWBFile.add_unit_column` to add a new column on the :py:class:`~pynwb.misc.Units` table for the
+# sorting quality of the units.
 
 nwbfile.add_unit_column(name="quality", description="sorting quality")
 
+####################
+# Generate some random spike data and populate the :py:class:`~pynwb.misc.Units` table using the
+# method :py:meth:`.NWBFile.add_unit`.
+
 firing_rate = 20
 n_units = 10
 res = 1000
@@ -272,7 +270,6 @@
 #######################
 # The :py:class:`~pynwb.misc.Units` table can also be converted to a pandas :py:class:`~pandas.DataFrame`.
 
-
 nwbfile.units.to_dataframe()
 
 #######################
@@ -315,7 +312,6 @@
 # Once you have finished adding all of your data to the :py:class:`~pynwb.file.NWBFile`,
 # write the file with :py:class:`~pynwb.NWBHDF5IO`.
 
-
 with NWBHDF5IO("ecephys_tutorial.nwb", "w") as io:
     io.write(nwbfile)
 

docs/gallery/domain/ophys.py

@@ -59,7 +59,8 @@
     lab="Bag End Laboratory",
     institution="University of Middle Earth at the Shire",
     experiment_description="I went on an adventure to reclaim vast treasures.",
-    session_id="LONELYMTN001",
+    keywords=["ecephys", "exploration", "wanderlust"],
+    related_publications="doi:10.1016/j.neuron.2016.12.011",
 )
 
 ####################
@@ -87,7 +88,6 @@
 # Create a :py:class:`~pynwb.device.Device` named ``"Microscope"`` in the :py:class:`~pynwb.file.NWBFile` object. Then
 # create an  :py:class:`~pynwb.ophys.OpticalChannel` named ``"OpticalChannel"``.
 
-
 device = nwbfile.create_device(
     name="Microscope",
     description="My two-photon microscope",
@@ -123,39 +123,23 @@
 # -----------------
 # Now that we have our :py:class:`~pynwb.ophys.ImagingPlane`, we can create a
 # :py:class:`~pynwb.ophys.OnePhotonSeries` object to store raw one-photon imaging data.
-# Here, we have two options. The first option is to supply the raw image data to PyNWB,
-# using the data argument. The second option is to provide a path to the image files.
-# These two options have trade-offs, so it is worth considering how you want to store
-# this data.
-
-# using internal data. this data will be stored inside the NWB file
-one_p_series1 = OnePhotonSeries(
-    name="OnePhotonSeries_internal",
+
+# the image data will be stored inside the NWB file
+one_p_series = OnePhotonSeries(
+    name="OnePhotonSeries",
+    description="Raw 1p data",
     data=np.ones((1000, 100, 100)),
     imaging_plane=imaging_plane,
     rate=1.0,
     unit="normalized amplitude",
 )
 
-# using external data. only the file paths will be stored inside the NWB file
-one_p_series2 = OnePhotonSeries(
-    name="OnePhotonSeries_external",
-    dimension=[100, 100],
-    external_file=["images.tiff"],
-    imaging_plane=imaging_plane,
-    starting_frame=[0],
-    format="external",
-    starting_time=0.0,
-    rate=1.0,
-)
-
 ####################
 # Since these one-photon data are acquired data, we will add the
 # :py:class:`~pynwb.ophys.OnePhotonSeries` objects to the :py:class:`~pynwb.file.NWBFile`
 # as acquired data.
 
-nwbfile.add_acquisition(one_p_series1)
-nwbfile.add_acquisition(one_p_series2)
+nwbfile.add_acquisition(one_p_series)
 
 ####################
 # Two-photon Series
@@ -178,29 +162,17 @@
 #     :align: center
 #
 
-# using internal data. this data will be stored inside the NWB file
-two_p_series1 = TwoPhotonSeries(
-    name="TwoPhotonSeries1",
+# the image data will be stored inside the NWB file
+two_p_series = TwoPhotonSeries(
+    name="TwoPhotonSeries",
+    description="Raw 2p data",
     data=np.ones((1000, 100, 100)),
     imaging_plane=imaging_plane,
     rate=1.0,
     unit="normalized amplitude",
 )
 
-# using external data. only the file paths will be stored inside the NWB file
-two_p_series2 = TwoPhotonSeries(
-    name="TwoPhotonSeries2",
-    dimension=[100, 100],
-    external_file=["images.tiff"],
-    imaging_plane=imaging_plane,
-    starting_frame=[0],
-    format="external",
-    starting_time=0.0,
-    rate=1.0,
-)
-
-nwbfile.add_acquisition(two_p_series1)
-nwbfile.add_acquisition(two_p_series2)
+nwbfile.add_acquisition(two_p_series)
 
 ####################
 # Motion Correction (optional)
@@ -212,6 +184,7 @@
 
 corrected = ImageSeries(
     name="corrected",  # this must be named "corrected"
+    description="A motion corrected image stack",
     data=np.ones((1000, 100, 100)),
     unit="na",
     format="raw",
@@ -221,6 +194,7 @@
 
 xy_translation = TimeSeries(
     name="xy_translation",
+    description="x,y translation in pixels",
     data=np.ones((1000, 2)),
     unit="pixels",
     starting_time=0.0,
@@ -229,7 +203,7 @@
 
 corrected_image_stack = CorrectedImageStack(
     corrected=corrected,
-    original=one_p_series1,
+    original=one_p_series,
     xy_translation=xy_translation,
 )
 
@@ -240,7 +214,6 @@
 # physiology data and add the motion correction data to the :py:class:`~pynwb.file.NWBFile`.
 #
 
-
 ophys_module = nwbfile.create_processing_module(
     name="ophys", description="optical physiology processed data"
 )
@@ -295,14 +268,13 @@
 # Then we will add the :py:class:`~pynwb.ophys.ImageSegmentation` object
 # to the previously created :py:class:`~pynwb.base.ProcessingModule`.
 
-
 img_seg = ImageSegmentation()
 
 ps = img_seg.create_plane_segmentation(
     name="PlaneSegmentation",
     description="output from segmenting my favorite imaging plane",
     imaging_plane=imaging_plane,
-    reference_images=one_p_series1,  # optional
+    reference_images=one_p_series,  # optional
 )
 
 ophys_module.add(img_seg)
@@ -348,7 +320,7 @@
     name="PlaneSegmentation2",
     description="output from segmenting my favorite imaging plane",
     imaging_plane=imaging_plane,
-    reference_images=one_p_series1,  # optional
+    reference_images=one_p_series,  # optional
 )
 
 for _ in range(30):
@@ -382,7 +354,7 @@
     name="PlaneSegmentation3",
     description="output from segmenting my favorite imaging plane",
     imaging_plane=imaging_plane,
-    reference_images=one_p_series1,  # optional
+    reference_images=one_p_series,  # optional
 )
 
 from itertools import product
@@ -453,9 +425,9 @@
 # Then we create a :py:class:`~pynwb.ophys.RoiResponseSeries` object to store fluorescence
 # data for those two ROIs.
 
-
 roi_resp_series = RoiResponseSeries(
     name="RoiResponseSeries",
+    description="Fluorescence responses for two ROIs",
     data=np.ones((50, 2)),  # 50 samples, 2 ROIs
     rois=rt_region,
     unit="lumens",
@@ -484,7 +456,6 @@
 #     :alt: fluorescence UML diagram
 #     :align: center
 
-
 fl = Fluorescence(roi_response_series=roi_resp_series)
 ophys_module.add(fl)
 
@@ -503,7 +474,6 @@
 # :py:class:`~pynwb.file.NWBFile`, make sure to write the file.
 # IO operations are carried out using :py:class:`~pynwb.NWBHDF5IO`.
 
-
 with NWBHDF5IO("ophys_tutorial.nwb", "w") as io:
     io.write(nwbfile)
 
@@ -525,10 +495,9 @@
 # with the name of the :py:class:`~pynwb.ophys.RoiResponseSeries` object,
 # which we named ``"RoiResponseSeries"``.
 
-
 with NWBHDF5IO("ophys_tutorial.nwb", "r") as io:
     read_nwbfile = io.read()
-    print(read_nwbfile.acquisition["TwoPhotonSeries1"])
+    print(read_nwbfile.acquisition["TwoPhotonSeries"])
     print(read_nwbfile.processing["ophys"])
     print(read_nwbfile.processing["ophys"]["Fluorescence"])
     print(read_nwbfile.processing["ophys"]["Fluorescence"]["RoiResponseSeries"])
@@ -545,11 +514,10 @@
 # Load and print all the data values of the :py:class:`~pynwb.ophys.RoiResponseSeries`
 # object representing the fluorescence data.
 
-
 with NWBHDF5IO("ophys_tutorial.nwb", "r") as io:
     read_nwbfile = io.read()
 
-    print(read_nwbfile.acquisition["TwoPhotonSeries1"])
+    print(read_nwbfile.acquisition["TwoPhotonSeries"])
     print(read_nwbfile.processing["ophys"]["Fluorescence"]["RoiResponseSeries"].data[:])
 
 ####################

docs/gallery/general/plot_file.py

@@ -76,13 +76,8 @@
 Processing Modules
 ^^^^^^^^^^^^^^^^^^
 
-Processing modules are objects that group together common analyses done during processing of data.
- To standardize the storage of
-common analyses, NWB provides the concept of an :py:class:`~pynwb.core.NWBDataInterface`, where the output of
-common analyses are represented as objects that extend the :py:class:`~pynwb.core.NWBDataInterface` class.
-In most cases, you will not need to interact with the :py:class:`~pynwb.core.NWBDataInterface` class directly.
-More commonly, you will be creating instances of classes that extend this class.
-
+Processing modules are objects that group together common analyses done during processing of data. They
+often hold data of different processing/analysis data types.
 
 .. seealso::
 
@@ -168,7 +163,7 @@
         "Baggins, Bilbo",
     ],  # optional
     lab="Bag End Laboratory",  # optional
-    institution="University of My Institution",  # optional
+    institution="University of Middle Earth at the Shire",  # optional
     experiment_description="I went on an adventure to reclaim vast treasures.",  # optional
     keywords=["behavior", "exploration", "wanderlust"],  # optional
     related_publications="doi:10.1016/j.neuron.2016.12.011",  # optional