Merge pull request #1456 from zm711/rtd-fix

Sphinx-Gallery Touchups

Author: alejoe91

environment_testing.yml

@@ -2,5 +2,6 @@ name: neo-test-env
 channels:
   - conda-forge
 dependencies:
+  - python=3.9
   - datalad
   - pip

examples/plot_igorio.py

@@ -3,17 +3,21 @@
 ===========================
 
 """
-
+###########################################################
+# Import our packages
 import os
 from urllib.request import urlretrieve
 import zipfile
 import matplotlib.pyplot as plt
 from neo.io import get_io
 
-
+#############################################################
+# Then download some data
 # Downloaded from Human Brain Project Collaboratory
 # Digital Reconstruction of Neocortical Microcircuitry (nmc-portal)
 # http://microcircuits.epfl.ch/#/animal/8ecde7d1-b2d2-11e4-b949-6003088da632
+
+
 datafile_url = "https://microcircuits.epfl.ch/data/released_data/B95.zip"
 filename_zip = "B95.zip"
 filename = "grouped_ephys/B95/B95_Ch0_IDRest_107.ibw"
@@ -23,7 +27,10 @@
 zip_ref.extract(path=".", member=filename)  # extract file to dir
 zip_ref.close()
 
-
+######################################################
+# Once we have our data we can use `get_io` to find an 
+# io (Igor in this case). Then we read the analogsignals
+# Finally we will make some nice plots
 reader = get_io(filename)
 signal = reader.read_analogsignal()
 plt.plot(signal.times, signal)

examples/plot_imageseq.py

@@ -4,14 +4,22 @@
 
 """
 
+##########################################################
+# Let's import some packages
+
 from neo.core import ImageSequence
 from neo.core import RectangularRegionOfInterest, CircularRegionOfInterest, PolygonRegionOfInterest
 import matplotlib.pyplot as plt
 import quantities as pq
 
 import random
 
-# generate data
+
+############################################################
+# Now we need to generate some data
+# We will just make a nice box and then we can attach this 
+# ImageSequence to a variety of ROIs
+# our ImageSequence will be 50 frames of 100x100 pixel images
 
 l = []
 for frame in range(50):
@@ -21,6 +29,10 @@
         for x in range(100):
             l[frame][y].append(random.randint(0, 50))
 
+#####################################################################
+# we then make our image sequence and pull out our results from the
+# image_seq
+
 image_seq = ImageSequence(l, sampling_rate=500 * pq.Hz, spatial_scale="m", units="V")
 
 result = image_seq.signal_from_region(
@@ -29,10 +41,13 @@
     PolygonRegionOfInterest(image_seq,(50, 25), (50, 45), (14, 65), (90, 80)),
 )
 
+###############################################################
+# It is easy to plot our results using matplotlib
+
 for i in range(len(result)):
     plt.figure()
     plt.plot(result[i].times, result[i])
     plt.xlabel("seconde")
     plt.ylabel("valeur")
-
+plt.tight_layout()
 plt.show()

examples/plot_multi_tetrode_example.py

@@ -1,13 +1,22 @@
 """
-Example for usecases.rst
+Analyzing and Plotting Data with Neo Structures
+===============================================
 """
+######################################################
+# First we import some packages. Since we are making simulated
+# data we will import quite a few neo features as well as use
+# quantities to provide units
 
 from itertools import cycle
 import numpy as np
 from quantities import ms, mV, kHz
 import matplotlib.pyplot as plt
 from neo import Block, Segment, ChannelView, Group, SpikeTrain, AnalogSignal
 
+##########################################################################
+# For Neo we start with a block of data that will contain segments of data
+# so we will create a block of probe data that has a couple tetrodes
+# Then we will load in 3 segments (for examples trials of a stimulus)
 store_signals = False
 
 block = Block(name="probe data", tetrode_ids=["Tetrode #1", "Tetrode #2"])
@@ -17,8 +26,13 @@
     Segment(name="trial #3", index=2),
 ]
 
+# we will decide how many units each tetrode has found. If only science was this easy
 n_units = {"Tetrode #1": 2, "Tetrode #2": 5}
 
+##################################################################################
+# Neo can also have groups. Groups are structures within a block that can cross segments
+# for example we could group a neuron across trials or across probes. 
+
 # Create a group for each neuron, annotate each group with the tetrode from which it was recorded
 groups = []
 counter = 0
@@ -29,19 +43,28 @@
 
 iter_group = cycle(groups)
 
