4 Getting started with PLMScoRe - Steph-Fulda/PLMScoRe GitHub Wiki

#Using PLMScoRe for the first time

##Loading PLMScoRe

The first thing to do is to make the PLMScoRe package available in R. I assume that you have installed R and possibly RStudio and also installed the PLMScoRe package as described in the prerequisites. You have opened R or RStudio and to load the package just type:

library(PLMScoRe)

press enter.

You are all set to start. Next in R type:

StartPLMScoRe()

Better still, to have the output available after running the function, type

plmresults<-StartPLMScoRe()

Please select REMLogic event file...

will appear in the R console and a file open dialog will pop up. Select your REMLogic event txt file.

Do you want to load an existing REMLogic specification file? (y/n)

For now type n. When using PLMScoRe for the first time, it will ask a lot of information about your specific specifications. At the end of the long list of questions you will have the option to save these specifications in a separate file. That means, the next time you could just load this REMLogic specification file. The next question popping up:

How many data columns do you have?
Put in number:

Type the number of columns your txt file has (and hit return). That is the only information you absolutely have to find out before starting (just open the txt file in any text editor, scroll down to the event table, and count the number of columns). As explained above, you need at least 4 columns denoting start times, duration of events, name of the events, and channel information. Theoretically, you could also export a file with one or two additional columns, denoting sleep stage and position.

Next, the column names found in your txt file will be displayed on the screen and you will be asked to provide information on which column denotes which information. (I know, it seems pretty obvious from the column names, but there might be versions in other languages than English or there might be differences from one country to another, so just to be sure...).
This is an example what you may see on your console:

1 - Sleep Stage
2 - Position
3 - Time [hh:mm:ss.xxx]
4 - Event
5 - Duration[s]
6 - Location
These are your column names.

What is the column with the start times?
Put in number:

Enter the respective numbers here and for the next questions:

What is the column with the duration information?
Put in number:
What is the column with the event names?
Put in number:
What is the column with the channel information?
Put in number:
If you have a column with sleep stages for each event,...
Put in number:

This last question asks if you have (like I do) exported also a fifth column with the sleep stage information for each event. If you have, enter the number, if not, just press enter.

This is an example of the time format in this file:
[1] "2013-04-11T20:00:01.000000"
Does this format correspond to the standard format YYYY-MM-DDTHH:MM:SS.ssss ?
(y/n or 1/0):

Obviously, knowing the specific time format is crucial. Without that, the program will not run. Comparing a few versions from different labs it seems that this specific time format is used universally. Let's hope that is indeed so. If you confirm this (with y), the program will actually make a quick test to see if that works with the available data. If it doesn't, it will ask you to put in your correct time format. In that case, please consult the R manual for help on how to specify the time format here.

By now, you have specified all the information needed to know how to read in the txt file. Next you will be asked to about the the information contained in the txt file. As before, the program will give you a list with options, based on what it found in your file and asks you to put in the relevant information. For example:

1 - EEG-C4-M1
2 - EEG-F3-M2
3 - EEG-O1-M2
4 - EEG-O2-M1
5 - EMG.Tibialis-Leg.Left
6 - EMG.Tibialis-Leg.Right
7 - Pos.Discreet
8 - Pulse.Averaged-Probe
9 - Resp.Flow-Cannula.Nasal
10 - Resp.Movement-Inductive.Abdomen
11 - Resp.Movement-Inductive.Thorax
12 - Resp.Phase-Inductive
13 - Resp.RMI-Inductive
14 - SpO2.Averaged-Probe
These are the available channels.

Please select LEFT leg channel.
Put in number:
Please select RIGHT leg channel.
Put in number:

Next, you will see a list of all events that have been scored on your respective leg channels and you will be asked to identify all events that denote leg movement events.

1 - PLM
2 - PLM-LM
3 - PLM-RRLM
LEFT Leg: Please select all events that denote single LM:   
*** If there is more than one, use R notation eg. 1,2,3 or 1:3, or 1,2,5:7

