Real-time, synchronized, closed-loop multimodal data acquisition — built for the operating room and the research lab.
Quick Start · How it works · Node Reference · Examples · Paper
Thalamus is an open-source platform for real-time, synchronized, closed-loop multimodal data capture, specifically tailored to meet the stringent demands of neurosurgical environments — while serving equally well in the research lab.
What's new
Highlights from the most recent releases (see CHANGELOG.md for the full history):
- Behavioral tasks — author and run trial-based experiments with the Task Controller: a Qt task runtime, a library of ready paradigms, and a simple async task API.
- Eye calibration — an interactive calibration tool that maps raw eye-camera signal to gaze/screen coordinates (Projective and Angular-Scaling models, point nudging, undo/redo, reward delivery).
- Live state editing — inspect and change a running pipeline's configuration
from the command line with the
registrytool. - Extensible plugins — the plugin API lets native extensions read analog data from other nodes and inject data back in.
- Reproducible recordings — every recording now stores the build type, version, and git commit, and archives the exact task code that ran.
How it works
Thalamus assembles experiments from a pipeline of nodes. Each node is a small, configurable unit that plays one of four roles:
| Role | Does | Examples |
|---|---|---|
| 🟢 Generators | produce data | WAVE, NIDAQ, INTAN, SPIKEGLX, GENICAM |
| 🔵 Consumers | record / output data | STORAGE2, LOG, NIDAQ_OUT, OPHANIM |
| 🟣 Transformers | consume → produce data | OCULOMATIC, ALGEBRA, LUA, NORMALIZE, ARUCO |
| 🟠 Controllers | coordinate the pipeline | RUNNER2, TASK_CONTROLLER |
You build an experiment by adding nodes, configuring them, and subscribing consumers
to the producers they care about. Recorded data is written to a compact .tha
capture file and converted to analysis-friendly formats (HDF5, CSV, Parquet, …) with
the bundled tooling. See the
Node Reference for the full
catalog of node types and the
Concepts guide for the data
model and file format.
Overview
Thalamus facilitates the advancement of clinical applications of Brain-Computer Interface (BCI) technology by integrating behavioral and electrophysiological data streams.
Design requirements Thalamus prioritizes
- Requires minimal setup within an operating room, clinical and research environment and could be easily controlled and quickly modified by the experimenter
- Operated with high reliability with few crashes
- Fail-safe architecture that guarantees minimal data loss in the setting of a crash
- Allows for real-time computation to support visualizations of research and clinical data streams
- Closed-loop control based on research and/or clinical data streams
- Acquires synchronous data from the available research and clinical sensors including relevant behavioral, physiologic, and neural sensors that could easily be scaled over time
- Supports a high-bandwidth, low latency, parallel distributed architecture for modular acquisition and computation that could easily be upgraded as technology continues to advance
- Open-source with source code available to support research use
- Embodies best practice in software engineering using unit tests and validation checks
- Supports advances in translational applications and, hence, also operates in research domains
Installation
Download the wheel for your platform from the
Releases page (or the Actions tab).
The package is published as thalamus_neuro; the importable module remains
thalamus. Builds are provided for Linux (manylinux), Windows (10+), and
macOS (arm64). Thalamus requires Python 3.10+.
We recommend a virtual environment so the bundled grpc version is not disturbed:
python -m venv venv-thalamus
source venv-thalamus/bin/activate # Linux/macOS
call venv-thalamus/scripts/activate # Windows
Then install the wheel for your platform, for example:
# Linux
python -m pip install thalamus_neuro-1.0.16-py3-none-manylinux_2_39_x86_64.whl
# Windows
python -m pip install thalamus_neuro-1.0.16-py3-none-win_amd64.whl
# macOS (arm64)
python -m pip install thalamus_neuro-1.0.16-py3-none-macosx_12_0_arm64.whl
Note — Drivers and runtimes for third-party devices (e.g. GenTL/GenICam cameras, National Instruments DAQs) must be installed separately. Thalamus itself only needs a standard computer with enough RAM for in-memory operation.
Run
python -m thalamus.pipeline # Data pipeline (no task controller)
python -m thalamus.task_controller # Data pipeline and task controller
python -m thalamus.hydrate FILE # Convert a .tha capture file to HDF5
python -m thalamus.dataframe ... # Export a node's data to CSV/Parquet/…
python -m thalamus.record_reader2 FILE # Inspect the contents of a .tha file
Documentation
Full documentation lives at https://cajigaslab.github.io/Thalamus/:
- Quick Start — install, build a pipeline, record, and analyze your first dataset.
- Concepts & Architecture — the node pipeline, data model, capture-file format, and tooling.
- Examples — runnable, copy-paste tutorials (including a hardware-free walkthrough).
- Node Reference — every node type and its configuration.
Runnable example scripts also live in the examples/ folder. For the
figures in our paper, see the SimpleUseCase folder. Release
history is in CHANGELOG.md.
Contributing
Like all open-source projects, Thalamus benefits from your involvement, suggestions, and contributions. Use the Issues tab to report bugs and request features, and see CONTRIBUTING.md for the repository layout, development setup, how to add a new node type, and the pull-request and release process.
License & citation
Thalamus is released under the GPL-3.0 license (see LICENSE). If you use Thalamus in your work, please cite our paper:
Thalamus: a real-time, closed-loop platform for synchronized multimodal data acquisition. Communications Engineering (Nature). https://www.nature.com/articles/s44172-026-00646-z
1 maintainer
Metadata
1 maintainer
Release files for thalamus-neuro 1.0.49
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| thalamus_neuro-1.0.49-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details |
| thalamus_neuro-1.0.49-py3-none-manylinux_2_39_x86_64.whl | Python 3 | none | Linux glibc 2.39+ x86-64 | Details |
| thalamus_neuro-1.0.49-py3-none-macosx_12_0_arm64.whl | Python 3 | none | macOS 12.0+ ARM64 | Details |
Total release size: 112.9 MB
Release files / thalamus_neuro-1.0.49-py3-none-win_amd64.whl
| Download URL | thalamus_neuro-1.0.49-py3-none-win_amd64.whl |
|---|---|
| Size | 43.7 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
437c79d4f7c0007acf3a7d4caf60d9e5e6861b5a46ebc01472d8811e03ed051a
|
|
BLAKE2b-256 checksum How to use checksums |
c2ecb08af58ff3b8cd502f1befc7ca1241cfca5b45cbcd6a49c9e0dbc5006cfe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / thalamus_neuro-1.0.49-py3-none-manylinux_2_39_x86_64.whl
| Download URL | thalamus_neuro-1.0.49-py3-none-manylinux_2_39_x86_64.whl |
|---|---|
| Size | 40.6 MB |
| Tags | Linux glibc 2.39+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
a8ccac61a928f65b247c364a5f0a5720f578749280a8526adee4ccf5440e34e9
|
|
BLAKE2b-256 checksum How to use checksums |
129c7c5a64830bcbe08180508ae50b3fd2378722fc37ac28ab2f80e4a19e7e6b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / thalamus_neuro-1.0.49-py3-none-macosx_12_0_arm64.whl
| Download URL | thalamus_neuro-1.0.49-py3-none-macosx_12_0_arm64.whl |
|---|---|
| Size | 28.7 MB |
| Tags | Python 3 macOS 12.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
7378e25c9abb6979e151194769cccc161596d44db8aebbd6217f62ac5be03150
|
|
BLAKE2b-256 checksum How to use checksums |
7b708182de78d03bec601e65a4a483f71ce8766b03e1aafba29a9e1171d7e964
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
