Metadata-Version: 2.4
Name: etho-python
Version: 1.2.4
Summary: etho
Author-email: Jan Clemens <clemensjan@googlemail.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Classifier: License :: OSI Approved :: MIT License
License-File: LICENSE
Requires-Dist: numpy<2; python_version < "3.11"
Requires-Dist: numpy; python_version >= "3.11"
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>=2,<3; python_version < "3.11"
Requires-Dist: zarr>=3,<4; python_version >= "3.11"
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.


## Platform support

`etho` is tested for behavioral acquisition rigs on Windows. The hardware stack
depends on vendor SDKs, which may also work on macOS or Linux but have not been
tested with `etho`. Development, unit tests, and documentation work can be done
on macOS or Linux when hardware SDKs are not required.


## Installation

Quick installation on a Windows rig from PowerShell:

```powershell
conda create -n etho -c conda-forge -y python=3.14 uv pip git
conda activate etho
uv pip install etho-python
etho init
```

`etho` supports Python 3.10 through 3.14. The Python version to use depends on
the hardware SDKs required by the rig. Check the Python versions supported by
the required hardware SDKs before installation. For FLIR/Spinnaker, public
downloads may list Python 3.10, but FLIR support can provide Python 3.14
bindings.

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


## Usage

Etho can be controlled via a GUI on the Windows rig. Launch it from the
activated PowerShell environment with:

```powershell
conda activate etho
etho gui
```

Alternatively, experiments can be run from the terminal:

```powershell
conda activate etho
etho run ".\protocol.yaml" ".\playlist.txt"
```

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


## Citation

A [JOSS paper](paper/paper.md) describing the software is in preparation. For now, if you use `etho` or components of it in your research, please check the **Cite this repository** button in the repository sidebar or cite:

Clemens, J. (2026). `Etho`: A Python framework for coordinating stimuli, data acquisition, and hardware control in neuroscience experiments. doi:10.5281/zenodo.20110619



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

- 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

- 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

- 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

