behavython 0.9.0

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 a streamlined setup, we provide a batch script that automates the entire process: creating the Conda environment, installing the required pip dependencies, and configuring the CUDA environment.

How to use the installer:

1. Download the script: Download behavython_installer.bat
   Right-click the link and select "Save Link As..." to download it as a .bat file
   In the windows explorer dowload prompt make sure to select "Save as type: All Files" and not "Text Documents" to avoid saving it as a .txt file
2. Run the Installer: Double-click the downloaded file and follow the on-screen instructions.
3. Detailed Instructions: For a full walkthrough of the automated process, refer to our Installation Guide.

Step-by-Step Installation (Manual)

We strongly recommend using mamba (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.

mamba create -n behavython python=3.10

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

mamba 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

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
mamba 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.

Example: Open Field (arena.json) Use the image as reference to order the points correctly. Here, you can copy this example and save as a .json file to use In order, the points should be created in imageJ in this sequence:

1. top-left
2. top-right
3. bottom-right
4. bottom-left

{
  "experiment_type": "open_field",
  "arena_corners": [
    [126.0, 72.0],
    [637.0, 74.0],
    [633.0, 581.0],
    [128.0, 581.0]
  ]
}

Example: Elevated Plus Maze (arena.json) As with the open field, use the image as reference to order the points correctly. Here, you can copy this example and save as a .json file to use In order, the points should be created in imageJ in this sequence:

1. Center Top Left
2. Top Left
3. Top Right
4. Center Top Right
5. Right Top
6. Right Bottom
7. Center Bottom Right
8. Bottom Right
9. Bottom Left
10. Center Bottom Left
11. Left Bottom
12. Left Top

{
  "experiment_type": "elevated_plus_maze",
  "maze_points": [
    [128, 336],
    [384, 336],
    [384, 32],
    [514, 32],
    [514, 336],
    [900, 336],
    [900, 446],
    [514, 446],
    [514, 1042],
    [384, 1042],
    [384, 446], 
    [128, 446]
  ]
}

Note: Incorrect coordinate ordering will corrupt spatial occupancy metrics.

Coordinate ordering reference for Open Field and Elevated Plus Maze.

ROI Configuration (Interaction Tasks)

For interaction paradigms (like Social Recognition or Object Discrimination), Behavython requires Region of Interest (ROI) definitions exported as CSV files. You can generate these using the ImageJ Oval Tool.

ROI Requirements:

• ImageJ Measurements: Go to Analyze → Set Measurements. You must ensure both Centroid and Bounding Rectangle are checked. The resulting CSV needs the bounding box (BX, BY, Width, Height) and centroid (X, Y) coordinates.
• File Naming Convention: The exported CSV must contain the original video name, followed by an ROI identifier:
  • Single-Object/Target: video_name_roi.csv
  • Two-Choice Tasks: video_name_roiL.csv and video_name_roiR.csv (Left and Right).
• File Format: The file must be a standard .csv (Comma Separated Values) file.

Example: Social Recognition/Discrimination (video_name_roi.csv)

 ,Area,X,Y,BX,BY,Width,Height
1,24065,376.500,387.500,289,300,175,175

---

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