fix examples displaying wrong order

Author: zm711

examples/plot_igorio.py

@@ -3,14 +3,16 @@
 ===========================
 
 """
-
+###########################################################
+# 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
@@ -23,7 +25,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,21 @@
 
 """
 
+##########################################################
+# 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
 
 l = []
 for frame in range(50):
@@ -29,6 +36,9 @@
     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])

examples/plot_multi_tetrode_example.py

@@ -1,5 +1,6 @@
 """
-Example for usecases.rst
+Analyzing and Plotting Data with Neo Structures
+===============================================
 """
 
 from itertools import cycle
@@ -57,8 +58,10 @@
                 current_group.add(signals[tetrode_id])
 
 
-# Now plot the data
+###################################################
+# Now we will plot the data
 
+###################################################
 # .. by trial
 plt.figure()
 for seg in block.segments:
@@ -70,6 +73,7 @@
     plt.title(f"PSTH in segment {seg.index}")
 plt.show()
 
+####################################################
 # ..by neuron
 
 plt.figure()
@@ -81,7 +85,8 @@
     plt.title(f"PSTH of unit {group.name}")
 plt.show()
 
-# ..by tetrode
+###########################################################
+# ..by tetrode (or other electrode number)
 
 plt.figure()
 for i, tetrode_id in enumerate(block.annotations["tetrode_ids"]):

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)

examples/plot_read_files_neo_rawio.py

@@ -4,58 +4,98 @@
 
 compare with read_files_neo_io.py
 """
+###########################################################
+# First we import a RawIO from neo.rawio
+# For this example we will use PlexonRawIO
 
 import urllib
 from neo.rawio import PlexonRawIO
 
 url_repo = "https://web.gin.g-node.org/NeuralEnsemble/ephy_testing_data/raw/master/"
 
+##############################################################
 # Get Plexon files
+# We will be pulling these files down, but if you have local file
+# then all you need to do is specify the file location on your
+# computer
+
 distantfile = url_repo + "plexon/File_plexon_3.plx"
 localfile = "File_plexon_3.plx"
 urllib.request.urlretrieve(distantfile, localfile)
 
-# create a reader
+###############################################################
+# Create a reader
+# All it takes to create a reader is giving the filename
+# Then we need to do the slow step of parsing the header with the
+# `parse_header` function. This collects metadata as well as
+# make all future steps much faster for us
+
 reader = PlexonRawIO(filename="File_plexon_3.plx")
 reader.parse_header()
 print(reader)
+# we can view metadata in the header
 print(reader.header)
 
+###############################################################
 # Read signal chunks
+# This is how we read raw data. We choose indices that we want or
+# we can use None to mean look at all channels. We also need to 
+# specify the block of data (block_index) as well as the segment
+# (seg_index). Then we give the index start and stop. Since we 
+# often thing in time to go from time to index would just require
+# the sample rate (so index = time / sampling_rate)
 channel_indexes = None  # could be channel_indexes = [0]
 raw_sigs = reader.get_analogsignal_chunk(
     block_index=0, seg_index=0, i_start=1024, i_stop=2048, channel_indexes=channel_indexes
 )
+
+# raw_sigs are not voltages so to convert to voltages we do the follwing
 float_sigs = reader.rescale_signal_raw_to_float(raw_sigs, dtype="float64")
+# each rawio gives you access to lots of information about your data
 sampling_rate = reader.get_signal_sampling_rate()
 t_start = reader.get_signal_t_start(block_index=0, seg_index=0)
 units = reader.header["signal_channels"][0]["units"]
+# and we can display all of this information
 print(raw_sigs.shape, raw_sigs.dtype)
 print(float_sigs.shape, float_sigs.dtype)
-print(sampling_rate, t_start, units)
+print(f"{sampling_rate=}, {t_start=}, {units=}")
+
+
+####################################################################
+# Some rawio's and file formats all provide information about spikes
+# If an rawio can't read this data it will raise an error, but lucky
+# for us PlexonRawIO does have spikes data!!
 
 # Count units and spikes per unit
 nb_unit = reader.spike_channels_count()
 print("nb_unit", nb_unit)
 for spike_channel_index in range(nb_unit):
     nb_spike = reader.spike_count(block_index=0, seg_index=0, spike_channel_index=spike_channel_index)
-    print("spike_channel_index", spike_channel_index, "nb_spike", nb_spike)
+    print(f"{spike_channel_index=}\n{nb_spike}\n")
 
-# Read spike times
+# Read spike times and rescale (just like analogsignal above)
 spike_timestamps = reader.get_spike_timestamps(
     block_index=0, seg_index=0, spike_channel_index=0, t_start=0.0, t_stop=10.0
 )
-print(spike_timestamps.shape, spike_timestamps.dtype, spike_timestamps[:5])
+print(f"{spike_timestamps.shape=}\n{spike_timestamps.dtype=}\n{spike_timestamps[:5]=}")
 spike_times = reader.rescale_spike_timestamp(spike_timestamps, dtype="float64")
-print(spike_times.shape, spike_times.dtype, spike_times[:5])
+print(f"{spike_times.shape=}\n{spike_times.dtype=}\n{spike_times[:5]}")
+
+#######################################################################
+# Some file formats can also give waveform information. We are lucky
+# again. Our file has waveform data!!
 
 # Read spike waveforms
 raw_waveforms = reader.get_spike_raw_waveforms(
     block_index=0, seg_index=0, spike_channel_index=0, t_start=0.0, t_stop=10.0
 )
-print(raw_waveforms.shape, raw_waveforms.dtype, raw_waveforms[0, 0, :4])
+print(f"{raw_waveforms.shape=}\n{raw_waveforms.dtype=}\n{raw_waveforms[0, 0, :4]=}")
 float_waveforms = reader.rescale_waveforms_to_float(raw_waveforms, dtype="float32", spike_channel_index=0)
-print(float_waveforms.shape, float_waveforms.dtype, float_waveforms[0, 0, :4])
+print(f"{float_waveforms.shape=}\n{float_waveforms.dtype=}{float_waveforms[0, 0, :4]=}")
+
+#########################################################################
+# RawIOs can also read event timestamps. But looks like our luck ran out
+# let's grab a new file to see this feature
 
 # Read event timestamps and times (take another file)
 distantfile = url_repo + "plexon/File_plexon_2.plx"
@@ -66,14 +106,14 @@
 reader = PlexonRawIO(filename="File_plexon_2.plx")
 reader.parse_header()
 nb_event_channel = reader.event_channels_count()
-print("nb_event_channel", nb_event_channel)
+print("nb_event_channel:", nb_event_channel)
 for chan_index in range(nb_event_channel):
     nb_event = reader.event_count(block_index=0, seg_index=0, event_channel_index=chan_index)
     print("chan_index", chan_index, "nb_event", nb_event)
 
 ev_timestamps, ev_durations, ev_labels = reader.get_event_timestamps(
     block_index=0, seg_index=0, event_channel_index=0, t_start=None, t_stop=None
 )
-print(ev_timestamps, ev_durations, ev_labels)
+print(f"{ev_timestamps=}\n{ev_durations=}\n{ev_labels=}")
 ev_times = reader.rescale_event_timestamp(ev_timestamps, dtype="float64")
-print(ev_times)
+print(f"{ev_times=}")

examples/plot_read_proxy_with_lazy_load.py

@@ -4,25 +4,37 @@
 
 """
 
