This application can be used for performing a range of operations on EEG data files, up to and including visualization and scoring operations.
Jeda is distributed in various forms. The source Java code is always provided, but there may or may not be (a) extra C code, (b) a compiled version of the Java code, (c) a set of data files.
The easiest hands-on introduction to Jeda is via the GUI-based 'demonstration version' of Jeda, which includes compiled Java and 22 datasets, and is described here. (You may want to look first at Java installation, to check if you have Java installed.) The Demo's GUI makes certain operations very convenient, however it is limiting.
Users who want to access all Jeda's features, and even recompile or modify the code, will need to read some or all of the the following sections.
Please note: this application currently works 'out of the box' only for a certain set of operations (flexible binning and averaging of single trial epochs, and spectral transformation). Anyone wanting other operations will have to provide their own plug-ins, or else be patient until I or someone else can oblige.
Also note: all core functionality is provided by Java code, so the code can easily be compiled and run on any platform. However the distribution contains optional extras that link to code written in other languages; and so to get the full benefit of the supplied code requires installation of various packages, and compliations in several languages. To access the more advanced aspects of this application, it helps to be a programming enthusiast!
The demonstration version of Jeda has a GUI interface; but in all
other situations familiarity with the Command Line Interface, as
provided by a terminal window, is necessary. In particular, running
and monitoring batch jobs is extremely simple with a terminal
window.
The main prerequisites for Jeda are Java 5.0 (or later), and a
computer with adequate RAM (i.e., a few times larger than the size of
your data files). The demonstration version of Jeda runs comfortably
on a system with 1GB of RAM.
Java comes in many versions, and there are certain distinctions that matter, and others that don't. The steps below attempt to determine whether or not your computer needs Java (or another version of Java) to be installed.
It is essential that Java is installed and running successfully. Installation of Ant is only required if you need to compile Jeda, i.e. if you have the Detailed version rather than the Demonstration version.
The distribution includes a compiled version of Jeda. The GUI demonstration can therefore be run immediately, as described elsewhere.
Uncompiled Jeda source code and all the extras are supplied as two 'jar' file called something like CLI-1.0-src-20091223.jar and CLI-1.0-data-20091223.jar. Put both these files into a new, empty directory, open a terminal, change the default directory to this new directory (use the 'cd' command), and unpack the distribution files by typing
jar xf CLI-1.0-src-20091223.jar
jar xf CLI-1.0-data-20091223.jar
This will create several files and subdirectories in the new directory. (The
'jar' utility used here is part of any Java JDK installation, and will
run provided you successfully set your PATH to include
JAVA_BINDIR.
The detailed distribution contains source code, which needs to be compiled before it can be run. There is Java source code, plus some addition optional C source code. The matter of integrating Java with native code is sufficiently complex that many users will prefer to get up and running with a pure Java version of Jeda. This is easily achieved by avoiding those plug-ins that rely on native code, by not running native compilation commands, and by using a simplified set of command line options.
Type
ant -pto get a reminder of all the ways in which Ant can be used. One option is
ant nonwhich compiles all Java source code (but not any source code in other languages — hence no native code or 'non'). A simple test of the compiled 'class' files is to type one of
java -cp build:lib/derby.jar frontendClasses.CLI -h java -cp build;lib\derby.jar frontendClasses.CLI -h(Both Linux and Windows versions are shown here.) If all is well, then you should see something like this.
Under Windows the ‘/’ directory separator goes the opposite way, and ':' becomes ';'. Also it seems necessary under Windows to extend the classpath to include (the fully-qualified path for) tools.jar, e.g. -cp build;lib\derby.jar;%JAVA_HOME%\lib\tools.jar.
Note that in general commands have two parts: the Java-specific part (e.g. java -cp build;lib\derby.jar), and the program-specific part (e.g. frontendClasses.CLI -h). The two parts must not be intermingled.
Regarding the Java-specific part, the command 'java' tells the operating system to load Java, and the subsequent items guide specify how Java is to be run. In this particular case:
Regarding the program-specific part, the command 'frontendClasses.CLI' tells Java to load the main entrypoint to Jeda, CLI, and the subsequent items specify how CLI is to be run. In this particular case:
The distinction between 'Java-specific' and 'program-specific' may seem arbitrary at first, however it reflects an important aspect of the design and robustness of Java. The former is responsible for creating and configuring a 'box', and the latter says what is to happen within the box. The former is generic to all of Java, and the latter is entirely specific to Jeda. The section below, Running, lists more of the command line switches (words preceded by '-'), and should clarify this distinction.
Processing EEG data using a purely Java version of Jeda is simpler for programmers, administrators and users. However legacy code is sometimes an irresistable temptation, so it is often found necessary to call code written in other languages; routines written in C or Matlab are prime candidates. A fuller version of Jeda can be built from the supplied jar file, which can call utility code written in C and scripts written in R. The following two sections provide some directions to help with building a full version. Administrative skills are assumed.
In addition to the Java JDK and Ant, a Linux system may need the following packages to be installed:
Then compile a full version of Jeda, including native code. Type
ant -pto see the ways in which Ant can be used: one option should be
antwhich compiles both Java and C source code. Java compilations are straightforward, but there several separate compilations of C code take place: 32- and 64-bit versions for linux, and a 32-bit version for Windows. The results are written to directories native32 and native64. It is convenient to have a link named 'native' pointing to the one relevant to your system, e.g. by typing ln -s native64 native.
A simple test of the compiled 'class' files is to type
java -cp build:lib/derby.jar:jri/JRI.jar -Djava.library.path=native:jri frontendClasses.CLI -hThe native code plugins should appear somewhere in the output.
Some like to store the bit following -cp in the environment variable named CLASSPATH. These notes instead always state the classpath explicitly in the command line.
In addition to the Java JDK and Ant, a Windows system may need the following installations:
The compiler is optional, and only required if you need to call legacy code. The packages R and rJava are optional, and only necessary if using R to perform scoring, in which case please note:Then compile a full version of Jeda, including native code. Type
ant -pto see the ways in which Ant can be used: one option should be
antwhich compiles both Java and C source code. Actually there are complications to do with 32 and 64 bit versions of the operating system, and so you might like to create a folder native to hold the DLL, or else generate distinct DLLs in folders native32 and native64.
A simple test of the compiled 'class' files is to type
java -cp build;lib\derby.jar;jri\JRI.jar;%JAVA_HOME%\lib\tools.jar -Djava.library.path=native;jri frontendClasses.CLI -hThe native code plugins should appear somewhere in the output.
Some like to store the bit following -cp in the environment variable named CLASSPATH. These notes instead always state the classpath explicitly in the command line.
Note that it seems necessary under Windows to extend the classpath to include (the fully-qualified path for) tools.jar.
There are a number of files that are significant to how the
the application is built and runs:
| File | Description |
|---|---|
| build.xml | This works with the 'ant' program, and encapsulates many operations to do with building the application and documentation, and with performing tests on the code |
| backend.properties | This is used to specify the location of script and cache files; also to set the default operational mode for the cache |
| derby.properties | This is used to enable and configure logging by Derby |
| logging.properties | This may be used to customize the style of diagnostic logging |
Once the application is installed, and runnable with the -h
option (as just described), then it is ready to try on real data. The
general form of the command line is always
java Java-related_options frontendClasses.CLI application-related_options
There are several Java-related options, the most relevent of which are listed below.
| Java option | Description |
|---|---|
| -cp classpath | The 'classpath' points to the various components of Jeda — the program components rather than the data. All compiled code is found under the directory 'build'. However the classpath must also include all relevant 'jar' files, so is commonly build:lib/derby.jar:jri/JRI.jar. In addition, Windows seems to require tools.jar to be included too (so append %JAVA_HOME%\lib\tools.jar). Also, if reading or writing to a database with Jeda you will need to point it to a JDBC driver (so append something like lib/mysql-connector-java-5.1.7-bin.jar). (Remember that in Windows ':' becomes ';', and '/' becomes '\'.) |
| -ea | This enables additional checking of the validity of variable values throughout the program. It is a debugging option. |
| -Xmx200m | This specifies the Java heap space (200MB in this example) allocated to the program. The default is 64MB while something like 200MB is generally necessary. Note that additional (non-Java heap) memory is required by the program — about 300MB. [Under Linux this can be seen by using top, and computing VIRT + RES.] |
| -Djava.library.path=native32:jri | When C methods are being called (specifically by eegfit and the JNI bridge to R) it is necessary to specify the location of the C libraries. In the present case the subdirectories are native32 (or native64) and jri. (Remember that in Windows ':' becomes ';', and '/' becomes '\'.) This option is unnecessary when using purely Java aspects of Jeda. |
| -Dserver.cache.enable={RW | RO | WO | false} | This enables reading from and writing to the cache. The cache holds copies of intermediate time-series results, and greatly speeds up operations when files are accessed repeatedly. The value specified on the command line overrides whatever is specifed in backend.properties. The default is RW. |
| -Djava.util.logging.config.file=myfile | The default configuration of the logger is managed by a properties file somewhere in the the Java distro. However if customization is required, then this option allows some other file to be specified. There is one called 'logging.properties' provided with Jeda. |
| -Dcom.sun.management.jmxremote.port=number -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=true |
This enables remote management. If the program is run with these system properties on a remote host, if jstatd is run on the remote system with an open policy, and if jmxremote.password is created and jmxremote.access is confirmed (in $JRE_HOME/lib/management/ on the remote host); then a connection may be made by typing 'jconsole &' or 'jvisualvm &' on the local machine, and entering remotehost:port and any name and password found in the access file. See here and here for more. [The filewall on the remote host will need to have the designated port open for incoming TCP connections.] |
| -Djava.awt.headless={true | false} | If headless operation is required, then set the property java.awt.headless to true on the command line (-Djava.awt.headless=true). This will disable all the graphical options within Jeda, which may be useful in special cases, as when running long processing jobs, or jobs on remote servers. |
The numerous application-related options are described thoroughly in the User documentation. Here is a very brief overview.
Overall there are two stages to the application-related options, both consisting of several sub-stages. The first stage involves processing the continuous time-series data:
| -fn filename -ff [EEG | EDF | NS5 etc] -fq SQL_WHERE -fileOverview |
Reading data files
|
| -scriptChannel dir/filename | Time-series operations
|
| -paradigm oddb,eeg etc -scriptEpoch filename -eventSelection SQLcommand -chanSelection SQLcommand -labelXxxxx value .... |
Epoch selection
|
| -previewSeries -reviewSeries |
FullTimeSeries
|
| -transform [null | power | phase | sq] -binZ Site (e.g.) -binH Stim (e.g.) -binV AlphaPh (e.g.) -dumpRaw -dumpUnbinned -dumpBinned |
Epoch extraction and binning
|
| -score option(params)[][] option(params)[][] ... | Transformations and scoring
|
| -display option(params)[][] option(params)[][] ... | Display results
|
| -output option(params)[][] option(params)[][] ... | Export results
|
The above instructions should enable you to compile Jeda. You will now want to try it out on real data. One option is to try the GUI demonstration program, as shown in Demonstration. Another is to drive Jeda directly by typing the following on the command line.
The following are Linux commands that display the raw data for eleven paradigms for session 1 of subject 81237443.
java -cp build:lib/derby.jar -Xmx200m frontendClasses.CLI -fn data/81237443-1.EC.NS5 -scriptChannel Minimal -paradigm ec -reviewSeries java -cp build:lib/derby.jar -Xmx200m frontendClasses.CLI -fn data/81237443-1.EO.NS5 -scriptChannel Minimal -paradigm ec -reviewSeries java -cp build:lib/derby.jar -Xmx200m frontendClasses.CLI -fn data/81237443-1.AH.NS5 -scriptChannel Minimal -paradigm ah -reviewSeries java -cp build:lib/derby.jar -Xmx200m frontendClasses.CLI -fn data/81237443-1.ODDB.NS5 -scriptChannel Minimal -paradigm oddb -reviewSeries java -cp build:lib/derby.jar -Xmx200m frontendClasses.CLI -fn data/81237443-1.EYET.NS5 -scriptChannel Minimal -paradigm eyet -reviewSeries java -cp build:lib/derby.jar -Xmx200m frontendClasses.CLI -fn data/81237443-1.GNG.NS5 -scriptChannel Minimal -paradigm gng -reviewSeries java -cp build:lib/derby.jar -Xmx200m frontendClasses.CLI -fn data/81237443-1.LET.NS5 -scriptChannel Minimal -paradigm let -reviewSeries java -cp build:lib/derby.jar -Xmx200m frontendClasses.CLI -fn data/81237443-1.WM.NS5 -scriptChannel Minimal -paradigm wm -reviewSeries java -cp build:lib/derby.jar -Xmx200m frontendClasses.CLI -fn data/81237443-1.PPI.NS5 -scriptChannel Minimal -paradigm ppi -reviewSeries java -cp build:lib/derby.jar -Xmx200m frontendClasses.CLI -fn data/81237443-1.FACES.NS5 -scriptChannel Minimal -paradigm faces -reviewSeries java -cp build:lib/derby.jar -Xmx200m frontendClasses.CLI -fn data/81237443-1.MAZE.NS5 -scriptChannel Minimal -paradigm maze -reviewSeries
The equivalent Windows commands are
java -cp build;lib\derby.jar;%JAVA_HOME%\lib\tools.jar -Xmx200m frontendClasses.CLI -fn data\81237443-1.EC.NS5 -scriptChannel Minimal -paradigm ec -reviewSeries java -cp build;lib\derby.jar;%JAVA_HOME%\lib\tools.jar -Xmx200m frontendClasses.CLI -fn data\81237443-1.EO.NS5 -scriptChannel Minimal -paradigm ec -reviewSeries java -cp build;lib\derby.jar;%JAVA_HOME%\lib\tools.jar -Xmx200m frontendClasses.CLI -fn data\81237443-1.AH.NS5 -scriptChannel Minimal -paradigm ah -reviewSeries java -cp build;lib\derby.jar;%JAVA_HOME%\lib\tools.jar -Xmx200m frontendClasses.CLI -fn data\81237443-1.ODDB.NS5 -scriptChannel Minimal -paradigm oddb -reviewSeries java -cp build;lib\derby.jar;%JAVA_HOME%\lib\tools.jar -Xmx200m frontendClasses.CLI -fn data\81237443-1.EYET.NS5 -scriptChannel Minimal -paradigm eyet -reviewSeries java -cp build;lib\derby.jar;%JAVA_HOME%\lib\tools.jar -Xmx200m frontendClasses.CLI -fn data\81237443-1.GNG.NS5 -scriptChannel Minimal -paradigm gng -reviewSeries java -cp build;lib\derby.jar;%JAVA_HOME%\lib\tools.jar -Xmx200m frontendClasses.CLI -fn data\81237443-1.LET.NS5 -scriptChannel Minimal -paradigm let -reviewSeries java -cp build;lib\derby.jar;%JAVA_HOME%\lib\tools.jar -Xmx200m frontendClasses.CLI -fn data\81237443-1.WM.NS5 -scriptChannel Minimal -paradigm wm -reviewSeries java -cp build;lib\derby.jar;%JAVA_HOME%\lib\tools.jar -Xmx200m frontendClasses.CLI -fn data\81237443-1.PPI.NS5 -scriptChannel Minimal -paradigm ppi -reviewSeries java -cp build;lib\derby.jar;%JAVA_HOME%\lib\tools.jar -Xmx200m frontendClasses.CLI -fn data\81237443-1.FACES.NS5 -scriptChannel Minimal -paradigm faces -reviewSeries java -cp build;lib\derby.jar;%JAVA_HOME%\lib\tools.jar -Xmx200m frontendClasses.CLI -fn data\81237443-1.MAZE.NS5 -scriptChannel Minimal -paradigm maze -reviewSeries
As can be seen, the Java-specific options tend to be generic, while the program-specific options specify:
Finally, to deal with multiple data files, try creating a 'script' or 'batch' file. Such files are a great help for automating and standardizing operations.
Below is a file, named 'preview', which means that you just have to type 'preview filename' in order to see the full timeseries.
#! /bin/bash
# This provides a simple means to run jeda. To see the full
# timeseries, it is only necessary to specify a filename.
# If a suitable paradigm is specified too, then the standard
# choice of epochs will be shown -- otherwise the file is
# treated as an EC recording.
if [ $# -eq 0 -o $# -gt 2 ]; then
echo "Usage:"
echo " $0 filename [ah|ec|eyet|faces|gng|let|maze|oddb|ppi|wm]"
exit 2
elif [ $# -eq 1 ]; then
f=${1}
p="ec"
else
f=${1}
p=${2}
fi
javaOps="-cp build:lib/derby.jar -Xmx200"
java $javaOps frontendClasses.CLI -fn $f -scriptChannel Minimal -paradigm $p -reviewSeries
The following examples demonstrate processing of multiple files, with the help of a 'for' loop.
# C Shell version
set javaops = "-Xmx300m -cp build:lib/derby.jar:jri/JRI.jar -Djava.library.path=native:jri"
foreach f (data/*.NS5)
java $javaops frontendClasses.CLI -fn $f other options...
end
or
# BASH version
javaops="-Xmx300m -cp build:lib/derby.jar:jri/JRI.jar -Djava.library.path=native:jri"
for f in data/*.NS5; do
java $javaops frontendClasses.CLI -fn $f other options...
done
Windows has a scripting language too. The files demo and
demo.bat, provided with Jeda, are examples of batch files.
Another option to ease the burden of repetitive commands is to create a shortcut or alias. Under Linux you can, for example, specify
# C Shell version alias review 'java -Dserver.cache.enable=false -cp build:lib/derby.jar -Xmx200m frontendClasses.CLI -scriptChannel Minimal -paradigm gng -reviewSeries -display "Summary()" -fn' # BASH version alias review='java -Dserver.cache.enable=false -cp build:lib/derby.jar -Xmx200m frontendClasses.CLI -scriptChannel Minimal -paradigm gng -reviewSeries -display "Summary()" -fn'on the command line. The alias encapsulates a complete Jeda command — except for '-fn' at the end, which still needs a filename in order to make sense. Then, having defined this alias, typing
review data/8281233.GNG.NS5will be equivalent to typing the full command explicity.
Date Lines Milestones 20060709 7005 Skeleton done, but no Channel stuff, scoring, viewing 20060806 8381 Added management of channel labelling 20060821 10987 Added Gratton to complete essential Channel stuff 20060902 12826 Added ability to generate synthetic data sets 20061017 15060 Added display of continuous time-series 20070226 17013 Added event selection through SQL technique 20070411 17207 Waveforms supplemented by table of attributes 20070701 20410 Binned queries, cache, improved visualization 20070907 21061 Framework for pluggable display options 20071108 23950 Framework for holding, viewing and probing scores 20080308 28088 Export of results in various formats 20080716 34541 Runtime compilation, mocks 20090116 35777 Consolidation and documentation 20090406 40567 Heart rate variability 20090510 41647 Simple GUI frontend 20090906 46670 Display option 'Summary' 20091105 48988 Revised main plotting class
| Goal | Weeks | Priority |
|---|---|---|
| Make a full dump of scores available to plot routines | 1 | •• |
| More unit tests | 3 | • |
| Fancy widget for fitting option | 3 | •• |
| Show topographical map | 4 | •• |
| Reader for PeterD's data | 1 | • |
| Option to export scores in ARFF format – for Weka | 1 | • |
| Add 'ranges' to delimit periods of hypoxia, artifact etc | 2 | • |
| Consider how to bin and average across subjects | 6 | • |
| Implement coherence, ICA and wavelet transforms | 12 | • |
| Generalize viewer to allow overlays and differencing | 6 | • |
| Test DB/cache management to handle multiple simultaneous sessions | 2 | • |
Jeda is rather limited. Why can't it do X?
Answers include (a) because so far I have only been concerned with ensuring it does what I want, (b) because other packages already do certain tasks very well (e.g. Eeglab and ICA), and (c) extensions are best programmed by those end-users who have specialized needs and knowledge. But tell me anyway about Jeda's deficiencies. I am happy to consider adding core functionality, and am happy to encourage you to add extensions. Specialized display options are definitely 'plugins' as they require minimal knowledge of the inner workings of Jeda, so are well-suited to independent development.
Is the code available for download or update via SVN?
Not at present. Requests for the source code will be handled via email (see below), as will suggestions for corrections and improvements.
I have signal processing algorithms implemented in Matlab. Can I call them or do I have to rewrite them in Java?
Calling code in other language is possible, and the distribution provides examples of calling C and R routines — although there are no Matlab examples yet. Mixed language programming is no fun, as passing objects and exceptions is extraordinarily laborious, and portability is severely compromised. Rewriting in Java should be considered.
Do the scores from Jeda match those generated by Brain Resource?
Probably not. Jeda is an independently-developed package, whose scores have never been compared with those from Brain Resource. Differences in detail are therefore likely. Nor is compatibility with Brain Resource a goal. Rather, Jeda is a vehicle offering total control over all stages of signal processing, and total freedom to extend the options.
How do I uninstall (or upgrade) Jeda?
This is easy: referring to Jeda Installation you will see that Jeda was installaed by unpacking it into an empty folder. Consequently, to uninstall Jeda you can simply delete that folder. Likewise, when upgrading, you can create a new folder, unpack the new distribution in this new folder; and delete the old folder whenever you wish.
| Validate HTML CSS | Last changed 2009-11-13 | Chris Rennie |