eferrea / bci-master Goto Github PK

[Opened as part of JOSS review openjournals/joss-reviews#3956]

The README file is currently the only existing documentation, and is a bit sparse (even though maybe a lot of this is very conventional for BCI software). In particular:

• The elements of the GUI could need more information: Why are the units presented in 4 panels (only for space reasons?) and what are the axes (x = channel and y = unit?). How exactly is the "tuning strength" encoded in the colors (a colorbar might be helpful as well)? What do the columns in the table show?
• The "extended functionalities" also merit some more explanation. In particular, it is sometimes unclear in what order these functionalities can be used: there is a "Load Decoder" but no "Save Decoder" – are decoders saved automatically? At what point should one change "Shared Control", etc. Also, I did not immediately understand the difference between "Check correlation" and "BCIIDLE".
• The Matlab code for BCI_Loop has some comments how to call it (e.g. with suggestions for the update time and the number of neurons), but other functions/classes like simNeurons_2D_velocity do not state what their arguments are; this information is only included in individual comments in the source code itself.
• Finally, the BCImat folder contains some basic tests in the Test folder, but it is unclear what these do (and they also have hardcoded IP addresses).

[Opened as part of JOSS review openjournals/joss-reviews#3956]

The repository should mention where users should contact you, whether you are interested in contribution and what system (e.g. GitHub issues and Pull Requests) you use for bug reports and contributions.

[Opened as part of JOSS review openjournals/joss-reviews#3956]

Obviously, automatic testing GUI software is complicated, so I don't expect the authors to write a test suite covering the full functionality of their software. It would be nice, however, to have clearer instructions on what is expected when using the artificial neurons. Something along the lines of "perform about 50 reaches in the task controller, then select about 20 units with a tuning strength above X. After pressing "Switch BCI", the cursor movement should go to the points on a fairly straight line; "Check correlation" should show correlations around Y". When I tested the software, it seemed to do something reasonable, but I wasn't really sure what to expect in detail.

[Opened as part of JOSS review openjournals/joss-reviews#3956]

From the README, I wasn't entirely sure whether the TrackM is supposed to be basically used as it is, or whether it is just presented as an example for the real code that users would write. If it is meant to be reused, then I find it quite inconvenient to change the source code just to change IP addresses (in particular, since the one that is given by default is an internal network address instead of something more generic like 127.0.0.1) – wouldn't it make sense to hand them over via command line arguments or a configuration file, for example? If this file is just an example, then I think more documentation is needed to describe what users would have to be aware of when writing such a program (link with VRPN, etc.).

[Opened as part of JOSS review openjournals/joss-reviews#3956]

Consider improving installation instructions
Going through with the installation was non-trivial, in particular since it requires several external dependencies that need to be installed first, and no help is given besides links to their websites.
I know that Visual Studio projects are a common way of setting up things in Windows, but maybe either clearly state that you focus on Windows, or use a more general build system (e.g. cmake). I was able to build things under Linux, but I basically ignored everything in the Visual Studio project (which also includes plenty of stuff that seems irrelevant, like log files, etc.), and directly built the files in the Source Files folder with:

g++ -I/usr/local/include -L/usr/local/lib *.cpp $(pkg-config --libs sfml-all) -lvrpn -lpthread -lquat

You should also note that the Matlab code requires the "Statistics and Machine Learning Toolbox". Also (but I haven't used Matlab in a long time, so this might be trivial): I had to use addpath with BCI_Classes etc. to get the BCI_Loop function to run.