WhiteICE documentation
======================

WhiteICE plays sounds (+ possible visuals) in the background to increase concentration or an other EEG target set by user.
WhiteICE requires EEG-device to use and keeps optimizing stimulus while audio(visual) stimulation is done.
WhiteICE supports two EEG devices: BrainAccess HALO EEG (through LSL protocol) and Interaxon Muse EEG (through MindMonitor OSC output).

To play sounds in the background with LSL or OSC protocol use commands

./whiteice --measure --device=lsl --concentration (BrainAccess HALO EEG)
./whiteice --measure --device=mindmonitor --concentration (Interaxon Muse EEG and MindMonitor App with target UDP port 4545).

If you want just test the software you can also use random device

./whiteice --measure --device=random --concentration

Software runs about 30 minutes when started in measurement mode where measurements of random stimulus is measured without
optimizing stimulus model after 30 minutes machine learning models are computed using reinforcement learning to find
stimulation that minimizes distance to target state. Besides concentration you can also set "--sleep" or "--relax" targets.
You can also set other targets with "--target=0,1,0,1,0,..." switch (values should be 0 or 1 or -1 if that signal's target is not set).

You can typically get about 0.5% effect towards target values.

WhiteICE should be used to measure EEG and play sounds in the background while using computer. Typically for good results
deep reinforcement algorithms should be run 1-2 hours or longer.

If you have multiple LSL devices in the local network, you can select certain LSL stream "--lsl-names='device name','EEG typename'".

If LSL device has more than 4 channels, you can set. --lsl-channels=8 to use 8-channel EEG. Currently software algoritms scale
as O(N^2) where N is number of EEG-channels so number of EEG channels cannot be very large (16 channels is means already
quite much computation in the background requiring fast CPU).

Software uses reinforcement learning which requires many examples and FAST CPU to learn from measurements.

You can plot figure from generated file "episodes-result.txt" which shows how target value increases.
Typically, you get something like 20 datapoints in "episodes-result.txt" in one hour and there needs
to be at least 1000 datapoints for interesting results. 1000/20 = 50 hours of stimulation! This means
you need many runs of the software.

You can set directory to save machine learning models with "--model-dir=<dir>" command.
WhiteICE tries to load existing machine learning models from <dir> when it starts and
when running it saves model files to <dir> every now and then.

By using of "--model-dir=" you can continue later the same session and finally
reinforcement learning algorithm might do something smart after 1000 or more episodes.

INTEPRETING PERFORMANCE METRICS
===============================

Software reports performance metrics like this (bigger is better):

"Measured *OVERALL* delta, policy vs random percentage: PERCENT% [average change: AVERAGE] [linear distance change: DISTANCE%] (positive means better)"

The most important measure is DISTANCE% it reports average measured distance to target value where as
PERCENT% and AVERAGE reports improvement of model's internal reinforcement values which are
not tightly bound to DISTANCE.

AVERAGE is second most important and it being positive values mean that policy decisions on the average
give positive reinforcement value (if it is negative algorithm don't function properly).

Finally, PERCENT% compares reinforcement values to random stimulation reinforcement values and
reports results. Now, the whole stimulation experience might reduce reinforcement values in average,
but temporal comparision of temporal reinforcement values (*RECENT*) shows positive results when compared
to temporal random stimulation which is not altered by global reduction of reinforcement values.



LICENSE
=======

This software is closed source but free to use (freeware).
Links with non-GPL libraries.

Software should be useful but machine learning algorithms only work statistically and may not work.
Software creator isn't responsible for any damage use of this software may cause
(thought audiovisual stimulation is quite safe in practice).


Softare is developed by Tomas Ukkonen (tomas.ukkonen@iki.fi)

