File: nedc_eeg_resnet_decode_realtime/v1.0.0/AAREADME.txt
Tool: The NEDC EEG ResNet Real-Time Decoding System
Version: 1.0.0

-------------------------------------------------------------------------------
Change Log:

20230331 (ML): initial version

-------------------------------------------------------------------------------

This tool is a real-time seizure detection system based on our previously
released research system. To learn more about the
origins of the tool, please see this publication::

 Khalkhali, V., Shawki, N., Shah, V., Golmohammadi, M., Obeid, I., &
 Picone, J. (2021). Low Latency Real-Time Seizure Detection Using
 Transfer Deep Learning. In I. Obeid, I. Selesnick, & J. Picone
 (Eds.), Proceedings of the IEEE Signal Processing in Medicine and
 Biology Symposium (SPMB) (pp. 1–7). Philadelphia, Pennsylvania,
 USA. https://isip.piconepress.com/publications/conference_proceedings/
 2021/ieee_spmb/eeg_transfer_learning/.

===============================================================================
A. WHAT'S NEW

Version 1.0.0: 
  + initial version of the system

===============================================================================
B. INSTALLATION REQUIREMENTS

Python code unfortunately often depends on a large number of add-ons, making
it very challenging to port code into new environments. This tool has been
tested extensively on Windows and Mac machines running Python v3.9.x.

Software tools required include:

 o Python 3.7.x or higher (we recommend installing Anaconda)
 o Numpy/SciPy: http://www.numpy.org/
 o PyTorch: https://pytorch.org/
 o Pillow: https://pillow.readthedocs.io/en/stable/
 o PyEDFlib: https://pypi.org/project/pyEDFlib/
 o Scikit-learn: https://scikit-learn.org/stable/

There is a requirements.txt included in the release that helps you automate
the process of updating your environment.

===============================================================================
C. USER'S GUIDE

C.1. WINDOW USERS

For Window users, we recommend users install Anaconda in order to run
a bash emulator.

Through the Anaconda prompt, create a new environment and specify the proper
python version:

 $ conda create -n <my_environment_name> python=3.9

Install a bash emulator that will allow running the annotation tool:

 $ conda install m2-base

Install the required packages:

 $ conda install numpy
 $ conda install pillow
 $ conda install torch
 $ conda install torchvision
 $ conda install lxml
 $ conda install scipy

The easiest way to run this is to change your current working directory
to the root directory of the installation and execute the tool as follows:

 $ cd <my_install_location>/nedc_eeg_resnet_realtime_decode/v1.0.0
 $ ./bin/nedc_eeg_resnet_realtime_decode
 
Once the software has been installed, you need to do the following things if
you want to run this from any directory:

 - set the environment variable NEDC_NFC to the root directory
   of the installation:

    $ export NEDC_NFC='<install_location>/nedc_eeg_resnet_realtime_decode/v1.0.0'

 - put $NEDC_NFC/bin in your path:

    $ export PATH=$PATH:$NEDC_NFC
 
You should be able to type:

 $ which nedc_eeg_resnet_realtime_decode

and see the command. Then you can simply type:

 $ nedc_eeg_resnet_realtime_decode

C.2. LINUX/MAC USERS

For Mac users, since Mac OSX comes with various older versions of Python,
you may need to utilize pip3 when attempting to install dependencies:

 pip3 install numpy
 pip3 install pillow
 pip3 install torch
 pip3 install torchvision
 pip3 install lxml
 pip3 install scipy

The easiest way to run this is to change your current working directory
to the root directory of the installation and execute the tool as follows:

 cd <my_install_location>/nedc_eeg_resnet_realtime_decode/v1.0.0
 ./bin/nedc_eeg_resnet_realtime_decode
 
Once the software has been installed, you need to do the following things if
you want to run this from any directory:

 - set the environment variable NEDC_NFC to the root directory
   of the installation
   (e.g., <my_install_location>/nedc_eeg_resnet_realtime_decode/v1.0.0)

 - put $NEDC_NFC/bin in your path
 
You should be able to type:

 $ which nedc_eeg_resnet_realtime_decode

and see the command. Then you can simply type:
  
 $ nedc_eeg_resnet_realtime_decode

+ Notes:

(1) If you have changed any bash script from /bin and would like to reset it to
    the original bash script, please navigate to /src/shell and enter 'make'.

(2) as a backup, this system will write the incoming signal data to a binary
    file with the same output directory and basename as the output csv file,
    the file extension will be '.bin', this binary file can then be used as the
    argument file to this system.

(3) This system is meant to work with short integer edf file data with a 50 Hz
    sampling frequency. You must present data sampled at 50 Hz to the system.
    For research work, we use an offline downsampler that converts
    the data.

(4) This program does not come with the software to stream an edf file
    to standard output (AKA stdout), if you want to provide the data to stdout
    you MUST change the following file, otherwise the system will work with
    50 Hz edf files or binary files, see the file below for more details:

     $NEDC_NFC/bin/nedc_eeg_resnet_realtime_decode, 
  
    see the instructions below for more details.

