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

WhiteICE plays sounds (+ possible visuals) in the background to increase concentration
or an other EEG target set by user. WhiteICE requires an 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).
Other EEGs might work if they support LSL protocol or OSC protocol.

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 in which
measurements of random stimulus is measured without optimizing stimulus modeland
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). There is also
experimental "--intelligence" target which don't give very reliable results if there
is only 4 EEG channels.

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

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
with "--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 measurements and FAST CPU to learn
from measurements.

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.

Software requires FAST CPU. In pratice I use AMD Ryzen 9 9955HX CPU. You can
check if the CPU is fast enough by looking for syncing errors in whiteice-engine.log
file "cat whiteice-engine.log | grep sync". Some errors in syncing are tolerable and
occur normally but if you get lot os syncin errors it means timings within software
don't work and measurements for computations are not reliable.

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

Software reports performance metrics (bigger is better):

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

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.

AVERAGE should be positive for good effect caused by reinforcement policy.

DISTANCE% is another metric that compares how stimulation target increases as a whole
(in practice watching/listening stimulation is tiresome so it may be negative
 but software still manages to increase the target EEG metric from the baseline).


LICENSE
=======

This software is closed source but free to use (freeware).
Links with non-GPL libraries. Licenses can be downloaded
from the website: https://www.hosaka.fi/.

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


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