| 1 |
#+TITLE: Project Aghermann |
| 2 |
#+AUTHOR: Andrei Zavada |
| 3 |
#+EMAIL: [email protected] |
| 4 |
#+DATE: 2012-06-01 Fri |
| 5 |
#+DESCRIPTION: Project Aghermann |
| 6 |
#+KEYWORDS: |
| 7 |
#+LANGUAGE: en |
| 8 |
#+OPTIONS: toc:1 num:1 |
| 9 |
#+LINK_UP: |
| 10 |
#+LINK_HOME: |
| 11 |
|
| 12 |
This is project Aghermann, a program designed to run Process S |
| 13 |
simulations on Slow-Wave Activity profiles from (human) EEG recordings |
| 14 |
as outlined in Achermann et al (1993). In this capacity, Aghermann |
| 15 |
produces a set of sleep homeostat parameters which can be used to |
| 16 |
describe and differentiate individual sleepers, such as short /vs/ |
| 17 |
long sleepers, early /vs/ late, etc. |
| 18 |
|
| 19 |
* Sources and availability |
| 20 |
|
| 21 |
The latest version is [[file:source/aghermann-@[email protected]][@VERSION@]], released @build_date@ ([[file:ChangeLog][ChangeLog]]). |
| 22 |
|
| 23 |
As of version 0.4.4 (2012-01-07), Aghermann is included in Debian |
| 24 |
sid (unstable). So you might only wish to build from sources if you |
| 25 |
want to eke out the extra couple of percent in speed -O3 will |
| 26 |
probably yield (or if your distro is of non-Debian lineage). |
| 27 |
|
| 28 |
The project’s public Git repositories are hosted on [[https://github.com/hmmr/aghermann][GitHub]], on |
| 29 |
[[http://anonscm.debian.org/gitweb/?p=debian-med/aghermann.git][Debian servers]] and, historically, also at [[http://sourceforge.net/projects/aghermann][SourceForge]]. |
| 30 |
|
| 31 |
* Features |
| 32 |
** Sleep experiment recording manager |
| 33 |
|
| 34 |
| 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]] | |
| 35 |
| *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]] | |
| 36 |
|
| 37 |
** EDF signal viewing and scoring facility |
| 38 |
|
| 39 |
| 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]] | |
| 40 |
|
| 41 |
*** Artifact detection |
| 42 |
|
| 43 |
*Artifact detection* comes as a side-effect in the computation of [[http://www.ncbi.nlm.nih.gov/pubmed/11008419][EEG |
| 44 |
Microcontinuity]], and may or may not meet your expectations. Most |
| 45 |
parameters affecting artifact detection are exposed for your |
| 46 |
tuning. Run with default settings, it tends to be a little too |
| 47 |
eager at the task, though. |
| 48 |
|
| 49 |
You can also mark as artifacts any *flat signal* portions, or |
| 50 |
portions where there is some (considerable and lasting) |
| 51 |
*perturbations in EMG*. |
| 52 |
|
| 53 |
*** Manual artifact marking |
| 54 |
|
| 55 |
EEG signals can be manually filtered for artifacts. The PSD |
| 56 |
analysis is then performed on cleaner pages, greatly enhancing the |
| 57 |
resulting spectral power profile. |
| 58 |
|
| 59 |
*** Filters |
| 60 |
|
| 61 |
Butterworth Low-pass, high-pass and band-pass filters are |
| 62 |
available as well as band-stop ("notch") filters at 50 and 60 Hz. |
| 63 |
|
| 64 |
*** Independent Component Analysis |
| 65 |
|
| 66 |
| 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]] | |
| 67 |
|
| 68 |
*** Cairo subpixel drawing |
| 69 |
|
| 70 |
All minute details exposed thanks to cairo *subpixel drawing* |
| 71 |
(alternatively, signal can be downsampled for faster redraw). |
| 72 |
|
| 73 |
Almost all drawing areas can be *saved as SVG* files. |
| 74 |
|
| 75 |
*** Pattern finding |
| 76 |
|
| 77 |
A *pattern* is characterized by a certain, band-pass filtered, |
| 78 |
/target frequency component/, its /envelope/ (a pair of tangential |
| 79 |
lines connecting local extrema over a certain range, above and |
| 80 |
below the waveform), and a /density function of zerocrossings of |
| 81 |
signal derivative/ (with variable sigma and sampling interval, |
| 82 |
interpolated). Using these criteria and some tuning, one can find |
| 83 |
occurrences of a pattern (say, a K-complex) in the signal. |
| 84 |
|
| 85 |
Patterns can be saved, and searched for in other subjects, and/or |
| 86 |
in other experiments. |
| 87 |
|
| 88 |
*** Phase difference between channels |
| 89 |
|
| 90 |
This is an experimental feature which can hint at the direction |
| 91 |
of propagation of EEG waves in a certain frequency band. It is |
| 92 |
determined as a shift of one signal's band-passed component against |
| 93 |
another such that the difference between them is minimal. |
| 94 |
|
| 95 |
*** Automatic scoring |
| 96 |
|
| 97 |
It has been considered but never matured enough to overcome the |
| 98 |
distrust of at least one well-to-do sleep researcher. The bright |
| 99 |
solution I found is, however, to delegate it to the user, one |
| 100 |
much desirable side effect of this being, I will not be blamed, let |
| 101 |
alone laughed at, for my scoring algorithm performing like speech |
| 102 |
recognition in Windows 95. |
| 103 |
|
| 104 |
**** Manual scoring |
| 105 |
Recordings can be conveniently scored manually; scores can be imported/exported in plain ASCII. |
| 106 |
|
| 107 |
**** Automated scoring |
| 108 |
Scoring can also be scripted, in Lua. |
| 109 |
|
| 110 |
To enable such scripted scoring, you have access, from within |
| 111 |
Lua, to the following functions (in lua-like pseudocode): |
| 112 |
|
| 113 |
#+BEGIN_SRC lua |
| 114 |
function get_channel_list () |
| 115 |
return n_channels, ch1, ch2, ... |
| 116 |
end |
| 117 |
|
| 118 |
function get_channel_list_of_type (type) |
| 119 |
return n_channels, ch1, ch2, ... |
| 120 |
end |
| 121 |
|
| 122 |
function get_channel_data (channel) |
| 123 |
return n_full_pages, n_total_pages, pagesize, samplerate |
| 124 |
end |
| 125 |
|
| 126 |
function get_psd (channel, start_page, end_page_inclusive, freq_min, freq_max) |
| 127 |
return vector_of_psd_values_in_given_range |
| 128 |
end |
| 129 |
|
| 130 |
function get_mc (channel, start_page, end_page_inclusive, freq0, unused) |
| 131 |
return vector_of_mc_values_at_given_freq |
| 132 |
end |
| 133 |
|
| 134 |
function get_swu (channel, start_page, end_page_inclusive, freq0, unused) |
| 135 |
return vector_of_swu_values_at_given_freq |
| 136 |
end |
| 137 |
|
| 138 |
function get_signal_envelope (channel, page, scope, dt) |
| 139 |
return vector_of_signal_envelope_breadth_values_taken_at_dt_intervals |
| 140 |
end |
| 141 |
|
| 142 |
function get_page_dirty (channel, page) |
| 143 |
return portion_0thru1_of_signal_marked_as_artifact |
| 144 |
end |
| 145 |
#+END_SRC |
| 146 |
|
| 147 |
And, to score a page, use score (page, score). |
| 148 |
|
| 149 |
The above functions are defined in [[basic_score.lua]], which |
| 150 |
appears as a default, system scoring profile. This script is |
| 151 |
barely useful in this form (it only takes into accout the first |
| 152 |
EEG channel, and only tries to detect NREM). You are encouraged |
| 153 |
to duplicate the relevant boilerplate from it to create a more |
| 154 |
advanced scoring script. |
| 155 |
|
| 156 |
|
| 157 |
** SWA profiles |
| 158 |
|
| 159 |
Three kinds of SWA profiles available for Achermann model simulations: |
| 160 |
|
| 161 |
+ *Power spectrum density* (PSD), which can be obtained in bins of |
| 162 |
0.25, 0.5 and 1 Hz and combined into larger frequency ranges, or |
| 163 |
conventional bands (delta, gamma etc). |
| 164 |
|
| 165 |
+ *Slow Wave Upswing* ([[file:swu.org][SWU]]), an experimental metric representing |
| 166 |
a measure of uniformity/simultaneity of neurons generating a |
| 167 |
slow wave. |
| 168 |
|
| 169 |
+ [[http://www.ncbi.nlm.nih.gov/pubmed/11008419][*EEG Microcontinuity*]] [[file:mc.org]["lite"]]. |
| 170 |
|
| 171 |
** Basic sleep analysis |
| 172 |
| 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]] | |
| 173 |
| [[file:img/equation-uc.png]] | | |
| 174 |
| (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. | | |
| 175 |
|
| 176 |
** Process S simulations following Achermann et al, 1993 |
| 177 |
| 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]] | |
| 178 |
|
| 179 |
Optimisation is performed using the simulated annealing method from |
| 180 |
GSL. |
| 181 |
|
| 182 |
** Data export |
| 183 |
|
| 184 |
+ Signal, SWA profiles and model parameters can be exported as tsv |
| 185 |
files for further stats. |
| 186 |
|
| 187 |
+ All graphic presentations can be saved in SVG format. |
| 188 |
|
| 189 |
* Accessory utilities to handle EDF files |
| 190 |
Included as separate programs are companion utilities to view/modify |
| 191 |
EDF header and create EDF files from plain ASCII tsv files. |
| 192 |
|
| 193 |
** EDF header viewer/editor |
| 194 |
|
| 195 |
| *edfhed* and *edfhed-gtk*, to view and modify the header of edf files. | [[file:img/edfhed-gtk.png][img/edfhed-gtk-t.png]] | |
| 196 |
|
| 197 |
** EDF channel converter/mixer |
| 198 |
|
| 199 |
Another simple terminal tool is *edfcat*, with two basic |
| 200 |
operations: (1) convert an ascii csv/tsv file into edf, and (2) |
| 201 |
drop channels from an edf file. Refer to its man page for |
| 202 |
details. More operations are planned. |
| 203 |
|
| 204 |
* Notes on security and accessibility |
| 205 |
|
| 206 |
+ There is no consideration specially given to potential security |
| 207 |
issues Aghermann might run into when used to open a corrupt or |
| 208 |
laced EDF file. If, for example, the header says there are more |
| 209 |
(or less) data records than there actually are in the file, |
| 210 |
Aghermann may still behave in a way one would consider correct or |
| 211 |
natural, but it may just segfault as likely as not. Your principal |
| 212 |
rule here is, trust your sources. |
| 213 |
|
| 214 |
+ Secondly, I have heeded no advice whatsoever on human interface |
| 215 |
guidelines as, for example, adopted by Gnome; the controls are |
| 216 |
designed in a way I considered the most efficient towards a better |
| 217 |
workflow, but only *after* you read the relevant man pages. And I |
| 218 |
see no purpose in an obligatory, but empty, menu bar that occupies |
| 219 |
space otherwise so precious when you have five waveforms cramped |
| 220 |
into your netbook screen. |
| 221 |
|
| 222 |
+ Likewise, if you have no mouse, there's no practical possibility to |
| 223 |
interact with the program. |
| 224 |
|
| 225 |
+ (In GTK+ menus, pressing space helpfully toggles a checkbox or |
| 226 |
selects a radio item but leaves the menu displayed, unlike clicking |
| 227 |
on the item or pressing Enter. This saved me a few dialog boxes |
| 228 |
along the way.) |
| 229 |
|
| 230 |
* Feedback/bugreports |
| 231 |
|
| 232 |
Should you find Aghermann useful (in its scoring capacity only, or |
| 233 |
even to the full extent of its modelling sophistication), comments |
| 234 |
and suggestions are welcome (preferably on |
| 235 |
[email protected]). Wishlist features can be |
| 236 |
considered as a matter of course. |