Aghermann Usage Notes
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 session chooser (by closing the default, empty experiment) 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.
If any edf file needs fixing its header, use edfhed or edfhed-gtk.
Notes on Signal Type and Label fields in EDF headers
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.
At present, EDF+ features (in particular, discontinuous signals and sub-fields of the `PatientID' field) are not supported.
Measurements Overview
All properly placed recordings will appear on the 1. Measurements
tab.
Displaying individual episode channel signals and scoring
Opening an episode in the Scoring Facility
In the 1. Measurements view, left-clicking on an episode will
start the scoring facility for that episode.
Ctrl-wheel will scale the profile up and down.
In the Scoring Facility, hover the mouse over the "(hint)" label to see what actions are available by clicking on the signal, power course overlay and hypnogram views; similarly, tooltips for the scoring controls will show corresponding keyboard shortcuts.
Right-Click pops up a context menu with actions applicable to the nearest-zeroline channel, as well as some generally applicable actions. Also note that two different context menus are available depending on whether you click above or below the channel zeroline: the first has the options for the signal proper (filtering, scale etc), whilst the second context menu exposes options and actions applicable for the whole-episode profile (currently, PSD and MC profiles), such as which of the two to display, whether to display the PSD spectrum overlay, and also whether to display the profile on EMG channels.
With Alt-Left-Click, you can drag channels around on montage.
Scoring controls will be inaccessible if you switch to a page
length different from that specified on the 1. Measurements -> Setup -> Profile tab.
Click Score at bottom-right to save the scores and artifact
markings (see below).
Multiple Scoring Facilities can be opened, also for one and the same episode. In the latter case, the one closing last will overwrite the .montage file for that episode.
Signals displayed
Both original and filtered waveforms can be displayed, individually or both at once. The filtered signal is produced by applying the following, in order:
- Any artifacts. These artifact-marked portions of the signal will have the signal dampened by a factor with edges smoothly merging with the adjacent signal regions.
- Any enabled filters.
Artifacts
To mark or clear an artifact manually, select a region with the mouse and choose the corresponding menu item. Holding Shift while making selection will do the marking in all channels.
You can experiment with the automatic Artifact detection algorithm. It is based on the difference between microcontinuity-dependent and -independent metrics (SS and SU) determined for a given epoch (these are the values displayed on the selection bottom-centre).
The various parameters affecting how SS and SU are computed and how a decision is reached are as follows:
| Parameter | Description |
|---|---|
| Granularity | Minimal length of a single artifact marking, sec |
| Continuity\/noise metrics | |
| F0 | Centre and -3db-cutoff frequencies, Hz (for these and other parameters, better see paper) |
| Fcutoff | |
| Bandwidth | |
| MC Gain | |
| Back-polate factor | |
| Artifact selection criteria | |
| E value | Unless given explicitly, determine this value as the largest bin of SS-/SU/ histogram (see below) |
| Smooth | Smooth SS-/SU/ vector before building histogram |
| Compute range | If enabled, histogram range is taken as min thru max of the SS-/SU/ vector, else as given explicitly |
| Histogram bins | Number of histogram bins |
| Upper threshold | Mark period as a hi-freq artifact if SS-/SU/[p] > E + E times this value |
| Lower threshold | Mark period as a lo-freq artifact if SS-/SU/[p] < E + E times this value (see pp 1190-1 of cited paper) |
Once you have tuned these parameters to your satisfaction, you can save them as a named profile, and subsequently apply AD globally to all your recordings.
Patterns
From a signal selection menu, you can take the selected portion as a pattern to search for. In the Patterns dialog, you define the four pattern properties and choose the channel to search in, and a search increment size.
Searching can take some seconds to build match indices, shown in the lower part of the field area. When you focus on one of the criteria spin buttons on the left, a corresponding match index appears; a match on a given criterion happens wherever its index attains the criterion line. When all four criteria are met, the pattern is found; it gets marked as an annotation in montage.
Patterns can be saved for future use. User-scope patterns will be kept in ~/.local/share/aghermann/patterns; experiment- and subject-scope ones, in dir .patterns/ in the experiment directory root and, respectively, any individual subject's dir.
Refining EEG further with ICA
You can also try to isolate/distill EEG signals with Independent Component Analysis (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:
- Map individual components to channels, possibly preserving others;
- Punch out some ICs and remix.
EEG score import/export
The import filter reads the tokens and attempt to identify the score as follows (in a case-insensitive manner):
| Code | Score |
|---|---|
| W, Wake, 0 | Wake |
| N1, N2..4; NREM1..4; 1..4 | NREM Stage 1..4 |
| R, REM, 5 | REM |
| -, unscored, 9 | Unscored |
These codes can be configured on Settings tab. 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, the current page
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.
Preparing the profiles for simulations
Once you are done preparing your SWA profiles, proceed to the most interesting part, the Process S simulations.
Edit as necessary the simulatied annealing 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 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, AZ1 amendment is ineffective for single-episode profiles.
Running the simulations
Then, double-click on a row in the 2. Simultions 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 with the default tunable values (which you set
on the Parameters->Tunables tab).
Click on an episode to display that episode alone. You can take a snapshot and save (as a png image) the current view by doing Alt+leftclick.
The unscored pages will be patched up per settings on the
2. Simulations -> 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 squared
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.
You can also run simulations in a batch.
