A Python framework for automated behavioral experiments with database integration.

EthoPy provides a flexible, state-based system for designing and running behavioral experiments. Built for neuroscience research, it offers tight integration with database storage, cross-platform support, and modular architecture for easy customization.

Getting Started

Requirements

• Python 3.8 or higher
• Maria DB Database
  • EthoPy requires database setup before running experiments. Follow our step-by-step guide: Getting Started Guide for a complete setup from installation to first experiment

Installation

pip install ethopy

Run Your First Experiment

# Test with simulation mode (no hardware required)
ethopy --task-path grating_test.py --log-console

# The simulation uses keyboard controls:
# ← → arrow keys: activate lick ports 1 & 2
# spacebar: proximity detection

Key Features

• State-based Experiments: Flexible state machine design for complex behavioral paradigms
• Database Integration: Automatic data storage with DataJoint
• Hardware Agnostic: Supports Raspberry Pi, Arduino, PC interfaces, or simulation mode
• Multiple Experiment Types: 2AFC, match-to-sample, passive presentation, calibration
• Rich Stimuli: Visual (gratings, moving bars, dots), olfactory, and custom stimuli
• Cross-platform: Linux, macOS, Windows compatibility

Architecture Overview

Understanding Ethopy's core architecture is essential for both using the system effectively and extending it for your needs. Ethopy is built around five 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.

• Experiment: Defines the state control system with multiple experimental states (PreTrial, Trial, Reward, Punishment, etc.). Each state has four overridable functions that control its behavior and transitions.
• Behavior: Handles animal responses and actions (port selection, licking activity, proximity detection)
• Stimulus: Creates and manages presented stimuli (visual, olfactory, auditory)
• Interface: Hardware communication layer (Raspberry Pi, Arduino, PC interfaces, simulation)
• Logger: Data storage and management using DataJoint for seamless database integration

Ecosystem

Extend EthoPy with additional tools:

• EthoPy Analysis - Data analysis pipelines
• EthoPy Plugins - Community extensions
• EthoPy Control - Web-based remote control

Documentation

Full Documentation

Essential Guides:

• Getting Started - Run your first experiment
• Installation Guide - Complete setup instructions
• Configuration - Database and hardware setup
• Task Creation - How to design your custom experiments
• Troubleshooting - Common issues and solutions

Contributing

We welcome contributions! See our Contributing Guide for:

• Development setup
• Code standards
• Documentation updates

License

MIT License - see LICENSE for details.

Support

• Documentation
• Report Issues