Skip to content

Luna command-line tool documentation

Overview

Luna is fundamentally a console/command-line package, i.e. there is no point-and-click. When talking specifically about this command-line interface to Luna, we refer it as lunaC, to distinguish it from the lunaR package for R. Basic familiarity with the Unix/macOS console environment and shell scripting is recommended.

Once installed and in your command path, lunaC is invoked via the luna command, often in the following form:

luna sample.lst -o out.db < commands.txt

which expects a list of IDs, EDFs (and possibly annotation files) in the sample list file sample.lst, reads a series of commands from commands.txt to be applied to each EDF, and writes the output to a lout database file called out.db.

Types of command line arguments

lunaC always expects the first argument to be either an EDF file or a sample-list. Subsequent arguments can come in any order and are interpreted as follows

  • terms containing = are interpreted as variables, with the exception of certain special reserved names that are options, e.g. annot or alias, as described below
  • terms starting with - are interpreted as special options, e.g. primarily -o and -s
  • once a -s option is encountered, all subsequent terms are interpreted as Luna commands rather than command line options; thus, if given, then -s must be the final argument
  • terms starting with @ are interpreted as parameter files, the contents of which are loaded in to define new variables and options
  • otherwise, terms that are numbers are interpreted as sample-list row numbers (either a single row, or a range, depending if one or two numbers are specified)
  • otherwise, that term is assumed to be the ID of a single individual to be analysed from the sample-list

Input

EDFs

Luna can read EDF and EDF+ files. The latter allow for discontinuities (by having an explicit time-track) and provide some support for annotations. After restructuring file (i.e. removing certain epochs), it will be represented internally in a form that corresponds to EDF+. Currently, Luna can only write EDF files however.

Luna can read a single EDF (rather than a sample list) by specifying a filename (with an .edf or .EDF extension):

luna test1.edf < commands.txt

Note

In this single EDF mode, it is not possible to attach annotations, or include a parameter file. Using sample lists is the preferred way to work for most projects.

In-memory representations

A note on some of the terminology used in this documentation: we often make a distinction between the on-disk EDF and its in-memory representation, or the internal EDF.

When Luna first "attaches" an EDF, it does not load anything other than the header. Subsequently, Luna uses a lazy-loading approach, whereby it only pulls records from disk when needed. These are cached in memory, so that if they are needed again, they do not need to be read in afresh.

All commands that manipulate EDFs and the signals therein operate on the internal EDF. Although we may use language such as "drop a channel from the EDF" we typically do not imply that the actual on-disk file has changed in any way.

Likewise, most commands refer to the internal, in-memory version of the EDF both for their input and output. As noted, this may differ from the on-disk version, for example, if channels and/or epochs have been dropped or added by SIGNALS, MASK, RESTRUCTURE and other commands. When describing a command such as DESC, if we say it reports "...information on the attached EDF", this implies it is the in-memory form that is being queried. That is, if the on-file EDF contains 64 channels, DESC will report 64 all other things being equal. However, if within that run of Luna other commands have been previously been issued that alter the internal EDF, then DESC may report something other than 64.

Finally, there is no memory or persistence of changes between different runs of lunaC: nothing is cached between sessions. For example, the following may report that 6 channels are present:

luna my.edf -s DESC 
You might subsequently run a command that drops channels and then calls DESC:
luna my.edf -s "SIGNALS drop=ECG,EMG & DESC"
in which case, only 4 channels will be reported. However, on running the first command again:
luna my.edf -s DESC
Luna will report 6 channels again, i.e. as nothing was changed in the original file my.edf.

Sample lists

The sample list (sample.lst in the example at the top of this page) file defines a project, i.e. a collection of EDFs and their associated IDs and annotations.

Warning

The sample list file must be ASCII plain text and tab-delimited, i.e. not containing any special characters or formatting as may occur if using a word processor to generate this file. Additionally, be sure to remove any Windows-style line-ending characters.

