notebook/src/sleepyland-notebooks/quickstart_tutorial.ipynb

{
 "cells": [
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "# Quickstart Tutorial\n",
    "\n",
    "---\n",
    "\n",
    "Links to notebooks in this repository:\n",
    "\n",
    "[Quickstart Tutorial](./quickstart_tutorial.ipynb) | [Introduction](./00_introduction.ipynb) | [Services](./01_services.ipynb) | [Sleep Staging](./02_sleep_staging.ipynb) | [Ensembling Sleep Staging](./03_ensembling_sleep_staging.ipynb) | [Sleep Dynamics](./04_sleep_dynamics.ipynb) | [Luna Toolbox Integration](./05_luna_integration.ipynb)\n",
    "\n",
    "---\n",
    "\n",
    "This list of notebooks guides you through the core features of **SLEEPYLAND**, integrating the functionality of the **Luna toolbox** and various other services. The Quickstart Tutorial will first guide you through the steps needed to start using the SLEEPYLAND UI for your sleep data analysis. Each step includes a brief description to help you understand the functionality and options available. We will first explore how to directly use the machine learning models for sleep staging."
   ],
   "id": "8d5a3666a2676aa9"
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "---\n",
    "\n",
    "> The user has three main options to perform the sleep staging via the UI. In this Quickstart tutorial we will guide you step-by-step through the **NSRR Data** option. We will benchmark and compare different sleep staging models using NSRR recordings. This option allows you to evaluate the performance of various models on standardized datasets.\n",
    "\n",
    "---"
   ],
   "id": "b03cf97c260dfd0c"
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "### Step1 - Upload/Download data\n",
    "\n",
    "To begin using SLEEPYLAND, you have two options for integrating NSRR sleep data: uploading your locally stored NSRR dataset or downloading data from the NSRR platform. Below are the detailed procedures for both options.\n",
    "\n",
    "**Option-A: Upload**\n",
    "\n",
    "If you have a dataset of NSRR sleep recordings stored locally, you can upload it directly into SLEEPYLAND. To ensure the platform recognizes and organizes your files correctly, your dataset must follow a specific hierarchical structure. For instance, if your dataset is named **learn**, it should be organized as follows:\n",
    "\n",
    "    **learn**\n",
    "    ├── `learn-nsrr01.edf`\n",
    "    ├── `learn-nsrr01.xml`\n",
    "    ├── `learn-nsrr02.edf`\n",
    "    ├── `learn-nsrr02.xml`\n",
    "    ├── `learn-nsrr03.edf`\n",
    "    └── `learn-nsrr03.xml`\n",
    "\n",
    "The whole folder contains the raw data files in `.edf` format and their corresponding annotation files, e.g., here `.xml` format.\n",
    "\n",
    "**Option-B: Download**\n",
    "\n",
    "If you prefer to directly download NSRR recordings from the NSRR platform follow these steps:\n",
    "\n",
    "1. **Obtain an access token**: visit the [NSRR data request platform](https://sleepdata.org/data/requests/nfs/start) and request an access token.\n",
    "2. **Choose a dataset**: select a dataset from the list of those supported in SLEEPYLAND.\n",
    "3. **Select specific recordings**: identify the recordings you need for your analysis and download them.\n",
    "\n",
    "Once the data is downloaded, you can double-check that the data are organized in the hierarchical structure described above (check in the shared `input` docker volume).\n",
    "\n",
    "---"
   ],
   "id": "a01286be4beea971"
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "### Step2 - Specify channels\n",
    "\n",
    "When setting up your analysis in SLEEPYLAND, you have the flexibility to select specific channels from your recordings. This allows you to tailor the analysis to your needs, whether focusing on particular signals or analyzing all available data for a comprehensive approach.\n",
    "\n",
    "#### Options for channel selection\n",
    "\n",
    "1. **All channels** (Default): if you want a broad analysis across all available signals, select the `All Channels` option (EEG and/or EOG).\n",
    "\n",
    "2. **Single-Channel configuration**: for a single-channel-type analysis, you can select either EEG or EOG specific channels while setting the other to `None`. For example:\n",
    "   - EEG: `C4-M1`\n",
    "   - EOG: `None`\n",
    "\n",
    "3. **Multi-Channel configuration**: if your analysis requires multiple types of signals, you can select both EEG and EOG channels simultaneously. Specify the specific channel configurations, such as:\n",
    "   - EEG: `C4-M1`\n",
    "   - EOG: `E1-M2`\n",
    "\n",
    "---"
   ],
   "id": "d37b699b5d4f5065"
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "### Step3 - Choose Models for Sleep Staging\n",
    "\n",
    "Choose from a selection of feature-based and deep learning based models for sleep staging:\n",
    "\n",
    "- **Feature-Based Models**: models like YASA offer sleep stage classification using features extracted from PSG data.\n",
    "- **Deep Learning Models**: options like U-Sleep, DeepResNet, and SleepTransformer models provide advanced automated sleep staging using different PSG setups.\n",
    "\n",
    "Refer to [List of Models for Sleep Staging](https://github.com/biomedical-signal-processing/sleepyland?tab=readme-ov-file#list-of-models-for-sleep-staging) section for more information on the currently supported/available models.\n",
    "\n",
    "---"
   ],
   "id": "d543c82ae7325853"
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "### Step4 - Run Predictions/Evaluations\n",
    "\n",
    "Once you have configured your settings, you can initiate the analysis by selecting either **Predict** or **Evaluate**.\n",
    "\n",
    "Choose the **Evaluate** option here - since all the supported NSRR data includes annotation files. This option allows you to evaluate the accuracy of the selected model by comparing its predictions against the provided annotations.\n",
    "\n",
    "---"
   ],
   "id": "20f519dc3645ac4"
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "### Step5 - Explore Results\n",
    "\n",
    "Use the UI to visually explore and compare sleep stages and dynamics across different tools. For a more customized analysis, you can also use a Jupyter Notebook to interact directly with the data, allowing for further exploration and visualization.\n",
    "\n",
    "---"
   ],
   "id": "5fb250731059fa4d"
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "Detailed instructions on how to navigate into the UI here [SLEEPYLAND YouTube playlist](https://www.youtube.com/playlist?list=PLl7J6NiydmVKJ2SAh7fTKaSK-JoPTgvG-). In the next [Introduction](./00_introduction.ipynb) notebook, we will walk through a step-by-step introduction to a typical SLEEPYLAND workflow, and we will show how to easly interact and exploit its associated services.\n",
   "id": "c32522d46d4cbfe4"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}