Docs Review - Issues List

[Learmstrong]

Hi all - please find below my points following a comprehensive docs review. [Please note that if a point does not make sense or is unecessary, it is definitely reflective of a lack of experience or understanding on my part :) Feel free to ignore.] I hope this is helpful… Please let me know if I can provide any clarification or if it needs to be reformatted.

 

EEG Notebook - Docs Review

Organization: Left Hand Menu Section Title / Subtitle → Paragraph Title → Problem

Missing Content

• Installation - Introduction - Usage Mode Two - How/where does one download an existing data set? 
• (Perhaps include in Supported Devices?)
• Initiating an EEG Stream - Open BCI Ganglion - Finding the Ganglion’s MAC Address
• Initiating an EEG Stream - Open BCI Cyton - Needed Parameters/Optional Parameters
• Initiating an EEG Stream - Open BCI Cyton + Daisy - Needed Parameters/Optional Parameters
• Analyzing Data
• All Notebook Examples - Cueing Group Analysis - Provide More Context (after each header, ahead of the code.)
• All Notebook Examples - Cueing Behavioral Analysis Winter 2019 - Provide More Context
• All Notebook Examples - Cueing Group Analysis Winter 2019 - Provide More Context 

 

Further Explication Needed

• Running Experiments - Command Line Interface - Perhaps consider giving an example of how the syntax ought to look when the command and flags are combined? (Introprompt Flag)
• Available Notebooks - Visual 300 - Add line for context
• Draft Copy: The visual P300 wave is a spike in brain activity associated with decision making and cognitive processing; it is a spike that occurs 300ms after perceiving a visual stimulus. This was validated in Muse by Alexandre Barachant with the Oddball paradigm, in which low-probability target items are interspersed with high probability non-target items. (Essentially when two different stimuli are presented and one of them occurs infrequently - this is the oddball.) 
• Available Notebooks - N170 - Add line for context
• The N170 is an ERP (event-related brain potential) specifically related to the perception of faces; it is a negative waveform that peaks about 170ms after stimulus presentation.
• Available Notebooks - SSVEP - Add line for context
• The steady state visual evoked potential (or SSVEP) is a response produced following visual stimulation at specific frequencies. It was validated by Hubert in a 12 minute experiment (6 x 2 minute trials). Stimulation frequencies of 30hz and 20hz were used and an extra electrode at POz was added. Clear peaks were found in the PSD at the stimulation frequencies. 
• All Notebook Examples - P300 Load and Visualize Data
• It is possible that those who will load data might lack experience (as opposed to someone with an EEG device who will run their own experiment.) It might be appropriate to explain some of the key terms in one section between N170 and P300: (I chose the P300 here because it is the first in the “Available Notebooks” Section.)
• Draft Copy
• Visualize the Power Spectrum: Viewing the power spectrum is a standard method for quantification of EEG. This basically measures a signal’s power content over its frequency. 
• Filtering: Filtering is a useful technique for producing interpretable EEG tracings - essentially they clean up the data. You can learn more about filters herewh.
• Epoching: This is a protocol in which specific time-windows are extracted from the continuous EEG signal. 
• Epoch Average: 
• The 2-1 Wave Shows the ERP Amplitude (I think?)
• The Green Wave Shows the Target Stimuli
• The Red Wave Shows the Non-Target Stimuli
• All Notebook Examples - Cueing Single Subject Analysis - Further clarify intro sentence.
• “Here, we are computing and plotting differences between time frequency window for analysis.” 

 

Clarification

• Available Notebooks - Unvalidated Experiments and Other Phenomena - More Context
• Do we include? No further mention throughout the notebook...

 

Spelling and Grammar

• Initiating an EEG Stream - Introduction First Paragraph - “Before running an experiment”
• Initiating an EEG Stream - Introduction Fourth Paragraph - “Various support devices”
• Available Notebooks - Visual P300 with Oddball Paradigm - “attain”
• All Notebook Examples - P300 Load and Visualize Data - Introduction Paragraph 1: “This experiment uses an oddball paradigm: “Images of cats and dogs are shown in a rapid serial visual presentation (RSVP) stream, with cats and dogs categorized respectively as ‘targets’ or ‘non-targets’, according to which has high or low probability of occurring, respectively.”
• All Notebook Examples - Cueing Single Subject Analysis - Spectogram - Add period after “time.”
• P300 Load and Visualize Data - Setup, Load Data - Remove Reference to N170 example data set and Replace
• P300 Load and Visualize Data - Filteriing - “Filtering”

 

Formatting

• Initiating an EEG Stream - Supported Devices - Organization
• Initiating an EEG Stream - Supported Devices - Add Photo for Interaxon Muse
• Available Notebooks - All Titles - Match order of paragraphs to order of experiments menu
• All Notebook Examples - Cueing Single Subject Analysis - Retitle “Now we compute and plot the differences” to “Computing and Plotting Differences.”
• All Notebook Examples - N170 run experiment - Capitalize, “Run Experiment”
• All Notebook Examples - P300 run experiment  - Capitalize, “Run Experiment”
• All Notebook Examples - SSVEP run experiment - Capitalize, “Run Experiment”
• All Notebook Examples - SSVEP run experiment - Pull intro/outro text (the blue # i.e “Next, we will chunk (epoch) the data into segments…”) out of code on Sections “Epoching,” “Stimuli-Specifc PSD,” and “Spectogram” and convert into standard formatted text so that it is entirely visible to the user.
• All Notebook Examples - SSVEP Decoding - ^Same Note as above. Convert intro text into standard formatted text for Sections “Epoching,” “Decoding,” and “Decoding.” 
• All Notebook Examples - Cueing Single Subject Studies - ^Same Note as above. Convert intro text into standard formatted text for Section “Now we compute and plot the differences.”

 

Possible Pain Points

• Take out spaces before codes in Installation section - Not a huge problem, but having to remove the indentations at the start of every line when copying it from Github to Jupyter is a little cumbersome.
• Test Installation - If you are trying to run an experiment on existing data, the "Initiate EEG device" code seems to hinder full execution of this test on my end. This might be an area where we “fork” a separate installation test for those who are using existing data.

[oreHGA]

I'll start to open PRs for the different sections in the comment and link to this issue