Review: suggestions for "First-order analysis" section

docs/first-order/current_source_density.ipynb

@@ -550,7 +550,7 @@
    "metadata": {},
    "source": [
     "### Selecting a Period\n",
-    "Oftentimes, the LFP data can be very large. Depending on the machine this analysis is performed on, there may not be enough memory to the following interpolation. This can be mitigated in two ways. Firstly, the `interp_hz` variable in the following section can be decreased. Otherwise, the analysis can be performed with some smaller period of time within the LFP data. If you wish to do this, set `period_start` and `period_end` to be reasonable times (in seconds) within the experiment to look at. Below are printed the first and last timestamps from the stimulus data and LFP data to inform this choice."
+    "Oftentimes, the LFP data can be very large. Depending on the machine this analysis is performed on, there may not be enough memory for the following interpolation. This can be mitigated in two ways. Firstly, the `interp_hz` variable in the following section can be decreased. Otherwise, the analysis can be performed with some smaller period of time within the LFP data. If you wish to do this, set `period_start` and `period_end` to be reasonable times (in seconds) within the experiment to look at. Below are printed the first and last timestamps from the stimulus data and LFP data to inform this choice."
    ]
   },
   {
@@ -650,7 +650,7 @@
    "metadata": {},
    "source": [
     "### LFP Interpolation\n",
-    "Because we cannot be certain that the LFP trace is at a perfectly regular Hz, we will interpolate it to be able to compare stimulus timestamps to their approximate LFP times. After you have a valid list of stimulus timestamps, you can generate a linearly-spaced timestamp array called `time_axis`, and interpolate the LFP data along it, making interpolated LFP data called `interp_lfp`. This should be a 2D array with dimensions `time` and `channel`, where channels are the different measurement channels along the probe. Here, the timestamps are interpolated to 250 Hertz, but you can change this by setting `interp_hz`."
+    "Because we cannot be certain that the LFP trace is at a perfectly regular sampling rate, we will interpolate it to be able to compare stimulus timestamps to their approximate LFP times. After you have a valid list of stimulus timestamps, you can generate a linearly-spaced timestamp array called `time_axis`, and interpolate the LFP data along it, making interpolated LFP data called `interp_lfp`. This should be a 2D array with dimensions `time` and `channel`, where channels are the different measurement channels along the probe. Here, the timestamps are interpolated to 250 Hertz, but you can change this by setting `interp_hz`."
    ]
   },
   {
@@ -708,7 +708,6 @@
     "    interp_lfp.append(f(time_axis))\n",
     "\n",
     "interp_lfp = np.array(interp_lfp)\n",
-    "# interp_lfp = np.transpose(interp_channels)\n",
     "\n",
     "print(interp_lfp.shape)"
    ]
