delvendahl / miniml

A deep learning framework for synaptic event detection

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., Friedrich R.W., Müller, M., and Delvendahl, I. (2023) Deep learning-based synaptic event detection. bioRxiv (doi:10.1101/2023.11.02.565316)

🧠 ABOUT

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

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

💻 INSTALLATION

To use miniML, clone the GitHub Repositiory and install the requirements. The Python dependencies are: sklearn, matplotlib, h5py, pandas, numpy, scipy, tensorflow, pyabf. To install all dependencies using pip, run the following command in your Python environment:

pip install -r requirements.txt

miniML can be run on a GPU to speed model inference. Either CUDA or tensorflow-metal are required for GPU use. Installation instructions for these requirements may depend on the specific hardware and OS and can be found online.

Update June 2024: 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.

⏱ RUNNING MINIML

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 Trace object features discrete methods for loading from these file formats (e.g., MiniTrace.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.

Finally, model inference can 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.

Detected events are analyzed and descriptive statistics can subsequently be saved in different formats (.pickle, .h5, .csv).

💡 EXAMPLE

The folder "example_data/" contains an example recording from a cerebellar mossy fiber to granule cell synapse together with a commented Jupyter Notebook (tutorial) illustrating the use of miniML.

📢 UPDATE INFORMATION

With the latest update, we include all the files required to generate and score the data to train a new model and use the model on your data. For the actual training, please refer to the following links to Kaggle:

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

We had to make one change that will impact scripts written for the previous miniML version. We split the direction parameter (used by the miniML detect_events() method) into two separate parameters: event_direction and training_direction (refer to miniML documentation for details). In practice, this means that you may have to rename the parameter direction to event_direction in existing scripts.

Please feel free to contact us in case of questions, either via email, or by opening an issue here on GitHub (chances are that other people have the same question).

✉️ CONTACT

[email protected] or [email protected]