BCI2000Tools.EventRelated - Revision history

Jhill at 23:05, 13 August 2024

2024-08-13T23:05:18Z

← Older revision		Revision as of 23:05, 13 August 2024
Line 15:		Line 15:
	Once you have subversion, you will need a BCI2000 username and password: if you do not already have one, go to https://www.bci2000.org/useradmin/		Once you have subversion, you will need a BCI2000 username and password: if you do not already have one, go to https://www.bci2000.org/useradmin/

	When you are ready, decide where you're going to put the BCI2000 files. You		When you are ready, decide where you're going to put the BCI2000 files and <code>cd</code> to that location. You
	do not need a separate copy for every project (you could, but that ~~could~~ lead to		do not need a separate copy for every project (you could do it that way, but that would lead to version-confusion very easily in future). Pick a place, then choose whether to download the whole (quite large) BCI2000 source distribution:
	version-confusion very easily in future). Pick a place, then choose whether to
	download the whole (quite large) BCI2000 source distribution:
	svn checkout https://bci2000.org/svn/trunk bci2000-svn		svn checkout https://bci2000.org/svn/trunk bci2000-svn
	or just the minimal set of files needed for Python:		or just the minimal set of files needed for Python:
Line 30:		Line 28:
	==2. Tell Python where the code is==		==2. Tell Python where the code is==

	Let's assume that when you type <code>python</code> at the command-line, you get the intended		Let's assume that when you type <code>python</code> at the command-line, you get the intended
	version of Python, in the environment you are comfortable with (with all the sciencey		version of Python, in the environment you are comfortable with (with all the sciencey
	third-party packages you're accustomed to for your other analyses). Getting to this		third-party packages you're accustomed to for your other analyses). To support <code>BCI2000Tools.EventRelated</code>, you will need <code>numpy</code>, <code>scipy</code> and <code>matplotlib</code>, and it is also recommended to get <code>IPython</code>. Getting to this
	point is non-trivial in itself and will not be covered here, except to say:		point is non-trivial in itself and will not be covered here, except to say:
	on Windows, maybe download and install Anaconda, then launch the "Anaconda Prompt"?		on Windows, maybe download and install Anaconda, then launch the "Anaconda Prompt"?
	On a non-Windows system, maybe you need to be typing <code>python3</code> instead of <code>python</code>?		On a non-Windows system, maybe you need to be typing <code>python3</code> instead of <code>python</code>? Maybe it's a good idea to set up a virtual environment first, then activate it, before installing anything?
	Maybe it's a good idea to set up a virtual environment first, then activate ~~that~~?
	The hardest program to write in Python is "Hello World" and this document unfortunately		The hardest program to write in Python is "Hello World" and this document unfortunately
	cannot help with that. Things have got somewhat better since https://xkcd.com/1987		cannot help with that. Things have got somewhat better since https://xkcd.com/1987
Line 59:		Line 56:
	by running the command <code>svn update</code> from that directory. The one thing that could go		by running the command <code>svn update</code> from that directory. The one thing that could go
	wrong is that, after telling Python where the files are, you decide to drag and move them		wrong is that, after telling Python where the files are, you decide to drag and move them
	somewhere else. ~~Then~~ Python will not know where to find them any more, and you~~'ll~~ have to		somewhere else. In that case, Python will not know where to find them any more, and you will have to
	tell it again.		tell it again.

Line 65:		Line 62:
	==3. Invoke BCI2000Tools.EventRelated==		==3. Invoke BCI2000Tools.EventRelated==

	You can invoke the <code>BCI2000Tools.EventRelated</code> code in various different ways. From		You can invoke the <code>BCI2000Tools.EventRelated</code> code in various different ways. From your system command prompt:
	your system command prompt:
	python -m BCI2000Tools.EventRelated ...		python -m BCI2000Tools.EventRelated ...
	or from the IPython command prompt (after launching with <code>python -m IPython</code>):		or from the IPython command prompt (after launching with <code>python -m IPython</code>):
Line 75:		Line 71:
	These are all roughly equivalent. The command-line invocations that use		These are all roughly equivalent. The command-line invocations that use
	<code>-m BCI2000Tools.EventRelated</code> merely translate your command-line arguments into		<code>-m BCI2000Tools.EventRelated</code> merely translate your command-line arguments into
	parameters that get passed to the <code>EpochSet</code> constructor, creating an <code>EpochSet</code>		parameters that get passed to the <code>EpochSet</code> constructor, creating an <code>EpochSet</code> instance that happens to be called <code>self</code> (if you're in IPython, you can then reassign it to a more meaningfully-named variable and continue from there).
	instance that happens to be called <code>self</code> (if you're in IPython, you can then
	reassign it to a more meaningfully-named variable and continue from there).

	In all cases the <code>...</code> stands for additional arguments. The main arguments will		In all cases the <code>...</code> stands for additional arguments. The main arguments will be names of (or paths to) BCI2000 <code>.dat</code> files. Various other options are explained from the command-line help (let's assume you're using IPython):
	be names of (or paths to) BCI2000 <code>.dat</code> files. Various other options are
	explained from the command-line help (let's assume you're using IPython):
	%run -m BCI2000Tools.EventRelated . --help		%run -m BCI2000Tools.EventRelated . --help
	Note that <code>BCI2000Tools.EventRelated</code> produces interactive plots by default:		Note that <code>BCI2000Tools.EventRelated</code> produces interactive plots by default: you can click on the raster-plot to see the waveform an scalp topography that cut through the time and place you select. If you are running IPython in a
	you can click on the raster-plot to see the waveform an scalp topography that
	cut through the time and place you select. If you are running IPython in a
	"notebook" interface, you may need to run the <code>%matplotlib notebook</code> or		"notebook" interface, you may need to run the <code>%matplotlib notebook</code> or
	<code>%matplotlib widget</code> command, or otherwise enable interactivity in your notebook		<code>%matplotlib widget</code> command, or otherwise enable interactivity in your notebook after consulting the relevant documentation.
	after consulting the relevant documentation.

	Here is a simple example command-line:		Here is a simple example command-line:
	%run -m BCI2000Tools.EventRelated testS001R@.dat -t DigitalInput1 -p 2-1B		%run -m BCI2000Tools.EventRelated testS001R@.dat -t DigitalInput1 -p 2-1B
	The <code>@</code> symbol equivalent to a <code>*</code>~~—so~~ this example will match all files that		The <code>@</code> symbol is equivalent to <code></code> (so, this example will match all files that conform to the pattern <code>testS001R.dat</code>) but unlike <code>*</code> it will not get intercepted and expanded by IPython itself.
	conform to the pattern <code>testS001R.dat</code>~~—but~~ unlike <code></code> it will not get
	intercepted and expanded by IPython itself.

	The <code>-t</code> option (a.k.a. <code>--trigger</code>) is critical. It specifies the name of a		The <code>-t</code> option (a.k.a. <code>--trigger</code>) is critical. It specifies the name of a channel or state variable whose value becomes non-zero whenever a stimulus event occurs. You ''could'' use the <code>StimulusCode</code> state variable itself here, but then you are relying on software timing; you will get ''much'' better results if you use a digital trigger activated by some kind of trigger box that senses the light or sound signal in hardware. In the example above, we are imagining that the trigger pulse got digitized into the <code>DigitalInput1</code> state variable (which is provided by the
	channel or state variable whose value becomes non-zero whenever a stimulus event		BCI2000 modules that support various g.tec devices). Once the program has used this to establish ''when'' an event occurred, it will work backwards to find the most
	occurs. You ''could'' use the <code>StimulusCode</code> state variable itself here, but then		recent change of the <code>StimulusCode</code> state variable to a non-zero value, and read that value to determine ''what'' kind of event occurred.
	you are relying on software timing; you will get ''much'' better results if you use
	a digital trigger activated by some kind of trigger box that senses the light or
	sound signal in hardware. In the example above, we are imagining that the trigger
	pulse got digitized into the <code>DigitalInput1</code> state variable, which is provided by
	BCI2000 modules that support g.tec devices. Once the program has used this to
	establish ''when'' an event occurred, it will work backwards to find the most
	recent change of the <code>StimulusCode</code> state variable to a non-zero value, and read
	that value to determine ''what'' kind of event occurred.

	The <code>-p</code> option (a.k.a. <code>--plot</code>) signifies that a plot is required, but it also		The <code>-p</code> option (a.k.a. <code>--plot</code>) signifies that a plot is required, but it also takes an argument that specifies what should be plotted. The example string here, <code>2-1B</code>, is a densely coded shorthand that translates to "subtract the average of <code>StimulusCode=1</code> events from the average of <code>StimulusCode=2</code> events, and perform subtractive baseline correction". Obviously, you need to know what <code>StimulusCode</code> value corresponds to what stimulus in your experiment, and adjust accordingly. You can pool stimulus codes, you can plot average responses with or without contrasting, you can turn baseline correction on or off, you can z-score, you can plot signed r-squared values. All of these options are explained in the documentation for the <code>Processing</code> class, which in IPython can be examined by saying:
	takes an argument that specifies what should be plotted. The example string here,
	<code>2-1B</code>, is a densely coded shorthand that translates to "subtract the average of
	<code>StimulusCode=1</code> events from the average of <code>StimulusCode=2</code> events, and perform
	subtractive baseline correction". Obviously, you need to know what <code>StimulusCode</code>
	value corresponds to what stimulus in your experiment, and adjust accordingly.
	You can pool stimulus codes, you can plot average responses with or without
	contrasting, you can turn baseline correction on or off, you can z-score, you can
	plot signed r-squared values. All of these options are explained in the
	documentation for the <code>Processing</code> class, which in IPython can be examined by
	saying:
	from BCI2000Tools.EventRelated import Processing		from BCI2000Tools.EventRelated import Processing
	Processing?		Processing?
Line 125:		Line 94:

	It is also worth emphasizing the role of the <code>-c</code> option (a.k.a.		It is also worth emphasizing the role of the <code>-c</code> option (a.k.a.
	<code>--highlightChannel</code>): this gives you versatile options for automatically		<code>--highlightChannel</code>), which we did not use in the example above: this gives you versatile options for automatically picking positive and/or negative peaks within certain spatial and temporal constraints, and initializing the interactive plot at that location. In doing so, the program also attaches the results of its search to <code>self.highlighted</code> for later examination and processing. Like the <code>-p</code> option, the <code>-c</code> option also takes a shorthand argument: read the <code>--help</code>.
	picking positive and/or negative peaks within certain spatial and temporal
	constraints, and initializing the interactive plot at that location. In doing
	so, the program also attaches the results of its search to <code>self.highlighted</code>
	for later examination and processing. Like the <code>-p</code> option, the <code>-c</code> option
	also takes a shorthand argument: read the <code>--help</code>.

	===Example Output===		===Example Output===

Jhill at 20:40, 13 August 2024

2024-08-13T20:40:22Z

← Older revision		Revision as of 20:40, 13 August 2024
Line 7:		Line 7:
	==1. Obtain the code==		==1. Obtain the code==

	BCI2000Tools is a set of Python modules and command-line programs. It is		BCI2000Tools is a set of Python modules and command-line programs. It is part of the BCI2000 distribution, where it resides inside the <code>tools/python</code> directory. If you already have these files, that's great. If you still need to download them, the best way to do it is by using Subversion, a.k.a. <code>svn</code>:
	part of the BCI2000 distribution, where it resides inside the <code>tools/python</code>
	directory. If you already have these files, that's great. If you still need to download them, the best way to do it is by using Subversion,
	a.k.a. <code>svn</code>:

	- On Windows, you should download and install TortoiseSVN, '''and during installation,~~'''~~		* On Windows, you should download and install TortoiseSVN, '''and during installation, remember to explicitly select "command line client tools'''" because the installer might not include this by default. After installation, start a whole new Command Prompt.
	~~'''~~remember to explicitly select "command line client tools'''" because the installer
	might not ~~select~~ by default. After installation, start a whole new Command Prompt.

	- macOS may already come with a command-line <code>svn</code> built-in, or you may need		* macOS may already come with a command-line <code>svn</code> built-in, or you may need to install the "XCode Command-line Tools" with <code>sudo xcode-select --install</code>. If all else fails you can install https://brew.sh and then <code>brew install svn</code>.
	to install the "XCode Command-line Tools" with <code>sudo xcode-select --install</code>.
	If all else fails you can install https://brew.sh and then <code>brew install svn</code>.

	Once you have subversion, you will need a BCI2000 username and password: if you		Once you have subversion, you will need a BCI2000 username and password: if you do not already have one, go to https://www.bci2000.org/useradmin/
	do not already have one, go to https://www.bci2000.org/useradmin/

	When you are ready, decide where you're going to put the BCI2000 files. You		When you are ready, decide where you're going to put the BCI2000 files. You

Jhill at 20:34, 13 August 2024

2024-08-13T20:34:05Z

← Older revision		Revision as of 20:34, 13 August 2024
Line 141:		Line 141:

	===Example Output===		===Example Output===
			> python -m IPython

	~~From~~
	~~> python -m IPython~~
	In [1]: run -m BCI2000Tools.EventRelated S05S005R@.dat -t DigitalInput3 -d A2 -p 1-2ZN -c Pz+@250-600 -s "Auditory (Sham Stim.)"		In [1]: run -m BCI2000Tools.EventRelated S05S005R@.dat -t DigitalInput3 -d A2 -p 1-2ZN -c Pz+@250-600 -s "Auditory (Sham Stim.)"


	[[Image:BCI2000ToolsEventRelatedExampleOutput.PNG\|frameless\|width=100%]]		[[Image:BCI2000ToolsEventRelatedExampleOutput.PNG\|frameless\|width=100%]]

Jhill at 20:30, 13 August 2024

2024-08-13T20:30:36Z

← Older revision		Revision as of 20:30, 13 August 2024
Line 146:		Line 146:
	In [1]: run -m BCI2000Tools.EventRelated S05S005R@.dat -t DigitalInput3 -d A2 -p 1-2ZN -c Pz+@250-600 -s "Auditory (Sham Stim.)"		In [1]: run -m BCI2000Tools.EventRelated S05S005R@.dat -t DigitalInput3 -d A2 -p 1-2ZN -c Pz+@250-600 -s "Auditory (Sham Stim.)"

	[[Image:BCI2000ToolsEventRelatedExampleOutput.PNG~~\|center~~\|frameless\|width=90%]]		[[Image:BCI2000ToolsEventRelatedExampleOutput.PNG\|frameless\|width=100%]]

Jhill at 20:29, 13 August 2024

2024-08-13T20:29:52Z

← Older revision		Revision as of 20:29, 13 August 2024
Line 146:		Line 146:
	In [1]: run -m BCI2000Tools.EventRelated S05S005R@.dat -t DigitalInput3 -d A2 -p 1-2ZN -c Pz+@250-600 -s "Auditory (Sham Stim.)"		In [1]: run -m BCI2000Tools.EventRelated S05S005R@.dat -t DigitalInput3 -d A2 -p 1-2ZN -c Pz+@250-600 -s "Auditory (Sham Stim.)"

	[[Image:BCI2000ToolsEventRelatedExampleOutput.PNG\|center]]		[[Image:BCI2000ToolsEventRelatedExampleOutput.PNG\|center\|frameless\|width=90%]]

Jhill at 20:21, 13 August 2024

2024-08-13T20:21:59Z

← Older revision		Revision as of 20:21, 13 August 2024
Line 146:		Line 146:
	In [1]: run -m BCI2000Tools.EventRelated S05S005R@.dat -t DigitalInput3 -d A2 -p 1-2ZN -c Pz+@250-600 -s "Auditory (Sham Stim.)"		In [1]: run -m BCI2000Tools.EventRelated S05S005R@.dat -t DigitalInput3 -d A2 -p 1-2ZN -c Pz+@250-600 -s "Auditory (Sham Stim.)"

	[[Image:~~BCI2000Tools_EventRelated_ExampleOutput~~.PNG\|center]]		[[Image:BCI2000ToolsEventRelatedExampleOutput.PNG\|center]]

Jhill at 20:16, 13 August 2024

2024-08-13T20:16:42Z

← Older revision		Revision as of 20:16, 13 August 2024
Line 139:		Line 139:
	for later examination and processing. Like the <code>-p</code> option, the <code>-c</code> option		for later examination and processing. Like the <code>-p</code> option, the <code>-c</code> option
	also takes a shorthand argument: read the <code>--help</code>.		also takes a shorthand argument: read the <code>--help</code>.

			===Example Output===

			From
			> python -m IPython
			In [1]: run -m BCI2000Tools.EventRelated S05S005R@.dat -t DigitalInput3 -d A2 -p 1-2ZN -c Pz+@250-600 -s "Auditory (Sham Stim.)"

			[[Image:BCI2000Tools_EventRelated_ExampleOutput.PNG\|center]]

Jhill: Created page with "=Analysis of Event-Related Potentials from BCI2000 Files with Python= These instructions assume you are OK with typing commands at a command prompt. If you are not, read this: https://bitbucket.org/jezhill/doc/wiki/CommandLine ==1. Obtain the code== BCI2000Tools is a set of Python modules and command-line programs. It is part of the BCI2000 distribution, where it resides inside the `tools/python` directory. If you already have these files, that's great. I..."

2024-08-13T20:01:34Z

Created page with "=Analysis of Event-Related Potentials from BCI2000 Files with Python= These instructions assume you are OK with typing commands at a command prompt. If you are not, read this: https://bitbucket.org/jezhill/doc/wiki/CommandLine ==1. Obtain the code== BCI2000Tools is a set of Python modules and command-line programs. It is part of the BCI2000 distribution, where it resides inside the <code>tools/python</code> directory. If you already have these files, that's great. I..."

New page

=Analysis of Event-Related Potentials from BCI2000 Files with Python=

These instructions assume you are OK with typing commands at a command prompt.
If you are not, read this: https://bitbucket.org/jezhill/doc/wiki/CommandLine

==1. Obtain the code==

BCI2000Tools is a set of Python modules and command-line programs. It is
part of the BCI2000 distribution, where it resides inside the <code>tools/python</code>
directory. If you already have these files, that's great. If you still need to download them, the best way to do it is by using Subversion,
a.k.a. <code>svn</code>:

- On Windows, you should download and install TortoiseSVN, '''and during installation,'''
'''remember to explicitly select "command line client tools'''" because the installer
might not select by default. After installation, start a whole new Command Prompt.

- macOS may already come with a command-line <code>svn</code> built-in, or you may need
to install the "XCode Command-line Tools" with <code>sudo xcode-select --install</code>.
If all else fails you can install https://brew.sh and then <code>brew install svn</code>.

Once you have subversion, you will need a BCI2000 username and password: if you
do not already have one, go to https://www.bci2000.org/useradmin/

When you are ready, decide where you're going to put the BCI2000 files. You
do not need a separate copy for every project (you could, but that could lead to
version-confusion very easily in future). Pick a place, then choose whether to
download the whole (quite large) BCI2000 source distribution:
svn checkout https://bci2000.org/svn/trunk bci2000-svn
or just the minimal set of files needed for Python:
svn checkout https://bci2000.org/svn/trunk/tools/python bci2000-tools-python
If you are going to use the real-time BCI2000 system on this computer, there are
advantages to going the first route and keeping everything in one place.
If this computer is ''only'' going to be used for analysis, then the second
route is fine.

==2. Tell Python where the code is==

Let's assume that when you type <code>python</code> at the command-line, you get the intended
version of Python, in the environment you are comfortable with (with all the sciencey
third-party packages you're accustomed to for your other analyses). Getting to this
point is non-trivial in itself and will not be covered here, except to say:
on Windows, maybe download and install Anaconda, then launch the "Anaconda Prompt"?
On a non-Windows system, maybe you need to be typing <code>python3</code> instead of <code>python</code>?
Maybe it's a good idea to set up a virtual environment first, then activate that?
The hardest program to write in Python is "Hello World" and this document unfortunately
cannot help with that. Things have got somewhat better since https://xkcd.com/1987
but there's probably still some way to go.

First change your working directory to the directory you just checked out with svn.
For example:
cd bci2000-tools-python
if that's what you called it on the <code>checkout</code> line. Or maybe it's:
cd C:\Somewhere\Somewhere\Somewhere\bci2000-svn\tools\python
if you're on Windows and you checked out the whole distro. Either way, you should now
be working in the directory that contains the file <code>setup.py</code>. From there, you type:
python -m pip install -e .
Make sure to include the <code>-e</code>. And the space and the dot at the end. In fact, include
''all'' the words and all punctuation: computers don't do the right thing unless the
command is exactly right, you know that. Copy-and-paste is your friend.

The <code>-e</code> causes your Python distribution (or virtual environment) to make a note of
where the BCI2000Tools reside, so in future Python will be able know what to reach for
when you <code>import BCI2000Tools.EventRelated</code> or <code>%run -m BCI2000Tools.EventRelated</code>.
The advantage of doing it this way is that you can later get bugfixes and updates simply
by running the command <code>svn update</code> from that directory. The one thing that could go
wrong is that, after telling Python where the files are, you decide to drag and move them
somewhere else. Then Python will not know where to find them any more, and you'll have to
tell it again.

==3. Invoke BCI2000Tools.EventRelated==

You can invoke the <code>BCI2000Tools.EventRelated</code> code in various different ways. From
your system command prompt:
python -m BCI2000Tools.EventRelated ...
or from the IPython command prompt (after launching with <code>python -m IPython</code>):
%run -m BCI2000Tools.EventRelated ...
or from your own Python program:
from BCI2000Tools.EventRelated import EpochSet
x = EpochSet( ... )
These are all roughly equivalent. The command-line invocations that use
<code>-m BCI2000Tools.EventRelated</code> merely translate your command-line arguments into
parameters that get passed to the <code>EpochSet</code> constructor, creating an <code>EpochSet</code>
instance that happens to be called <code>self</code> (if you're in IPython, you can then
reassign it to a more meaningfully-named variable and continue from there).

In all cases the <code>...</code> stands for additional arguments. The main arguments will
be names of (or paths to) BCI2000 <code>.dat</code> files. Various other options are
explained from the command-line help (let's assume you're using IPython):
%run -m BCI2000Tools.EventRelated . --help
Note that <code>BCI2000Tools.EventRelated</code> produces interactive plots by default:
you can click on the raster-plot to see the waveform an scalp topography that
cut through the time and place you select. If you are running IPython in a
"notebook" interface, you may need to run the <code>%matplotlib notebook</code> or
<code>%matplotlib widget</code> command, or otherwise enable interactivity in your notebook
after consulting the relevant documentation.

Here is a simple example command-line:
%run -m BCI2000Tools.EventRelated testS001R@.dat -t DigitalInput1 -p 2-1B
The <code>@</code> symbol equivalent to a <code>*</code>—so this example will match all files that
conform to the pattern <code>testS001R*.dat</code>—but unlike <code>*</code> it will not get
intercepted and expanded by IPython itself.

The <code>-t</code> option (a.k.a. <code>--trigger</code>) is critical. It specifies the name of a
channel or state variable whose value becomes non-zero whenever a stimulus event
occurs. You ''could'' use the <code>StimulusCode</code> state variable itself here, but then
you are relying on software timing; you will get ''much'' better results if you use
a digital trigger activated by some kind of trigger box that senses the light or
sound signal in hardware. In the example above, we are imagining that the trigger
pulse got digitized into the <code>DigitalInput1</code> state variable, which is provided by
BCI2000 modules that support g.tec devices. Once the program has used this to
establish ''when'' an event occurred, it will work backwards to find the most
recent change of the <code>StimulusCode</code> state variable to a non-zero value, and read
that value to determine ''what'' kind of event occurred.

The <code>-p</code> option (a.k.a. <code>--plot</code>) signifies that a plot is required, but it also
takes an argument that specifies what should be plotted. The example string here,
<code>2-1B</code>, is a densely coded shorthand that translates to "subtract the average of
<code>StimulusCode=1</code> events from the average of <code>StimulusCode=2</code> events, and perform
subtractive baseline correction". Obviously, you need to know what <code>StimulusCode</code>
value corresponds to what stimulus in your experiment, and adjust accordingly.
You can pool stimulus codes, you can plot average responses with or without
contrasting, you can turn baseline correction on or off, you can z-score, you can
plot signed r-squared values. All of these options are explained in the
documentation for the <code>Processing</code> class, which in IPython can be examined by
saying:
from BCI2000Tools.EventRelated import Processing
Processing?
or:
%run -m BCI2000Tools.EventRelated . --help-processing

It is also worth emphasizing the role of the <code>-c</code> option (a.k.a.
<code>--highlightChannel</code>): this gives you versatile options for automatically
picking positive and/or negative peaks within certain spatial and temporal
constraints, and initializing the interactive plot at that location. In doing
so, the program also attaches the results of its search to <code>self.highlighted</code>
for later examination and processing. Like the <code>-p</code> option, the <code>-c</code> option
also takes a shorthand argument: read the <code>--help</code>.