Sample lists must contain at least two tab-delimited fields: the subject ID, followed by the EDF file location:

id001   test1.edf
id002   test2.edf

In this next example we specify an annotation file (e.g. containing stage information) for each EDF. Note, in the first case we use an absolute file path, but a relative one in the second.

id001   test1.edf   /data/annots/test1-staging.xml
id002   test2.edf   staging2.xml    

Relative paths are evaluated relative to the directory that Luna is run from. On a single system, and if files won't be moved often, it is better to use absolute paths. See below for notes on using relative paths, which can be more convenient in some circumstances.

Instead of an annotation file, it is also possible to specify a folder, which will be searched for matching FTR files: e.g.

id001   test1.edf   /data/annots/test1-staging.xml  /data/ftr-files/

Command files

Command files or scripts (i.e. commands.txt in the example at the top of this page), contain one or more Luna commands. This can be more flexible and convenient than placing all commands after the -s argument.

Some conventions:

  • blank lines are skipped
  • all text after a % character on a line is treated as a comment and skipped
  • new commands should start on a new line
  • lines that begin with one or more spaces are assumed to be continuations of the same command, meaning that commands can be spread over several lines
  • scripts can contain variables

For example, say we wished to set EPOCH an EDF and apply power spectral density estimation via the PSD command to the channel named EEG, outputting spectra for each epoch. For a sample-list s.lst and output file out.db, we could specify this on the command line as:

luna s.lst -o out.db -s "EPOCH & PSD epoch sig=EEG"

Alternatively, we could place the following in a plain-text file called commands.txt (or anything else, there are no limitations on the file name or extension):

EPOCH 
PSD epoch sig=EEG
and run it as follows:

luna s.lst -o out.db < commands.txt

Alternatively, we could achieve the same outcome but with a more verbosely-expressed script, with ample comments and spreading commands and options over multiple lines:

% This is a new command file
% v1.0, 5-Feb-19
% First epoch the data, default epoch duration is 30 seconds

EPOCH

% Power spectral density estimation for the EEG channel
% Note the we start lines after PSD with spaces (otherwise, they
% would be interpreted as new commands)

PSD
  epoch     % produce per-epoch level output 
  sig=EEG   % only apply this command to channels named EEG

Variables

In a command file, a variable var is denoted by the following syntax:

${var}

For example, to take the example from the previous section, we could modify it to allow different epoch durations and channel names:

EPOCH len=${l}
PSD epoch sig=${s}

When running Luna on this command file, it would then be necessary to specify a value for the variables l and s, e.g.:

luna s.lst l=20 s=EEG < commands.txt 

which will then perform the spectral analyses using 20-second epochs. If l and s were not specified, Luna would give an error.

Using variables can make command files more generic by reducing the need to make minor edits across different projects. For example, consider one project that labels stage N2 sleep NREM2 and has EEG channels C3-M2 and C4-M1, whereas another project uses Stage2 with EEG channel EEG1 only. In this scenario, we could still use a single command file:

EPOCH
MASK ifnot=${nrem2}
PSD sig=${eeg}

but then invoke Luna with project-specific values for these variables (spaces added for clarity):

luna proj1.lst nrem=N2      eeg=C3-M2,C4-M1  -o out1.db < commands.txt
luna proj2.lst nrem=Stage2  eeg=EEG1         -o out2.db < commands.txt

Hint

Using project-specific parameter files as described below can further simplify working with multiple projects.

Finally, one special variable is the ^ symbol, which denotes the individual/EDF ID for the file currently being processed. That is, it does not need to be specified directly, but will be automatically substituted for each EDF processed. This can be used to point to individual-specific files. For example, below we use a combination of a project-specific variable p and the special individual-ID ^ variable with the EPOCH-ANNOT command:

...
EPOCH-ANNOT file=/path/to/${p}/data/^.eannot 
...  

One might then issue commands such as:

