ActiTect & RBDisco: Actigraphy Toolkit and RBD Prediction

This repository hosts ActiTect, a general-purpose Python toolkit for actigraphy analysis(preprocessing, feature extraction, QC, and visualization), and RBDisco, an extension that provides reproducible pipelines and pretrained models for RBD prediction from wrist actigraphy as described here.

Overview
Installation
ActiTect Usage (CLI / API)
RBDisco Usage (CLI / API)
Citation

Overview

ActiTect is a modular, open-source toolkit for standardized analysis of research-grade actigraphy data. It provides a unified command-line and Python interface for loading and preprocessing data from commonly used wearable devices. Core processing steps include resampling, bandpass filtering, auto-calibration, artifact removal, and sleep/non-wear segmentation, enabling harmonized analyses across cohorts and studies. The RBDisco plugin extends ActiTect with pretrained machine-learning models for the detection of REM Sleep Behavior Disorder (RBD) from actigraphy recordings.

<figure> <img src="docs/overview.png" alt="Pipeline overview" style="width:500px;"> <figcaption>Figure 1 – ActiTect/RBDisco overview: full description at https://arxiv.org/abs/2511.05221. </figcaption> </figure>

Installation

You can install the package from source with

conda create -n actitect python=3.9  # use an venv instead if you dont run conda
conda activate actitect
mkdir actitect_experiment
cd actitect_experiment 
git clone git@github.com:db-2010/actitect.git

and then simply run

python actitect/install.py       # for the full package, including RBDisco 
or
python actitect/install.py -c    # only the general purpose actigraphy toolkit

Note: The package might be published to PyPi in the future for a pure pip install.

after this, you should see

... 
2025-10-02 12:34:17 [INFO] Installation successful!

ActiTect Usage

<figure> <img src="docs/demo_fig.png" alt="demo actigraphy plot" style="width:500px;"> <figcaption>Figure 2 – Processed actigraphy data. </figcaption> </figure>

You can use the general purpose actigraphy toolkit either as a CLI tool or directly via a light, pythonic API. The supported actigraphy file formats are

Axivity AX3/AX6: .cwa
GENEActiv: .bin
ActiGraph: .gt3x
Generic: .csv

<details> <summary>Unsupported Devices (Generic CSV)</summary>

If your device is not natively supported, you can still use the tool by exporting to a generic .csv format first. The files must contain a column time that lists the sampling timestamps in ISO8601 (%Y-%m-%dT%H:%M:%S.%f%z) format and columns x, y, z in units of g:

time,x,y,z
2023-07-03 15:00:03.699,0.5947265625,0.15283203125,0.742431640625
2023-07-03 15:00:03.707763,0.59033203125,0.16357421875,0.74609375
2023-07-03 15:00:03.715652,0.6279296875,0.136474609375,0.73046875
...

</details>

ActiTect CLI Usage

If you want to use ActiTect as a CLI tool,you can use

actitect-process [-h] [-r ROOT_DIR] [-c CONFIG_FILE] [-d DATA_DIR] [-m META_FILE] [-o OUT_DIR] [-ns] [-cp] [-rp] [-sf]

to read and process an entire dataset under a given directory. The full processing includes uniform resampling, Butterworth bandpass filtering, auto-calibration, non-wear detection, sleep segmentation and nocturnal movement feature calculation. Please refer to actitect-process --help for all options, an overview of the important ones is given below.

<details> <summary>File organization options </summary> <div id="actitect-file-org"></div>

-d, --data_dir Description: (str) The directory (relative to root_dir or absolute path) that contains the raw actigraphy files. Default: ./data/raw/ Note: Only needed if binary files should be located outside the default directory.
-m, --meta_file Description: (str) The path to the metadata CSV file, relative to root_dir or abs. path. Default: ./data/meta/metadata.csv
-o, --out_dir Description: (str) The directory where processed data and features will be stored. Default: ./data/processed/ (relative to root_dir or abs. path) Note: By default, both the processed data and calculated features are stored, refer to Operational flags below to view file saving options.

</details> <details> <summary>Operational flags </summary> <div id="actitect-operational-flags"></div>

Operational Flags:

