Updating README.md

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:
+
+```
+├── 📁 ggir_outputs
+│ └── 📁 output_sub001
+│     ├── 📄 config.csv
+│     ├── 📁 meta
+│     └── 📁 results
+├── 📁 raw
+│ └── 📄 sub001.gt3x
+└── 📁 scripts
+    └── 📄 run_ggir.R
+```
 
-## Preprocessing the data
+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`:
+
+<figure>
+  <img src="paper/man/figures/README-initialscreen.png" alt="Alt text" width="100%"/>
+  <figcaption>Figure 1: ActiSleep Tracker initial screen. To start, select the data you would like to load and click `Load Files`.</figcaption>
+</figure>
+
+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>
+  <img src="paper/man/figures/README-loaddata.png" alt="Alt text" width="100%"/>
+  <figcaption>Figure 2: Main screen. From here, you can change the sleep annotations from your data and add multiple slee windows.</figcaption>
+</figure>
+
+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).
+
+<figure>
+  <img src="paper/man/figures/README-usingmultiplesleepwindows.png" alt="Alt text" width="100%"/>
+  <figcaption>Figure 3: Day with a nap time during the day. You can add a secondary sleep slider and adjust it as needed.</figcaption>
+</figure>
 
-```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}
+   ```