luna proj1.lst p=proj1 -o out1.db < commands.txt
luna proj2.lst p=proj2 -o out2.db < commands.txt

and Luna would look to the correct places to attach the epoch-annotations, e.g. perhaps something like:

/path/to/proj1/data/id0001.eannot
/path/to/proj1/data/id0002.eannot
/path/to/proj1/data/id0003.eannot
...
and
/path/to/proj2/data/id0001.eannot
/path/to/proj2/data/id0002.eannot
/path/to/proj2/data/id0003.eannot
...

Parameter files

As well as defining variables, there are a number of other command-line options that control aspects of Luna's behavior, as tabulated below. For example, to set the search path one might use:

luna s.lst path=/home/joe/data/edfs/ -o out1.db < commands.txt

Rather than having to retype such things every time, it can be convenient to wrap them up in a parameter file, which is included with a special @ syntax, as follows:

luna s.lst @param.txt -o out.db < commands.txt

where the file param.txt (which can be called anything) is a plain-text file that includes (possibly among other options) the line:

path    /home/joe/data/edfs

That is, the options in the file param.txt are expanded out as though they were typed on the command line. Whereas the command line expects key/value pairs to be connected with an equals (=) character, in a parameter file we use a tab instead. Thus, a parameter file should contain exactly two tab-delimited columns on every row. As a larger example:

alias   EEG|C3-M2|C3|EEG1
sig EEG
annot-folder    /path/to/my/annots/
path    /path/to/my/data/
sr  256
sample  project-name
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|0"
excl    "Arousal resulting from respiratory effort|Arousal (ARO RES)","Arousal|Arousal ()","ASDA arousal|Arousal (ASDA)","Limb movement - left|Limb Movement (Left)","Periodic leg movement - left|PLM (Left)","Respiratory artifact|Respiratory artifact","Respiratory effort related arousal|RERA","Spontaneous arousal|Arousal (ARO SPONT)","Unscored|9","Unsure|Unsure"

In this example, we define an alias (EEG) which is specified to be the only channel loaded (via the sig option). As well as setting the annot-folder and path folders, this parameter file also defines a number of other variables that might be used in command scripts. For example, ${sr} might be the sampling rate; ${nrem1}, ${nrem2}, etc, specify the annotation labels used for sleep stages; the comma-delimited list in ${excl} might define a list of exclusionary annotation, e.g. to be used with MASK:

MASK if=${excl}

Specifying all relevant project-specific variables in a parameter file allows generic command files to be applied more easily across multiple projects. For example (and as noted above), this is handy if different EDFs have different labels, e.g. Stage 2 sleep|2 and N2

nrem2   "Stage 2 sleep|2"

whereas a second study may use the annotation N2

nrem2   N2

but a single command file can be used (that references the variable ${nrem2}) for both studies, because project-specific parameter files are used. (Note that the use of quotes above is necessary because the annotation Stage 2 sleep|2 contains spaces.)

Annotations

The standard EDF format does not allow for any additional annotations, i.e. labels that typically describe events in the data, such as sleep stages, artifacts, or other scored features (e.g. spindles). The EDF+ format has some limited support for annotations but is awkward to work with, and so EDF+ annotation channels are effectively ignored by Luna at the moment.

EDF+ annotations

EDF+ annotations are limited by record size, and hard to generate or edit without altering the original EDF+ file. For many practical applications, where the annotations reflect derived features of the sleep time series data, it is simpler to keep the signal data and the annotation information separate. Although EDF+ annotations are correctly parsed by Luna they are currently not used in any downstream analyses, e.g. when masking epochs, etc.

However, Luna accepts various other types of explicit annotation files that contain information about events in the EDF. As noted above in the sample-list section, any files and folders specified after the second tab-delimited column (i.e. following ID and EDF) are interpreted as annotations files or folders. For an annotation folder, Luna will try to read all files in that folder (although see notes about FTR files). Typically, one might specify an individual-specific annotation folder, for example:

