ResXR Python Pipeline

Converts behavioral and sensor recordings from Unity/Meta Quest XR experiments into Motion-BIDS datasets. Each session folder of tracking CSVs and a SessionMetadata.json becomes a standardized dataset with per-system motion files, channel descriptions, JSON sidecars, merged events, and an HTML quality report. It is a Python package (≥3.10) with a resxr command-line tool and a small programmatic API.

This pipeline is the data-processing half of ResXR; the recordings it reads are produced by the resxr-unity-research-template. The two share no code — only the input file format.

📖 Full documentation

https://docs.resxr.org (Python Pipeline section) — installation, configuration, input/output formats, validation, the API, and more. The pages below are the source of truth; this README is only a quick start.

Install

The demo data (DATA/) and the reference output (output/) are stored with Git LFS, about 860 MB together. Install Git LFS and run git lfs install once before you clone: without it, the clone holds small pointer files in place of these files, and the demo run fails.

Clone the repository, then set up an environment with conda or uv.

Conda:

git lfs install                          # once per machine
git clone https://github.com/ResXR/resxr-python-pipeline.git
cd resxr-python-pipeline
conda env create -f environment.yml      # or environment-dev.yml for dev tools
conda activate resxr_env                 # resxr_dev for the dev environment

uv:

git lfs install                          # once per machine
git clone https://github.com/ResXR/resxr-python-pipeline.git
cd resxr-python-pipeline
uv sync --all-extras

With uv, run the commands below through uv run (for example uv run resxr -c config/pipeline_config.yaml), or activate .venv first.

See Installation for details and requirements.

Run

The repository ships demo data under DATA/ and a ready-to-run config, so you can process it immediately:

resxr -c config/pipeline_config.yaml            # run the pipeline
resxr -c config/pipeline_config.yaml --dry-run  # validate config without writing

Equivalent invocations: python -m resxr -c config/pipeline_config.yaml, or from Python:

import resxr
resxr.run(config_path="config/pipeline_config.yaml")

From Python, warnings and errors are printed without any setup; to see the progress lines too, configure logging first, for example logging.basicConfig(level=logging.INFO).

Follow the Quickstart for a full walkthrough.

Documentation map

Topic	Page
Input file format (the data contract)	Input Data Format
Every config option	Configuration
The six processing stages	Pipeline Stages
Quality checks & custom checks	Validation
Output dataset layout	BIDS Output
HTML quality reports	Quality Reports
Command-line options	CLI Reference
Programmatic API	Python API

License

Apache License 2.0 — see LICENSE.

Contributing

Contributions are welcome. Fork the repository, create a feature branch, and open a pull request. See CHANGELOG.md for release history.

Citation

If you use the pipeline in your research, please cite it with its Zenodo DOI, 10.5281/zenodo.23562102. This DOI covers all versions and resolves to the latest release; the v0.2.2 release also has its own DOI, 10.5281/zenodo.23562103.

Bergstein, Y., Barel, N., Shai Basson, G., Bromberg, O., & Schonberg, T. (2026). ResXR Python Pipeline [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.23562102

GitHub's Cite this repository link, in the sidebar of the repository page, exports the metadata in CITATION.cff as APA or BibTeX.