Debian Codegraph @

doc/org/aghermann.org.in

raw
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.