id0001    edf1.edf    /path/to/annotations/id0001/
id0002    edf2.edf    /path/to/annotations/id0002/
... (etc) ...

and place all annotations for that individual/EDF in that folder.

Annotation formats

Luna accepts a number of formats of annotation file, which are described in more detail in the respective reference sections linked to below:

Format Description
NSRR XML Format used by the National Sleep Research Resource to distribute sleep staging, and information on manually-scored arousals, movements and artifacts
.annot Generic Luna annotation files
.eannot Simple epoch-level annotation files (can also be loaded with the EPOCH-ANNOT command)
FTR Feature files, typically generated by certain Luna commands

Ranges

Given a sample list, by default Luna will iterate through all EDFs in that list. To restrict analyses to a single EDF, you can specify it directly on the command line, either by its ID or by the number that is its position in the sample list. For the sample list used in the tutorial, for example, if this is called s.lst:

nsrr01  edfs/learn-nsrr01.edf   edfs/learn-nsrr01-profusion.xml
nsrr02  edfs/learn-nsrr02.edf   edfs/learn-nsrr02-profusion.xml
nsrr03  edfs/learn-nsrr03.edf   edfs/learn-nsrr03-profusion.xml
you could analyze only nsrr02 by either
luna s.lst nsrr02 < commands.txt
or
luna s.lst 2 < commands.txt

Note

If a number is given after the sample list, it is always interpreted as the position in the sample list, not an ID. In other words, best not to use pure numbers as IDs in the sample list if possible.

To operate on a range of subjects within a sample list, just give two numbers: e.g.

luna large.lst 50 100 < commands.txt

The above would analyze from the 50th to the 100th EDFs in the large.lst project sample list. This can be useful if using Luna on a cluster, to parallelize processing via batch submission, for example.

Time points

In a few contexts (various outputs and FTR files, for example) Luna encodes time in time-points where 1 unit is 10-9 seconds (stored internally as uint64_t types). For a given EDF, time-points start at 0, corresponding to the start of the EDF.

Channel location files

Some commands that work with hdEEG data require a channel location map. These should be in Cartesian X, Y, Z format.

  • Four tab-delimited columns
  • First column is channel name
  • Second to fourth columns are X, Y and Z coordinates

Internally, all coordinates are converted to spherical coordinates on a unit sphere.

Special variables

Currently, the special variables used by Luna are:

Special Variable Description
sig Include this signal(s) in analysis
path Set search path for files in sample lists
alias Specify a channel alias
exclude Specify a file of IDs to exclude from analysis
annot-file Specify annotations to attach on the command line
annots Only load this (comma-delimited) list of annotations (rather than all)
annot-folder Project-wide folder to look for FTR annotation files in
skip-annots Y/N to skip all annotation files (default N)
ftr Y/N to load FTR files automatically (default Y)
epoch-len Specify the default epoch duration
assume-pm-start Y/N to assume that PM on a 12-hour clock (i.e. that 09:00 implies 21:00) (default Y)
power bands (various) Change default power bands (delta, theta, etc.)

Signal lists

To restrict analyses to a subset of signals/channels in an EDF, use the sig option either on the command line

luna s.lst sig=EEG,ECG,EMG -s DESC
or in a parameter file as separate lines

sig EEG
sig ECG
sig EMG
or as a comma-delimited list
sig EEG,ECG,EMG

Note

These options (when used on the command line, or via a parameter file) mean that only these channels are loaded from the EDF, i.e. it is as though the other channels do not exist from Luna's perspective. This is different from the using the sig option to modify the behavior of an individual Luna command: in this latter case, it is only that particular command that is restricted to those signals/channels, and so other channels are still part of the in-memory EDF for subsequent processing. For example:

...
FILTER bandpass=0.3,35 ripple=0.01 tw=0.2 sig=C3 
STATS sig=C3,EMG,ECG
...

Note

The terms signals and channels are used interchangeably throughout this documentation.

