Aghermann

Aghermann is 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.

1 Sources and availability

The latest version is 1.1.2, released 2017-01-03 (ChangeLog). There is little onging work since version 1.0, most of which is catching up with new build requirements in Debian or eventual deprecations coming our way from GTK. Unless and until someone comes along with compellingly interesting ideas, it is considered feature complete.

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 squeeze the extra couple of percent in speed -O3 will probably yield (or if your distro is of non-Debian lineage).

In 2020, I have given the upkeep of Aghermann to good folks over at Debian-med. If you find aghermann from my tree does no longer build natively on your system, check out their patches.

There is an ebuild, too, in gentoo ‘science’ overlay, available since 2015-02-18.

The project’s public Git repositories are hosted at home, on GitLab, on Debian servers and, historically, also at SourceForge.

2 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.measurements-t.png
Per-channel annotations, with an experiment-wide dialog for quickly jumping to so bookmarked episodes.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 EDF (European Data Format) files. These recordings can then be conveniently scored; scores can be imported/exported in plain ASCII.sf-t.png

Artifact detection

Artifact detection comes as a side-effect in the computation of 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.

Filters

Butterworth Low-pass, high-pass and band-pass filters are available as well as band-stop ("notch") filters at 50 and 60 Hz.

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.

Independent Component Analysis

Independent Component Analysis using FastICA routines from itpp. Reconstituted signals can be saved back to EDF source.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 tangential line connecting local extrema over a certain range), 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):

    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
    	  

    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).
  • EEG Microcontinuity "lite".
  • Slow Wave Upswing (SWU).

Basic sleep metrics

For individual episodes, ultradian (NREM-REM) cycle period can be estimated, by fitting a function of the form:overview-single-episode-with-uc-t.png
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 the original article. and to my PhD dissertation. For a brief recapitulation, see here.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.

EDF header viewer/editor

Included as separate programs are two companion utilities, edfhed and edfhed-gtk, to view and modify the header of edf files.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.

3 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.)

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