bluebrain / neuror

A collection of tools to repair morphologies

NeuroR

Introduction

NeuroR is a collection of tools to repair morphologies.

You can try NeuroR's functionality on MyBinder:

• Cut-plane detection -
• Morphology repair -

Acknowledgements

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.

This work has been partially funded by the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Specific Grant Agreement No. 720270, 785907 (Human Brain Project SGA1/SGA2) and by the EBRAINS research infrastructure, funded from the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Specific Grant Agreement No. 945539 (Human Brain Project SGA3).

Citation

Cite NeuroR with the following DOI:

NeuroR implements the methods discussed in the following paper:

Anwar H., Riachi I., Schürmann F., Markram H. (2009). “An approach to capturing neuron morphological diversity,” in Computational Neuroscience: Realistic Modeling for Experimentalistsed. De Schutter E., editor. (Cambridge: The MIT Press) 211–232

DOI: 10.7551/mitpress/9780262013277.003.0010

Morphology repair with NeuroR

There are presently three types of repair which are outlined below.

Sanitization

This is the process of sanitizing a morphological file. It currently:

• ensures it can be loaded with MorphIO
• raises if the morphology has no soma or of invalid format
• removes unifurcations
• set negative diameters to zero
• raises if the morphology has a neurite whose type changes along the way
• removes segments with near zero lengths (shorter than 1e-4)

Note: more functionality may be added in the future

Cut plane repair

The cut plane repair aims at regrowing part of a morphologies that have been cut out when the cell has been experimentally sliced.

neuror cut-plane repair contains the collection of CLIs to perform this repair.

Additionally, there are CLIs for the cut plane detection and writing detected cut planes to JSON files:

• If the cut plane is aligned with one of the X, Y or Z axes, the cut plane detection can be done automatically with the CLIs:

neuror cut-plane file
neuror cut-plane folder

• If the cut plane is not one the X, Y or Z axes, the detection has to be performed through the helper web application that can be launched with the following CLI:

neuror cut-plane hint

Unravelling

Unravelling is the action of "stretching" the cell that has been shrunk because of the dehydratation caused by the slicing.

The unravelling CLI sub-group is:

neuror unravel

The unravelling algorithm can be described as follows:

• Segments are unravelled iteratively.
• Each segment direction is replaced by the averaged direction in a sliding window around this segment.
• The original segment length is preserved.
• The start position of the new segment is the end of the latest unravelled segment.

Installation

NeuroR is distributed as a Python package available on PyPi:

$ pip install --pre neuror[plotly]

Note: NeuroR relies on the experimental version 2 of NeuroM, hence the --pre option.

Only Python 3.6 and above are supported.

Prior to running pip install, we recommend updating pip in your virtual environment unless you have a compelling reason not to do it:

$ pip install --upgrade pip setuptools

Contributing

If you want to improve the project or you see any issue, every contribution is welcome. Please check the contribution guidelines for more information.

License

NeuroR is licensed under the terms of the GNU Lesser General Public License version 3. Refer to COPYING.LESSER and COPYING for details.

Copyright (c) 2019-2024 Blue Brain Project/EPFL

neuror's Issues

Different results depending on availability of AVX-512 instruction set and numpy>1.25 's vectorized sort/argsort

numpy==1.25 introduced simd vectorized version of quicksort with: numpy/numpy#23707

That change affects the behavior of the sort and argsort functions when using quicksort (default) based on the existence of the avx-512 instruction set.

In NeuroR, one of the functions that are affected is scipy.optimize.minimize:

NeuroR/neuror/cut_plane/detection.py

Line 279 in ae52411

