From 336fcdfc53eb0817b9ea07eb53dcd98d796e908d Mon Sep 17 00:00:00 2001 From: nathaliaesper Date: Thu, 29 May 2025 11:40:28 -0400 Subject: [PATCH 1/2] Updating README.md --- README.md | 118 +++++++++++++----- paper/man/README-initialscreen.png | 3 + paper/man/README-loaddata.png | 3 + .../man/README-usingmultiplesleepwindows.png | 3 + 4 files changed, 94 insertions(+), 33 deletions(-) create mode 100644 paper/man/README-initialscreen.png create mode 100644 paper/man/README-loaddata.png create mode 100644 paper/man/README-usingmultiplesleepwindows.png diff --git a/README.md b/README.md index e852d67..4bbed16 100644 --- a/README.md +++ b/README.md @@ -1,62 +1,97 @@ -# App Actigraphy +# ActiSleep Tracker [![Build](https://github.com/childmindresearch/app-actigraphy/actions/workflows/test.yaml/badge.svg?branch=main)](https://github.com/childmindresearch/app-actigraphy/actions/workflows/test.yaml?query=branch%3Amain) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) ![stability-wip](https://img.shields.io/badge/stability-work_in_progress-lightgrey.svg) [![L-GPL License](https://img.shields.io/badge/license-L--GPL-blue.svg)](https://github.com/childmindresearch/app-actigraphy/blob/main/LICENSE) -[![pages](https://img.shields.io/badge/api-docs-blue)](https://childmindresearch.github.io/app-actigraphy) -This webapp is an application designed for annotating sleep data. This repository contains the source code and related files for the application. +ActiSleep Tracker is an application designed to run after processing actigraphy data with the [GGIR package](https://wadpac.github.io/GGIR/) and allows users to annotate sleep data. This repository contains the source code and related files for the application. ## Getting Started -The app may be installed either through Docker (recommended for users) or Poetry (recommended for developers), see the instructions for each below. Whichever method you use to launch the app, the app will be available at http://localhost:8051. +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 the App through Docker +### Running ActiSleep Tracker through Docker -1. Ensure you have Docker installed. -2. Run the Docker image: +1. Install Docker: Ensure you have Docker installed on your system. [Get Docker](https://docs.docker.com/get-started/get-docker/) +2. Pull the Docker image: + ```bash + docker pull cmidair/actigraphy:main + ``` +3. Run the Docker image with your data: ```bash docker run \ -p 127.0.0.1:8051:8051 \ - --volume ${LOCAL_DATA_DIR}:/data \ - --volume `pwd`/assets:/app/assets \ + --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). -### Running the App through Poetry +## How to use ActiSleep Tracker? -1. Ensure you have [Poetry](https://python-poetry.org/docs/) installed. -2. Clone the repository: - ```bash - git clone https://github.com/childmindresearch/app-actigraphy.git - cd app-actigraphy - ``` -3. Install dependencies: - ```bash - poetry install - ``` -4. Run the app: - ```bash - poetry run actigraphy {DATA_DIR} - ``` +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`. + +After cloning this repository or processing your actigraphy data with GGIR, you should have a folder structure similar to: -## Preprocessing the data +``` +├── 📁 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. -To batch preprocess GGIR data for the app, use the `actigraphy_preprocess` entrypoint as follows: +Run ActiSleep Tracker through Docker by typing: ```bash docker run \ - --volume ${LOCAL_DATA_DIR}:/data \ - cmidair/actigraphy:latest \ - actigraphy_preprocess \ + -p 127.0.0.1:8051:8051 \ + --volume /Users/nathalia.esper/Documents/actisleep-tracker/paper/data/ggir_outputs:/data \ + cmidair/actigraphy:main ``` +If you are using your own dataset, replace `/Users/nathalia.esper/Documents/actisleep-tracker/paper/data/ggir_outputs` with the path to the GGIR's outputs. -This may also be done with Poetry through: +The application will the available at http://localhost:8051. + +Select the output you would like to visualize; then, click on `Load Files`: + +
+ Alt text +
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: + +
+ Alt text +
Figure 2: Main screen. From here, you can change the sleep annotations from your data and add multiple slee 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 black). 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](https://wadpac.github.io/GGIR/articles/chapter10_SleepAnalysis.html#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](https://wadpac.github.io/GGIR/articles/chapter10_SleepAnalysis.html). + +
+ Alt text +
Figure 3: Day with a nap time during the day. You can add a secondary sleep slider and adjust it as needed.
+
-```bash - poetry run actigraphy_preprocess {DATA_DIR} -``` ## Developer notes @@ -71,3 +106,20 @@ The Actigraphy app is developed to annotate sleep data, and for this project, we - `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 Poetry + +1. Ensure you have [Poetry](https://python-poetry.org/docs/) installed. +2. Clone the repository: + ```bash + git clone https://github.com/childmindresearch/app-actigraphy.git + cd app-actigraphy + ``` +3. Install dependencies: + ```bash + poetry install + ``` +4. Run the app: + ```bash + poetry run actigraphy {DATA_DIR} + ``` diff --git a/paper/man/README-initialscreen.png b/paper/man/README-initialscreen.png new file mode 100644 index 0000000..67a09cf --- /dev/null +++ b/paper/man/README-initialscreen.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4122048ab8529a25b65ed0cb1a9edd3124bc5c43db7fb0454a3dbab6cfb358d2 +size 67329 diff --git a/paper/man/README-loaddata.png b/paper/man/README-loaddata.png new file mode 100644 index 0000000..810614c --- /dev/null +++ b/paper/man/README-loaddata.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:470fce052b52f335f1039d8a0565b251b44fef46678f768d3584b83007ec7f15 +size 170593 diff --git a/paper/man/README-usingmultiplesleepwindows.png b/paper/man/README-usingmultiplesleepwindows.png new file mode 100644 index 0000000..23b6f12 --- /dev/null +++ b/paper/man/README-usingmultiplesleepwindows.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ad291a4bbe3349abd17388d455e54696bfec5ee769022b1216ff493332219b9d +size 431913 From 7d46bb129cf1217480e8cb12518c891ad484c43a Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 29 May 2025 15:41:51 +0000 Subject: [PATCH 2/2] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4bbed16..d85ad9c 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ Run ActiSleep Tracker through Docker by typing: --volume /Users/nathalia.esper/Documents/actisleep-tracker/paper/data/ggir_outputs:/data \ cmidair/actigraphy:main ``` -If you are using your own dataset, replace `/Users/nathalia.esper/Documents/actisleep-tracker/paper/data/ggir_outputs` with the path to the GGIR's outputs. +If you are using your own dataset, replace `/Users/nathalia.esper/Documents/actisleep-tracker/paper/data/ggir_outputs` with the path to the GGIR's outputs. The application will the available at http://localhost:8051. @@ -78,11 +78,11 @@ Once the file is loaded, you will see the following screen: 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. +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 black). 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](https://wadpac.github.io/GGIR/articles/chapter10_SleepAnalysis.html#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](https://wadpac.github.io/GGIR/articles/chapter10_SleepAnalysis.html).