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 2021-27 (Falkner/Murthy 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

• git (if on Windows, add PATH to USER VARIABLES)
• uv (if on Windows, add PATH to USER VARIABLES)
• das (install in standalone conda environment)
• vocalocator-ssl (install in standalone conda environment)

Installation and updating

Clone the repository and set up virtual environment with uv:

git clone https://github.com/bartulem/usv-playpen.git
cd usv-playpen
uv venv --python=3.13

Linux (terminal) instructions

echo 'alias activate-pni="source /path/.../usv-playpen/.venv/bin/activate"' >> ~/.bashrc
source ~/.bashrc
activate-pni
uv sync

macOS (terminal) instructions

echo 'alias activate-pni="source /path/.../usv-playpen/.venv/bin/activate"' >> ~/.zshrc
source ~/.zshrc
activate-pni
uv sync

Windows (powershell) instructions

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.

Disk usage on quota-limited systems

uv caches wheels and build artifacts under ~/.cache/uv; with the torch/jax/CUDA stack this grows to tens of GB and keeps growing across uv sync runs. On a quota-limited home directory (e.g. the PNI cluster's ~95 GB soft limit) run uv cache clean periodically — it is safe, since it only removes re-downloadable caches (the next uv sync re-fetches). If you also use conda on that machine, conda clean --all reclaims its package cache too.

Usage

Run the GUI with:

activate-pni && usv-playpen

User guide with detailed instructions is available here.