result = optimize.minimize(_success_function,

which uses internally numpy's argsort in:
https://github.com/scipy/scipy/blob/cfe80116aaa145061246b8aec0e98248fbefb835/scipy/optimize/_optimize.py#L907

See also:
numpy/numpy#24064

Github hosted runners for ubuntu-latest seem to have enabled the aforementioned instruction set as they output different values than the expected ones in the past: https://github.com/BlueBrain/NeuroR/actions/runs/5484236591/jobs/9991722132

nptyping==2 breaks NeuroR

The new version of nptyping breaks NeuroR.

Unraveling breaks up sections

I tried to unravel the morphology of L23_PC_cADpyr_229_2 from the Blue Brain-database but the sections seem to get scattered in the x-direction.

import matplotlib.pyplot as plt

from morphio import Morphology
from neuror.unravel import unravel


def display(morph, color):
    for sec in morph.sections:
        x = sec.points.T
        plt.plot(x[0], x[1], x[2], c=color)


u, _ = unravel('data/morph_7.h5')
u.write('data/morph_7_unr.h5')

plt.subplot(projection='3d')
display(Morphology('data/morph_7.h5'), 'k')
display(Morphology('data/morph_7_unr.h5'), 'tab:blue')
plt.show()

Raise an Error if 0-length section is found at the soma

This is related to #105.

Context

Currently, if a 0-length section is found at the soma, sanitize will drop the entire neurite that is attached to it.

This behavior is not what a normal user could expect, especially because there is no Warning or Error when this dropping takes place during sanitization and the user cannot know that this has happened.

Action

After discussions (@lidakanari @adrien-berchet @mgeplf @eleftherioszisis) we agreed that the solution would be to raise an informative Error (e.g. ValueError("Zero-length section found at the soma ...") and terminate the execution of sanitize.

update readme/doc for sanitize

Just noticed it is outdated. Also, we need to add the .remove_unifurcations in the code once morphio is updated.

add z-range to error detection

z-range is the thickness of the morpho in the z-direction, corresponding to slice thickness. A small range can be understood as an error from reconstruction

Sanitize deletes all children sections when parent section length is zero

Hi, @Stannislav noticed that during sanitize of a neuron, if a section has zero length subsequent sections are deleted as well. This is probably coming from here:

NeuroR/neuror/sanitize.py

Line 112 in 79b4394

def fix_non_zero_segments(neuron, zero_length=_ZERO_LENGTH):

This should not be the expected behavior for sanitize (imo). Instead when a zero length section is removed subsequent sections should be stitched back to its parent.

Could you please look into this issue? Thanks a lot!

Segfault in fix_zero_diameters because of stack limit

When using neuror.zero_diameter_fixer.fix_zero_diameters on the attached morphology, I get a segmentation fault.
After some investigation with @arnaudon , it appeared that it happens when the Python recursion limit is updated in the function with sys.setrecursionlimit and is set to a value greater than the actual stack size (which can be updated using ulimit -s <new_size>). When increasing the stack size with ulimit the problem disappears.

Here is a MWE:
First update the stack size in bash then run Python:

    ulimit -s 8192
    python

Then in Python:

    import morphio
    from neuror.zero_diameter_fixer import fix_zero_diameters
    morph = morphio.mut.Morphology("AA0319.asc")
    fix_zero_diameters(morph)

It should end in a segfault while the same with ulimit -s 16384 should pass.

I think the best way to solve this issue would be to change the algorithm to avoid recursion. But it might not be easy...

AA0319.asc.zip

option to bypass soma check in sanitize

@mariarv wants to sanitize dendrites for some morphologies, but does not care about soma. Some of her morphs don't have soma, so an option in sanitize such as ignore_soma=False could be of some use.

axon from dendrite discussion

I found the PR which made sanitize crash: #52
See BlueBrain/NeuroM#977 (comment)

Sanitize deletes all children sections when parent section (non-soma) is zero

This is a continuation of #99
Running neuror sanitize file simple1.asc out.asc on

("CellBody"
  (Color Red)
  (CellBody)
  (0.001000000 0.001000000 0.000000000 0.010000000)
  (-0.001000000 0.001000000 0.000000000 0.010000000)
  (-0.001000000 -0.001000000 0.000000000 0.010000000)
  (0.001000000 -0.001000000 0.000000000 0.010000000)
)

( (Color Cyan)
  (Axon)
  (0.000000000 0.000000000 0.000000000 2.000000000)
  (0.000000000 -4.000000000 0.000000000 2.000000000)
  (
    (0.000000000 -4.000000000 0.000000000 4.000000000)
    (0.000000000 -4.000000000 0.000000000 4.000000000)
    (0.000000000 -4.000000000 0.000000000 4.000000000)
    (
        (6.000000000 -4.000000000 0.000000000 4.000000000)
        (7.000000000 -5.000000000 0.000000000 4.000000000)
    |
        (6.000000000 -4.000000000 0.000000000 4.000000000)
        (8.000000000 -4.000000000 0.000000000 4.000000000)
    )
  |
    (0.000000000 -4.000000000 0.000000000 4.000000000)
    (-5.000000000 -4.000000000 0.000000000 4.000000000)
  )
)

Which results in:

[...snip cellbody]
( (Color Cyan)
  (Axon)
  (0.000000000 0.000000000 0.000000000 2.000000000)
  (0.000000000 -4.000000000 0.000000000 2.000000000)
  (
    (0.000000000 -4.000000000 0.000000000 4.000000000)
    (-5.000000000 -4.000000000 0.000000000 4.000000000)
  )
)

and doesn't have the correct subtree.

Incorrect type hint for axons

In https://github.com/BlueBrain/NeuroR/blob/master/neuror/main.py#L243

Should be something like axons: Optional[List] = None, instead of axons: Optional[Path] = None,.

2 small issues in sanitize

1: the check of non constant type has a wrong message, it compares with root, not parent section
2: the remove zero lenght should have a hidden warning if it does it, and a strong warning if it removes a root section, as the whole tree will be removed. It removes if only one point is left.

update tests to ensure ordered morphs

see: BlueBrain/morph-tool#59

Improve repair by using pool of dendrites (as for axons)

This change is beyond the scope of #65 and will be treated in a future PR.
The rational is similar to synthesis, where all dendrites of all morphologies of same mtypes are used to synthesize a morphology, to avoid biases from specific features of morphologies. With this improvement, the repaired branches would be more varied, and not be almost a copy of other branches of the current morphology.

Sanitize slighly missleading message

In https://github.com/BlueBrain/NeuroR/blob/master/neuror/sanitize.py#L39
it says no soma, but there can be a non valid soma, with for example this morph: https://github.com/BlueBrain/MorphIO/blob/master/tests/data/soma_single_frustum.swc

Maybe write 'no valid soma` instead?