+##########################################################################################
+# Segments are also containers of data. Segments can hold raw signal data like an AnalogSignal
+# Segments can also hold spiketrain data (in a SpikeTrain). It can also hold event data (which
+# we are not show in this example)
+
+
 # Create dummy data, one segment at a time
 for segment in block.segments:
 
-    # create two 4-channel AnalogSignals with dummy data
+    # create two 4-channel AnalogSignals with simulated data (because we have two tetrodes!)
+    # note that the AnalogSignal with have numpy array-like data with units and sampling rates
+    # Neo keeps track of these units while also giving you the flexibility of treating the raw data
+    # like a numpy array
     signals = {
         "Tetrode #1": AnalogSignal(np.random.rand(1000, 4) * mV, sampling_rate=10 * kHz, tetrode_id="Tetrode #1"),
         "Tetrode #2": AnalogSignal(np.random.rand(1000, 4) * mV, sampling_rate=10 * kHz, tetrode_id="Tetrode #2"),
     }
     if store_signals:
         segment.analogsignals.extend(signals.values())
 
-    # create spike trains with dummy data
-    # we will pretend the spikes have been extracted from the dummy signal
+    # create spike trains with simulated data
+    # we will pretend the spikes have been extracted from the simulated signal
     for tetrode_id in ("Tetrode #1", "Tetrode #2"):
         for i in range(n_units[tetrode_id]):
             spiketrain = SpikeTrain(np.random.uniform(0, 100, size=30) * ms, t_stop=100 * ms)
@@ -57,8 +80,16 @@
                 current_group.add(signals[tetrode_id])
 
 
-# Now plot the data
+###################################################
+# Now we will plot the data
+# Neo doesn't provide it's own plotting functions, but
+# since its data can be treated like numpy arrays
+# it is easy to use standard packages like matplotlib
+# for all your plotting needs
+# We do a classic in neuroscience and show various ways 
+# to plot a PSTH (Peristimulus histogram)
 
+###################################################
 # .. by trial
 plt.figure()
 for seg in block.segments:
@@ -68,8 +99,10 @@
     count, bins = np.histogram(stlist)
     plt.bar(bins[:-1], count, width=bins[1] - bins[0])
     plt.title(f"PSTH in segment {seg.index}")
+plt.tight_layout()
 plt.show()
 
+####################################################
 # ..by neuron
 
 plt.figure()
@@ -79,9 +112,11 @@
     count, bins = np.histogram(stlist)
     plt.bar(bins[:-1], count, width=bins[1] - bins[0])
     plt.title(f"PSTH of unit {group.name}")
+plt.tight_layout()
 plt.show()
 
-# ..by tetrode
+###########################################################
+# ..by tetrode (or other electrode number)
 
 plt.figure()
 for i, tetrode_id in enumerate(block.annotations["tetrode_ids"]):
@@ -92,4 +127,5 @@
     count, bins = np.histogram(stlist)
     plt.bar(bins[:-1], count, width=bins[1] - bins[0])
     plt.title(f"PSTH blend of tetrode {tetrode_id}")
+plt.tight_layout()
 plt.show()

examples/plot_read_files_neo_io.py

@@ -4,6 +4,9 @@
 
 """
 
+####################################################
+# Start with package import and getting a datafile
+
 import urllib
 
 import neo
@@ -15,11 +18,22 @@
 localfile = "File_plexon_3.plx"
 urllib.request.urlretrieve(distantfile, localfile)
 
+
+
+###################################################
+# Now we can create our reader and read some data
+
 # create a reader
 reader = neo.io.PlexonIO(filename="File_plexon_3.plx")
 # read the blocks
 blks = reader.read(lazy=False)
 print(blks)
+
+######################################################
+# Once we have our blocks we can iterate through each
+# block of data and see the contents of all parts of 
+# that data
+
 # access to segments
 for blk in blks:
     for seg in blk.segments:
@@ -29,16 +43,28 @@
         for st in seg.spiketrains:
             print(st)
 
+#######################################################
+# Let's look at another file type
+            
 # CED Spike2 files
 distantfile = url_repo + "spike2/File_spike2_1.smr"
 localfile = "./File_spike2_1.smr"
 urllib.request.urlretrieve(distantfile, localfile)
-
 # create a reader
 reader = neo.io.Spike2IO(filename="File_spike2_1.smr")
+
+#########################################################
+# Despite being a different raw file format we can access
+# the data in the same way
+
 # read the block
 bl = reader.read(lazy=False)[0]
 print(bl)
+
+##########################################################
+# Similarly we can view the different types of data within
+# the block (AnalogSignals and SpikeTrains)
+
 # access to segments
 for seg in bl.segments:
     print(seg)