ActiSleep Tracker

ActiSleep Tracker is an application designed to run after processing actigraphy data with the GGIR package and allows users to annotate sleep data. This repository contains the source code and related files for the application.

Getting Started

The application may be installed either through Docker (recommended for users) or Poetry (recommended for developers). Whichever method you use to launch the app, the app will be available at http://localhost:8051.

Running ActiSleep Tracker through Docker

1. Install Docker: Ensure you have Docker installed on your system. Get Docker
2. Pull the Docker image:

   docker pull cmidair/actigraphy:main

3. Run the Docker image with your data:

   docker run \
       -p 127.0.0.1:8051:8051 \
       --volume /local/path/to/data:/data \
       cmidair/actigraphy:main

Replace /local/path/to/data with the path to your input data directory (i.e., GGIR's output folder).

How to use ActiSleep Tracker?

All the steps below will consider that you cloned this GitHub repository inside your Documents folder. There is an examplar raw data under paper/data/raw and a processed version using GGIR 3.2-6 under paper/data/ggir_outputs. If you wish to use this data, be aware that it's stored via Git LFS, so you'll have to run the following commands to download it.

git clone https://github.com/childmindresearch/actisleep-tracker.git
cd actisleep-tracker
git lfs install
git lfs pull

After cloning this repository or processing your actigraphy data with GGIR, you should have a folder structure similar to:

├── 📁 ggir_outputs
│ └── 📁 output_sub001
│     ├── 📄 config.csv
│     ├── 📁 meta
│     └── 📁 results
├── 📁 raw
│ └── 📄 sub001.gt3x
└── 📁 scripts
    └── 📄 run_ggir.R

where outputs contains all files generated by GGIR; raw is the raw actigraphy data; and scripts contains all the scripts used in this project.

Run ActiSleep Tracker through Docker by typing:

   DATA_DIR="INSERT_PATH_TO_YOUR_DATA_DIRECTORY"
   docker run \
   -p 127.0.0.1:8051:8051 \
   --volume $DATA_DIR:/data \
   cmidair/actigraphy:main

If you want to try our sample dataset, navigate to the root of the repository and use DATA_DIR=./paper/data/ggir_outputs.

The application will the available at http://localhost:8051.

Select the output you would like to visualize; then, click on Load Files:

Figure 1: ActiSleep Tracker initial screen. To start, select the data you would like to load and click `Load Files`.

Note: the file may take some time to load for the first time.

Once the file is loaded, you will see the following screen:

Figure 2: Main screen. From here, you can change the sleep annotations from your data and add multiple sleep windows.

The top slider is used to select the day to visualize. Next, you have three main questions to answer about that night:

1. Are there multiple sleep periods in these data? - Select this toggle button if you identify more than one sleep window on that day (i.e., multiple sleep windows at night or nap times during the day).
2. Do you need to review this night? - Select this toggle button if that day will need further review.
3. Are >2 hours of data missing between 8PM to 8AM? - Select this toggle button if there is insufficient data for sleep analysis. For the protocol we designed, we were considering sleep periods between 8PM to 8AM, but you can use this toggle and adapt to your own needs.

The graph represents the angle of sensor's z-axis (in blue) and arm movement (in grey). The slider below the graph is used to adjust the main sleep window. To change the window, just slide the slider to the desired onset and/or offset sleep times. In cases where your data has more than one sleep window (multiple sleep windows at night or nap times during the day), you can use the Add Slider button to create a new sleep window. Note that the main sleep episode should always use the slider below the graphs. The code will automatically save all changes you made and will create three files:

1. ggir_outputs/output_sub001/logs/data_cleaning_sub001.csv: a data cleaning file that contains nights that should be omitted from sleep analysis;
2. ggir_outputs/output_sub001/logs/multiple_sleep_sub001.csv: file that documents cases with more than one sleep window per day, facilitating analyses of naps and nocturnal awakenings.
3. ggir_outputs/output_sub001/logs/sleeplog_sub001.csv: initial sleep onset and offset predictions from GGIR.

Figure 3: Day with a nap time during the day. You can add a secondary sleep slider and adjust it as needed.

Developer notes

The Actigraphy app is developed to annotate sleep data, and for this project, we've utilized the Dash framework. It's important to note that Dash apps usually aren't geared towards full-stack applications, but given the project requirements, adopting it was a pragmatic necessity. In this repository, we've implemented a custom Dash architecture to address some typical challenges associated with a full-stack Dash app, particularly through the introduction of a custom callback manager. The organization of the project is structured as follows:

• app.py contains the main Dash app, which is responsible for the layout of the app.
• components/ houses the components utilized by the app. Each component is tasked with its specific layout and logic. Some of the components include file selection, day slider, and graph visualization.
• core/ contains the core tools of the app, including configurations, utilities, command line interface and the callback manager.
• core/callback_manager.py is responsible for registering callbacks for the app. It is also responsible for registering callbacks for the components. This file allows the callbacks to be placed across multiple files by defining a global manager.
• database/ contains the tools for interacting with the database.
• io/ contains the tools for loading and saving data.
• plotting contains the tools for plotting data.

That being said, the callback architecture has grown complex, especially in the graph component where chains of callbacks can cause the app to slow down.

Running the App through uv

Installation via uv is intended for developers; end-users should use the Docker installation described earlier.

1. Ensure you have uv installed.
2. Clone the repository:

   git clone https://github.com/childmindresearch/actisleep-tracker.git
   cd actisleep-tracker

3. Install dependencies:

   uv sync

4. Run the app:

   uv run actigraphy $DATA_DIR