DSM-tools 1.1.0

A python package for DSM utilities, which make seuences out of neuron SWC and use deep learning models to encode neurons and predict their types.

DSM-tools

DSM-tools is a Python module that converts neuron morphology into sequences by binary tree traversals and implements deep learning models for encoding the sequences and predicting cell types.

This project was started by Feng Xiong (xiongfengNJ) in 2020, SEU-ALLEN, Nanjing.

The Python package was authorised to be developed by Zuo-Han Zhao (zzhmark) in 2022.

Installation

Depedencies

• Python (>=3.9)
• tensorflow (>=2.10.0)
• scikit-learn (>=1.1.3)
• SimpleITK (2.2.0)
• gensim (>=4.2.0)
• matplotlib (>=3.6.2)
• pandas (>=1.5.1)
• importlib_resources (>=5.10.0)

Install by PyPI

pip install DSM-tools

Install by GitHub

pip install git+https://github.com/xiongfengNJ/DSM-tools

User Guide

Here's some simple usage that get you a quick start.

Transform SWC files to sequence dataframes

from dsmtools.preprocessing import NeuronSequenceDataset

# dataset generation tool, with computation settings
ds = NeuronSequenceDataset(swc_file_paths, jobs=10)

# processing
ds.read_parallel()
ds.qc_parallel(qc_len_thr=10)
ds.make_sequence_parallel()

# save the result (OrderedDict) as pickle
ds.pickle_result('output.pickle')

By default, it gives you a set of features for each neuron by the order of preorder traversals.

Predict cell types with HAN model

from dsmtools.modeling import DSMDataConverter, DSMHierarchicalAttentionNetwork

# further convert the dataframes to dataset fed to tensorflow
converter = DSMDataConverter(ds)
han_x = converter.convert_for_han()

# models trained with our data ready for use
han = DSMHierarchicalAttentionNetwork.load_1282_seu()
le = DSMHierarchicalAttentionNetwork.label_encoder_1282_seu()

# decode the one-hot matrix back to labels
le.inverse_transform(np.argmax(han.predict(han_x), axis=1))

The prediction for autoencoder is similar.

Train an autoencoder

from dsmtools.modeling import DSMAutoencoder

ae_x = converter.convert_for_ae()

# build model
ae = DSMAutoencoder(result_dir='output')
ae.compile(feature_dim=6, seq_len=2000)

# training
ae.fit(train_x, test_x, model_save_path='ae_checkpoint.h5', epochs=300, batch_size=32)

ae.plot_learning_curve('ae_learning.png')

The training for HAN is similar.

Please see the examples directory for details.

Fine tune the data processing

You can inherit classes like NeuronSequenceDataset to change the data processing behaviours, which should be quite easy. The tree manipulating class NeuronTree offers you the freedom of exploring your own definition of subtree nodes to generate traversal sequences.

Contact & Support

Documentation

DSM-tools API Documentation: https://xiongfengnj.github.io/DSM-tools
powered by pdoc, served in GitHub Pages.

GitHub projects

Package source: https://github.com/xiongfengNJ/DSM-tools

Experiment code: https://github.com/xiongfengNJ/neuron2seq

Experiment data: http://101.43.104.173:8500

Online service: http://101.43.104.173:8501

Team

SEU-ALLEN Joint Center,
Institute for Brain and Intelligence,
Southeast University

Lab homepage: https://braintell.org

Citation

Our paper is still under review, please check the link for preprint. For now, you can cite it as:

Hanchuan Peng, Feng Xiong, Peng Xie et al. DSM: Deep Sequential Model for Complete Neuronal Morphology Representation and Feature Extraction, 29 June 2022, PREPRINT (Version 1) available at Research Square [https://doi.org/10.21203/rs.3.rs-1627621/v1]