https://github.com/bartulem/usv-playpen
GUI/CLI to control experiments w/ multichannel audio, neural and video recordings, conduct data processing, analyses and make visualizations.
https://github.com/bartulem/usv-playpen
behavior neuroscience vocalizations
Last synced: 6 days ago
JSON representation
GUI/CLI to control experiments w/ multichannel audio, neural and video recordings, conduct data processing, analyses and make visualizations.
- Host: GitHub
- URL: https://github.com/bartulem/usv-playpen
- Owner: bartulem
- License: gpl-3.0
- Created: 2022-11-16T01:41:05.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-04-10T23:16:46.000Z (16 days ago)
- Last Synced: 2026-04-11T04:29:51.782Z (16 days ago)
- Topics: behavior, neuroscience, vocalizations
- Language: Python
- Homepage: https://usv-playpen.readthedocs.io/en/latest/
- Size: 86.3 MB
- Stars: 4
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://img.shields.io/badge/Python-3.13-blue)
[](https://zenodo.org/badge/latestdoi/566588932)
[](https://github.com/bartulem/usv-playpen/)
[](https://usv-playpen.readthedocs.io/en/latest/?badge=latest)
[](https://www.repostatus.org/#active)
[](https://img.shields.io/github/v/release/bartulem/usv-playpen)
[](https://github.com/bartulem/usv-playpen/blob/main/LICENSE)
[](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)
[](https://github.com/bartulem/usv-playpen/)
[](https://github.com/bartulem/usv-playpen/)
# usv-playpen
GUI/CLI to facilitate conducting experiments with multi-probe e-phys
(Neuropixels), multichannel audio (Avisoft) and multi-camera video (Loopbio)
acquisition. Developed for behavioral recording purposes at the
[Princeton Neuroscience Institute](https://pni.princeton.edu/) 2021-26
([Falkner](https://www.falknerlab.com/)/[Murthy](https://murthylab.princeton.edu/)
labs). Due to necessary proprietary software, recordings can only be performed
on OS Windows. The data processing, analysis and visualization branches of the
GUI are platform-independent.
## Prerequisites
- [CoolTerm](https://coolterm.en.lo4d.com/windows) (necessary only on the audio
recording PC)
- [git](https://git-scm.com/download/) (if on Windows, add PATH to USER
VARIABLES)
- [uv](https://docs.astral.sh/uv/getting-started/installation/) (if on Windows,
add PATH to USER VARIABLES)
- [das](https://janclemenslab.org/das/) (install in standalone conda
environment)
- [vocalocator-ssl](https://github.com/Aramist/vocalocator-ssl) (install in
standalone conda environment)
## Installation and updating
Clone the repository and set up virtual environment with _uv_:
```bash
git clone https://github.com/bartulem/usv-playpen.git
cd usv-playpen
uv venv --python=3.13
```
### Linux (terminal) instructions
```bash
echo 'alias activate-pni="source /path/.../usv-playpen/.venv/bin/activate"' >> ~/.bashrc
source ~/.bashrc
activate-pni
uv sync
```
### macOS (terminal) instructions
```bash
echo 'alias activate-pni="source /path/.../usv-playpen/.venv/bin/activate"' >> ~/.zshrc
source ~/.zshrc
activate-pni
uv sync
```
### Windows (powershell) instructions
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
Add-Content -Path $PROFILE -Value "`nfunction activate-pni {`n . 'C:\path\...\usv-playpen\.venv\Scripts\Activate.ps1'`n}"
. $PROFILE
activate-pni
uv sync
```
### Updating to a specific version
Navigate to the cloned repository. To see which version you currently have:
```
git describe --tags
```
To see all available versions:
```
git fetch --tags
git tag --sort=-version:refname
```
To update to a specific version (works identically on Linux, macOS, and
Windows):
```
git fetch --tags
git checkout v0.9.5
uv sync --reinstall-package usv-playpen
```
Or, if you have a GPU:
```
git fetch --tags
git checkout v0.9.5
uv sync --reinstall-package usv-playpen --extra gpu
```
Replace `v0.9.5` with whichever version you want. The
`--reinstall-package usv-playpen` flag is required to force uv to recompute the
package version from the new git tag; without it the GUI may display a stale
version number. All machines should be set to the same tag to guarantee
identical behaviour.
## Usage
Run the GUI with:
```bash
activate-pni && usv-playpen
```
User guide with detailed instructions is available
[here](https://usv-playpen.readthedocs.io/en/latest/).