bluebrain/tmd

A python package for the topological analysis of neurons.

TMD

A python package for the topological analysis of neurons.

The TMD performs the topological analysis of neuronal morphologies and extracts the persistence barcodes of trees.

This Python module includes:

• Basic loading of neuronal morphologies in swc and h5 file format.
• Extraction of the topological descriptors of tree morphologies.
• Visualization of neuronal trees and neurons.
• Plotting persistence diagrams, barcodes and images.

Installation

This package should be installed using pip:

pip install TMD

For installation of optional viewers:

pip install TMD[viewer]

Usage

# Import the TMD toolkit in IPython
import tmd

# Load a neuron
neuron = tmd.io.load_neuron('input_path_to_file/input_file.swc')

# Extract the tmd of a neurite, i.e., neuronal tree
pd = tmd.methods.get_persistence_diagram(neuron.neurites[0])

Citation

If you use this software or method for your research, we kindly ask you to cite the following publication associated to this repository:

A Topological Representation of Branching Neuronal Morphologies

Cite this article as:

Kanari, L., Dłotko P., Scolamiero M., et al., A Topological Representation of Branching Neuronal Morphologies, Neuroinformatics 16, nᵒ 1 (2018): 3‑13. https://doi.org/10.1007/s12021-017-9341-1.

Related publications

Comprehensive Morpho-Electrotonic Analysis Shows 2 Distinct Classes of L2 and L3 Pyramidal Neurons in Human Temporal Cortex, Cerebral Cortex

Cite this article as:

Deitcher Y., Eyal G., Kanari L., et al., Comprehensive Morpho-Electrotonic Analysis Shows 2 Distinct Classes of L2 and L3 Pyramidal Neurons in Human Temporal Cortex, Cerebral Cortex, Volume 27, Issue 11, November 2017, Pages 5398–5414, https://doi.org/10.1093/cercor/bhx226

Objective Morphological Classification of Neocortical Pyramidal Cells:

Cite this article as:

Lida Kanari, Srikanth Ramaswamy, Ying Shi, Sebastien Morand, Julie Meystre, Rodrigo Perin, Marwan Abdellah, Yun Wang, Kathryn Hess, Henry Markram, Objective Morphological Classification of Neocortical Pyramidal Cells, Cerebral Cortex, Volume 29, Issue 4, April 2019, Pages 1719-1735, https://doi.org/10.1093/cercor/bhy339

Developed in Blue Brain Project.

Funding & Acknowledgment

The development of this software was supported by funding to the Blue Brain Project, a research center of the École polytechnique fédérale de Lausanne (EPFL), from the Swiss government’s ETH Board of the Swiss Federal Institutes of Technology.

For license and authors, see LICENSE.txt and AUTHORS.md respectively.

Copyright © 2021-2022 Blue Brain Project/EPFL

tmd's Issues

Simplify kwargs in plotting

Proposal by @adrien-berchet to simplify the kwargs in all plots:

params = {
    "title": "Tree structure",
    "xlabel": plane[0],
    # All other default values...
}
params.update(kwargs)

Make xlim and xlims consistent in plotting functions

As shown in #39 , some functions take a xlim argument while others take xlims, which inconsistent and error-prone.

Use MorphIO as IO layer

Node labeling affects persistence diagram outcome

Hey there,

I've been working on morphology package in Python3 which features your computation of persistence diagrams. While I was trying to match your results with mine I realized that there is a "bug" in your code.
I created a simple test swc file test_neuron.swc which looks like this

Then I switch nodes 3 and 10, to get a tree that looks the same but has slightly different node labeling:

Now, when I compute the persistence diagram (i.e. using the projection) I get different outputs for both trees (first: version1, second: version2):

Note the different death-time for the 3rd entry (index 2).

Looking into your code I saw that you make implicit assumptions about the order of nodes and their labels. From my own experience that can create weird bugs if the data does not adhere to these standards (as the one above). Maybe you could rewrite your load_neuron function to enforce the node labeling that the rest of your code needs? Another idea would be to make the assumptions on the input data explicit somewhere, so any user is aware of these.

The two swc files I used are:

