#+TITLE: Project Aghermann #+AUTHOR: Andrei Zavada #+EMAIL: johnhommer@gmail.com #+DATE: 2012-06-01 Fri #+DESCRIPTION: Project Aghermann #+KEYWORDS: #+LANGUAGE: en #+OPTIONS: toc:1 num:1 #+LINK_UP: #+LINK_HOME: This is project Aghermann, a program 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. * Sources and availability The latest version is [[file:source/aghermann-@VERSION@.tar.bz2][@VERSION@]], released @build_date@ ([[file:ChangeLog][ChangeLog]]). As of version 0.4.4 (2012-01-07), Aghermann is included in Debian sid (unstable). So you might only wish to build from sources if you want to eke out the extra couple of percent in speed -O3 will probably yield (or if your distro is of non-Debian lineage). The project’s public Git repositories are hosted on [[https://github.com/hmmr/aghermann][GitHub]], on [[http://anonscm.debian.org/gitweb/?p=debian-med/aghermann.git][Debian servers]] and, historically, also at [[http://sourceforge.net/projects/aghermann][SourceForge]]. * Features ** Sleep experiment recording manager | 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. | [[file:img/measurements.png][img/measurements-t.png]] | | *Per-channel annotations*, as well as annotations *embedded in EDF+* files, with an experiment-wide dialog for quickly jumping to so bookmarked episodes. | [[file:img/annotations.png][img/annotations-t.png]] | ** EDF signal viewing and scoring facility | Aghermann provides a capable facility for displaying EEG and accompanying recordings, such as EOG and EMG, saved in plain EDF or EDF+C (European Data Format) files. | [[file:img/sf.png][img/sf-t.png]] | *** Artifact detection *Artifact detection* comes as a side-effect in the computation of [[http://www.ncbi.nlm.nih.gov/pubmed/11008419][EEG Microcontinuity]], and may or may not meet your expectations. Most parameters affecting artifact detection are exposed for your tuning. Run with default settings, it tends to be a little too eager at the task, though. You can also mark as artifacts any *flat signal* portions, or portions where there is some (considerable and lasting) *perturbations in EMG*. *** Manual artifact marking EEG signals can be manually filtered for artifacts. The PSD analysis is then performed on cleaner pages, greatly enhancing the resulting spectral power profile. *** Filters Butterworth Low-pass, high-pass and band-pass filters are available as well as band-stop ("notch") filters at 50 and 60 Hz. *** Independent Component Analysis | Independent Component Analysis using [[http://www.cs.helsinki.fi/u/ahyvarin/whatisica.shtml][FastICA]] routines from [[http://itpp.sourceforge.net/current/group__fastica.html][itpp]]. Reconstituted signals can be saved back to EDF source. | [[file:img/ica.png][img/ica-t.png]] | *** Cairo subpixel drawing All minute details exposed thanks to cairo *subpixel drawing* (alternatively, signal can be downsampled for faster redraw). Almost all drawing areas can be *saved as SVG* files. *** Pattern finding A *pattern* is characterized by a certain, band-pass filtered, /target frequency component/, its /envelope/ (a pair of tangential lines connecting local extrema over a certain range, above and below the waveform), and a /density function of zerocrossings of signal derivative/ (with variable sigma and sampling interval, interpolated). Using these criteria and some tuning, one can find occurrences of a pattern (say, a K-complex) in the signal. Patterns can be saved, and searched for in other subjects, and/or in other experiments. *** Phase difference between channels This is an experimental feature 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. *** Automatic scoring It has been considered but never matured enough to overcome the distrust of at least one well-to-do sleep researcher. The bright solution I found is, however, to delegate it to the user, one much desirable side effect of this being, I will not be blamed, let alone laughed at, for my scoring algorithm performing like speech recognition in Windows 95. **** Manual scoring Recordings can be conveniently scored manually; scores can be imported/exported in plain ASCII. **** Automated scoring Scoring can also be scripted, in Lua. To enable such scripted scoring, you have access, from within Lua, to the following functions (in lua-like pseudocode): #+BEGIN_SRC lua function get_channel_list () return n_channels, ch1, ch2, ... end function get_channel_list_of_type (type) return n_channels, ch1, ch2, ... end function get_channel_data (channel) return n_full_pages, n_total_pages, pagesize, samplerate end function get_psd (channel, start_page, end_page_inclusive, freq_min, freq_max) return vector_of_psd_values_in_given_range end function get_mc (channel, start_page, end_page_inclusive, freq0, unused) return vector_of_mc_values_at_given_freq end function get_swu (channel, start_page, end_page_inclusive, freq0, unused) return vector_of_swu_values_at_given_freq end function get_signal_envelope (channel, page, scope, dt) return vector_of_signal_envelope_breadth_values_taken_at_dt_intervals end function get_page_dirty (channel, page) return portion_0thru1_of_signal_marked_as_artifact end #+END_SRC And, to score a page, use score (page, score). The above functions are defined in [[basic_score.lua]], which appears as a default, system scoring profile. This script is barely useful in this form (it only takes into accout the first EEG channel, and only tries to detect NREM). You are encouraged to duplicate the relevant boilerplate from it to create a more advanced scoring script. ** SWA profiles Three kinds of SWA profiles available for Achermann model simulations: + *Power spectrum density* (PSD), which can be obtained in bins of 0.25, 0.5 and 1 Hz and combined into larger frequency ranges, or conventional bands (delta, gamma etc). + *Slow Wave Upswing* ([[file:swu.org][SWU]]), an experimental metric representing a measure of uniformity/simultaneity of neurons generating a slow wave. + [[http://www.ncbi.nlm.nih.gov/pubmed/11008419][*EEG Microcontinuity*]] [[file:mc.org]["lite"]]. ** Basic sleep analysis | For individual episodes, ultradian (NREM-REM) cycle period can be estimated, by fitting a function of the form: | [[file:img/overview-single-episode-with-uc.png][img/overview-single-episode-with-uc-t.png]] | | [[file:img/equation-uc.png]] | | | (with negative values clamped at 0) which produces a period, /T/, as well as a decay rate, /r/, the latter being a good equivalent of the classic Process S decay rate from seminal Borbély, Daan & Beersma papers. | | ** Process S simulations following Achermann et al, 1993 | For description of the underlying model, refer to [[http://www.ncbi.nlm.nih.gov/pubmed/8453498][the original article]]. and to [[http://dissertations.ub.rug.nl/faculties/science/2007/a.zavada][my PhD dissertation]]. For a brief recapitulation, see [[file:model.org][here]]. | [[file:img/mf.png][img/mf-t.png]] | Optimisation is performed using the simulated annealing method from GSL. ** Data export + Signal, SWA profiles and model parameters can be exported as tsv files for further stats. + All graphic presentations can be saved in SVG format. * Accessory utilities to handle EDF files Included as separate programs are companion utilities to view/modify EDF header and create EDF files from plain ASCII tsv files. ** EDF header viewer/editor | *edfhed* and *edfhed-gtk*, to view and modify the header of edf files. | [[file:img/edfhed-gtk.png][img/edfhed-gtk-t.png]] | ** EDF channel converter/mixer Another simple terminal tool is *edfcat*, with two basic operations: (1) convert an ascii csv/tsv file into edf, and (2) drop channels from an edf file. Refer to its man page for details. More operations are planned. * 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, but only *after* you read the relevant man pages. 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.) * Feedback/bugreports Should you find Aghermann useful (in its scoring capacity only, or even to the full extent of its modelling sophistication), comments and suggestions are welcome (preferably on aghermann@lists.sourceforge.net). Wishlist features can be considered as a matter of course.