-nr, --no_resume Description: Disable default resume behavior. By default, ActiTect skips records that already have info-*.json and the expected feature CSVs on disk. Default: resume enabled (flag not set).
-ns, --no_store Description: When provided, the script saves only the calculated features and not the processed data. Default: False. Note: If flag is not activated, the processed actigraphy data is stored as .parquet file. (~2GB for a 7d recording at 100Hz.)
-cp, --create_plots Description: Whether to create plots of the raw and processed actigraphy data. Default: True.
-sf, --skip_feature_calc Description: If enabled, will skip the calculation of motion features. Default: False. Note: Use this if you're only interested in the processing part.
--allow_incomplete_preprocessing Description: If set, allow to continue downstream logic (feature extraction etc.), if one of the processing steps has failed. Default: False.

</details>

Note: You have full flexibility over the steps and parameters (e.g. bandpass frequencies, skipping steps etc.), by providing a modified preprocessing config file (-c, the default/example file can be found here).

Metadata File and Project Structure

To successfully run the CLI command, you will need a metadata.csv file, linking each raw actigraphy file to your unique identifier, i.e. a patient ID or similar.

<details> <summary>metadata.csv format </summary>

The metadata.csv file should have one row per subject/record and contain at least the columns

filename: the filename of the actigraphy data.
ID: a random identifier for the subject the data is taken from.
record_ID: if you have multiple recordings for the same subject, they are processed independently and you can use record_ID to assign an identifier to each. E.g. 'left' and 'right' if you have recordings from the both arms. If one subject (=ID), has multiple records but no entries in record_ID, they will automatically be named rec1, rec2, ... etc.
diagnosis: a string indicating the cohort group of the subject, e.g. 'RBD' for RBD diagnosed subject and 'HC' for neg.
train/test: should be set to 'test'. (todo: allow to leave empty: implement predict method without eval)
exclude: can be used to exclude certain subject from the analysis by setting it to '1', otherwise empty.

| # | filename | ID | record_ID | diagnosis | train/test | exclude | |-----|--------------------------|----------|-----------|-----------|------------|---------| | 1 | <name1>.<cwa/bin/csv> | <ID-1> | | RBD | test | | | 2 | <name2>.<cwa/bin/csv> | <ID-2> | | RBD | test | 1 | | 3 | <name3a>.<cwa/bin/csv> | <ID-3> | left | HC | test | | | 3 | <name3b>.<cwa/bin/csv> | <ID-3> | right | HC | test | | | ... | ... | ... | ... | ... | ... |

Note: if you are only interested in the preprocessing part of the pipeline, the columns diagnosis and train/test are irrelevant and can be left empty.

</details>

Concerning file organization, you can either specify your desired paths via the command line options or use the default structure shown below.

<details> <summary>Default file organization </summary> <div id="default-file-org"></div>

The actigraphy binaries are listed under ./data/raw/ and the metafile should be stored at ./data/raw/meta/metadata.csv. Processed data will be stored at ./data/processed/ and optionally the RBDisco results under ./results/.

actitect_experiment/ (the main folder of your experiment)  
  ├── actitect (the cloned repo)
  │     ├── README.md 
  │     ├── libs/
  │     ├── ... 
  ├── data/ 
  │     ├── raw/ (put your actigraphy binaries here...)
  │     │    ├── <name1>.<cwa/bin/csv> 
  │     │    ├── <name2>.<cwa/bin/csv>
  │     │    ├── ...
  │     ├── meta/  (...and don't foget the metadata file.)
  │     │    ├── metadata.csv
  │     ├── processed/ (this is where the results of processing will be stored by default)
  │     │    ├── <ID1>/
  │     │    ├── ...
  │    ...  ...
  ├── results/ (this is where results of RBDisco classifier will be stored by default)
 ...

</details>

ActiTect API Usage

For users interested in only specific steps of the toolkit, they are accessible via a pythonic API containing

actitect.api.load(): load data of any supported device into memory.
actitect.api.process(): process the data, including preprocessing and non-wear/sleep detection.
actitect.api.plot(): visualize raw or processed actigraphy data.
actitect.api.compute_per_night_sleep_features(): compute numerical descriptors of sle

Actitect

Install / Use

README

ActiTect & RBDisco: Actigraphy Toolkit and RBD Prediction

Overview

Installation

ActiTect Usage

ActiTect CLI Usage

Metadata File and Project Structure

ActiTect API Usage