#test_neuron.swc
1 1 0.0 0.0 0.0 0.5 -1
2 3 0.0 1.0 0.0 0.5 1
3 3 0.0 2.0 0.0 0.5 2
4 3 0.0 3.0 0.0 0.5 3
5 3 0.0 4.0 0.0 0.5 4
6 3 0.0 3.2 0.5 0.5 4
7 3 0.0 2.5 0.5 0.5 3
8 3 0.0 1.5 1.0 0.5 2
9 3 0.0 2.5 1.3 0.5 8
10 3 0.0 1.5 2.0 0.5 8

and

#test_neuron_v2.swc
1 1 0.0 0.0 0.0 0.5 -1
2 3 0.0 1.0 0.0 0.5 1
3 3 0.0 1.5 2.0 0.5 8
4 3 0.0 3.0 0.0 0.5 10
5 3 0.0 4.0 0.0 0.5 4
6 3 0.0 3.2 0.5 0.5 4
7 3 0.0 2.5 0.5 0.5 10
8 3 0.0 1.5 1.0 0.5 2
9 3 0.0 2.5 1.3 0.5 8
10 3 0.0 2.0 0.0 0.5 2

The code for computing the diagrams was

import tmd

files = ['test_neuron.swc', 'test_neuron_v2.swc']
# define filter functions
features = ['radial_distances', 'path_distances', 'projection', 'section_branch_orders']

for file in files:
    n = tmd.io.load_neuron("." + file)

    for f in features:
        ph = tmd.methods.get_ph_neuron(n, feature=f)
        tmd.methods.write_ph(ph, ".%s_%s.txt"% (file.split(".")[0], f))

Unable to load morphologies downloaded BBP EPFL project.

I was trying to use cell morphologies from https://bbp.epfl.ch/nmc-portal/downloads but these morphologies are provided in .asc and arent accepted by TMD. After converting it using NLMorphologyConverter I am yet unable to read the output .swc file. Is there a reader (like NeuroM) for .asc files in TMD?

Setting xlim on plot.persistence_image

Hello, I'm trying to set the xlim on "tmd.view.common.save_plot(plot.persistence_image(ph_axon, xlim=[0,900])," but it doesn't work. The "tmd.view.common.save_plot(plot.diagram(ph_axon, xlim=[0,900])" is working. So I was wondering, do I oversee something?

thanks for help,
best regards

ERROR: Package 'tmd' requires a different Python: 2.7.12 not in '>=3.6'

Tests not runnign properly with tox

When using TMD is the module case sensitive to swc, asc and h5 file types?

I downloaded a dataset from ebrains because the previous dataset I used had incomplete data. When running my personal tutorial for neurots I ran into an AssertionError.

The source code:

import json
from pathlib import Path

import neurots
from neurots import extract_input


def run(distr_dir, params_dir, neuron_dir, data_dir):
    for i in range(0,50,1):
        """Run the example for extracting inputs for synthesis."""
        # Generate distribution from directory of neurons

        distr_name = "test_distr_{}.json".format(i)
        params_name = "test_params_{}.json".format(i)
        neuron_name = "test_neuron_{}.swc".format(i)

        distr = extract_input.distributions(
            data_dir / "neurons",
            feature="path_distances", 
            diameter_model="default",
        )

        

if __name__ == "__main__":
    data_dir = Path("C:\\Users\\user\\Documents\\Experiment_01\\Data\\Human\\Neocortex_interneurons")
    params_dir = Path("C:\\Users\\user\\Documents\\Experiment_01\\Parameters\\Neocortex_interneuron")
    distr_dir = Path("C:\\Users\\user\\Documents\\Experiment_01\\Distributions\\Neocortex_interneuron")
    neuron_dir = Path("C:\\Users\\user\\Documents\\Experiment_01\\Synthesized\\Neurons\\Neocortex_interneuron")
    
    #result_dir.mkdir(parents=True, exist_ok=True)

    run(distr_dir, params_dir, neuron_dir, data_dir)
    print("DONE!!!")

The warning: "C:\Users\user\Documents\Experiment_01\Data\Human\Neocortex_interneurons\neurons\hbp-00938_morph-ChIN-STR_sbj1-160504_cell3_original__CIN_160504_slice2_Cell3ChaTcre_TdTomato_jofn_20170109.ASC is not a valid h5, swc or asc file. If asc set use_morphio to True.

I removed the files from their respective subfolders and all of the morphologies in a single folder. The folder contains both swc files and asc files but all of the swc files are in lowercase.

