Metadata-Version: 2.4
Name: etho-python
Version: 1.0
Summary: etho
Author-email: Jan Clemens <clemensjan@googlemail.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Classifier: License :: OSI Approved :: MIT License
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: h5py
Requires-Dist: opencv-python-headless
Requires-Dist: bleak
Requires-Dist: pandas
Requires-Dist: pyzmq
Requires-Dist: gevent
Requires-Dist: future
Requires-Dist: pillow
Requires-Dist: msgpack-python
Requires-Dist: pyyaml
Requires-Dist: ipython
Requires-Dist: defopt
Requires-Dist: msgpack-numpy
Requires-Dist: rich
Requires-Dist: psutil
Requires-Dist: tables
Requires-Dist: pydaqmx
Requires-Dist: pyqtgraph
Requires-Dist: qtpy
Requires-Dist: PySide6-Essentials
Requires-Dist: zarr
Requires-Dist: zerorpc-numpy
Requires-Dist: pytest ; extra == "dev"
Requires-Dist: flit>=3.2,<4 ; extra == "dev"
Requires-Dist: sphinx ; extra == "doc"
Requires-Dist: furo ; extra == "doc"
Requires-Dist: shibuya ; extra == "doc"
Requires-Dist: sphinx-copybutton ; extra == "doc"
Requires-Dist: ghp-import ; extra == "doc"
Requires-Dist: myst-nb ; extra == "doc"
Requires-Dist: sphinx-panels ; extra == "doc"
Requires-Dist: sphinxcontrib-images ; extra == "doc"
Requires-Dist: sphinx-tabs ; extra == "doc"
Requires-Dist: sphinx-iconify ; extra == "doc"
Requires-Dist: sphinx-design ; extra == "doc"
Project-URL: documentation, https://janclemenslab.org/etho/
Project-URL: source, https://github.com/janclemenslab/etho
Provides-Extra: dev
Provides-Extra: doc

# `etho`: A Python framework for coordinating stimuli, data acquisition, and hardware control in neuroscience experiments

[![Test](https://github.com/janclemenslab/etho/actions/workflows/python-package.yml/badge.svg)](https://github.com/janclemenslab/etho/actions/workflows/python-package.yml)
[![Documentation](https://img.shields.io/badge/docs-online-blue)](https://janclemenslab.org/etho)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![DOI](https://zenodo.org/badge/120959515.svg)](https://doi.org/10.5281/zenodo.20110619)

`etho` is an open-source Python framework for running behavioral neuroscience experiments that require coordinated stimulus presentation, hardware control, data acquisition, and experiment logging.

It was developed for neuroscience experiments, where multiple hardware devices must operate together with reproducible timing. `etho` coordinates cameras, National Instruments DAQ hardware, acoustic and optogenetic stimulation, environmental sensors, and external imaging systems through a modular service-based architecture.

The software is designed to make experiments reproducible, configurable, and maintainable by separating:
- experiment logic and hardware (`protocol.yaml`)
- stimulus definitions (`playlist.txt`)
- acquisition callbacks and logs

from the underlying device code.

See the [documentation](https://janclemenslab.org/etho) for details.


## Installation

Quick installation:

```bash
uv venv --python 3.14
.venv\Scripts\activate
uv pip install etho-python
```

Some hardware backends require additional vendor SDKs and drivers and specific python versions.
See the full [installation guide](https://janclemenslab.org/etho/install.html).


## Usage

Etho can be controlled via a GUI. Launch it with:

```bash
etho gui
```

Alternatively, experiments can be run from the terminal:

```bash
etho run protocol.yaml
```

Data generated by etho can be inspected, annotated, and analyzed with [xarray-behave](https://github.com/janclemenslab/xarray-behave).


## Citation

If you use `etho`earch, please cite:

```bibtex
TODO
```

A [JOSS paper](paper/paper.md) describing the software is in preparation.

The `etho` software has been used in the following publications:

- Vijendravarma, R. K., Narasimha, S., Steinfath, E., Clemens, J., & Leopold, P. (2022). *Drosophila* females have an acoustic preference for symmetric males. Proceedings of the National Academy of Sciences, 119(13), e2116136119. https://doi.org/10.1073/pnas.2116136119

- Steinfath, E., Khalili, A., Stenger, M., Schultze, B. L., Nair, S. R., Alizadeh, K., & Clemens, J. (2025). A neural circuit for context-dependent multimodal signaling in *Drosophila*. Nature Communications, 16, 9472. https://doi.org/10.1038/s41467-025-64907-9

- Palacios-Muñoz, A., & Clemens, J. (2025). *Drosophila* males integrate song and pheromones using context-specific strategies. bioRxiv. https://doi.org/10.1101/2025.07.25.666755

- Ravindran Nair, S., Palacios-Muñoz, A., Martineau, S., Nasr, M., & Clemens, J. (2026). Sex-specific behavioral feedback modulates sensorimotor processing and drives flexible social behavior. Nature Communications, 17, 4026. https://doi.org/10.1038/s41467-026-72057-9
