In this final section, we'll repeat some (but not all) of the steps from the previous tutorial pages, using Moonlight instead of the command-line (lunaC) or R (lunaR) packages. As might be expected, this makes some things easier, but other things harder: that is the reason for both to exist, after all.
Moonlight: an interactive viewer, not a full analysis environment
Moonlight is an R/Shiny package wrapped around the Luna C/C++ library and the lunaR R package. It is intended to be an extended viewer for PSG signal data, with close bindings to some of Luna's functionality, e.g. for deriving hypnograms, for automated sleep staging, for spectral and other time-frequency analyses, for basic manipulations of datasets, and for embedding annotations alongside the signal data. It is expressly not intended to be a full analysis environment. For a start, Moonlight does not provide any mechanism for saving altered EDFs or annotation files. Although we currently allow arbitrary Luna commands to be evaluated, this is primarily provided for didactic purposes (i.e. as an immediate way to see Luna commands in action).
Display EDF files
If not already done, follow these initial steps to download the three tutorial EDF and annotation files. From there, you can upload one study at a time to Moonlight for viewing and other functions. There are several ways to run Moonlight, but the option that is (initially) easiest is to use our hosted version at http://remnrem.net/. Open that link in a new browser window (i.e. to keep this page also visible) and click on the Moonlight link when it appears to start a new session.
Restrictions on the number of concurrent Moonlight users at http://remnrem.net/
The http://remnrem.net is a free service - hosted by the Purcell lab and NSRR using the AWS cloud. As such, currently we necessarily have restrictions on the number of concurrent users this service is able to support. If the app gives a message that the maximum number of users has been reached, try again later. Alternatively, follow these instructions to use locally either a Dockerized version of Moonlight or install and run it directly using lunaR.
As described in the original tutorial
(here), we used
commands to review the contents of each EDF and any associated
annotations. This is easily achieved using Moonlight: once you have
a running instance of the app, click the Browse button (top-left
corner) and select the pair of EDF/annotation files (
.xml) for individual
nsrr01. Both files must be selected at the
same time, and uploaded with a single click of the blue Upload
button: i.e. it is not possible to load multiple files sequentially.
One EDF at a time
You can only view a single EDF at a time with Moonlight. You can upload multiple annotation files, but they are all assumed to be associated with the same, single EDF.
Running Moonlight locally
Faster uploads is another reason for installing Moonlight locally, especially if working with larger PSG files (e.g. hdEEG), or with datasets containing PHI that cannot be shared. (Note that absolutely no files or other derived data are stored on the server when using Moonlight, and we do not have access to any uploaded files).
The upload may take 5 or so seconds depending on your connection. After upload has completed, you should see the following:
At the top of the page (and always present) is a spectrogram
(generated by the
a hypnogram (generated by the
command) and a so-called mask bar plot (introduced
below). Underneath, with the Headers tab selected, the lower panel
shows two tables, with information primarily generated by the
HEADERS command. These show the
signals present and some other basic properties of the EDF, such as
the length of the recording.
In the original tutorial, we used several options to specify channel lable aliases, that were applied on first loading new data. However, unlike command-line Luna, it is not possible to specify parameter files when uploading files to automatically remapping channel/annotation labels. In large part, such remapping is typically not necessary in the context of an single-dataset, interactive viewer. (Nonetheless, as shown below, it is possible to rename channels and remap annotations after upload, via some of the tools available in the Manips panel.)
Moonlight also supports viewing associated annotations (e.g. from one or more XML,
other files). As shown below, the annotations are also listed under
the Annotations tab (fourth from the left). In this example, the
list boxes in the leftmost panel show 14 channels (EDF signals) and 10
Selecting specific annotations in the left menu will display them in
the Annotations tab: as shown below, here we have selected
R (REM sleep epochs). Note that the Annotations tab contains two sub-panels: Summary and
Instances. Selecting the latter shows the specific events (with
start/stop times) for the set of selected annotations (as shown below - the x-axis
is hours from the EDF start).
The Summary sub-panel (as shown in the image above) shows the number number and
total duration for each class of annotation.
If channels (interchangeably referred to as signals here also) and/or annotations are selected in the left Channels and Annotations lists, the Signals tab (fifth from the left) will show a plot of the raw signals. By default, this is centered on a 30-second window, but can be expanded by clicking on Out (or All). If too long an area is selected, Moonlight will not show the signals, as this could involve plotting millions and millions of datapoints (any selected annotations will still be shown, however).
Note the reduced hypnogram just above the signal plots, with color-coded bars indicating wake, NREM or REM epochs as green, blue or red respectively. The black dot below it represents the currently displayed epoch(s) of raw signal(s) in the main portion of the window. Clicking on this bar moves the viewer to that position; the Prev and Next buttons can also be used to shift the viewing window backwards and forwards in time.
Signal summary statistics
The next step of the original tutorial, as described here, was to estimate some basic
statistics for various channels - e.g. starting with the
SaO2 channel. We can repeat that process by simply visiting the Stats
tab and selecting
SaO2 in the left Channels list:
The table shows some of the whole-night statistics for this channel, calculated on-the-fly and, as such, respecting any masks that are set, as shown below. Clicking on the Epoch sub-panel shows epoch-level equivalent metrics (not shown).
Channel-wise versus epoch-wise statistics
If you look
carefully, you'll see the original tutorial gave different means
compared to these. This reflects the fact that the Stats module
STATS epoch rather than simply
STATS as per the original
epoch argument means that Luna estimates overall
statistics (e.g. mean) as the median of all epoch-level means
(as well as generating/reporting epoch-level statistics). That is,
the values reported by Moonlight reflect
STATS epoch output, rather than
Working with annotations
We've seen above how the Annotations tab provides a summary and tabulation of all annotations. We've further seen how annotations can be integrated into the Signals viewer.
As an additional check of the correspondence between what we saw in the tutorial
and what we see via Moonlight, consider that the first individual (
nsrr01) had 37
Indeed, from the screenshot shown in the prior section, we saw this was also the case here.
The next step in the tutorial asked how many
events were observed during REM sleep (N=27). We can repeat this
in Moonlight by taking advantage of the fact that the Annotations
tab respects any masks currently set. We can apply masks by going to the
Manips (manipulations) tab, and selecting the Mask sub-tab. A box lists
the available annotations that can be used to either include or exclude epochs.
This feature is a simple wrapper around Luna's
so be sure to review the details there.
The options above equate to
Note that the Expression box should be left empty if selecting annotation(s) from the list -- this box
provides a means for adding different options to
MASK (as we see below when using the
After clicking Set, you should see the following:
Note that the bar underneath the top hypnogram is now striped gray and orange. Gray means that the mask has been set for that epoch -- whether or not a mask has been set corresponds to whether or not that epoch is REM sleep (red in the hypnogram) or not.
If we go back to the Annotations panel and select
you'll see that only apnea events that fall in REM are now shown:
An additional nuance covered in the original tutorial was to change the definition of overlap, to restrict to only counting events that started in a REM epoch (rather than the default of including all annotations with any overlap. Reflecting an inevitable trade-off between simplicity and flexibility, the Annotations panel does not support this additional option directly.
However, here we take this as an opportunity to see how the
Luna panel (an advanced feature) allows us to recapitulate almost any Luna command within Moonlight. As pictured below,
this panel allows an arbitrary series of Luna commands to be evaluated. To mimic the behavior
ANNOTS start in the original tutorial, we can type it in here and then click Execute:
If the evaluated command(s) generates output tables (i.e. as described here, these will be listed
below the Execute button. The bottom table shows the currently selected table from this list:
here output from
ANNOTS stratified by
ANNOT (annotation class). Here we see that there are 26
Obstructive_Apnea events under this definition (i.e. starting in REM), which matches the original Luna tutorial.
We can alternatively select the table that lists all individual events (starting in REM), as shown below:
Note that, as with most Moonlight panels, these tables have a Copy button underneath - if clicked, the contents of that table are copied to the Clipboard, and can then be pasted into a program such as Excel or otherwise saved to a text file.
As shown above, if sleep stage annotations are recognized by Luna
(they will be mapped to the canonical forms
W, as well as
L), Moonlight will draw a hypnogram under
the spectrogram when first attaching the new dataset. The Hypnogram
tab (third from left) allows one to look at hypnogram-derived metrics
in Moonlight, including stage durations.
In the original tutorial we saw that the first individual had 54.5, 261.5, 8.5 and 119 minutes of N1, N2, N3 and R respectively. Selecting the Hypnogram/Stages sub-panel, we see the same information (along with some additional metrics):
Information on sleep cycles and epoch-level descriptions are also available via the other Hypnogram sub-panels.
To see how Luna masks are applied, it can be useful to use Moonlight to check that are doing what we assume they should: To this end, we will reproduce these steps from the orignal tutorial, which involved selecting epochs for the first individual that:
were in persistent sleep (at least 10 minutes of sleep prior)
occured between 11pm and 3am
were during stage 2 NREM sleep
did not contain any apnea or hypopnea events
As noted above, Moonlight is not the ideal platform for implementing multi-step analyses - if for no other reason, this type of GUI fundamentally violates the principles of reproducible research.
In the original tutorial we created an intermediate file
to flag epochs in persistent sleep (named
We can attach such
files (here, a simple file of one line per
epoch, one label per line: here
PS1), by additionally selecting it
when first uploading the EDF. To do this, we need to reload the two original files (EDF and XML)
alongside this new annotation file. (Moonlight primarily
recognizes (NSRR format) XML,
.eannot files as
annotation files.) One current limitation is that all files must be in
the same folder in order to be selected for upload, and so
ps-nrr01.eannot into the
edfs/ folder (see the original
tutorial for how this file was created - it is also present under the
cmd/ folder in
Re-uploading these three files (note: it is not necessary to have
nsrr01 as part of the filename -
all files attached at this step will be assumed to be associated with the same, single EDF):
We can now view the new
PS1 annotations alongside wake (
W) epochs - as expected, no
W epochs are
not all sleep epochs are
PS1, as per the definition of persistent sleep used here:
To follow the steps of the original tutorial (which we'll do in the
same order - although they could be performed in any
order), we'll first restrict to epochs between 11pm and 3am. This
involves using the
hms option as
part of a mask (under the Manips tab in Moonlight). Note that
the syntax is the same as the original Luna commands. After clicking
Set, you should see that the mask plot bar (under the top hypnogram)
nows shows that only epochs in this particular 4 hour interval are included
(colored orange, rather than gray):
To next restrict to persistent sleep
PS1 epochs only, we can use the same Mask panel, but selecting
PS1 epochs. (We could equivalently
have selected to Exclude
PS0 epochs). This has the effect of further graying-out certain epochs in the mask plot bar:
Next, we restrict to N2 only, using a similar approach. After this step, we'll see the following:
Finally, we'll exclude any epochs that have either an overlapping
Hypopnea event. You can select multiple annotations to exclude
by holding down shift or control when selecting:
Then clicking on Set should remove (more precisely, set the mask flag for) those epochs too. The small gray box that shows the console output from Luna shows (final row) that we are left with 86 remaining epochs, which matches the original tutorial:
Having set this mask, we can restructure the internal dataset, to
actually remove masked epochs rather than just flagging them. This
leaves us with what is effectively a discontinuous (EDF+D) in-memory
dataset. Restructuring can be achieved by clicking
Re-epoch in the
lower left corner of the screen. Now the previously gray epochs
(i.e. with a mask set but not removed) will be now be white (i.e. actually
removed from the in-memory dataset). The Structure/Segments tab (second
from the left) shows the structure of what is now a discontinuous recording/EDF+D:
That is, from the original recording, we selected (86/2)/60 = 0.72 hours of sleep. The table below the cartoon also shows where the segments/gaps start/stop. Selecting the adjavent Structure/Epoch sub-panel shows three breakdowns of epochs:
leftmost: original epochs (30 seconds by default) starting from the start of the EDF (for a continuous recording)
middle: epochs aligned with any sleep stage annotations - this may be different from the previous if sleep staging is not aligned with the start of the recording, e.g. the first staging annotation starts 28 minutes and 2 seconds into the recording, but for many datasets these will be identical to the left table
rightmost: the set of aligned epochs in the current in-memory dataset, i.e. following any masking/restructuring - here we see there are 86 epochs as expected. The numbers in brackets show the epoch count in the revised dataset (i.e. the first epoch in the extracted dataset was the 124th epoch in the original, etc).
To summarize, with the above steps we have recapitulated the following Luna commands, as per the original tutorial:
EPOCH MASK none MASK hms=23:00:00-03:00:00 EPOCH-ANNOT file=cmd/ps-nsrr01.eannot MASK mask-if=PS0 MASK mask-ifnot=N2 MASK mask-if=Obstructive_Apena,Hypopnea DUMP-MASK RE
The next section of the original tutorial showed some examples of manipulating signals: e.g. changing physical units for EEGs, resampling, filtering and re-referencing. Although Moonlight is not the obvious tool for making such changes (i.e. given that you cannot save/download EDFs), inasmuch as it might be useful for certain viewing procedures (or as a prelude to automated staging), the Manips panel gives a selection of sub-panels to perform these steps. Each is a trivial wrapper around an underlying Luna command, and so you should consult the appropriate Luna documentation as needed:
|Moonlight panel||Luna command||Description|
||Offline rereferencing one or more signals against a single reference|
||Resample one or more signals|
||Apply bandpass filter|
||Rename a single signal to something else|
||Remove one or more signals from the EDF|
||Generate a copy of a single signal|
||Arbitrary transformations of signals|
||Set the epoch mask given various criteria|
||Make new channels with specified labels/convntions|
||Change annotation labels|
For example, to follow the (quite arbitrary) steps of the tutorial:
extratct two central EEGs only, and rename them as
change physical units to milli-volts
resample to 100 Hz
bandpass filter to 0.3 - 35 Hz
We first use Drop, selecting all channels except the EEGs:
We then use Rename to set the labels to
EEG2 (having to repeat this step for each):
There is no Manips tab to change units per se, but we can use the Luna tab to apply the simple
mV command (no
is needed here, as we've already dropped all channels except the two EEGs, i.e. so
mV will be applied to both):
Next, the Resample tab (selecting both signals) to get 100 Hz signals:
Next, applying a bandpass filter to both EEGs:
And finally, re-referencing
EEG2 (this is just to illustrate
the options available -- i.e. referencing two central, contralateral-mastoid referenced channels
against each other is not likely to be a meaningful operation in practice):
Having performed these steps, returning to the original Headers table, it should have
updated to reflect these changes: i.e. it now just lists two signals
EEG2) that have mV units (previously uV), etc.
We can also view these newly transformed signals as we would original signals.
Finally, when viewing we can apply on-the-fly bandpass filters to the
signals also - by selecting the desired frequency range and then
clicking Filter (to toggle it on/off). With the two EEGs filtered
in the sigma range, we see a clear periodic pattern (sigma power
bursts approximately every second in quite a regular manner),
EEG1 which is likely artifact (as will be explored
in the next section). This visualization shows that clear value of
Again, this example is presented with the caveat that the command-line Luna is a far superior tool for real data analysis. Here we present this for didactic value and to mirror the original Luna tutorial, in which we apply some very simple artifact detection approaches. Luna has a broader range of artifact detection and correction methods than is covered here, as described on this page
The steps of the original tutorial basically ran through the following commands
EPOCH MASK if=W RESTRUCTURE FILTER bandpass=0.3,35 ripple=0.02 tw=1 ARTIFACTS mask CHEP-MASK ep-th=3,3,3 epoch CHEP epochs DUMP-MASK
After first clicking
Refresh (lower left panel) to clear any existing masks, etc,
for the attached
nsrr01 EDF, we can directly paste the above multi-step Luna script
into the Luna panel, and select Execute (note - the panel scrolls, so not all lines are shown here):
This produces all of the same output as the orignal Luna run, which is
accessible via the Tables embedded in this page. Here we see that five
tables have been generated. By default, the first is automatically selected and shown: in this case, output
ARTIFACTS stratified by
Looking at the other tables present, we can see that the
DUMP-MASK command flags the mask epochs (not shown here). As in the orignal tutorial,
we flagged a particular epoch (220) for visual review. Indeed, if we look at the
DUMP-MASK outputs, we'd see that epoch 220 is indeed
flagged as an artifact. We can then directly use the viewer to look at this signal - i.e. giving the same view of the original tutorial:
Naturally, one advantage of using an explicit viewer like Moonlight is that it is easier to click on other channels to see the broad picture of what happens during this epoch:
At the risk of repeating this one time too many: Moonlight is absolutely not the optimal platform for full-blown analyses of sleep data - the command-line Luna is the preferred tool in that case. With that aside, here we will repeat the final steps of the tutorial using Moonlight.
Finally, the original tutorial performed some limited spectral and NREM
spindle analyses of the sleep EEG. There is no single interface panel
for this - rather, we will use the Luna panel to evaluate
arbitrary Luna commands - here the (slightly modified) text from
SIGNALS keep=EEG EPOCH MASK ifnot=N2 RESTRUCTURE FILTER bandpass=0.3,35 ripple=0.02 tw=1 fft ARTIFACTS mask CHEP-MASK ep-th=3,3,3 CHEP epoch RESTRUCTURE PSD spectrum dB SPINDLES fc=11,15 annot=spindles per-spindle
After copy-and-pasting the above into the appropriate place [which reads (Enter Luna commands here)] and clicking
Execute, you should see the following (assuming
nsrr01 was uploaded and/or you pressed
Refresh after doing earlier
That is, as per the standard output for Luna, we see the
table of the
SPINDLES command (described
here. For example for the
channel, we see the density (
DENS) of both fast and slow spindles is
quite low (<1 spindle per minute). Other metrics are scrolled off the
right side of the screen (you can scroll across the table with the
Displaying Luna tables
Unlike other parts of Moonlight, where it know the structure of the expected output and can easily format it nicely, the Luna tab generates arbitary tables in terms of the columns, rows and header labels. As such, it is not as straightforward to automatically format items for neat display.
Because we added the
annot=spindles flag to
generated an annotation to indicate when the detected spindle events occurred.
These will be automatically added to the lists of available annotations, and
can be viewed in the Signals tab along with other signals and annotations:
Note that we've selected the
spindles annotation in both the top
Annotations box (which controls which annotations are displayed) and
the lower Listed Annotations also. The latter box then lists the
individual events in the box below (lower left pabel). Clicking on an
event will move the Signals window to that position. Note that
spindles must also be selected in the top box in order to see it in
the display. You can zoom into the main display by selecting the
desired area with the mouse, e.g. to see the spindle close up (not shown). To
get back to the original view, perform a single-click anywhere in the display window.
As a final step (which goes beyond the original tutorial but underscores the value of visual
analysis), we'll revisit the issue of potential artificat in the
signal as noted above. If we turn on the Filter set to the approximate sigma range (here 10.75 Hz - 18 Hz)
and also add the ECG channel to the display also, we can see a clear correspondence between spikes in the
EEGs and the ECGs:
Looking at the raw traces (toggling Filter off) and zooming into (by selecting a region of the main view panel with the mouse) we can see a clear correspondence between the QRS complex R peak in the ECG and what is seen in the EEG (here just showing one EEG channel). This is a classic case of cardiac contamination in the EEG signal.
We can attempt to attenuate this contamination with Luna's
SUPPRESS-ECG command, i.e. running the following
via the Luna tab in Moonlight (not shown):
SUPPRESS-ECG ecg=ECG sig=EEG
After performing the above and returning to the same region in the Signals tab, we can see the artifact has been greatly (if perhaps not completely) removed:
Although beyond the scope of this tutorial, if one re-runs the `SPINDLES command on the signals after dealing with cardiac contamination effects, we typically see increased spindle density estimates (as the cardiac contamination has the effect of increasing baseline sigma activity, making it harder to detect spindles above the increased noise).
This concludes the Moonlight tutorial, seeded on the original Luna (and lunaR) tutorials. Moonlight has a number of other capabilities not even mentioned here. To learn about these other features (including automated sleep staging) please visit this page.