===============================================================================
D. ADDITIONAL INSTRUCTIONS

These kinds of complete machine learning systems are a bit complicated because
there are a lot of files involved. We have distributed example files with
this release so that you have a working example of the complete system.
Please make sure you run the complete system before you attempt to change
the code.

A. Real-Time Decoding

If you would like to run real-time decoding please follow these steps:

1. INTRODUCTION

  Real-time decoding is run by streaming an edf file to standard output and
  piping the data to the driver script, the program will write a csvbi file in
  $NEDC_NFC/test/output containing the results. Here is an example of how you
  can run this program using our nedc_stream_edf tool (this tool is available
  on our website, please see the tool for more details on the arguments and how
  it works):

  First navigate to $NEDC_NFC/bin/nedc_eeg_resnet_realtime_decode. This is our
  driver bash script. Then change the following code:

  "streaming data on stdin" | \
      $TOOL_DIR/driver/driver.py -p $PARAMS_DECODE -o $OUTPUT_DIR -r $RDIR \
                                 -b $BASENAME $INPUT_FILE


  The data input to the system should be 16-bit binary data of the form:
  
    x[0][0] x[1][0] x[2][0] ... x[N][0]
    x[0][1] x[1][1] x[2][1] ... x[N][1]
 
    where N is the samples per second (sample frequency), and x[2][1] denotes
    the third sample in time for channel no. 2. The data are 16-bit binary
    integers in the range [-32767, 32767].    
  

2. CUSTOMIZING DECODING ARGUMENTS

  For most of our decoding arguments we use a parameter file, the arguments in
  this file can be customized to fit your particular dataset. The file is found
  here:

   $NEDC_NFC/lib/params_v01.txt
  
  Please look through this file and adjust the values to match your dataset.
  The argument filename by default is:

   none

  by default the system is set up for streaming data which is why the filename
  is set as none, if you would like to decode from a file (edf or binary) please
  navigate to:

   $NEDC_NFC/bin/nedc_eeg_resnet_realtime_decode_env

  and change the following variable:

   INPUT_FILE="...change to wanted filename and path..."  
  
  the input model filename by default is:

   $NEDC_NFC/models/model.pckl

  If you want to change the name/path of the model please navigate to:

   $NEDC_NFC/bin/nedc_eeg_resnet_realtime_decode_env

  and change the following variable:

   MODEL_FILE="...change to wanted filename and path..."  

  Decoding produces a csvbi output file, the output directory for the csvbi
  file by default is:

   $NEDC_NFC/test/output
  
  If you want to change the output directories please navigate to:

   $NEDC_NFC/bin/nedc_eeg_resnet_realtime_decode_env
                                                                    
  and change the following variable:

   OUTPUT_DIR="...change to wanted path..."

  the output csv file name by default is:

   nedc_000
  
  If you want to change the output file name please navigate to:

   $NEDC_NFC/bin/nedc_eeg_resnet_realtime_decode_env
                                                                    
  and change the following variable:

   BASENAME="...change to wanted path..."

  (see the note below for a description of rdir) By default, rdir is set as:

   None
  
  If you want to change rdir please navigate to:
  
   $NEDC_NFC/bin/nedc_eeg_resnet_realtime_decode_env
                                                                    
  and change the following variable:
  
   RDIR="...change to wanted path..."

Notes:

  For decoding it is important that the output csv_bi files are able to save
  your system's way of organizing your files, we use the argument rdir
  (replace directory) so that you can specify a common directory path
  present in all argument files that can be removed. For example if you
  have the following argument files:

   /home/files/edf/train/trainset1/0001.edf
   /home/files/edf/train/trainset1/0002.edf
   /home/files/edf/dev/devset4/0001.edf
   /home/files/edf/dev/devset4/0002.edf
   /home/files/edf/eval/evalset2/0001.edf
   /home/files/edf/eval/evalset2/0002.edf

  You might set the rdir argument to /home/files/edf that way the output csv_bi
  files retain all organizational directories (trainset1, evalset2, etc.). This
  is what the output files would be with this specific rdir argument:

   $NEDC_NFC/test/output/train/trainset1/0001.csv_bi
   $NEDC_NFC/test/output/train/trainset1/0002.csv_bi
   $NEDC_NFC/test/output/dev/devset4/0001.csv_bi
   $NEDC_NFC/test/output/dev/devset4/0002.csv_bi
   $NEDC_NFC/test/output/eval/evalset2/0001.csv_bi
   $NEDC_NFC/test/output/eval/evalset2/0002.csv_bi

  If rdir is not a valid filepath, by default it won't save any input file
  directories.
  
3. DECODING

  Decoding can be run using this driver bash script:

  $NEDC_NFC/bin/nedc_eeg_resnet_realtime_decode_env

  We recommend running decoding on CPU as running it on GPU will not make
  it run any faster.

-------------------------------------------------------------------------------
If you have any additional comments or questions about the data or software,
please direct them to help@nedcdata.org. We will do our best to answer them.
However, this distribution is fairly complex, so familiarity with Linux, shell,
and Python is required.

Best regards,

Joe Picone