The sig option works with the alias options also, i.e.

luna s.lst sig="my-new-label,EMG,ECG" alias="my-new-label|EEG" -s DESC
Here, we've relabeled EEG as my-new-label and used sig to select it; the output from DESC reads:
Signals           : ECG EMG my-new-label

Restrictions for channel names

Channel names should not have any of the following characters: comma, tab, new-line, pipe (|). Ideally, there are advantages to not using any special characters (e.g. space, parentheses, asterisks, etc) or even things such as minus, plus signs, etc, as it makes it easier to specify channels on the command line and in scripts; it also can make processing the output much easier, i.e. if you use destrat to produce a data table where the channel labels are used to make variable names, you will want to restrict channel labels to alphanumeric characters and the underscore character as a separator. See this FAQ. You can use Luna aliases to make better channel names.

Search paths

As noted above, when parsing sample-lists Luna can use either absolute or relative paths for EDFs and annotation file-names. To use the same project on different computers, it is often convenient to hard-code absolute path names, i.e.

id001   /home/joe/edfs/proj1/edf1.edf
id002   /home/joe/edfs/proj1/edf2.edf
id003   /home/joe/edfs/proj1b/edf3.edf

as this means that you can run Luna from any folder and it will still know where to look for the EDFs. Alternatively, the path option (either on the command line, or in a parameter file) lets you write a sample list in relative terms:

id001   proj1/edf1.edf
id002   proj1/edf2.edf
id003   proj1b/edf3.edf

One would then give the path separately, which will be added as a prefix to all relative paths in the sample list:

luna s.lst path=/home/joe/edfs < commands.txt 

(i.e. otherwise Luna would not be able to find the EDFs unless it was run from the /home/joe/edfs/ folder directly.)

This can also be convenient if the project is moved, i.e. if /home/joe/edfs/ becomes /home/mary/projects/, then you only need change the path rather than recreate the sample list:

luna s.lst path=/home/mary/projects/ < commands.txt 

Aliases

Aliases are different names for channels/signals in an EDF. Aliases can be useful if different EDFs in a project have different labels for the same channel, e.g. C3, C3-M1 and C3-A1. Alternatively, aliases can be useful if a channel has a long unwieldy name, perhaps that contains spaces or other special characters.

Aliases can be specified either on the command line:

luna s.lst alias="C3|C3-M1|C3-A1" -s STATS sig=C3
or in a parameter file:
alias   C3|C3-M1|C3-A1

