[![Python version](https://img.shields.io/badge/Python-3.13-blue)](https://img.shields.io/badge/Python-3.13-blue)
[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.7926971-blue)](https://doi.org/10.5281/zenodo.7926971)
[![repo size](https://img.shields.io/github/repo-size/bartulem/usv-playpen)](https://github.com/bartulem/usv-playpen/)
[![Documentation Status](https://readthedocs.org/projects//usv-playpen/badge/?version=latest)](https://usv-playpen.readthedocs.io/en/latest/?badge=latest)
[![tests](https://github.com/bartulem/usv-playpen/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bartulem/usv-playpen/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/bartulem/usv-playpen/graph/badge.svg)](https://codecov.io/gh/bartulem/usv-playpen)
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
![shields.io-issues](https://img.shields.io/github/issues/bartulem/usv-playpen)
[![Release](https://img.shields.io/github/v/release/bartulem/usv-playpen)](https://img.shields.io/github/v/release/bartulem/usv-playpen)
[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](https://github.com/bartulem/usv-playpen/blob/main/LICENSE)
[![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)
[![GitHub stars](https://img.shields.io/github/stars/bartulem/usv-playpen?style=social)](https://github.com/bartulem/usv-playpen/)
[![GitHub forks](https://img.shields.io/github/forks/bartulem/usv-playpen?style=social)](https://github.com/bartulem/usv-playpen/)

# usv-playpen

![](https://raw.githubusercontent.com/bartulem/usv-playpen/refs/heads/main/src/usv_playpen/img/usv_playpen_gui.png)

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

- [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/).