Skip to content

Getting Started with EthoPy

This guide will walk you through the process of setting up and running your first experiment with EthoPy. After completing this guide, you'll have a solid understanding of how to configure and run basic behavioral experiments.

Prerequisites

Before starting, ensure you have:

  • Python 3.8 or higher (but less than 3.12) installed
  • MariaDB database

Note

We recommend using Docker for setting up a new database.

Step 1: Installation

Setting Up a Virtual Environment

Before installing dependencies, it's recommended to use a virtual environment to keep your project isolated and manageable. Choose one of the following methods:

1
2
conda create --name myenv python=3.x
conda activate myenv
More details

1
2
python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate
More details

1
2
uv venv
source .venv/bin/activate  # On Windows use: .venv\Scripts\activate
More details

Once activated, proceed with installation.

Install EthoPy Package

Choose the installation method that fits your needs:

Install with pip: 

1
pip install ethopy

Install from source: 

1
pip install git+https://github.com/ef-lab/ethopy_package

For contributing or modifying the package: 

1
2
3
git clone https://github.com/ef-lab/ethopy_package.git
cd ethopy_package
pip install -e ".[dev,docs]"

Verify installation:

1
ethopy --version

Step 2: Database Setup

EthoPy relies on a MariaDB database for experiment configuration and data logging. If there is not a database availabe, here is a quick setup of setting mysql database with docker:

  1. Start the database container:

1
ethopy-setup-djdocker
Alteratively follow the instructions from datajoint here

The default username is "root".

Note: if ethopy-setup-djdocker does not work try to setup the docker image based on the datajoint instructions

Note: By default, Docker requires sudo because the Docker daemon runs as root. This command adds your user to the docker group, so you can run Docker commands without sudo.

1
sudo usermod -aG docker $USER

restart your session (log out and back in) or run: 

1
newgrp docker

Step 3: Configure ethopy

Create a configuration file at path:

~/.ethopy/local_conf.json

%USERPROFILE%\.ethopy\local_conf.json

dj_local_conf includes the parameters relevant to the datajoint configuration: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "dj_local_conf": {
        "database.host": "127.0.0.1",
        "database.user": "root",
        "database.password": ...,
        "database.port": 3306
    },
  "SCHEMATA": {
    "experiment": "lab_experiments",
    "stimulus": "lab_stimuli",
    "behavior": "lab_behavior",
    "interface": "lab_interface",
    "recording": "lab_recordings"
  }
}

Check if connection with db is established with your local configuration. 

1
ethopy-db-connection

Step 4: Create required schemas

Create all required database schemas.

1
ethopy-setup-schema

Tip

For verifing the schema/tables creation you can download DBeaver which is a popular and versatile database tool.

Step 5: Run your first experiment

1
ethopy --task-path grating_test.py --log-console
The option --task-path is for defining the path of the task. The example tasks can run by the file name, for any other experiment you must define the full path. Option --log-console is to enable the logging in terminal.

Simulation Interface (setup_conf_idx 0): in this task, EthoPy runs with setup_conf_idx 0, which uses the DummyPorts interface for simulation. This allows you to test tasks on your computer without requiring actual hardware. The interface maps keyboard inputs to behavioral ports: left arrow activates the left port, right arrow activates the right port, and spacebar controls proximity detection (press to indicate animal in position, release for off position). This simulation mode enables fast prototyping and testing of behavioral tasks.

You can check all the options of ethopy by: 

1
ethopy --help

Example Tasks

Explore these sample tasks in the ethopy/task/ directory:

  1. grating_test.py - Grating stimulus presentation
  2. bar_test.py - Moving bar stimulus
  3. dot_test.py - Moving dot patterns

Troubleshooting and Help

If you encounter issues, refer to the Troubleshooting Guide.

For specific questions, check the: - API Reference for detailed module documentation - GitHub Issues for known problems

Where to Go Next

Now that you have a basic understanding of EthoPy:

  1. Creating Custom Components
  2. How to create a Task
  3. Explore the Plugin System to extend functionality
  4. Dive deeper into Local Configuration for advanced settings
  5. Understand setup configuration index
  6. Learn more about Database Setup
  7. Study the API Reference for detailed documentation
  8. Check Contributing if you want to help improve EthoPy