+################################################
+# Import our packages first
+
 import urllib
 import neo
 import quantities as pq
 import numpy as np
 
 url_repo = "https://web.gin.g-node.org/NeuralEnsemble/ephy_testing_data/raw/master/"
 
-# Get Plexon files
+
+###############################################
+# Let's get a file
+
+# Get med file
 distantfile = url_repo + "micromed/File_micromed_1.TRC"
 localfile = "./File_micromed_1.TRC"
 urllib.request.urlretrieve(distantfile, localfile)
 
+##################################################
 # create a reader
+
 reader = neo.MicromedIO(filename="File_micromed_1.TRC")
 reader.parse_header()
 
 
 lim0, lim1 = -20 * pq.ms, +20 * pq.ms
 
+#####################################################
+# Now let's make a function that we want to apply to
+# look at lazy for eager uses of the API
 
 def apply_my_fancy_average(sig_list):
     """basic average along triggers and then channels
@@ -33,6 +45,9 @@ def apply_my_fancy_average(sig_list):
     sigs = np.stack(sig_list, axis=0)
     return np.mean(np.mean(sigs, axis=0), axis=1)
 
+##################################################
+# We start with eager where `lazy=False`. Everything
+# is loaded into memory
 
 seg = reader.read_segment(lazy=False)
 triggers = seg.events[0]
@@ -44,6 +59,11 @@ def apply_my_fancy_average(sig_list):
     all_sig_chunks.append(anasig_chunk)
 m1 = apply_my_fancy_average(all_sig_chunks)
 
+#####################################################
+# Here we do `lazy=True`, so we do lazy loading. We
+# only load the events that we want into memory
+# and we use a proxy object for our analogsignal until we
+# load it chunk by chunk (no running out of memory!)
 
 seg = reader.read_segment(lazy=True)
 triggers = seg.events[0].load(time_slice=None)  # this load all trigers in memory
@@ -55,5 +75,8 @@ def apply_my_fancy_average(sig_list):
     all_sig_chunks.append(anasig_chunk)
 m2 = apply_my_fancy_average(all_sig_chunks)
 
+##########################################################
+# We see that either way the result is the same, but 
+# we do not exhaust our RAM/memory
 print(m1)
 print(m2)

examples/plot_roi_demo.py

@@ -3,6 +3,8 @@
 =====================================
 
 """
+#############################################
+# Import our packages
 
 import matplotlib.pyplot as plt
 import numpy as np
@@ -11,7 +13,7 @@
 import random
 import quantities as pq
 
-
+##################################################################
 # First we create our image_sequence. Let's generate some data
 
 l = []
@@ -24,6 +26,8 @@
 
 image_seq = ImageSequence(l, sampling_rate=500 * pq.Hz, spatial_scale="m", units="V")
 
+#################################################################
+# Now we will write a function for plotting an roi
 def plot_roi(roi, shape):
     img = rand(120, 100)
     pir = np.array(roi.pixels_in_region()).T
@@ -35,6 +39,8 @@ def plot_roi(roi, shape):
     ax = plt.gca()
     ax.add_artist(shape)
 
+##################################################################
+# Finally we will plot each roi
 
 roi = CircularRegionOfInterest(image_sequence=image_seq, x=50.3, y=50.8, radius=30.2)
 shape = plt.Circle(roi.centre, roi.radius, color="r", fill=False)