Metadata-Version: 2.1
Name: DSM-tools
Version: 1.0.0
Summary: 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.
Author: Feng Xiong
Author-email: Zuo-Han Zhao <zzhmark@126.com>
License: MIT License
        
        Copyright (c) 2022 xiongfeng, Zuo-Han Zhao
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Exhibition & online tools, http://101.43.104.173:8501
Project-URL: Experiment code, https://github.com/xiongfengNJ/neuron2seq
Project-URL: Data server, http://101.43.104.173:8500/
Project-URL: Package source, https://github.com/xiongfengNJ/DSM-tools
Keywords: neuron,morphology,HAN,autoencoder
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tensorflow
Requires-Dist: pandas
Requires-Dist: importlib-resources
Requires-Dist: gensim
Requires-Dist: SimpleITK
Requires-Dist: matplotlib

# 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 in 2020, SEU-ALLEN, Nanjing. 
The package was developed by Zuo-Han Zhao.

## Installation

### Depedencies
* Python (>=3.9)
* tensorflow (>=2.5.0)
* scikit-learn
* SimpleITK
* gensim (>=4.2.0)
* matplotlib
* pandas
* importlib_resources

### Install by PyPI
```shell
pip install DSM-tools
```

### Install by GitHub
```shell
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

```python
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_sequences_parallel()

# save the result (OrderedDict) as pickle
ds.pickle_sequences('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


```python
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

```python
from dsmtools.modeling import DSMAutoencoder

ae_x = converter.convert_for_ae()

# build model
ae = DSMAutoencoder(result_dir='output')
ae.compile(input_dim=6, seq_max_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](https://github.com/xiongfengNJ/DSM-tools/examples) directory for details.
### Fine tune the data processing

You can inherit classes like [`NeuronSequenceDataset`](https://github.com/xiongfengNJ/DSM-tools/src/dsmtools/preprocessing/sequencing.py)
to change the data processing behaviours, which should be quite easy.
The tree manipulating class [`NeuronTree`](https://github.com/xiongfengNJ/DSM-tools/src/dsmtools/preprocessing/neuron_tree.py)
offers you the freedom of Exploring your own definition of subtree nodes to generate traversal sequences.


## Documentation

Comming soon..

## 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] ](https://www.researchsquare.com/article/rs-1627621/v1)
