Skip to content

Luna & the National Sleep Research Resource

Luna provides a number of convenience features to support working with polysomnography data from the National Sleep Research Resource (NSRR), including pre-populated sample lists, parameter files, channel aliases and remappings for annotations.

NSRR sample lists

After downloading PSGs (via the NSRR Ruby Gem, as shown here for SHHS, for example), you can create sample-lists using Luna's --build command.

Annotation aliases

Slightly different annotation encodings are sometimes used between and within different NSRR cohorts. For example, in some studies a leg movement may be encoded as PLM (Left) whereas in others it might be Limb Movement (Left). Arousals, in particular, use an array of trivially different terms (for example, varying in how they are formatted or whether upper or lower case is used). This can make specifying annotations (e.g. for use in MASKS) unnecessarily difficult.

To simplify NSRR annotations, Luna will, by default, automatically convert NSRR annotations to a standard, easy-to-parse format (i.e. with no special characters or spaces). Luna also defines a series of variables that represent higher-level groups of annotations, as tabulated below. artifact.

To turn off Luna's automatic conversion of NSRR annotations, set

on the command line or parameter file.

Below we list the annotation remappings by broad class: arousals, respiratory events, sleep staging, PLMs, artifacts and miscellaneous. We then list the pre-defined set of variables that group related annotation terms.


Remapped term Original NSRR terms
arousal_standard Arousal ()
Arousal|Arousal ()
Arousal|Arousal (Arousal)
Arousal|Arousal (Standard)
Arousal|Arousal (STANDARD)
ASDA arousal|Arousal (ADSA)
ASDA arousal|Arousal (asda)
ASDA arousal|Arousal (ASDA)
Arousal (Asda)
Arousal (ASDA)
arousal_spontaneous Arousal (ARO SPONT)
Spontaneous arousal|Arousal (apon aro)
Spontaneous arousal|Arousal (ARO SPONT)
Spontaneous arousal|Arousal (spon aro)
Spontaneous arousal|Arousal (SPON ARO)
arousal_external External arousal|Arousal (External Arousal)
arousal_respiratory Arousal resulting from respiratory effort|Arousal (ARO RES)
Arousal resulting from respiratory effort|Arousal (RESP ARO)
Arousal (ARO RES)
Respiratory effort related arousal|RERA
arousal_cheshire Arousal resulting from Chin EMG|Arousal (Cheshire)
Arousal resulting from Chin EMG|Arousal (CHESHIRE)
arousal_plm Arousal (ARO Limb)
Arousal resulting from periodic leg movement|Arousal (PLM)
Arousal resulting from periodic leg movement|Arousal (PLM ARO)

Respiratory events

Remapped term Original NSRR terms
apnea_obstructive Obstructive Apnea
Obstructive apnea|Obstructive Apnea
apnea_central Central Apnea
Central apnea|Central Apnea
apnea_mixed Mixed Apnea
Mixed apnea|Mixed Apnea
hypopnea Hypopnea
periodic_breathing Periodic Breathing
Periodic breathing|Periodic Breathing
respiratory_paradox Respiratory Paradox
desat SpO2 desaturation
SpO2 desaturation|SpO2 desaturation
unsure Unsure

Sleep staging

Remapped term Original NSRR terms
NREM1 Stage 1 sleep|1
NREM2 Stage 2 sleep|2
NREM3 Stage 3 sleep|3
NREM4 Stage 4 sleep|4
REM REM sleep|5
wake Wake
unscored Unscored
movement Movement|6


Remapped term Original NSRR terms
plm_left Periodic leg movement - left|PLM (Left)
PLM (Left)
Limb Movement (Left)
Limb movement - left|Limb Movement (Left)
plm_right Periodic leg movement - right|PLM (Right)
PLM (Right)
Limb Movement (Right)
Limb movement - right|Limb Movement (Right)


Remapped term Original NSRR terms
artifact_respiratory Respiratory artifact|Respiratory artifact
Respiratory artifact
artifact_proximal_pH Proximal pH artifact
artifact_distal_pH Distal pH artifact
artifact_blood_pressure Blood pressure artifact
artifact_TcCO2 TcCO2 artifact
artifact_SpO2 SpO2 artifact
SpO2 artifact|SpO2 artifact
artifact_EtCO2 EtCO2 artifact
EtCO2 artifact|EtCO2 artifact


