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.

Delays

These resources have not yet been transferred to this website... please check back in a week or so.

NSRR sample lists

These sample-lists are designed to work cleanly with NSRR cohorts downloaded via the NSRR Ruby Gem, as here for SHHS, for example. [ nb. files not yet uploaded -- to be completed ]

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

In each sample list, the IDs (first column) are designed to match the IDs in the corresponding CSV files in the datasets/ folder. The second and third columns point to the EDFs (in polysomnography/edfs/ and any subfolders) and XML annotation files (in polysomnography/annotations-events-nsrr and any subfolders).

For example, the SHHS sample list starts:

200001  shhs/polysomnography/edfs/shhs1/shhs1-200001.edf    shhs/polysomnography/annotations-events-nsrr/shhs1/shhs1-200001-nsrr.xml
200002  shhs/polysomnography/edfs/shhs1/shhs1-200002.edf    shhs/polysomnography/annotations-events-nsrr/shhs1/shhs1-200002-nsrr.xml
200003  shhs/polysomnography/edfs/shhs1/shhs1-200003.edf    shhs/polysomnography/annotations-events-nsrr/shhs1/shhs1-200003-nsrr.xml
200004  shhs/polysomnography/edfs/shhs1/shhs1-200004.edf    shhs/polysomnography/annotations-events-nsrr/shhs1/shhs1-200004-nsrr.xml
200005  shhs/polysomnography/edfs/shhs1/shhs1-200005.edf    shhs/polysomnography/annotations-events-nsrr/shhs1/shhs1-200005-nsrr.xml
... (etc) ...

Note that the EDF and XML paths are relative to whichever folder you were in when you ran the command to download these data, i.e.:

nsrr download shhs

When subsequently using Luna with these data, you will therefore need to specify a path that points to the folder containing the shhs subfolder, either directly on the command line or via a parameter file.

Hint

To save typing, one can define a shell alias for the Luna command, that includes this path as well as the project's sample-list and parameter-files. For example, consider the following:

  • The command nsrr download shhs was run in the folder /home/joe/sleepdata/
  • The SHHS1 sample-list (e.g. shhs1.lst from the list above) was downloaded to /home/joe/projects/luna/samples/
  • The SHHS parameter-file (e.g. shhs1.txt below) was downloaded to /home/joe/projects/luna/parameters/

In this case, one might set the following shell alias: (note: this is distinct from Luna's use of channel aliases): on the Mac command line, for example:

alias luna-shhs1="luna /home/joe/projects/luna/samples/shhs1.lst @/home/joe/projects/luna/parameters/shhs1.txt path=/home/joe/sleepdata/"

which means you should then be able to run Luna on the SHHS1 project, simply typing:

luna-shhs1 -o out.db < commands.txt 

and it should work no matter which folder it is executed from, pointing to the correct sample list, parameter file and sets of EDFs and XMLs.

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

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

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

nsrr-remap=N
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.

Arousals

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)
RERA
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
Hypopnea|Hypopnea
periodic_breathing Periodic Breathing
Periodic breathing|Periodic Breathing
respiratory_paradox Respiratory Paradox

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
Wake|0
unscored Unscored
Unscored|9
Unsure
Unsure|Unsure
movement Movement|6

PLMs

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)

Artifacts

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
desat SpO2 desaturation
SpO2 desaturation|SpO2 desaturation

Misc

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