Project Aghermann
-----------------

This is project Aghermann, a program by Andrei Zavada
<johnhommer@gmail.com> designed to run Process S simulations on
Slow-Wave Activity profiles from (human) EEG recordings as outlined in
Achermann et al (1993).  In this capacity, Aghermann produces a set of
sleep homeostat parameters which can be used to describe and
differentiate individual sleepers, such as short vs long sleepers,
early vs late, etc.

Also provided are general-purpose facilities for displaying EEG and
accompanying recordings, such as EOG and EMG, saved in EDF (European
Data Format) files.  These recordings can then be conveniently scored;
scores can be imported/exported in plain ASCII.  No scoring asistance
is provided, although it is planned in some limited form.

Various other useful features are:

* EEG signals can be manually filtered for artifacts.  The PSD
  analysis is then performed on clean epochs, greatly enhancing the
  resulting spectral power profile.  Power course profiles can be
  obtained for an arbitrary frequency range.

* Independent Component Analysis.

* Butterworth Low-pass, high-pass and band-pass filters.

* Pattern finding.  A pattern is characterized by its low-frequency
  component (adjustable cutoff and filter order), its envelope (a
  tangential line connecting local extrema, with adjustable
  'tightness'), and a density function of the zerocrossings of signal
  derivative (with variable sigma and sampling interval,
  interpolated).  Using these criteria and some tuning, one can find
  occurrences of a [attern (say, a K-complex) in the signal.

* Phase difference between channels, which can hint at the direction
  of propagation of EEG waves in a certain frequency band.  It is
  determined as a shift of one signal's band-passed component against
  another such that the difference between them is minimal.

Aghermann keeps the recordings in an organized fashion in a tree,
following an experimental design commonly used in sleep research,
i.e., groups of subjects sleeping several (timed) episoded per
session, with recordings from a number of channels.

For description of the underlying model, refer to:

@Article{Achermannetal1993,
  Author         = {Achermann, P. and Dijk, D.-J. and Brunner, D.P. and
                   Borbély, A.A.},
  Title          = {A model of human sleep homeostasis based on {EEG}
                   slow-wave activity: {Q}uantitative comparison of data
                   and simulations},
  Journal        = {Brain Res. Bull.},
  Volume         = 31,
  Pages          = 97-113,
  year           = 1993
}

and to my PhD dissertation:
http://dissertations.ub.rug.nl/faculties/science/2007/a.zavada


NOTES ON SECURITY AND ACCESSIBILITY

   There is no consideration specially given to potential security
   issues Aghermann might run into when used to open a corrupt or
   laced EDF file.  If, for example, the header says there are more
   (or less) data records than there actually are in the file,
   Aghermann may still behave in a way one would consider correct or
   natural, but it may just segfault as likely as not.  Your principal
   rule here is, trust your sources.

   Secondly, I have heeded no advice whatsoever on human interface
   guidelines as, for example, adopted by Gnome; the controls are
   designed in a way I considered the most efficient towards a better
   workflow.  And I see no purpose in an obligatory, but empty, menu
   bar that occupies space otherwise so precious when you have five
   waveforms cramped into your netbook screen.

   Likewise, if you have no mouse, there's no practical possibility to
   interact with the program.

   (In GTK+ menus, pressing space helpfully toggles a checkbox or
   selects a radio item but leaves the menu displayed, unlike clicking
   on the item or pressing Enter.  This saved me a few dialog boxes
   along the way :)


USAGE NOTES

1. Setting up the experimental design

   Assuming you have all your edf files available and have your
   experimental design laid out, first spend a minute collecting your
   edf sources in an experiment tree following this pattern:

     ExperimentRoot/Group/Subject/Session/Episode.edf

   Secondly, make sure the recording times stored in the edf files are
   actual and correct as Aghermann will not take guesses if this
   information is missing or incorrect.

   Once your directory tree is set up, start Aghermann, go to
   experiment selector and point it to the newly created experiment
   tree root directory.

   Alternatively, you can drag-and-drop edf files and assign them
   individually to groups/sessions.

2. Additoinal notes on Signal Type and Label fields in EDF headers

   o Also make sure the `Label' field is (without quotes) either of
     the form:

       "<SignalType> <Channel>",

     or just

       "<Channel>",

     where <SignalType> is one of "EEG", "ECG", "EOG", "ERG", "EMG",
     "NC", "MEG", "MCG", "EP", "Temp", "Resp", "SaO2", "Light",
     "Sound", "Event", "Freq".  Only signals of EEG type will be
     selected for the PSD analysis (other features are applicable to
     all signals regardless).

     If SignalType is omitted, Aghermann will try to match the Channel
     against the list of System 1020 channels for EEG signal types.
     Additionally, channels "Left" and "Right" are recognised as EOG,
     and "Chin", as an EMG signal.

   o At present, EDF+ features (in particular, discontinuous signals
     and sub-fields of the `PatientID' field) are not yet supported.


3. Displaying signals and scoring

   In the Measurements view, clicking on an episode will start the
   scoring facility for thta episode.

   In the scoring view, hover the mouse over the "(hint)" label to see
   what actions are available by clicking on the signal, power course
   and hypnogram views; similarly, tooltips for the scoring controls
   will show corresponding keyboard shortcuts.

   Scoring controls will be inaccessible if you switch to a page
   length different from that specified on the Measurements ->
   Setup -> PSD and Scoring tab.

   Click Score at bottom-right to save the scores and artifact
   markings (see below).

   There is a very basic scoring assistant; after consultations with
   certain knowledgeable figures in sleep research, however, I remain
   ever firmly convinced that, the five lines of code it consists of,
   is already five lines too much.

4. Filtering out artifacts

   Both original and filtered waveforms can be displayed, individually
   or at once.  The filtered signal is produced by applying the
   following, in order:

   o Manually selected artifacts (mouse leftclick+drag+release over a
     length of bad signal on the displayed page).  These
     artifact-marked portions of the signal will have the signal
     dampened by a factor of .85 with edges smoothly merging with the
     adjacent signal.

   o Display filters.

   You can also try to isolate/distill EEG signals with ICA; for
   explanation of the many options to control ICA process, please
   refer to the authors of the original software (there are handy
   links right next to the Separate button).

   There are two modes of reconstructing channels with ICA:

   o 'Map' individual components to channels, possibly preserving others;

   o 'Punch' out some ICs and remix.


5. EEG score import/export

   The import filter will read the tokens and attempt to identify the
   score as follows (in a case-insensitive manner):

   W, Wake, 0:			Wake
   N1, N2..4; NREM1..4; 1..4:	NREM Stage 1..4
   R, REM, 5:			REM
   M, MVT, 6:			MVT (Movement Time)
   -, unscored, 9:		Unscored

   All other, unrecognised tokens are skipped and the next token is
   read, but the page currently being identified is not assigned any
   score.  That is, for example, if your file has something other than
   "-", "unscored" or "0" for the Unscored identifier, it will not get
   assigned a score at all, with the next score being applied instead.
   Do some sed work to change the score codes accordingly.


6. Preparing the profiles for simulations

   Once you are done with the preparation of your spectral power
   profiles, proceed to the most interesting part, the Process S
   simulations.

   Edit as necessary the simulation controlling parameters and the
   tunables.  With tunables, those for which the step is set to 0,
   will not be tuned.

   If you have a single sleeping episode per subject/session, the DB2
   amendment does not make sense as it requires some substantial wake
   intervals between sleeping episodes: turn it off in such a case,
   and also set the step value for the rise rate set to 0.  (Strictly
   speaking, for DB2 amendments to be effective, the profile needs to
   be (a) >24h long, and (b) have the timepoint at t=24h in Wake.)

   Likewise, AZ amendment is ineffective for single-episode profiles.


7. Running the simulations

   Then, double-click on a row in the Overview tab.  If all
   constituent episodes have been sufficiently scored, the model run
   facility will be displayed, showing the profile with the simulated
   SWA and S obtained for default tunable values (which you set on the
   Parameters->Tunables tab).

   Click on an episode to display that episode alone.  Take a snapshot
   and save (as a png image) the current view by doing Alt+leftclick.

   The unscored pages and those scored as MVT will be patched up per
   settings on the Controlling Parameters tab (i.e., they can be
   assigned a Wake score or the score of the previous page).

   Click Run to find the minimal cost function (sum of squred
   distances between original and simulated SWA) using simulated
   annealing (set/review controlling parameters on
   Parameters->Simulated Annealing tab).

   One especially useful and nifty feature is the live updating of the
   course of Process S in response to your modifying the parameter
   values.  Enabling Live update before starting the annealing will
   show the process of optimisation, but this will be slow.

   You can review the courses of S and either copy-paste the resulting
   tunable values for your stats, or return to the main window and
   click Export to save all obtained simulations to a tsv file.


Should you find Aghermann useful (in its scoring capacity only, or
even to the full array of its modelling sophistication), write me a
note.  Wishlist features can be considered as a matter of course.

Good luck!
