Copyright
---------
All the programs and data file are copyrighted material. 
The Copyright (C) to each program and each data file is held by the 

    Department of Epileptology, University of Bonn, Germany
    
You may use and refer to the programs and the data files as you do with any scientific publication. The correct reference to the programs will be

A. Müller, H. Osterhage, R. Sowa, R.G. Andrzejak, F. Mormann, K. Lehnertz.
    "A distributed computing system for multivariate time series analyses of multichannel neurophysiological data",
    Journal of Neuroscience Methods, xx,xxx-xxx, 2005 

Disclaimer
----------
This software is given WITHOUT ANY WARRANTY; without even an implied statement of merchantability or fitness for a particular purpose. 
If you decide to use these programs, you do so entirely AT YOUR OWN RISK.
___________________________________________________________________________________________________________________________________________________

This document contains information as to how to handle the client-server application described in

A. Müller, H. Osterhage, R. Sowa, R.G. Andrzejak, F. Mormann, K. Lehnertz.
"A distributed computing system for multivariate time series analyses of multichannel neurophysiological data",
Journal of Neuroscience Methods, xx,xxx-xxx, 2005 

using 
- an examplary EEG data file (test_eeg.f32), 
- an examplary task file (test_task.xml), 
- an examplary default task file (defaulttask.xml)
- executables for the server (tsadcs_server.exe for Windows(C) operating systems only) and for the client (tsadcs_clientw.exe for Windows(C) 
  and tsadcs_clientu for Linux(C) operating systems) with a restricted functionality, and
- an executable for viewing EEG data or results (tsadcs_dataviewer.exe for Windows(C) operating systems)

provided by the Department of Epileptology, University of Bonn, Germany. 
A more comprehensive guide to the software is in preparation and will be provided soon. Questions or comments may be posted to: h.osterhage@gmx.de

Initial installation steps
--------------------------
Server program:
Copy the server program tsadcs_server.exe to the computer you want to use as the <server>. Note that this program runs under Windows(C) only.
The server program assumes that the data and task files are stored in a single directory. It will also store the result files @.res (and
accompanying @.xml files) in this directory. If you want to use this functionality create the base directory <c:\tsadcs>, and copy the 
files test_eeg.f32, test_task.xml, and default_task.xml into this directory.
Alternatively you can redefine the base directory and the output directory using the command line options of the server program (see below).

Client program:
Copy the client program (tsadcs_clientw.exe for Windows(C) and tsadcs_clientu for Linux(C) operating systems) to the computer(s) you want to 
use as <client(s)>.


Starting the server program
---------------------------
(1) Start the server program by executing the file <tsadcs_server.exe>. If you want to use other directory settings (see above) or other parameter 
settings you may choose the following command line options (default values in brackets):
    -p <port address to listen to> (6800) 
    -d <name of default task file, including full path> (c:\...\defaulttask.xml)
    -o <output directory> (c:\your_output_directory)
    -i <report interval in secs> (300)
    -c <client wait time in secs> (300)
    -w <time out interval in secs> (600)
    -j <maximum number of jobs in one job queue> (100)

(Example: tsadcs_server.exe -p 6800 -o c:\output .....)

(2) Activate the task sheet (second sheet from left) and click the <load task-file-list> button (first from left in upper panel). 
This will open an <open-file> dialog that allows you to select the task file (default: test_task.xml).

(3) Start the job scheduler by clicking on the <start serving task-file-list> button (6th from left in upper panel) and wait until 
the job queue is filled up (this may take some time, depending on the size of the job queue, the number of measures, and the number of channels). 
Upon completion the server program prompts the message:  "jobqueue number xxx filled".

(4) Activate the server program by clicking on the <activate/deactivate> button (2nd from right in upper panel). The server program 
is now listening to connections from the client(s). Results will be written to the file @.res (and @.xml) in either the base directory 
or the chosen output directory.


Starting/stopping the client program
------------------------------------
(1) If the server program is running, clients can be connected to the server. The client program is a console application and can be 
started by typing 
on Windows(C) operating systems:    tsadcs_clientw.exe <IP address of the server> <active port address of the server>
on Linux(C) operating systems:      ./tsadcs_clientu <IP address of the server> <active port address of the server>
If you do not know the server IP address, just look at the server window: it is shown at the buttom right. 
The active port address of the server is chosen as 6800 by default.

(2) Hit <return> and type <start> in the command line. The client program now connects to the server, starts processing jobs, 
and prompts the message "sending/receiving data". Clients connected to the server are listed during run time in the <client sheet> 
of the server window.

(3) Type <quit> in the command line when all jobs are done.


Closing the server program
--------------------------
The server program can be closed at any time. If this is done properly, connected clients will be disconnected properly.
(1) click on the <activate/deactivate> button and wait until all clients have been removed (disconnected) from the <client sheet>.
(2) click on the <close program> buttom (1st button from right in upper panel)


Viewing EEG / result data
--------------------------
The program dataviewer.exe allows you the view the EEG data or the result data file on your computer screen. Just click and select and view.
Note, that in order to view result data, both files @.res and @.xml must be stored in the same directory. 


Structure of the EEG data file
------------------------------
The program assumes that the input data (N channels with M sample points each) is stored in a binary file having the following structure:

control-header
channelinfo 1 
channelinfo 2
... 
channelinfo N
data in multiplexed order (4 byte floats), i.e.,
1st data point(channel 1), 1st data point(channel 2), ..., 1st data point(channel N)
2nd data point(channel 1), 2nd data point(channel 2), ..., 2nd data point(channel N)
...
Mth data point(channel 1), Mth data point(channel 2), ..., Mth data point(channel N)



The control-header is a record of size 1024 byte and contains general informations as to the recording. 
It has the following structure:

*   id               : string[20]                       /for internal use
*   version          : string[6]                        /for internal use                        
    poschannels      : 4-byte signed integer            /points to the position in file where channelinfo begins (0 offset)
    posdata          : 4-byte signed integer            /points to the position in file where data begins (0 offset)
    numchannels      : 2-byte unsigned integer          /total number channels in file
    samplepoints     : 4-byte integer                   /number of data points/channel in data file
    srate            : 8-byte float                     /sampling rate in [Hz]
    starttime,                     
    stoptime         : tdatetime - 8-byte float         /beginning and end of recording (see Delphi manual)
*   reserved1        : array[1..13] of byte             /reserved for future use
*   datatype         : 4-byte signed integer            /for internal use
*   minsamplef,
*   maxsamplef       : 4-byte float                     /for internal use
*   samplesize       : 2-byte unsigned integer          /for internal use
*   reserved2        : array [1..931] of byte           /reserved for future use


The channelinfos are records of size 512 btye and contain informations as to the corresponding channels. 
The structure is:

    name             : 256 byte - Pascal-String         /name of ith recording channel (0 offest)
*   unitstr          : string[31]                       /physical unit
*   reserved         : array[1..224] of byte            /reserved for future use

The marked entries are optional. All other entries are needed for software consistency.