Difference between revisions of "Contributions:BCPy2000"

From BCI2000 Wiki
Jump to: navigation, search
(Author)
(Updated to include python 3.7 port)
 
(25 intermediate revisions by one other user not shown)
Line 1: Line 1:
 
==Synopsis==
 
==Synopsis==
BCPy2000 takes the C++ out of BCI2000 programming. It is aimed at developers of new applications and new signal processing methods, providing a platform for rapid, flexible development of experimental Brain-Computer Interface systems in Python. It takes advantage of various high-level Python packages: VisionEgg[http://visionegg.org] for stimulus presentation, NumPy[http://numpy.scipy.org] and SciPy[http://scipy.org] for signal processing and classification, and IPython[http://ipython.scipy.org] for interactive debugging.
+
BCPy2000 takes the C++ out of BCI2000 programming. It is aimed at developers of new applications and new signal processing methods, providing a platform for rapid, flexible development of experimental Brain-Computer Interface systems in Python. It takes advantage of various high-level Python packages: Psychopy[https://www.psychopy.org] for stimulus presentation, NumPy[http://numpy.scipy.org] and SciPy[http://scipy.org] for signal processing and classification, and IPython[http://ipython.scipy.org] for interactive debugging.
  
You can program a python-based application module, signal processing module, or even a signal source module for generating custom test signals and playing back data files. You can slow the system right down or even step through packet-by-packet, while interactively debugging your python code with pdb.
+
You can program a python-based application module, signal processing module, or even a signal source module for generating custom test signals and playing back data files. Each module can open an IPython shell in which you can inspect and interact with every aspect of the running system. If you're using a BCPy2000-implemented source module, you can slow the system right down or even step through packet-by-packet, which can help you while you're interactively debugging your python code in one of your other modules with pdb.
  
 
BCPy2000 implements a lot of infrastructure that allows you to get an application module running quickly. It also contains a set of optional tools, which are still a work in progress, but which are rapidly turning into a kind of "standard library" of Pythonic signal-processing algorithms and stimulus widgets.
 
BCPy2000 implements a lot of infrastructure that allows you to get an application module running quickly. It also contains a set of optional tools, which are still a work in progress, but which are rapidly turning into a kind of "standard library" of Pythonic signal-processing algorithms and stimulus widgets.
Line 8: Line 8:
 
The source code is available under the terms of the GNU General Public License v3.
 
The source code is available under the terms of the GNU General Public License v3.
  
BCPy2000 is coming soon: 30.09.2008
+
To learn more, see the BCPy2000 web pages[http://bci2000.org/downloads/BCPy2000]
  
 
==Location==
 
==Location==
Line 15: Line 15:
 
==Versioning==
 
==Versioning==
 
===Author===
 
===Author===
Thomas Schreiner, Jeremy Hill, Christian Puzicha, Jason Farquhar
+
Jeremy Hill, Thomas Schreiner, Christian Puzicha, Jason Farquhar
  
 
===Version History===
 
===Version History===
no changes recorded yet.
+
====2020-06-10: BCPy2000 3.7====
 +
Sixth build release. A complete restructuring of the original BcPy2000 build to support Python 3.7. VisionEgg is now deprecated and was replaced with Psychopy[https://www.psychopy.org]. This version has also been built using Pipenv[https://pipenv.pypa.io/en/latest/] in order to create a fully deterministic build leveraging both Pip and a custom Python environment.
 +
 
 +
====2011-07-10: BCPy2000 33960====
 +
Fifth build release.  Various small bugfixes and improvements, and the downloads now contain BCI2000 v.3.0 binaries
 +
 
 +
====2010-07-08: BCPy2000 17374====
 +
Fourth build release.  Various bugfixes and tuneups, a few new API methods in the core classes, and lots of new things in the "optional and patchily-documented tools" section.
 +
 
 +
====2009-09-22: BCPy2000 13637====
 +
Third build release:  Numerous small bugfixes and improvements, and a refactoring of the code to allow the VisionEgg/PyOpenGL back-end to be replaced more easily.  Now distributed together with a portable Python distribution.
 +
 
 +
====2009-03-16:  BCPy2000 11336====
 +
Second release of demo build. The three Python-related core modules are now gnu-compilable and can run on non-Windows platforms.
 +
A number of accumulated enhancements, optimizations and bug fixes, including improved precision of sound stimulus timing, and playback of older-style .dat files (bug reported by Marco Rotonda)
 +
 
 +
====2008-09-30:  BCPy2000 8570 (also known as 1.0)====
 +
Fully integrated framework, with documentation. Higher-level tools are still somewhat patchily documented.
 +
 
 
===Source Code Revisions===
 
===Source Code Revisions===
(TODO: In this section, indicate the BCI2000 source code revisions (changesets)
 
that you used when developing your contribution, and information about
 
testing/compilation. Adapt the list to your own needs.
 
Hint: You obtain the revision of a source code repository by
 
right-clicking its top level directory, and choosing "show log" from the
 
TortoiseSVN submenu.)
 
*Initial development: XXXX
 
*Tested under: YYYY
 
*Known to compile under: ZZZZ
 
*Broken since: UUUU
 
  
==Functional Description==
+
*Initial development: 2148
See the documentation chapter of my [http://{{SERVERNAME}}/downloads/doc/BCPy2000Thesis.pdf thesis].
+
*Tested under: 3396
 +
*Known to compile under: 3396
 +
*Broken since: ----
  
 
==Parameters==
 
==Parameters==
See the documentation chapter of my [http://{{SERVERNAME}}/downloads/doc/BCPy2000Thesis.pdf thesis].
+
 
 +
BCPy2000 has whatever parameters you want to define in your own python module implementations. There are a few that it implements in the framework already, however:
 +
 
 +
====ShowSignalTime====
 +
This boolean, defined by the application framework, determines whether a signal-packet clock should be shown in the bottom right corner of the screen.
 +
 
 +
====TrialsPerBlock====
 +
Your experiment need not be trial-based, but there's a flexible and automatic way of keeping track of trials within blocks, and blocks within runs, if you choose to design it that way. The self.design() application API method helps you set this up, and this parameter, defined by the application module, specifies the number of trials in a block.
 +
 
 +
====BlocksPerRun====
 +
This defaults to 1, so we usually consider a "block" to be the same thing as a "run". However, we once designed an experiment where multiple blocks of trials where recorded continuously in one file, along with the inter-block rest periods. So that had multiple BlocksPerRun. The self.design() application API method allows you to configure this.
 +
 
 +
====WarpFactor====
 +
The default speed at which the Python source module sends its artificial signals through the system. The default value of this parameter, 1.0, means real time.
 +
 
 +
====EnslavePython====
 +
If you check this, then the PythonSignalProcessing and PythonApplication modules will be rendered unable to change the state variables, and PythonApplication's phase transitions will follow the PresentationPhase state instead of allowing the phase machine to run on its own. This allows recorded experiments to be played back, if you're careful about how they're programmed. Type self.doc('Replay') from one of the IPython prompts for more details.
 +
 
 +
====ApplicationDescription====
 +
An arbitrary string describing your Python application module's behaviour, filled in by the self.Description() hook in your BciApplication class implementation.
 +
 
 +
====SignalProcessingDescription====
 +
An arbitrary string describing your Python signal-processing module's behaviour, filled in by the self.Description() hook in your BciSignalProcessing class implementation.
 +
 
 +
====SourceDescription====
 +
An arbitrary string describing your Python source module's behaviour, filled in by the self.Description() hook in your BciSource class implementation.
  
 
==States==
 
==States==
See the documentation chapter of my [http://{{SERVERNAME}}/downloads/doc/BCPy2000Thesis.pdf thesis].
+
BCPy2000 modules have whatever states you want to define for them in your Python implementation. However, the application module framework defines one or two already:
 +
 
 +
====PresentationPhase====
 +
Records the state of the application's "phase machine" as a number. You probably should not rely on the numerical value of this state variable to interpret what was happening, when you read the file back. Instead, define your own state variables with more transparent names, and ensure that your BciApplication.Transition method sets these states accordingly when a transition occurs. Type self.doc('Phase Machine') at one of the modules' IPython prompts for more details.
 +
 
 +
====EventOffset====
 +
This is used as a poor substitute for stimulus timing information when a physical synchronization signal is not available. It is set automatically whenever a phase transition occurs, and its value lets you localize that event in the data stream with reasonable precision. Type self.doc('Timing') at one of the BCPy2000 modules' shell prompts for more info.
 +
 
 +
====CurrentTrial====
 +
If you have chosen to implement a trial-based experimental design, this state variable keeps track of the trial number.
 +
 
 +
====CurrentBlock====
 +
If you have chosen to implement multiple blocks per run in your experimetnal design (see the parameter BlocksPerRun) then this keeps track of the block number.

Latest revision as of 22:56, 5 June 2020

Synopsis

BCPy2000 takes the C++ out of BCI2000 programming. It is aimed at developers of new applications and new signal processing methods, providing a platform for rapid, flexible development of experimental Brain-Computer Interface systems in Python. It takes advantage of various high-level Python packages: Psychopy[1] for stimulus presentation, NumPy[2] and SciPy[3] for signal processing and classification, and IPython[4] for interactive debugging.

You can program a python-based application module, signal processing module, or even a signal source module for generating custom test signals and playing back data files. Each module can open an IPython shell in which you can inspect and interact with every aspect of the running system. If you're using a BCPy2000-implemented source module, you can slow the system right down or even step through packet-by-packet, which can help you while you're interactively debugging your python code in one of your other modules with pdb.

BCPy2000 implements a lot of infrastructure that allows you to get an application module running quickly. It also contains a set of optional tools, which are still a work in progress, but which are rapidly turning into a kind of "standard library" of Pythonic signal-processing algorithms and stimulus widgets.

The source code is available under the terms of the GNU General Public License v3.

To learn more, see the BCPy2000 web pages[5]

Location

http://www.bci2000.org/svn/trunk/src/contrib/BCPy2000

Versioning

Author

Jeremy Hill, Thomas Schreiner, Christian Puzicha, Jason Farquhar

Version History

2020-06-10: BCPy2000 3.7

Sixth build release. A complete restructuring of the original BcPy2000 build to support Python 3.7. VisionEgg is now deprecated and was replaced with Psychopy[6]. This version has also been built using Pipenv[7] in order to create a fully deterministic build leveraging both Pip and a custom Python environment.

2011-07-10: BCPy2000 33960

Fifth build release. Various small bugfixes and improvements, and the downloads now contain BCI2000 v.3.0 binaries

2010-07-08: BCPy2000 17374

Fourth build release. Various bugfixes and tuneups, a few new API methods in the core classes, and lots of new things in the "optional and patchily-documented tools" section.

2009-09-22: BCPy2000 13637

Third build release: Numerous small bugfixes and improvements, and a refactoring of the code to allow the VisionEgg/PyOpenGL back-end to be replaced more easily. Now distributed together with a portable Python distribution.

2009-03-16: BCPy2000 11336

Second release of demo build. The three Python-related core modules are now gnu-compilable and can run on non-Windows platforms. A number of accumulated enhancements, optimizations and bug fixes, including improved precision of sound stimulus timing, and playback of older-style .dat files (bug reported by Marco Rotonda)

2008-09-30: BCPy2000 8570 (also known as 1.0)

Fully integrated framework, with documentation. Higher-level tools are still somewhat patchily documented.

Source Code Revisions

  • Initial development: 2148
  • Tested under: 3396
  • Known to compile under: 3396
  • Broken since: ----

Parameters

BCPy2000 has whatever parameters you want to define in your own python module implementations. There are a few that it implements in the framework already, however:

ShowSignalTime

This boolean, defined by the application framework, determines whether a signal-packet clock should be shown in the bottom right corner of the screen.

TrialsPerBlock

Your experiment need not be trial-based, but there's a flexible and automatic way of keeping track of trials within blocks, and blocks within runs, if you choose to design it that way. The self.design() application API method helps you set this up, and this parameter, defined by the application module, specifies the number of trials in a block.

BlocksPerRun

This defaults to 1, so we usually consider a "block" to be the same thing as a "run". However, we once designed an experiment where multiple blocks of trials where recorded continuously in one file, along with the inter-block rest periods. So that had multiple BlocksPerRun. The self.design() application API method allows you to configure this.

WarpFactor

The default speed at which the Python source module sends its artificial signals through the system. The default value of this parameter, 1.0, means real time.

EnslavePython

If you check this, then the PythonSignalProcessing and PythonApplication modules will be rendered unable to change the state variables, and PythonApplication's phase transitions will follow the PresentationPhase state instead of allowing the phase machine to run on its own. This allows recorded experiments to be played back, if you're careful about how they're programmed. Type self.doc('Replay') from one of the IPython prompts for more details.

ApplicationDescription

An arbitrary string describing your Python application module's behaviour, filled in by the self.Description() hook in your BciApplication class implementation.

SignalProcessingDescription

An arbitrary string describing your Python signal-processing module's behaviour, filled in by the self.Description() hook in your BciSignalProcessing class implementation.

SourceDescription

An arbitrary string describing your Python source module's behaviour, filled in by the self.Description() hook in your BciSource class implementation.

States

BCPy2000 modules have whatever states you want to define for them in your Python implementation. However, the application module framework defines one or two already:

PresentationPhase

Records the state of the application's "phase machine" as a number. You probably should not rely on the numerical value of this state variable to interpret what was happening, when you read the file back. Instead, define your own state variables with more transparent names, and ensure that your BciApplication.Transition method sets these states accordingly when a transition occurs. Type self.doc('Phase Machine') at one of the modules' IPython prompts for more details.

EventOffset

This is used as a poor substitute for stimulus timing information when a physical synchronization signal is not available. It is set automatically whenever a phase transition occurs, and its value lets you localize that event in the data stream with reasonable precision. Type self.doc('Timing') at one of the BCPy2000 modules' shell prompts for more info.

CurrentTrial

If you have chosen to implement a trial-based experimental design, this state variable keeps track of the trial number.

CurrentBlock

If you have chosen to implement multiple blocks per run in your experimetnal design (see the parameter BlocksPerRun) then this keeps track of the block number.