@@ -906,7 +905,7 @@
    "metadata": {},
    "source": [
     "### Using Elephant to Estimate CSD\n",
-    "**Elephant** takes input in the form of a **Neo** *AnalogSignal*. Before analysis, we create the *AnalogSignal* object with the LFP trace as input, in addition to the `hz` valueas the `sampling_rate` of the data, and a list of numbers, `coords` representing the channels of the LFP data. After this, it is as simple as calling `estimate_csd`."
+    "**Elephant** takes input in the form of a **Neo** *AnalogSignal*. Before analysis, we create the *AnalogSignal* object with the LFP trace as input, in addition to the `hz` value as the `sampling_rate` of the data, and a list of numbers, `coords` representing the channels of the LFP data. After this, it is as simple as calling `estimate_csd`."
    ]
   },
   {
@@ -962,7 +961,7 @@
    "metadata": {},
    "source": [
     "### Displaying Current Source Density\n",
-    "The current source density over time can be shown below with **matplotlib's** `imshow` method."
+    "The current source density over time can be shown below with **matplotlib's** `imshow` method. The dark areas represent sinks and bright areas represent sources."
    ]
   },
   {

docs/first-order/optotagging.ipynb

@@ -7,7 +7,9 @@
    "metadata": {},
    "source": [
     "# Identifying Optotagged Units\n",
-    "In some transgenic mice, particular types of neurons express a trait whereby they will fire in response to direct laser stimulation. This is stored in the `optogenetic_stimulation` table of our NWB files. Identifying these cells is called *Optotagging*. Optotagging makes it possible to link the in vivo spike recordings of neuronal units to genetically defined cell classes. Doing this analysis with the optogenetic stimulus information is relatively similar to the analysis in [Visualizing Neuronal Unit Responses](../visualization/visualize_unit_responses.ipynb). To do this, we take all the relevant stimulation times from the stimulus table and identify which neuronal units fire within a predetermined window of time following the stimulus times. Neurons that spike more frequently and consistently after stimulus are likely to be optotagged."
+    "In some transgenic mice, particular types of neurons express a trait whereby they will fire in response to direct laser stimulation. These mice express light-gated ion channels (channelrhodopsins) in a Cre-dependent manner, thus units that fire action potentials in response to light pulses are likely to express the gene of interest. The particular form of laser stimulation is stored in the `optogenetic_stimulation` table of our NWB files. \n",
+    "\n",
+    "Identifying these expressive neurons is called *Optotagging*. Optotagging makes it possible to link the in vivo spike recordings of neuronal units to genetically defined cell classes. Doing this analysis with the optogenetic stimulus information is relatively similar to the analysis in [Visualizing Neuronal Unit Responses](../visualization/visualize_unit_responses.ipynb). To do this, we take all the relevant stimulation times from the stimulus table and identify which neuronal units fire within a predetermined window of time following the stimulus times. Neurons that spike more frequently and consistently after stimulus are likely to be optotagged."
    ]
   },
   {
@@ -45,8 +47,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import time\n",
-    "\n",
     "from math import isclose\n",
     "import matplotlib.pyplot as plt\n",
     "import numpy as np\n",
@@ -116,7 +116,7 @@
    "metadata": {},
    "source": [
     "### Extracting Optogenetic Stimulus Data and Units Data\n",
-    "The two components needed for this analysis are the `optogenetic_stimulation` table and the `Units` table. The optogenetic stimulus table contains the intervals where lasers are fired at the brain. The primary property we will use from this is `start_time` which contains the times that stimulus is presented. From the `Units` table, we will extract the `spike_times` which will be aligned relative to a predefined window of time around each stimulus time to determine if it occurred in response to the stimulus. These tables are retrieved and printed below."
+    "The two components needed for this analysis are the `optogenetic_stimulation` table and the `Units` table. The optogenetic stimulus table contains the intervals during which laser stimulation is delivered to the brain. The primary property we will use from this table is `start_time`, which contains the times that stimulus is delivered. From the `Units` table, we will extract the `spike_times` which will be aligned relative to a predefined window of time around each stimulus time to determine if it occurred in response to the stimulus. These tables are retrieved and printed below."
    ]
   },
   {
@@ -793,7 +793,7 @@
    "metadata": {},
    "source": [
     "### Selecting Units and Stimuli\n",
-    "Here subsets of the data can be selected for analysis. The important properties of the stimulus table shown above are, `condition` (type of laser pulse presented), the voltage `level`, and the `duration`. Below, you can define `stim_select` to select individual rows of the table based on these properties.\n",
+    "Here subsets of the data can be selected for analysis. The important properties of the stimulus table shown above are, `condition` (type of laser pulse delivered), the voltage `level`, and the `duration`. Below, you can define `stim_select` to select individual rows of the table based on these properties.\n",
     "\n",
     "The same can be done for the units table by defining the function `unit_select`. For information on the properties of the `Units` table, see [Visualizing Unit Quality Metrics](../visualization/visualize_unit_metrics.ipynb)"
    ]
@@ -1004,7 +1004,10 @@
    "id": "38266739",
    "metadata": {},
    "source": [
-    "### Plotting Spike Counts"
+    "### Plotting Spike Counts\n",
+    "The plot below show how different units respond to the optogenetic laser stimulation that was selected. It can be seen below that among the SST units, many cells show responsive activity following the laser activation, while the wildtype (non-genetically modified cells) don't show any significant response to the optogenetic stimulation.\n",
+    "\n",
+    "**Note that there are also some units that seem to fire at the very beginning and/or very end of the light pulse. These spikes are almost certainly artifactual, as it takes at least 1 ms to generate a true light-evoked action potential. To manage this, we use the censor period to constrain the stimulus period analyzed, indicated by the dotted white lines.**"
    ]
   },
   {
@@ -1103,7 +1106,7 @@
     "show_counts(sorted_sst_spike_counts,\n",
     "            sst_bin_edges,\n",
     "            stim_bounds=[censor_period, stim_duration-censor_period],\n",
-    "            title=\"SST Unit spike counts over time\",\n",
+    "            title=\"sorted SST Unit spike counts over time\",\n",
     "            c_label=f\"# Spikes (per {time_resolution} seconds)\",\n",
     "            vmin=0,\n",
     "            vmax=5)"
@@ -1116,9 +1119,7 @@
    "metadata": {},
    "source": [
     "### Identifying Optotagged Units\n",
-    "Now that the `spike_counts` array has been made, several other plots can be generated as well. Below, the mean and the standard deviation are taken for each unit of the baseline spiking behavior before any stimulus is presented.\n",
-    "\n",
-    "**Note that there are also some units that seem to fire at the very beginning and/or very end of the light pulse. These spikes are almost certainly artifactual, as it takes at least 1 ms to generate a true light-evoked action potential. To manage this, we use the censor period to constrain the stimulus period analyzed**"
+    "Now that the `spike_counts` array has been made, several other plots can be generated as well. Below, the mean and the standard deviation are taken for each unit of the baseline spiking behavior before any stimulus is presented."
    ]
   },
   {
@@ -1165,7 +1166,9 @@
    "metadata": {},
    "source": [
     "### Calculating Unit Optotagging Metrics\n",
-    "Here, certain metrics are calculated for each unit based on their spiking behaviors in response to stimulus. There is no single standard for what metrics to use for determining optotagged units, but the ones below may prove useful. You can adapt this code to calculate additional metrics for the units as well. Each function below calculates a metric (or two) for a given unit. As input, they use the `spike_counts`, and `spike_matrix` arrays which were already generated earlier, as well as the `stim_times` and `units_spike_times` which were produced from the NWB file. Finally, these metrics are displayed for each unit table below."
+    "Here, certain metrics are calculated for each unit based on their spiking behaviors in response to the stimulus. Metrics such as these are used to identify if a unit is \"optotagged\". i.e if a unit is responsive to the laser, and thus is a genetically modified inhibitory neuron. There is no single standard for what metrics to use for determining optotagged units, but the ones below may prove useful. You can adapt this code to calculate additional metrics for the units as well. Each function below calculates a metric (or two) for a given unit. As input, they use the `spike_counts`, and `spike_matrix` arrays which were already generated earlier, as well as the `stim_times` and `units_spike_times` which were produced from the NWB file. Finally, these metrics are displayed for each unit table below.\n",
+    "\n",
+    "Among the metrics below, the response spike rate, fraction time responsive, fraction trials responsive, and ks salt value are likely to be higher if the unit is optotagged. The first spike latency and first spike jitter are likely to be lower if the unit is optotagged."
    ]
   },
   {

docs/first-order/receptive_fields.ipynb

@@ -9,7 +9,7 @@
     "# Showing Receptive Fields\n",
     "Note: some of this content is adapted from the [Allen SDK](https://allensdk.readthedocs.io/en/latest/_static/examples/nb/ecephys_receptive_fields.html).\n",
     "\n",
-    "One of the most important features of visually responsive neurons is the location and extent of their *receptive field*. This is the region within the visual field in which stimulation can affect the neuron's response. Is it highly localized or spatially distributed? Is it centered on the stimulus display, or is it on an edge? How much does it overlap with the receptive fields of neurons in other regions? Obtaining answers to these questions is a crucial step for interpreting a results related to neurons' visual coding properties. This notebook demonstrates how to use the 'gabors' stimulus table and the `Units` table to compute the receptive fields."
+    "One of the most important features of visually responsive neurons is the location and extent of their *receptive field*. This is the region within the visual field in which stimulation can affect the neuron's response. Is it highly localized or spatially distributed? Is it centered on the stimulus display, or is it on an edge? How much does it overlap with the receptive fields of neurons in other regions? Obtaining answers to these questions is a crucial step for interpreting results related to neurons' visual coding properties. This notebook demonstrates how to use the 'gabors' stimulus table and the `Units` table to compute the receptive fields."
    ]
   },
   {
@@ -105,7 +105,7 @@
    "metadata": {},
    "source": [
     "### Reading Data\n",
-    "We need two components of data for this analysis; The `Units` table, which is discussed more in depth in [Visualizing Unit Quality Metrics](../visualization/visualize_unit_metrics.ipynb). In particular we need the `spike_times` property for the units. We also need the stimulus table from the NWB File's `Intervals` section. !Reword this sentence!: Because receptive field analysis is so central to interpreting results related to visual coding, experiments include some [Gabor patches](http://neuroanatody.com/2016/05/whats-in-a-gabor-patch/), shown repeatedly at a set of different coordinates within the mouse's visual field. This stimulus is usually shown at the beginning of the session, and typically uses the same parameters for every mouse. So for our purposes, we select the stimulus table named `gabors_presentations`. Below the `Units` table and the *gabors stimulus table* are shown."
+    "We need two components of data for this analysis; The `Units` table, which is discussed more in depth in [Visualizing Unit Quality Metrics](../visualization/visualize_unit_metrics.ipynb). In particular we need the `spike_times` property for the units. We also need the stimulus table from the NWB File's `Intervals` section. Because receptive field analysis is so central to interpreting results related to visual coding, experiments include some [Gabor patches](http://neuroanatody.com/2016/05/whats-in-a-gabor-patch/) which are used to reliably drive neural responses, shown repeatedly at a set of different coordinates within the mouse's visual field. This stimulus is usually shown at the beginning of the session, and typically uses the same parameters for every mouse. So for our purposes, we select the stimulus table named `gabors_presentations`. Below the `Units` table and the *gabors stimulus table* are shown."
    ]
   },
   {
@@ -942,7 +942,7 @@
    "metadata": {},
    "source": [
     "### Selecting Units\n",
-    "It would be inconvenient to try to view and generate the receptive fields for all units at once. Below you can select units based on their quality metrics and the brain region they appear. If you'd like, redefine the `select_condition` function to set different criteria for selecting the units you'd like to view. For more information on the useful metrics of units in the `Units` table, see [Visualizing Unit Quality Metrics](../visualization/visualize_unit_metrics.ipynb). Because it can be very useful to select units by brain region or by probe, you may use the `get_unit_location` and `get_unit_probe` functions below, which take information from the `Electrodes` table to get the location and probes for each unit respectively. The sets of probe names and location names are printed for your convenience."
+    "It would be inconvenient to try to view and generate the receptive fields for all units at once. Below you can select units based on their quality metrics and the brain region they appear in. If you'd like, redefine the `select_condition` function to set different criteria for selecting the units you'd like to view. For more information on the useful metrics of units in the `Units` table, see [Visualizing Unit Quality Metrics](../visualization/visualize_unit_metrics.ipynb). Because it can be very useful to select units by brain region or by probe, you may use the `get_unit_location` and `get_unit_probe` functions below, which take information from the `Electrodes` table to get the location and probes for each unit respectively. The sets of probe names and location names are printed for your convenience."
    ]
   },
   {
@@ -1027,7 +1027,7 @@
    "metadata": {},
    "source": [
     "### Getting Fields\n",
-    "Below the receptive fields for each selected unit are calculated and a visualization for each one is generated. First, we get the dimensions of the receptive field plots from the set of possible gabor coordinates in the stimulus. Next we identify how many spikes happen in response to every stimulus for each coordinate of each unit's receptive field. Finally, we plot each receptive field in a 2D array."
+    "Below the receptive fields for each selected unit are calculated and a visualization for each one is generated. First, we get the dimensions of the receptive field plots from the set of possible coordinates of the gabor patch stimulus. Next we identify how many spikes happen in response to every stimulus for each coordinate of each unit's receptive field. Finally, we plot each receptive field as a 2D array."
    ]
   },
   {