where the format is a series of |-delimited labels, with the first being the primary alias, or canonical channel label.. That is, all subsequent terms are remapped to the primary alias in output (i.e. C3). When specifying channels, one can either use the original EDF terms (e.g. C3-M1) or the primary alias (C3). That is, even if an EDF in this project only has a channel C3-M1, it will still be included in any analysis that requires C3. Similarly, in all output (including new EDFs generated via the WRITE command), the canonical channel labels (primary aliases) will be swapped in whenever needed. (It is not necessary that the canonical form exists in any of the project's EDFs: it could be an entirely new label you wish to apply to this group of differently-named but otherwise identical channels.)

Note

Because most shell scripts interpret | as a special control character (pipe), we had to use quotes when specifying the alias on the command line above, i.e. alias="C3|C3-M1|C3-A1". This also implies that channel names should not contain | characters in.

Exclude lists

To skip one or more EDFs in a project, you can create an exclude list: a plain-text file with one ID per row. You can then use the exclude option to point to this file, either on the command line:

luna s.lst exclude=skip.txt -s DESC
or by specifying it in a parameter file
exclude skip.txt
These individuals/EDFs will be skipped in all analyses.

Attaching annotations

To attach an annotation file without having to edit the sample-list, you can use the annot-file (or equivalently annot-files, annots-file or annots-files) option.

luna s.lst 1 annot-file=path/to/file.annot < cmd.txt
This will be most useful when working with a single EDF.

The annot-folder option specifies a single, project-wide annotation folder, which will be searched for FTR files that belong to that individual:

annot-folder    /path/to/data/folders/

Selecting annotations

To only load certain annotation classes use the annot (or equivalently annots) option. For example, the following only loads classes labeled wake and artifact1:

luna s.lst annots=wake,artifact1 < commands.txt 
To specify this in a parameter file:
annot          wake,artifact1

This can be useful if the sample-list otherwise specifies that many annotations are loaded by default (e.g. by pointing to an annotation folder for that individual/EDF).

Other annotation options

The skip-annots option (yes/no) indicates whether to skip loading all annotations (default no):

skip-annots    Y

The ftr option (yes/no) turns on or off loading of FTR files automatically (default yes):

ftr            N

The epoch-len command can be used to specify a default epoch duration (in seconds) different from 30, which will be used when attaching .eannot files specified in the sample-list (i.e. to calculate the implied number of epochs in the EDF).

epoch-len   20

Force evening start time

The assume-pm-start flag can be set to yes (Y, yes, or 1) or no (N, no or 0). Internally Luna assumes a 24-hour clock; if the EDF start time is set to 09:00, for example, this will be converted to 21:00 unless the assume-pm-start flag is set to no.

Spectral power bands

The following special variables can be changed on the command line or via a parameter file:

Band name Definition
slow Slow power band (default 0.5-1 Hz)
delta Delta power band (default 1-4 Hz)
theta Theta power band (default 4-8 Hz)
alpha Alpha power band (default 8-12 Hz)
sigma Sigma power band (default 12-15 Hz)
beta Beta power band (default 15-30 Hz)
gamma Gamma power band (default 30-1000 Hz)
total Total power band, denominator for relative power (default 0-1000 Hz)

For example, to change the definition of sigma power to 11 to 15 Hz (instead of 12 to 15 Hz):

luna s.lst sigma=11-15 -s "PSD sig=C3,C4"

Output

Logs

Luna writes a log to the standard error (stderr) stream, i.e. the console, that reports the progress of a given command. This will display the version of Luna, the date and time the command was initiated, and the input commands. For each EDF processed, Luna will then list the ID along with some basic information about the EDF, its attached annotations and the commands applied to that EDF. Any error messages will be sent to the stderr also.

===================================================================
+++ luna | v0.2, 12-Dec-2018 | starting process 2019-01-10 14:20:10
===================================================================
input(s): s.lst
output  : .
commands: c1    DESC    

___________________________________________________________________
Processing: nsrr01 [ #1 ]
 total duration 11:22:00, with last time-point at 11:22:00
 40920 records, each of 1 second(s)

 signals: 14 (of 14) selected in a standard EDF file:
  SaO2 | PR | EEG(sec) | ECG | EMG | EOG(L) | EOG(R) | EEG
  AIRFLOW | THOR RES | ABDO RES | POSITION | LIGHT | OX STAT

 annotations:
  [Arousal ()] 194 event(s) (from edfs/learn-nsrr01-profusion.xml)
  [Hypopnea] 361 event(s) (from edfs/learn-nsrr01-profusion.xml)
  [NREM1] 109 event(s) (from edfs/learn-nsrr01-profusion.xml)
  [NREM2] 523 event(s) (from edfs/learn-nsrr01-profusion.xml)
  [NREM3] 16 event(s) (from edfs/learn-nsrr01-profusion.xml)
  [NREM4] 1 event(s) (from edfs/learn-nsrr01-profusion.xml)
  [Obstructive Apnea] 37 event(s) (from edfs/learn-nsrr01-profusion.xml)
  [REM] 238 event(s) (from edfs/learn-nsrr01-profusion.xml)
  [SpO2 artifact] 59 event(s) (from edfs/learn-nsrr01-profusion.xml)
  [SpO2 desaturation] 254 event(s) (from edfs/learn-nsrr01-profusion.xml)
  [Wake] 477 event(s) (from edfs/learn-nsrr01-profusion.xml)
 ..................................................................
 CMD #1: DESC

___________________________________________________________________
...processed 1 EDFs, done.
...processed 1 command(s),  all of which passed
-------------------------------------------------------------------
+++ luna | finishing process 2019-01-10 14:20:10
===================================================================

Default text output

Beyond the log information described above, if no database option is specified (with -o or -a) then, by default, all primary output goes to stdout, i.e. the console/terminal, and will be interleaved with the logging information. That is, here output refers to the information produced by individual Luna commands, rather than the log information per se.

This is typically not very useful. You can redirect the output to a separate file, say out.txt:

luna s.lst < commands.txt > out.txt 

Whilst a few commands such as DESC or SUMMARY produce their own format of output (simple text formatted for human reading), most commands adopt the same output framework, such that the same information can be channeled to either a text file (described here), a database (described next) or even an object in R if using the Luna R extension library.

Using the HEADERS command as an example on the first EDF in the tutorial dataset:

luna s.lst nsrr01 sig=ECG,EMG  -s HEADERS > out.txt

The out.txt file contains the following:

nsrr01  HEADERS .   .   NS  2
nsrr01  HEADERS .   .   NR  40920
nsrr01  HEADERS .   .   REC.DUR 1
nsrr01  HEADERS .   .   TOT.DUR.SEC 40920
nsrr01  HEADERS .   .   TOT.DUR.HMS 11:22:00
nsrr01  HEADERS CH/ECG  .   SR      250
nsrr01  HEADERS CH/ECG  .   PDIM        mV
nsrr01  HEADERS CH/ECG  .   PMIN        -1.25
nsrr01  HEADERS CH/ECG  .   PMAX        1.25
nsrr01  HEADERS CH/ECG  .   DMIN        -128
nsrr01  HEADERS CH/ECG  .   DMAX        127
nsrr01  HEADERS CH/EMG  .   SR      125
nsrr01  HEADERS CH/EMG  .   PDIM        uV
nsrr01  HEADERS CH/EMG  .   PMIN        -31.5
nsrr01  HEADERS CH/EMG  .   PMAX        31.5
nsrr01  HEADERS CH/EMG  .   DMIN        -128
nsrr01  HEADERS CH/EMG  .   DMAX        127

Each row is one value for one variable from one command. In this case, only the HEADERS command was performed. The six tab-delimited columns are:

  • Individual/EDF ID
  • Command name
  • Any stratifying factors (or . if not)
  • Any epoch/interval time factors (or . if not)
  • Variable name
  • Value

Stratifying factors mean that the same variable is repeated in different contexts: for example, for different channels in the same EDF. This is represented above by the factor (channel, CH) and the two levels (ECG and EMG). Given that SR is the sample rate for a channel, we can see that the ECG channel has a sample rate of 250 Hz, whereas the EMG has a sample rate of 125 Hz, for example. The first variables, e.g. NR and NS do not have any stratifying factors (. in columns 3 and 4) as these are general properties of the entire EDF, and so only occur once.

This format is primarily used for debugging or in some other very focused cases. Although it is relatively easy to parse, in general you'll want to use Luna's lout database format, described next.

lout databases

This is the primary mode of output for most Luna commands. Here we run the same command as in the previous section but instead using a lout database to collect the output:

luna s.lst nsrr01 sig=ECG,EMG -o out.db -s HEADERS 

This generates a file out.db (actually an SQLite database) which is not designed to be directly displayed in the terminal via a text-editor or spreadsheet. Rather, it is an intermediate form, from which various text-files can be extracted in a variety of formats. See this page for information on how to work with output databases, using either destrat or lunaR.

New EDFs

Luna can output new EDFs after manipulating signals, masking epochs, etc, via the WRITE command.

Annotations

Some commands, such as SPINDLES, can produce FTR files, which can be used as annotation files in other Luna analysis (or for visualization with Scope).