miniML: A deep learning framework for synaptic event detection

This repository contains the code described in the following publication:
O'Neill P.S., Baccino-Calace M., Rupprecht P., Lee, S., Hao, Y.A., Lin, M.Z., Friedrich R.W., Müller, M., and Delvendahl, I. (2025) A deep learning framework for automated and generalized synaptic event analysis. eLife 13:RP98485 (doi:10.7554/eLife.98485)

🧠 ABOUT

miniML is a deep-learning-based tool to detect synaptic events in 1d time-series data. It uses a CNN-LSTM network architecture that was trained using a large dataset of synaptic events (miniature excitatory postsynaptic currents) from cerebellar mossy fiber to granule cell synapses.

In this repository, we provide documentation, pre-trained models, and Python code to run model inference on recorded data. In addition, an application example (cerebellar granule cell mEPSC recording) is included.

📢 RELEASES

v.1.1.0 - 04 September 2026

• package installable from PyPI ("miniml-detect")
• major updates to GUI implementation and the code base
• several small bug fixes
• updated documentation
• switch to using pyheka package for .dat file import

v.1.0.0 - 24 July 2026

• Initial release as package

📈 ROADMAP

Next versions of miniML will move to Keras3 and/or pyTorch backends, in order to support newer package and Python versions.

💻 INSTALLATION

To use miniML, either clone the repository and install it locally, or install it directly from PyPI using pip:

pip install miniml-detect[gui]

Local installation:

git clone https://github.com/delvendahl/miniML.git
cd miniML
pip install .[gui]

It is strongly recommended to install miniML into its own virtual environment! miniML requires Python 3.11. The default Python dependencies are: sklearn, matplotlib, h5py, numpy, scipy, tensorflow, pyabf, pyheka, ruptures, pyQT5, qt-material, pyqtgraph.

An executable script miniml-gui will be created to start the application's GUI:

miniml-gui

[!IMPORTANT] The release of TensorFlow 2.16 and Keras 3 introduced breaking changes that raise an error when loading models trained with earlier TensorFlow versions. To avoid this, it is recommended to use TensorFlow 2.14 or 2.15.

Installation without GUI

For the GUI, additional dependencies are required (PyQt5, qt-material, and pyqtgraph). Install miniML without the GUI using pip install . (local) or pip install miniml-detect (PyPI).

📚 DOCUMENTATION

Detailed documentation for miniML can be found here.

⏱ RUNNING MINIML

Analysis workflow in Python

First, a miniML MiniTrace object needs to be created containing 1d timeseries data. Currently, miniML supports direct loading from HEKA .dat files, Axon .abf files as well as HDF .h5 files. The miniml.fileio.TraceLoader object features discrete methods for loading from these file formats (e.g., TraceLoader.from_h5_file()). Data in other file formats need to be imported as Python objects.

Next, a miniML EventDetection object is initiated. Here, one needs to specify a miniML model file to use as well as the Trace object to operate on.

miniML model inference can then be run using the detect_events() method. This method will run miniML over the given data using the specified model. Runtime will depend on data length.

Following event detection, the individual detected events are analyzed and descriptive statistics are calculated for the recording.

miniML includes several plotting methods. They can be found in the Plotter class in plotting.py. A detection object has to be passed as data argument.

Event data and statistics can be saved in different formats (.h5, .csv).

To start the application's GUI, run the following command in a terminal or command prompt:

miniml-gui

💡 EXAMPLE

The folder "example_data/" contains an example recording from a cerebellar mossy fiber to granule cell synapse. To use miniML on this data, run the commented example Jupyter Notebook (tutorial) illustrating the use of miniML.

📦 MODELS

The documentation includes notebooks showing how to train miniML models. You can also use the following links to Kaggle to train mminiML models on the cloud:

1 - Transfer learning
2 - Full training
3 - Training dataset

The repository contains trained models for several event detection scenarios, as outlined in the associated paper. If you have trained a model that could be useful for other researchers, please consider opening a pull request or get in touch with us in order to add it to the repository.

📝 CITATION

If you use miniML in your work, please cite:

@article{ONeill2025,
  article_type = {journal},
  title = {A deep learning framework for automated and generalized synaptic event analysis},
  author = {O'Neill, Philipp S and Baccino-Calace, Martín and Rupprecht, Peter and Lee, Sungmoo and Hao, Yukun A and Lin, Michael Z and Friedrich, Rainer W and Mueller, Martin and Delvendahl, Igor},
  volume = 13,
  year = 2025,
  month = {mar},
  pub_date = {2025-03-05},
  pages = {RP98485},
  citation = {eLife 2025;13:RP98485},
  doi = {10.7554/eLife.98485},
  url = {https://doi.org/10.7554/eLife.98485},
}

🙏 ACKNOWLEDGEMENTS

The development of miniML was funded by the Swiss National Science Foundation, the University of Zurich Research Talent Development Fund, and the German Research Foundation.

The GUI uses Material Icons by Google (https://fonts.google.com/icons).

The template matching implementation was adapted from https://github.com/samuroi/SamuROI

🐛 ISSUES

Please feel free to contact us in case of questions, either via email, or by opening an Issue here on GitHub.

✉️ CONTACT

philipp.oneill@physiologie.uni-freiburg.de or igor.delvendahl@physiologie.uni-freiburg.de