.. SPDX-FileCopyrightText: Copyright © 2023 Idiap Research Institute <contact@idiap.ch>
..
.. SPDX-License-Identifier: GPL-3.0-or-later

.. _sleepless.install:


==============
 Installation
==============

Installation may follow one of three paths: deployment or development for
CPU-only execution, or a mixed development and deployment environment with
Nvidia CUDA support. Choose the relevant tab for details on each of those
installation paths.

.. tab:: Deployment

   Install using pip_, or your preferred Python project management solution (e.g.
   uv_, rye_ or poetry_).

   **Stable** release, from PyPI:

   .. code:: sh

      pip install sleepless

   **Latest** development branch, from its git repository:

   .. code:: sh

      pip install git+https://gitlab.idiap.ch/medai/software/sleepless@main


.. tab:: Development

   Checkout the repository, and then use pixi_ to setup a full development
   environment:

   .. code:: sh

      git clone git@gitlab.idiap.ch:medai/software/sleepless
      pixi install --frozen
      pixi run sleepless --help

   .. tip::

      The ``--frozen`` flag will ensure that the latest lock-file available
      with sources is used.  If you'd like to update the lock-file to the
      latest set of compatible dependencies, remove that option.

      If you use `direnv to setup your pixi environment
      <https://pixi.sh/latest/features/environment/#using-pixi-with-direnv>`_
      when you enter the directory containing this package, you can use a
      ``.envrc`` file similar to this:

      .. code:: sh

         watch_file pixi.lock
         export PIXI_FROZEN="true"
         eval "$(pixi shell-hook)"


.. tab:: CUDA

   Checkout the repository, and then use pixi_ to setup a version of this
   package that can run on a CUDA-enabled machine:

   .. code:: sh

      git clone git@gitlab.idiap.ch:medai/software/sleepless
      pixi install --frozen -e cuda
      pixi run -e cuda sleepless --help

   To enable CUDA support, always run applications using the ``cuda``
   environment via ``pixi run -e cuda ...``.  Refer to further pixi
   configuration tips on the *Development* tab above.


.. _sleepless.setup:

Setup
-----

A configuration file may be useful to setup global options that should be often
reused.  The location of the configuration file depends on the value of the
environment variable ``$XDG_CONFIG_HOME``, but defaults to
``~/.config/sleepless.toml``.  You may edit this file using your preferred
editor.

Here is an example configuration file that may be useful as a starting point:

.. code:: toml

   [datadir]
   EDF = "/Users/myself/dbs/EDF"
   MASS = "/Users/myself/dbs/MASS"


.. tip::

   To get a list of valid data directories that can be configured, execute:

   .. code:: sh

      sleepless dataset list

   You must procure and download datasets by yourself.  The raw data is not
   included in this package as we are not authorised to redistribute it.

   To check whether the downloaded version is consistent with the structure
   that is expected by this package, run:

   .. code:: sh

      sleepless dataset check EDF

.. _sleepless.setup.datasets:

Supported Datasets
==================

Here is a list of currently supported datasets in this package, alongside
notable properties.  Each dataset name is linked to the location where raw data
can be downloaded.

.. list-table::
   :header-rows: 1

   * - Datasets
     - EEG channels
     - EOG channels
     - EMG channels
     - Annotation method
     - Train
     - Validation
     - Test
     - Reference
   * - ST-EDF
     - 3
     - 1
     - 1
     - R&K
     - 28
     - 8
     - 8
     - [SLEEP_EDF-2018]_
   * - SC-EDF
     - 3
     - 1
     - 1
     - R&K
     - 97
     - 28
     - 28
     - [SLEEP_EDF-2018]_
   * - _SS3-MASS
     - 20
     - 2
     - 3
     - AASM
     - 33
     - 10
     - 10
     - [MASS-2014]_


.. include:: links.rst