You will be asked to indicate which of these are events that denote leg movements. This is asked separately for the left and the right leg channel.

Right Leg: Please select all events that denote single LM:   
*** If there is more than one, use R notation eg. 1,2,3 or 1:3, or 1,2,5:7

"It might be tempting to select the entry PLM but in my experience REMLogic uses PLM to denote the PLM series and not single leg movement events. If you are unsure, whether this is also the case in your program, I suggest opening the recording and checking what got named PLM, if it is the series it will show a long event spanning over 4 or more leg movements."

In this first step, the program presented you with the list of events that had been found as annotations on the leg channels in this recording. If you want to score only the present recording that is all you need. If you want to set up this information to work also with other recordings, you may want to select additional events that have not been scored in the present night but might be found in other recordings. These events will be part of the general event list found in the header of the event file. The program will ask you whether you want to select additional events:

Do you want to select additional LM events from the list of all annotations?(y/n or 1/0)

If you answer with y or 1, you will be presented with the list of all annotations and you can select those you want to add.

Specifying at least one leg channel and selecting at least one leg movement event is mandatory for the program to run. Information about sleep, arousal, and respiratory events is optional and will be asked next. The next questions all follow the same format. First, you will be asked if the specific information is present in your data. For example:

Are there arousal events? (y/n of 1/0)

If you confirm this, you will be presented with the following choice:

*** [1] 'all annotations' refers to the complete list of annotations  
        given in the header of the REMLogic event file.  
    [2] 'scored annotations' refer to annotations used in this particular   
        scoring session, and found in the events column of the REMLogic event file.  
Do you want to select annotations from  
 [1] all annotations or  
 [2] scored annotations?  
Put in number:

All annotations [1] are those events that are in the header of the event file, these are all events that have been defined for the exported category and may or may not be present in this specific recording. In contrast, scored annotations [2] are all events that have been exported and are present/scored in this specific recording. Depending on your local practice, [1] may be a very long list while [2] is generally shorter. If you just want to use the program for the present night, it is easier to use [2], if you want to set up a specification for future use with other recordings choosing [1] makes sure that you can include all possible events. If you have selected [2], after you selected events, you will be asked whether you want to choose additional events from [1].

If you selected a wrong input or forgot to select an event, do not worry. At the end, before the program runs, you will have the chance to change or modify your input one last time.

You will also be asked whether the file contains information about the start/stop of the recording:

Are there events denoting start/stop or lights off/lights on? (y/n or 1/0)

This information is needed to determine registration time. The following convention is implemented in PLMScoRE:

Determination of start, in preferred order:

if a start event is defined and that start event is present, this will be taken as the start of the time in bed (TIB) [if more than 1 start event are present, the latest one will be taken]
if no start event is present but sleep is scored, the first scored wake/sleep epoch is taken as the start
if there is both a start event and sleep/wake scoring, the latest event of the two (start event, first scored epoch) is taken as the start
if no start event is present and no sleep is scored, it will be assumed that the registration started 30 s before the first event (any of LM, arousal, respiration)

Determination of stop, in preferred order:

if a stop event is defined and that stop event is present, this will be taken as the stop of the TIB [if more than 1 stop event are present, the latest one will be taken]
if no stop event is present but sleep is scored, the last scored wake/sleep epoch is taken as the stop
if both a stop event and sleep/wake scorings are present, the earlier of the two (stop event, last scored epoch) is taken as the stop
if no stop event is present and no sleep is scored, it will be assumed that the registration stopped 30 s after the last event (any of LM, arousal, respiration)

The penultimate question concerns the WASM 2016 rules. For the identification of respiratory event associated leg movements there are two different criteria and you can choose which one you want to use:

Which set of PLMS rules do you want to choose?  
Currently, only the newest WASM (IRLSSG/EURLSSG) 2016 rules are implemented.  

There are two different criteria for respiratory event related LM:  
		[1] - 2s to +10.25 s (recommended)  
		[2] - 0.5 s to +0.5 s  
Please choose one:

There are some good arguments to choose option [1] and that is something I would definitely recommend.

