Skip to content

Ethopy

PyPI Version Python Versions Documentation License: MIT

Ethopy is a state control system for automated, high-throughput behavioral training based on Python. It provides a flexible framework for designing and running behavioral experiments with:

  • Tight integration with database storage & control using Datajoint
  • Cross-platform support (Linux, macOS, Windows)
  • Optimized for Raspberry Pi boards
  • Modular architecture with overridable components
  • Built-in support for various experiment types, stimuli, and behavioral interfaces

Features

  • Modular Design: Comprised of several overridable modules that define the structure of experiments, stimuli, and behavioral control
  • Database Integration: Automatic storage and management of experimental data using Datajoint
  • Multiple Experiment Types: Support for various experiment paradigms (match to sample, 2AFC, open field, etc.)
  • Hardware Integration: Interfaces with multiple hardware setups (raspberry, arduino, desktop computer, screen, camera etc.)
  • Stimulus Control: Various stimulus types supported (Gratings, Movies, Olfactory, 3D Objects)
  • Real-time Control: State-based experiment control with precise timing
  • Extensible: Easy to add new experiment types, stimuli, or behavioral interfaces

System Architecture

The following diagram illustrates the relationship between the core modules:

Installation & Setup

Requirements

  • Python 3.8 or higher
  • Maria DB Database (instructions for database setup)

Basic Installation

1
pip install ethopy

For optional features: 

1
2
3
4
5
6
7
8
# For 3D object support
pip install "ethopy[obj]"

# For development
pip install "ethopy[dev]"

# For documentation
pip install "ethopy[docs]"

Running Experiments

  1. Service Mode: Controlled by the Control table in the database
  2. Direct Mode: Run a specific task directly

Example of running a task: 

1
2
3
4
5
# Run a grating test experiment
ethopy -p grating_test.py

# Run a specific task by ID
ethopy --task-idx 1

Core Architecture

Understanding Ethopy's core architecture is essential for both using the system effectively and extending it for your needs. Ethopy is built around four core modules that work together to provide a flexible and extensible experimental framework. Each module handles a specific aspect of the experiment, from controlling the overall flow to managing stimuli and recording behavior.

1. Experiment Module

The base experiment module defines the state control system. Each experiment is composed of multiple states, with Entry and Exit states being mandatory.

Each state has four overridable functions that control its behavior:

Available Experiment Types

  • MatchPort: Stimulus-port matching experiments
  • Passive: Passive stimulus presentation
  • FreeWater: Water delivery experiments
  • Calibrate: Port calibration for water delivery

Configuration

Experiments require setup configuration through: - SetupConfiguration - SetupConfiguration.Port - SetupConfiguration.Screen

Experiment parameters are defined in Python configuration files and stored in the Task table within the lab_experiment schema.

2. Behavior Module

Handles animal behavior tracking and response processing.

Available Behavior Types

  • MultiPort: Standard setup with lick detection, liquid delivery, and proximity sensing
  • HeadFixed: Passive head fixed setup

    Important: Regular liquid calibration is essential for accurate reward delivery. We recommend calibrating at least once per week to ensure consistent reward volumes and reliable experimental results.

3. Stimulus Module

Controls stimulus presentation and management.

Available Stimulus Types

  • Visual
  • Grating: Orientation gratings
  • Bar: Moving bars for retinotopic mapping
  • Dot: Moving dots

Logger Module (Non-overridable)

Manages all database interactions across modules. Data is stored in three schemas:

lab_experiments:

lab_behavior:

lab_stimuli:

Interface Module (Non-overridable)

Manages hardware communication and control.

Development & Contributing

Development Setup

  1. Clone the repository: 

    1
2
    git clone https://github.com/ef-lab/ethopy_package/  # Main repository
cd ethopy

  2. Install development dependencies: 

    1
    pip install -e ".[dev,docs]"

Code Quality

The project uses several tools to maintain code quality:

  • ruff: Code formatting and linting
  • isort: Import sorting
  • pytest: Testing and test coverage

Run tests: 

1
pytest tests/

Documentation

Documentation is built using MkDocs. Install documentation dependencies and serve locally:

1
2
pip install ".[docs]"
mkdocs serve

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For questions and support: