behavython 0.8.2

Automated behavioral analysis software and pipeline for neuroscience.

Automated Behavioral Analysis Interface
Currently built to integrate seamlessly with DeepLabCut
Other tools coming soon!

Report Bug · Request Feature

---

Table of Contents

• About
• Getting Started
  • Automated Installation (Windows)
  • Step-by-Step Installation (Manual)
  • GPU Setup (Critical)
• Pretrained Models
• Workflow & Configuration
• Outputs & Metrics
• Contributing
• License
• Contact

---

About

Behavython is an automated, high-throughput behavioral analysis interface. It features a modular architecture that converts raw tracking data (CSV/H5) into structured, biologically relevant behavioral metrics.

It natively supports:

• Geometry-based paradigms: Open Field, Elevated Plus Maze (EPM)
• Interaction-based paradigms: Social Recognition, Social Discrimination, Object Discrimination

The software enforces strict scientific reproducibility through automated environment management, robust data validation, and granular metric exports.

---

Getting Started

Automated Installation (Windows)

For Windows users, we provide a batch script that automates the creation of the Conda environment, installs the correct pip dependencies, and handles the CUDA setup.

Download and run the installer from the repository:

• Open the link and save the page (right-click → Save As) as a .bat file, that is, behavython_installer.bat:
  Download the file from here

• Learn how to use the installer from here:
  Installation Guide

Step-by-Step Installation (Manual)

We strongly recommend using Conda (or Miniconda/Mamba) to manage your isolated Python environment to prevent dependency conflicts.

1. Create the environment: Create a clean environment explicitly using Python 3.10.

conda create -n behavython python=3.10

2. Activate the environment: You must be inside the environment for the next steps.

conda activate behavython

3. Install Behavython: Use pip inside the activated environment. Crucial: You must include the extra index URL to fetch the correct GPU-compiled PyTorch wheels. Omitting this may result in an incompatible CPU-only installation.

pip install behavython --extra-index-url [https://download.pytorch.org/whl/cu118](https://download.pytorch.org/whl/cu118)

GPU Setup (Critical)

⚠️ Required for correct execution

Behavython relies heavily on GPU-accelerated frameworks. You must install the NVIDIA CUDA toolkit and cuDNN AFTER you have completed the pip installation above, and it must be done INSIDE the active behavython environment.

# Ensure you are still inside the 'behavython' environment
conda install -c conda-forge cudatoolkit=11.2 cudnn=8.1.0

Failure to configure the GPU dependencies correctly will result in severe processing slowdowns and potential runtime memory errors during DeepLabCut operations.

---

Pretrained Models

Behavython comes with a pretrained model for roi and mouse tracking (c57 black on white arena top view) These can be downloaded from the GitHub Releases page.

The latest release (models-v1.0) includes:

• c57_network_2025_minified.zip - Optimized for C57 rodent tracking.
• roi_network.zip - Dedicated network for Region of Interest detection in social recognition experiments.

Extract these ZIP archives into .behavython/models/ folder in your home directory located in:

• Windows: C:\Users\<YourUsername>\.behavython\models\
• Linux/Mac: ~/.behavython/models/
• Note: Ensure the extracted model files are directly within the models folder, not nested inside additional subdirectories.

---

Workflow & Configuration

The Pipeline

Video → DeepLabCut → Filtered CSV → Behavython Core Pipeline → Metrics & Parquet

Arena Configuration (Geometry Tasks)

For Open Field and Elevated Plus Maze (EPM) experiments, Behavython requires a .json configuration file defining the spatial geometry. You can extract these coordinates using the ImageJ Point Tool.

• Open Field: Requires exactly 4 ordered corners (Top-Left, Top-Right, Bottom-Right, Bottom-Left).
• Elevated Plus Maze: Requires exactly 12 ordered points defining the outer boundaries, arms, and center zone.

Note: Incorrect coordinate ordering will corrupt spatial occupancy metrics.

ROI Configuration (Interaction Tasks)

For interaction paradigms, utilize the ImageJ Oval Tool to define your regions of interest.

• Analyze → Set Measurements: Ensure Centroid and Bounding Rectangle are checked.
• Name the exported CSV files logically (e.g., video_roiL.csv and video_roiR.csv for two-choice tasks, or video_roi.csv for single-object).

---

Outputs & Metrics

The pipeline outputs data in multiple formats for both statistical aggregation and granular programmatic review.

General Storage

• analysis_summary.xlsx / .csv: Scalar metrics aggregated per animal.
• analysis_timeseries.parquet: Highly compressed, frame-by-frame data utilizing Apache Arrow for efficient downstream data science workflows.
• analysis_log.json: Comprehensive error and warning logs per session.

Task-Specific Metrics

Geometry Experiments (Open Field, EPM):

• Zone occupancy times and percentages.
• Transition counts between zones.
• Discrete spatial_state arrays per frame.

Interaction Experiments (Social/Object):

• Investigation and approach proportions.
• Mean inter-bout intervals (seconds).
• Discrete bout analysis (Collision bouts, approach-only bouts, abortive retreats).
• analysis_collisions.parquet: Granular export containing distance to objects, interaction angles, and frame-by-frame flags.

---

Contributing

Contributions to the codebase and scientific pipelines are welcome.

• Open an issue to report bugs or suggest features.
• Submit a pull request for code changes. Ensure modifications align with the project's modular architecture and strict type-hinting standards.

---

License

This project is distributed under the GNU GPL v3.0 License. See the LICENSE file for more information.

---

Contact

• Matheus Costa — [e-mail]
• João Pedro — [e-mail]

---

Acknowledgments

• Flávio Mourão — https://github.com/fgmourao
• Núcleo de Neurociências (NNC) — http://www.nnc.ufmg.br

Developed at
Núcleo de Neurociências (NNC)
Universidade Federal de Minas Gerais (UFMG)
Brazil