Finally, you can also choose what kind of output you would like to have:

What kind of output would you like to have? (multiple outputs possible)
   [1] screen
   [2] csv file
   [3] pdf 
Please input number(s):

Choosing screenwill print a summary table on the R console and plots the IMI distribution in R. csv file will save a large comma-separated file with all information about leg movements that can be derived from the recording. pdf will save a one-page pdf file with the summary table and the IMI plots. Per convention, if files are generated and saved, these will be saved in the same folder where the REMLogic event txt file is located and with the same name as this txt file.

Ok, nearly there! Finally (promise!) you will see all the choices have you made:

THESE ARE YOUR SPECIFICATIONS:    
Global:Legs:  
   Left leg channel name :  EMG.Tibialis-Leg.Left   
   Right leg channel name :  EMG.Tibialis-Leg.Right   
   Left leg LM event names :    
        PLM-LM  
        PLM-RRLM  
   Right leg LM event names :    
       PLM-LM  
       PLM-RRLM  
Sleep:  
 Sleep scored :  1   
 Wake annotation name(s) :  SLEEP-S0   
 N1 annotation name(s) :  SLEEP-S1   
 N2 annotation name(s) :  SLEEP-S2   
 N3 annotation name(s) :  SLEEP-S3   
 REM annotation name(s) :  SLEEP-REM   
Arousal:  
 Arousals scored :  1   
 Arousal event names :    
	AROUSAL  
	AROUSAL-APNEA  
	AROUSAL-HYPOPNEA  
	AROUSAL-PLM  
	AROUSAL-RESP  
Respiration:  
 Respiratory events scored :  1   
 Respiratory event names :    
	APNEA  
	APNEA-CENTRAL  
	APNEA-MIXED  
	APNEA-OBSTRUCTIVE  
	HYPOPNEA  
	HYPOPNEA-CENTRAL  
	HYPOPNEA-MIXED  
	HYPOPNEA-OBSTRUCTIVE  
Start/Stop events:  
 Start/Stop events present :  1   
 Start/Lights off event name :  LIGHTS-OFF   
 Stop/Lights on event name :  LIGHTS-ON   
REMLogic text file specifications:  
 Time format :  %Y-%m-%dT%H:%M:%OS   
 Number of columns :  6   
 Start time column number :  3   
 Event column number :  4   
 Duration column number :  5   
 Channel location column number :  6   
 Sleep stage column number (if present) :  1   

Local:  
REMLogic event txt file: D:\RLS\Scoring\XYZ-Events.txt   
PLMS scoring rules: WASM20016  
Respiratory event related LM: -2.0 s to + 10.25 s (recommended)  
 Output option(s) :  screen   
Do you want to change any of the specifications?(y/n or 1/0)

This is your last chance to change the input parameters. If you choose to do so, you can further choose which of the parameters you want to change.

If you want to change annotations you can profit from the convention that selecting [2] scored annotations will overwrite any existing annotations, while [1] all annotations will add to existing ones. So if you want to remove an annotation, first select [2].

After all that hard work, the program runs a preliminary check on the input parameters and if everything is ok, you will have the opportunity to save the specification file.

Everything seems to be ok  
Do you want to save the specification file?(y/n or 1/0)

I recommend to do that, so you save some time the next time around. Even if you load an existing specification file, you will still have the option to change selected parameters, so it will be quicker in any case. If everything went ok, you will see some variation of the following on the screen:

THANK YOU, that seems to be all.  

Running final check...  

BASIC INFO:    

Registration started: 	2013-05-11 21:11:01
Registration stopped: 	2013-05-12 07:34:50
Time in bed:		10:23:49.534
Total sleep time:	08:13:60.000

No. left LMA events:	699
No. right LMA events:	912

No. arousal events:	239
No. respiratory events:	248

PLMScoRing started...

If you do, CONGRATULATIONS!!! See what comes next.

4 Getting started with PLMScoRe - Steph-Fulda/PLMScoRe GitHub Wiki

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️