wristpy Documentation

Welcome to wristpy, a Python library designed for processing and analyzing wrist-worn accelerometer data.

This library provides a set of tools for loading sensor information, calibrating raw accelerometer data, calculating various physical activity metrics, finding non-wear periods, and detecting sleep periods (onset and wakeup times). Additionally, we provide access to other sensor data that may be recorded by the watch, including; temperature, luminosity, capacitive sensing, battery voltage, and all metadata.

Quick Start

Note

⚠️ Important Note for macOS Users

wristpy depends on libomp, a system-level dependency that is not always installed by default on macOS. Install it via:

brew install libomp

Installation

Install wristpy from PyPI:

pip install wristpy

Interfaces

wristpy provides three flexible interfaces:

• Command-line tool for direct execution

• Python library importable in scripts or notebooks

• Docker image for containerized deployment

Using the Command-Line Interface

Run a single file:

wristpy /input/file/path.gt3x -o /save/path/file_name.csv -c gradient

Run an entire directory:

wristpy /path/to/files/input_dir -o /path/to/files/output_dir -c gradient -O .csv

See all available command-line arguments:

wristpy --help

Using Python (script or notebook)

Process a single file:

from wristpy.core import orchestrator

results = orchestrator.run(
    input='/path/to/your/file.gt3x',
    output='/path/to/save/file_name.csv',
    calibrator='gradient'
)

For detailed examples and usage patterns, see the Wristpy Tutorial.

Supported Devices & Formats

wristpy currently supports:

Format	Manufacturer	Device	Status
GT3X	Actigraph	wGT3X-BT	✅ Supported
BIN	GENEActiv	GENEActiv	✅ Supported

Processing Pipeline

The wristpy processing pipeline includes:

• Data Loading - Sensor data loaded via actfast

• Data Calibration - Post-manufacturer calibration (None, gradient, ggir options)

• Metrics Calculation - ENMO, MAD, Actigraph counts, MIMS, angle-Z

• Non-wear Detection - Multiple algorithms including CTA and DETACH

• Sleep Detection - HDCZ and HSPT algorithms for sleep onset/wakeup detection

• Physical Activity Levels - Classification into inactive, light, moderate, vigorous categories

For complete details, see the Wristpy Tutorial.

Getting Help

• GitHub Repository: childmindresearch/wristpy

• Issues & Bug Reports: GitHub Issues

• Contributing: See our Development Guide guide

Documentation Contents

User Guide

• Wristpy Tutorial
  • Introduction
  • Example 1: Running the default processor
  • Example 2: Loading data and plotting the raw signals
  • Example 3: Plot the epoch-level measurements
  • Example 4: Visualize the detected non-wear times
  • Example 5: Compute and plot the sleep windows

API Reference

• core
• io
• processing

Development

• Development Guide

Indices and Tables

• Index

• Module Index

• Search Page