respyra logo

respyra

A general-purpose respiratory tracking toolbox for interoception research

PyPI License: MIT Python 3.10 GitHub

respyra is a Python toolbox that integrates a Vernier Go Direct Respiration Belt with PsychoPy to enable real-time respiratory tracking experiments. Participants follow a sinusoidal target with their breathing while receiving continuous visual biofeedback. The toolbox supports configurable experimental conditions including multi-frequency target waveforms and visuomotor perturbations (visual gain manipulation), in which the displayed breathing trace is amplified or attenuated relative to ground truth.

Task schematic

Key features

  • Real-time respiratory tracking — live breathing waveform with sinusoidal target dot

  • Visuomotor perturbation — configurable feedback gain to amplify or attenuate the visual trace

  • Composable conditions — define multi-frequency, multi-segment waveforms from simple building blocks

  • Three feedback modes — graded (continuous color), binary, or trinary error feedback

  • Automated calibration — range calibration with percentile-based outlier rejection and saturation detection

  • Crash-resilient logging — incremental CSV with per-row flush

  • Post-session visualization — 6-panel summary figure for quick data quality checks

  • Non-blocking belt I/O — background thread + queue architecture keeps PsychoPy’s frame loop smooth

For the full scientific background and validation data, see the accompanying preprint.

Getting started

Install from PyPI:

pip install respyra

Then run a no-hardware demo:

python -m respyra.demos.demo_display

Or with a belt connected:

respyra-task

Documentation

Installation

Python 3.10 setup, PyPI install, platform notes

Installation
Quick Start

Run demos and your first experiment in minutes

Quick Start
User Guide

Session flow, configuration, conditions, data output

User Guide
Creating Experiments

Custom configs, condition presets, counterbalancing, and advanced flows

Creating Experiments
API Reference

Auto-generated docs from source code docstrings

API Reference
Examples

Annotated walkthroughs of demos and experiment scripts

Examples
Visualization

Summary figures, panel walkthrough, programmatic use

Visualization
Troubleshooting

BLE issues, sensor saturation, frame drops, and more

Troubleshooting
Adapting the Belt

Swap in a different respiratory sensor

Adapting to a Different Respiratory Sensor
Contributing

Development setup, testing, linting, and pull requests

Contributing to respyra

Citation

If you use respyra in your research, please cite the preprint:

Allen, M. (2026). respyra: A General-Purpose Respiratory Tracking Toolbox for Interoception Research. PsyArXiv. https://osf.io/preprints/psyarxiv/wjuce_v1