<commit_before>Sleep EDFx Toolbox
==================

A toolbox to download, extract, load and view signals from the PhysioNet Sleep EDF Expanded Database.

This work is part of the research performed at the [Rodriguez-Villegas Lab, Imperial College London, UK](http://www.imperial.ac.uk/rodriguez-villegas-lab).


##Features##

* Download the complete set of 61 recordings 
* Extract the EDF files and convert them to Matlab signals
* Get Matlab-compatible hypnogram from the annotations
* Extract overnight sleep data and hypnogram from consistent start and end times
* View signals between any time along with its hypnogram
* Compute performance results
* Use RK or AASM classification



## Installation
* Download or clone the repository and add it to your path
* **IMPORTANT**: For EDF to Matlab conversion, [EEGLAB](http://sccn.ucsd.edu/eeglab/) is required and its installation must be on the search path



##Usage##

### All-in-one: download EDF files, annotations, extract data and process hypnograms

This is the simplest method to get started with the PhysioNet Sleep EDF Expanded database. 

```matlab
initialSetupEDFx(download_dir)
```

* `destination_directory` is an optional argument to specify location for download

This function is needed only for the first time to get all the needed data and set up your working area with all the tests arranged in separate folders from where they can be loaded. Each test will be in a sub-directory inside the `download_dir` and each `test_dir` will have the source edf file, `matlab` folder with signals in .m files and an `info` folder with sampling frequency, list of channels and other annotations.

### Loading a test

```matlab
[data, f_samp, number_of_epochs, hypnogram, times] = loadEDFx(test_dir, classification_mode)
```

* Specify the top level `test_dir` of the test to be loaded. For example, `C:\Full_Path\ST7120`
* `classification_mode` to use can be either `'RK'` or `'AASM'`

The function returns the following:

* `data` is a container (dictionary) with all channels/signals in the test.
* Use `data.keys` to get a list of all available channels.
* To work with a particular channel's data, for example, fpz-cz you can load it as `data('eeg_fpz')`
* `f_samp` is the sampling frequency
* `number_of_epochs` is the number of 30-second epochs in the test (for overnight sleep)
* `hypnogram` is the corresponding hypnogram for each 30-s epoch in the loaded data
* `times` is a vector containing the start and end times of the test recording

Please refer to the following publication on how the starting and end times are calculated which in turn influence the total number of epochs. The publication also details the hypnogram conversion from RK to AASM.

**Recommendations for performance assessment of automatic sleep staging algorithms**, *SA Imtiaz and <NAME>*, Engineering in Medicine and Biology Society (EMBC), 2014 36th Annual International Conference of the IEEE.


### Viewing signals for a test

```matlab
viewEDFxSignals(signal, times, start_time, end_time, f_samp, hypnogram)
```
<commit_msg>fixed typo<commit_after>Sleep EDFx Toolbox
==================

A toolbox to download, extract, load and view signals from the PhysioNet Sleep EDF Expanded Database.

This work is part of the research performed at the [Rodriguez-Villegas Lab, Imperial College London, UK](http://www.imperial.ac.uk/rodriguez-villegas-lab).


##Features##

* Download the complete set of 61 recordings 
* Extract the EDF files and convert them to Matlab signals
* Get Matlab-compatible hypnogram from the annotations
* Extract overnight sleep data and hypnogram from consistent start and end times
* View signals between any time along with its hypnogram
* Compute performance results
* Use RK or AASM classification



## Installation
* Download or clone the repository and add it to your path
* **IMPORTANT**: For EDF to Matlab conversion, [EEGLAB](http://sccn.ucsd.edu/eeglab/) is required and its installation must be on the search path



##Usage##

### All-in-one: download EDF files, annotations, extract data and process hypnograms

This is the simplest method to get started with the PhysioNet Sleep EDF Expanded database. 

```matlab
initialSetupEDFx(destination_directory)
```

* `destination_directory` is an optional argument to specify location for download

This function is needed only for the first time to get all the needed data and set up your working area with all the tests arranged in separate folders from where they can be loaded. Each test will be in a sub-directory inside the `destination_directory` and each newly created `test_directory` will have the source edf file, `matlab` folder with signals in .m files and an `info` folder with sampling frequency, list of channels and other annotations.

### Loading a test

```matlab
[data, f_samp, number_of_epochs, hypnogram, times] = loadEDFx(test_dir, classification_mode)
```

* Specify the top level `test_dir` of the test to be loaded. For example, `C:\Full_Path\ST7120`
* `classification_mode` to use can be either `'RK'` or `'AASM'`

The function returns the following:

* `data` is a container (dictionary) with all channels/signals in the test.
* Use `data.keys` to get a list of all available channels.
* To work with a particular channel's data, for example, fpz-cz you can load it as `data('eeg_fpz')`
* `f_samp` is the sampling frequency
* `number_of_epochs` is the number of 30-second epochs in the test (for overnight sleep)
* `hypnogram` is the corresponding hypnogram for each 30-s epoch in the loaded data
* `times` is a vector containing the start and end times of the test recording

Please refer to the following publication on how the starting and end times are calculated which in turn influence the total number of epochs. The publication also details the hypnogram conversion from RK to AASM.

**Recommendations for performance assessment of automatic sleep staging algorithms**, *<NAME> and <NAME>*, Engineering in Medicine and Biology Society (EMBC), 2014 36th Annual International Conference of the IEEE.


### Viewing signals for a test

```matlab
viewEDFxSignals(signal, times, start_time, end_time, f_samp, hypnogram)
```

{'fraction_non_alphanumeric': 0.07274490785645005, 'fraction_numerical': 0.005172971225347559, 'mean_word_length': 4.931927133269415, 'pattern_counts': {'":': 0, '<': 6, '<?xml version=': 0, '>': 6, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 12, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7071328', 'n_tokens_mistral': 1764, 'n_tokens_neox': 1657, 'n_words': 854}