Remapped term Original NSRR terms
bradycardia Bradycardia
tachycardia Tachycardia
tachycardia_narrowcomplex Narrow Complex Tachycardia
Narrow complex tachycardia|Narrow Complex Tachycardia
notes Technician Notes

Therefore, one can subsequently write

MASK if=apnea_mixed

to exclude epochs with a mixed apnea event, for example.

Higher-level variables

In addition to the remapping above, Luna provides a number of internal variables that group sets of NSRR annotations.

Variable definitions
${arousal} = arousal_standard,arousal_spontaneous,arousal_external,arousal_respiratory, arousal_plm,arousal_cheshire
${apnea} = apnea_obstructive,apnea_central,apnea_mixed,hypopnea
${artifact} = artifact_respiratory,artifact_proximal_pH,artifact_distal_pH, artifact_blood_pressure,artifact_TcCO2,artifact_SpO2,artifact_EtCO2
${arrhythmia} = bradycardia,tachycardia,tachycardia_narrowcomplex
${plm} = plm_left,plm_right
${n1} = NREM1
${n2} = NREM2
${n3} = NREM3,NREM4
${rem} = REM
${wake} = wake
${sleep} = NREM1,NREM2,NREM3,NREM4,REM

Note that these higher-level variables are conceptually and practically distinct from the remappings of terms described in the previous tables.

Remappings: these occur whilst the annotation file is being read into Luna, meaning that different terms can be mapped to the same annotation, resulting in a single annotation class. For example, if a project contained both PLM (Left) and Limb Movement (Left) terms, it would be as if they were all replaced with a single term plm_left, yielding a single annotation (of class plm_left).

Variables: in contrast, the variable ${plm} is just like any other Luna variable, and so does not alter how annotations are read in or stored: there are still two potential distinct annotations, plm_left and plm_right. Rather, it is just that writing ${plm} is the same as writing plm_left,plm_right which means any PLM (left or right leg). (Note: in MASK statements, a comma-delimited list a,b typically means a OR b.)

For example, to exclude epochs with a mixed apnea, one might write:

MASK if=apnea_mixed
which uses the remapped annotation term apnea_mixed. If instead one wished to exclude epochs that contained any type of apnea, one could use the higher-level variable ${apnea}
MASK if=${apnea}

Note that we use the ${x} variable notation in this latter case, as ${apnea} is a variable rather than an annotation class name. That is, the above is identical to writing:

MASK if=apnea_obstructive,apnea_central,apnea_mixed,hypopnea

Channel aliases

Data from NSRR studies were collected in different sites over long periods of time; as such, there is not always a high degree of consistency in the naming conventions for channels in the EDFs. Over a number of NSRR studies, we enumerated 328 distinct labels, for example (none of these studies are hdEEG studies).

A number of redundancies are trivial in that they are due to capitalization issues (although note that many analysis packages including Luna are case-sensitive). Even within some cohorts (e.g. SHHS2) we see multiple versions of the same label:

  “EEG2”  “EEG 2”   "EEG sec”  "EEG(sec)”    "EEG(SEC)"

We will generate a alias file that you can @include with any NSRR dataset you analyze.

to be completed

Cohort parameter files

Here are some convenience parameter-files for these NSRR cohorts: [ to be completed ]

Cohort N EDFs records Sample list
CCSHS ccshs.txt
CFS cfs.txt
CHAT (baseline) chat-baseline.txt
CHAT (follow-up) chat-followup.txt
CHAT (non-randomized) chat-nonrandomized.txt
MESA mesa.txt
MrOS mros.txt
SHHS1 shhs1.txt
SHHS2 shhs2.txt
SOF sof.txt

See the hints in the section above for some notes on using a shell alias to automatically point to the parameter file for a given project (i.e. rather than having to retype it every time).

The following variables defined (with examples from CFS):

Variable CFS Example Description
${eeg} eeg=C3,C4 EEG channels
${emg} emg=EMG Primary EMG channel
${eog} eog=LOC,ROC Left and right EOG channels
${ecg} ecg=ECG1 Primary ECG channel
Back to top