Dataset:
interneurons_swc.zip

Edit: Error occurs in line 214 in io.py after the extension was assert in line 207.

KeyError for a neuron while computing persistence diagram

When calling get_persistence_diagram on my neuron ( swc file attached) that looks like this:

I get the following error:

In [18]: perd = tmd.methods.get_persistence_diagram(neuron.neurites[0])
---------------------------------------------------------------------------
KeyError                                  Traceback (most recent call last)
Input In [18], in <cell line: 1>()
----> 1 perd = tmd.methods.get_persistence_diagram(neuron.neurites[0])

File ~/anaconda3/envs/testnavis/lib/python3.9/site-packages/tmd/Topology/methods.py:102, in get_persistence_diagram(tree, feature, **kwargs)
    100 def get_persistence_diagram(tree, feature='radial_distances', **kwargs):
    101     '''Method to extract ph from tree that contains mutlifurcations'''
--> 102     ph, _ = tree_to_property_barcode(
    103         tree,
    104         filtration_function=_filtration_function(feature, **kwargs),
    105         property_class=NoProperty
    106     )
    107     return ph

File ~/anaconda3/envs/testnavis/lib/python3.9/site-packages/tmd/Topology/methods.py:62, in tree_to_property_barcode(tree, filtration_function, property_class)
     59 while len(alives) > 1:
     60     for alive in alives:
---> 62         p = parents[alive]
     63         c = children[p]
     65         if np.alltrue(active[c]):
KeyError: 15

In fact this is a neuron exported from the navis library.

> import navis
> n = navis.example_neurons(1)
> navis.write_swc(n,'nrn.swc')

nrn.swc.zip

Persistence diagram failed/empty list for some neurons

Hi:

I'm using this TMD method for SWC file classification for basal dendrites, it yields pretty good results. But for some SWCs, when using get_ph_neuron(), some neurons failed with an error "key error", and some neurons have nothing in the persistence diagram list. Could you please shed some light on what's causing the issue?

Thanks!

How to resolve SomaError

I tried extracting input distributions from the files I have and received a SomaError: A soma is already defined. I was wondering how this error could be resolved. I have other files (.swc) in the same folder but only the .asc files give me this issue.

The source code:

import json
from pathlib import Path

import neurots
from neurots import extract_input


def run(distr_dir, params_dir, neuron_dir, data_dir):
    for i in range(0,50,1):
        """Run the example for extracting inputs for synthesis."""
        # Generate distribution from directory of neurons

        distr_name = "test_distr_{}.json".format(i)
        params_name = "test_params_{}.json".format(i)
        neuron_name = "test_neuron_{}.swc".format(i)

        distr = extract_input.distributions(
            data_dir / "neurons",
            feature="path_distances", 
            diameter_model="default",
        )


if __name__ == "__main__":
    data_dir = Path("C:\\Users\\user\\Documents\\Experiment_01\\Data\\Human\\Neocortex_interneurons")
    params_dir = Path("C:\\Users\\user\\Documents\\Experiment_01\\Parameters\\Neocortex_interneuron")
    distr_dir = Path("C:\\Users\\user\\Documents\\Experiment_01\\Distributions\\Neocortex_interneuron")
    neuron_dir = Path("C:\\Users\\user\\Documents\\Experiment_01\\Synthesized\\Neurons\\Neocortex_interneuron")
    
    #result_dir.mkdir(parents=True, exist_ok=True)

    run(distr_dir, params_dir, neuron_dir, data_dir)
    print("DONE!!!")

Data:
Morphologies.zip

Edit: The error occurs in line 166 of io.py

Tutorial not running

Dear developers,
I found your paper and with read it with great interest. Furthermore, I have discovered this repository and would like to integrate it into my academic research at the Ruhr University in Bochum, Germany.

For this I have wanted to try to implement your example in doc/Tutorial.txt
Prior to that, I have cloned the repository and installed all the requirements as mentioned in the readme. I am using a Ubuntu 18.04.2 LTS machine.

When running your example, I am able to import your library and read a neuron SWC file, found in this repository.
I am having trouble with the last command. The following error is being returned to my terminal:

'Neuron' object has no attribute 'neurite'

I would like to request assistance with this. I have been browsing your files and did not find suitable documentation for this specific error. Is there a FAQ or wiki entry?

I am looking forward to hearing from you!
Best regards