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

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`
`desat`	`SpO2 desaturation` `SpO2 desaturation\|SpO2 desaturation`
`unsure`	`Unsure` `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` `Wake\|0`
`unscored`	`Unscored` `Unscored\|9`
`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`

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

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