morphio 3.0.2__tar.gz → 3.1.0__tar.gz

{MorphIO-3.0.2 → MorphIO-3.1.0}/.github/workflows/publish-sdist-wheels.yml

@@ -13,7 +13,7 @@ env:
   CIBW_BUILD: 'cp3?-*'
   CIBW_SKIP: 'cp35-* cp39-* *-manylinux_i686'
   CIBW_BEFORE_TEST: pip install -r {project}/tests/requirement_tests.txt
-  CIBW_TEST_COMMAND: nosetests -s -v -P {project}/tests
+  CIBW_TEST_COMMAND: pytest -s -v {project}/tests
 
 jobs:
   build_wheels:
@@ -78,7 +78,7 @@ jobs:
           sudo apt install -y libhdf5-dev
           pip install -r tests/requirement_tests.txt
           pip install dist/*
-          nosetests -s -v -P tests
+          pytest -s -v tests
       - name: Store sdist as artifact
         uses: actions/upload-artifact@v2
         with:

{MorphIO-3.0.2 → MorphIO-3.1.0}/CONTRIBUTING.md

@@ -130,7 +130,7 @@ Run the following command to build incrementally the project: `pip install -e .`
 
 ## Test
 
-Run the following command to run the Python unit-tests: `nosetests`
+Run the following command to run the Python unit-tests: `pytest tests`
 
 ## Coding conventions
 

MorphIO-3.1.0/MorphIO.egg-info/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.1
+Name: MorphIO
+Version: 3.1.0
+Summary: A neuron morphology IO library
+Home-page: https://github.com/BlueBrain/MorphIO/
+Author: Blue Brain Project, EPFL
+License: LGPLv3
+Description: |license| |build| |docs|
+        
+        MorphIO
+        =======
+        
+        Documentation
+        -------------
+        
+        MorphIO documentation is built and hosted on `readthedocs <http://morphio.readthedocs.org/>`.
+        
+        * `latest snapshot <http://morphio.readthedocs.org/en/latest/>`_
+        * `latest release <http://morphio.readthedocs.org/en/stable/>`_
+        
+        Introduction
+        ------------
+        
+        MorphIO is a library for reading and writing neuron morphology files. It supports the following
+        formats:
+        
+        * SWC
+        * ASC (aka. neurolucida)
+        * H5 v1
+        * H5 v2 is not supported anymore, see `H5v2`_
+        
+        It provides 3 C++ classes that are the starting point of every morphology analysis:
+        
+        * ``Soma``: contains the information related to the soma.
+        
+        * ``Section``: a section is the succession of points between two bifurcations. To the bare minimum
+          the ``Section`` object will contain the section type, the position and diameter of each point.
+        
+        * ``Morphology``: the morphology object contains general information about the loaded cell
+          but also provides accessors to the different sections.
+        
+        One important concept is that MorphIO is split into a *read-only* part and a *read/write* one.
+        
+        
+        H5v2
+        ====
+        
+        Starting at version 2.6.0, the file format ``h5v2`` is no longer supported. If you have
+        morphologies in this format, you can convert them to h5v1 with:
+        
+        .. code-block:: bash
+        
+           pip install "morphio<2.6" "morph-tool==2.3.0"
+        
+        and then:
+        
+        .. code-block:: bash
+        
+           # single file, OUTPUT must end with `.h5`
+           morph-tool convert file INPUTFILE OUTPUT
+           # bulk conversion
+           morph-tool convert folder -ext h5 INPUTDIR OUTPUTDIR
+        
+        
+        Contributing
+        ============
+        If you want to improve the project or you see any issue, every contribution is welcome.
+        Please check the `contribution guidelines <https://github.com/BlueBrain/morphio/blob/master/CONTRIBUTING.md>`_ for more
+        information.
+        
+        Acknowledgements
+        ================
+        This research was supported 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).
+        
+        License
+        =======
+        MorphIO is licensed under the terms of the GNU Lesser General Public License version 3. Refer to
+        COPYING.LESSER and COPYING for details.
+        
+        .. |license| image:: https://img.shields.io/pypi/l/morphio
+                        :target: https://github.com/BlueBrain/morphio/blob/master/COPYING.LESSER
+        
+        .. |build| image:: https://travis-ci.com/BlueBrain/MorphIO.svg?token=KRP9rHiV52PC6mX3ACXp&branch=master
+                        :target: https://travis-ci.com/BlueBrain/MorphIO
+                        :alt: Build Status
+        
+        .. |docs| image:: https://readthedocs.org/projects/morphio/badge/?version=latest
+                     :target: https://morphio.readthedocs.io/
+                     :alt: documentation status
+        
+        
+Keywords: computational neuroscience,morphology,neuronneurolucidaneuromorphology
+Platform: UNKNOWN
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
+Description-Content-Type: text/x-rst
+Provides-Extra: docs

{MorphIO-3.0.2 → MorphIO-3.1.0}/MorphIO.egg-info/SOURCES.txt

@@ -193,17 +193,25 @@ ci/coverage_test.sh
 ci/cpp_test.sh
 ci/python_test.sh
 doc/Makefile
+doc/README.md
 doc/environment.yml
 doc/source/Doxyfile
 doc/source/DoxygenLayout.xml
-doc/source/api.rst
 doc/source/conf.py
 doc/source/cpp.rst
 doc/source/footer.html
+doc/source/glia.rst
 doc/source/header.html
 doc/source/index.rst
+doc/source/install.rst
+doc/source/markers.rst
+doc/source/mitochondria.rst
+doc/source/morphology.rst
+doc/source/python.rst
+doc/source/reticulum.rst
 doc/source/specification.rst
 doc/source/specification_neurolucida.rst
+doc/source/warnings.rst
 doc/source/_templates/doxygen_page.rst_t
 doc/source/doxygen/.gitignore
 doc/source/images/swc/neuromorpho.svg
@@ -285,7 +293,6 @@ src/vasc/properties.cpp
 src/vasc/section.cpp
 src/vasc/vasculature.cpp
 tests/CMakeLists.txt
-tests/__init__.py
 tests/main.cpp
 tests/requirement_tests.txt
 tests/test_0_API.py
@@ -316,6 +323,7 @@ tests/data/multiple_point_section.asc
 tests/data/multiple_soma.swc
 tests/data/nested_single_children.asc
 tests/data/neurite_wrong_root_point.swc
+tests/data/no_soma.swc
 tests/data/nrn-order-already-sorted.h5
 tests/data/nrn_ordering.swc
 tests/data/pia.asc

MorphIO-3.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.1
+Name: MorphIO
+Version: 3.1.0
+Summary: A neuron morphology IO library
+Home-page: https://github.com/BlueBrain/MorphIO/
+Author: Blue Brain Project, EPFL
+License: LGPLv3
+Description: |license| |build| |docs|
+        
+        MorphIO
+        =======
+        
+        Documentation
+        -------------
+        
+        MorphIO documentation is built and hosted on `readthedocs <http://morphio.readthedocs.org/>`.
+        
+        * `latest snapshot <http://morphio.readthedocs.org/en/latest/>`_
+        * `latest release <http://morphio.readthedocs.org/en/stable/>`_
+        
+        Introduction
+        ------------
+        
+        MorphIO is a library for reading and writing neuron morphology files. It supports the following
+        formats:
+        
+        * SWC
+        * ASC (aka. neurolucida)
+        * H5 v1
+        * H5 v2 is not supported anymore, see `H5v2`_
+        
+        It provides 3 C++ classes that are the starting point of every morphology analysis:
+        
+        * ``Soma``: contains the information related to the soma.
+        
+        * ``Section``: a section is the succession of points between two bifurcations. To the bare minimum
+          the ``Section`` object will contain the section type, the position and diameter of each point.
+        
+        * ``Morphology``: the morphology object contains general information about the loaded cell
+          but also provides accessors to the different sections.
+        
+        One important concept is that MorphIO is split into a *read-only* part and a *read/write* one.
+        
+        
+        H5v2
+        ====
+        
+        Starting at version 2.6.0, the file format ``h5v2`` is no longer supported. If you have
+        morphologies in this format, you can convert them to h5v1 with:
+        
+        .. code-block:: bash
+        
+           pip install "morphio<2.6" "morph-tool==2.3.0"
+        
+        and then:
+        
+        .. code-block:: bash
+        
+           # single file, OUTPUT must end with `.h5`
+           morph-tool convert file INPUTFILE OUTPUT
+           # bulk conversion
+           morph-tool convert folder -ext h5 INPUTDIR OUTPUTDIR
+        
+        
+        Contributing
+        ============
+        If you want to improve the project or you see any issue, every contribution is welcome.
+        Please check the `contribution guidelines <https://github.com/BlueBrain/morphio/blob/master/CONTRIBUTING.md>`_ for more
+        information.
+        
+        Acknowledgements
+        ================
+        This research was supported 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).
+        
+        License
+        =======
+        MorphIO is licensed under the terms of the GNU Lesser General Public License version 3. Refer to
+        COPYING.LESSER and COPYING for details.
+        
+        .. |license| image:: https://img.shields.io/pypi/l/morphio
+                        :target: https://github.com/BlueBrain/morphio/blob/master/COPYING.LESSER
+        
+        .. |build| image:: https://travis-ci.com/BlueBrain/MorphIO.svg?token=KRP9rHiV52PC6mX3ACXp&branch=master
+                        :target: https://travis-ci.com/BlueBrain/MorphIO
+                        :alt: Build Status
+        
+        .. |docs| image:: https://readthedocs.org/projects/morphio/badge/?version=latest
+                     :target: https://morphio.readthedocs.io/
+                     :alt: documentation status
+        
+        
+Keywords: computational neuroscience,morphology,neuronneurolucidaneuromorphology
+Platform: UNKNOWN
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
+Description-Content-Type: text/x-rst
+Provides-Extra: docs

MorphIO-3.1.0/README.rst

@@ -0,0 +1,85 @@
+|license| |build| |docs|
+
+MorphIO
+=======
+
+Documentation
+-------------
+
+MorphIO documentation is built and hosted on `readthedocs <http://morphio.readthedocs.org/>`.
+
+* `latest snapshot <http://morphio.readthedocs.org/en/latest/>`_
+* `latest release <http://morphio.readthedocs.org/en/stable/>`_
+
+Introduction
+------------
+
+MorphIO is a library for reading and writing neuron morphology files. It supports the following
+formats:
+
+* SWC
+* ASC (aka. neurolucida)
+* H5 v1
+* H5 v2 is not supported anymore, see `H5v2`_
+
+It provides 3 C++ classes that are the starting point of every morphology analysis:
+
+* ``Soma``: contains the information related to the soma.
+
+* ``Section``: a section is the succession of points between two bifurcations. To the bare minimum
+  the ``Section`` object will contain the section type, the position and diameter of each point.
+
+* ``Morphology``: the morphology object contains general information about the loaded cell
+  but also provides accessors to the different sections.
+
+One important concept is that MorphIO is split into a *read-only* part and a *read/write* one.
+
+
+H5v2
+====
+
+Starting at version 2.6.0, the file format ``h5v2`` is no longer supported. If you have
+morphologies in this format, you can convert them to h5v1 with:
+
+.. code-block:: bash
+
+   pip install "morphio<2.6" "morph-tool==2.3.0"
+
+and then:
+
+.. code-block:: bash
+
+   # single file, OUTPUT must end with `.h5`
+   morph-tool convert file INPUTFILE OUTPUT
+   # bulk conversion
+   morph-tool convert folder -ext h5 INPUTDIR OUTPUTDIR
+
+
+Contributing
+============
+If you want to improve the project or you see any issue, every contribution is welcome.
+Please check the `contribution guidelines <https://github.com/BlueBrain/morphio/blob/master/CONTRIBUTING.md>`_ for more
+information.
+
+Acknowledgements
+================
+This research was supported 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).
+
+License
+=======
+MorphIO is licensed under the terms of the GNU Lesser General Public License version 3. Refer to
+COPYING.LESSER and COPYING for details.
+
+.. |license| image:: https://img.shields.io/pypi/l/morphio
+                :target: https://github.com/BlueBrain/morphio/blob/master/COPYING.LESSER
+
+.. |build| image:: https://travis-ci.com/BlueBrain/MorphIO.svg?token=KRP9rHiV52PC6mX3ACXp&branch=master
+                :target: https://travis-ci.com/BlueBrain/MorphIO
+                :alt: Build Status
+
+.. |docs| image:: https://readthedocs.org/projects/morphio/badge/?version=latest
+             :target: https://morphio.readthedocs.io/
+             :alt: documentation status
+

{MorphIO-3.0.2 → MorphIO-3.1.0}/binds/python/bind_misc.cpp

@@ -63,8 +63,10 @@ void bind_misc(py::module& m) {
         .value("custom8", morphio::enums::SectionType::SECTION_CUSTOM_8)
         .value("custom9", morphio::enums::SectionType::SECTION_CUSTOM_9)
         .value("custom10", morphio::enums::SectionType::SECTION_CUSTOM_10)
-        // .value("glia_process", morphio::enums::SectionType::SECTION_GLIA_PROCESS)
-        // .value("glia_endfoot", morphio::enums::SectionType::SECTION_GLIA_ENDFOOT)
+        .value("glia_perivascular_process",
+               morphio::enums::SectionType::SECTION_GLIA_PERIVASCULAR_PROCESS)
+        .value("glia_process", morphio::enums::SectionType::SECTION_GLIA_PROCESS)
+        .value("all", morphio::enums::SectionType::SECTION_ALL)
         .export_values();
 
     py::enum_<morphio::enums::VascularSectionType>(m, "VasculatureSectionType")

{MorphIO-3.0.2 → MorphIO-3.1.0}/ci/python_test.sh

@@ -21,6 +21,5 @@ pip install .
 pip install -r tests/requirement_tests.txt
 
 CURRENT=$(pwd)
-
 cd ..
-nosetests -P ${CURRENT}/tests
+pytest ${CURRENT}/tests

MorphIO-3.1.0/doc/README.md

@@ -0,0 +1,16 @@
+### Local doc building
+
+For building documentation locally, make sure you have `sphinx-bluebrain-theme` and `doxygen`.
+
+```bash
+pip install sphinx-bluebrain-theme
+```
+
+and
+
+```bash
+# for Linux
+sudo apt install doxygen
+# for MacOS
+brew install doxygen
+```

MorphIO-3.1.0/doc/source/glia.rst

@@ -0,0 +1,16 @@
+Glia
+====
+
+MorphIO also support reading and writing glia (such as astrocytes) from/to disk according to the
+`H5 specification <https://developer.humanbrainproject.eu/docs/projects/morphology-documentation/latest/h5v1.html>`__
+
+.. code-block:: python
+
+    import morphio
+
+    # Immutable
+    immutable_glia = morphio.GlialCell("astrocyte.h5")
+
+    # Mutable
+    empty_glia = morphio.mut.GlialCell()
+    mutable_glia = morphio.mut.GlialCell("astrocyte.h5")

{MorphIO-3.0.2 → MorphIO-3.1.0}/doc/source/index.rst

@@ -4,7 +4,14 @@
    :hidden:
 
    Home <self>
-   api
+   install
+   morphology
+   glia
+   mitochondria
+   reticulum
+   markers
+   warnings
+   python
    cpp
    specification
    specification_neurolucida

MorphIO-3.1.0/doc/source/install.rst

@@ -0,0 +1,60 @@
+Install
+=======
+
+Dependencies
+------------
+
+To build MorphIO from sources, the following dependencies are required:
+
+* cmake >= 3.2
+* libhdf5-dev
+* A C++11 compiler
+
+Debian:
+
+.. code-block:: shell
+
+   sudo apt install cmake libhdf5-dev
+
+Red Hat:
+
+.. code-block:: shell
+
+   sudo yum install cmake3.x86_64 hdf5-devel.x86_64
+
+Max OS:
+
+.. code-block:: shell
+
+   brew install hdf5 cmake
+
+
+Install as a C++ library
+------------------------
+
+For manual installation:
+
+.. code-block:: shell
+
+   git clone git@github.com:bluebrain/morphio.git --recursive
+   cd morphio
+   mkdir build && cd build
+   cmake ..
+   make install
+
+To use the installed library:
+
+.. code-block:: CMake
+
+   find_package(MorphIO REQUIRED)
+   target_link_libraries(mylib MorphIO::morphio)
+
+
+Install as a Python package
+---------------------------
+
+The python binding can directly be installed using pip:
+
+.. code-block:: shell
+
+   pip install morphio

MorphIO-3.1.0/doc/source/markers.rst

@@ -0,0 +1,127 @@
+NeuroLucida markers
+===================
+
+A marker is an `s-expression <https://en.wikipedia.org/wiki/S-expression>`__ at the top level of the
+Neurolucida file that contains additional information about the morphology. For example:
+
+.. code-block:: lisp
+
+  ("pia"
+    (Closed)
+    (MBFObjectType 5)
+    (0 1 2 3)
+    (3 4 5 4)
+    (6 7 8 5)
+    (9 10 11 6)
+   )
+
+This PR adds a `Morphology.markers` attribute that stores the markers found in the file. A Marker
+object has 3 attributes:
+- label
+- points
+- diameters.
+
+**Specification**
+
+The following s-expressions are parsed:
+
+* Any s-exp with a top level string. Like:
+
+    .. code-block:: lisp
+
+      ("pia"
+      (Closed)
+      (MBFObjectType 5)
+      (0 1 2 3)
+      (3 4 5 4)
+      (6 7 8 5)
+      (9 10 11 6)
+      )
+
+* An sexp with one of the following top level regular expression:
+
+    - Dot[0-9]*
+    - Plus[0-9]*
+    - Cross[0-9]*
+    - Splat[0-9]*
+    - Flower[0-9]*
+    - Circle[0-9]*
+    - Flower[0-9]*
+    - TriStar[0-9]*
+    - OpenStar[0-9]*
+    - Asterisk[0-9]*
+    - SnowFlake[0-9]*
+    - OpenCircle[0-9]*
+    - ShadedStar[0-9]*
+    - FilledStar[0-9]*
+    - TexacoStar[0-9]*
+    - MoneyGreen[0-9]*
+    - DarkYellow[0-9]*
+    - OpenSquare[0-9]*
+    - OpenDiamond[0-9]*
+    - CircleArrow[0-9]*
+    - CircleCross[0-9]*
+    - OpenQuadStar[0-9]*
+    - DoubleCircle[0-9]*
+    - FilledSquare[0-9]*
+    - MalteseCross[0-9]*
+    - FilledCircle[0-9]*
+    - FilledDiamond[0-9]*
+    - FilledQuadStar[0-9]*
+    - OpenUpTriangle[0-9]*
+    - FilledUpTriangle[0-9]*
+    - OpenDownTriangle[0-9]*
+    - FilledDownTriangle[0-9]*
+
+    Example:
+
+    .. code-block:: lisp
+
+        (FilledCircle
+        (Color RGB (64, 0, 128))
+        (Name "Marker 11")
+        (Set "axons")
+        ( -189.59    55.67    28.68     0.12)  ; 1
+        )  ;  End of markers
+
+ℹ️ Markers can may have only `(X Y Z)` specified instead of the more common `(X Y Z D)`. In this case, diameters are set to 0.
+
+**Usage**
+
+.. code-block::python
+    cell = Morphology(os.path.join(_path, 'pia.asc'))
+    all_markers = cell.markers
+    pia = m.markers[0]
+
+    # fetch the label marker with the `label` attribute
+    assert_equal(pia.label, 'pia')
+
+    # fetch the points with the `points` attribute
+    assert_array_equal(pia.points,
+                         [[0, 1, 2],
+                          [3, 4, 5],
+                          [6, 7, 8],
+                          [9, 10, 11]])
+
+    # fetch the diameters with the `diameters` attribute
+    assert_array_equal(pia.diameters, [3, 4, 5, 6])
+
+⚠️ Only top level markers are currently supported. This means the following nested marker won't be available the the MorphIO API.
+
+.. code-block:: lisp
+
+  ( (Color White)  ; [10,1]
+    (Dendrite)
+    ( -290.87  -113.09   -16.32     2.06)  ; Root
+    ( -290.87  -113.09   -16.32     2.06)  ; R, 1
+    (
+      ( -277.14  -119.13   -18.02     0.69)  ; R-1, 1
+      ( -275.54  -119.99   -16.67     0.69)  ; R-1, 2
+      (Cross  ;  [3,3]
+        (Color Orange)
+        (Name "Marker 3")
+        ( -271.87  -121.14   -16.27     0.69)  ; 1
+        ( -269.34  -122.29   -15.48     0.69)  ; 2
+      )  ;  End of markers
+    )
+   )

MorphIO-3.1.0/doc/source/mitochondria.rst

@@ -0,0 +1,68 @@
+.. _mitochondria-readme:
+
+Mitochondria
+============
+
+It is also possible to read and write mitochondria from/to the h5 files (*SWC and ASC are not
+supported*). As mitochondria can be represented as trees, one can define the concept of
+*mitochondrial section* similar to neuronal section and end up with a similar API. The morphology
+object has a *mitochondria* handle method that exposes the basic methods:
+
+* ``root_sections``: returns the section ID of the starting mitochondrial section of each
+    mitochondrion.
+* ``section(id)``: returns a given mitochondrial section
+* ``append_section``: creates a new mitochondrial section
+* ``depth_begin``: a depth first iterator
+* ``breadth_begin``: a breadth first iterator
+* ``upstream_begin``: an upstream iterator
+
+.. code-block:: python
+
+    from morphio import MitochondriaPointLevel, PointLevel, SectionType
+    from morphio.mut import Morphology
+
+    morpho = Morphology()
+
+    # A neuronal section that will store mitochondria
+    section = morpho.append_root_section(
+      PointLevel([[2, 2, 2], [3, 3, 3]], [4, 4], [5, 5]),
+      SectionType.axon)
+
+    # Creating a new mitochondrion
+    mito_id = morpho.mitochondria.append_section(
+      -1,
+      MitochondriaPointLevel([section.id, section.id], # section id hosting the mitochondria point
+                             [0.5, 0.6], # relative distance between the start of the section and the point
+                             [10, 20] # mitochondria diameters
+                             ))
+
+    # Appending a new mitochondrial section to the previous one
+    morpho.mitochondria.append_section(
+      mito_id, MitochondriaPointLevel([0, 0, 0, 0],
+                                      [0.6, 0.7, 0.8, 0.9],
+                                      [20, 30, 40, 50]))
+
+    # Iteration works the same as iteration on neuronal sections
+    first_root = morpho.mitochondria.root_sections[0]
+    for section_id in morpho.mitochondria.depth_begin(first_root):
+      section = morpho.mitochondria.section(section_id)
+      print('relative_path_length - diameter')
+      for relative_path_length, diameter in zip(section.diameters,
+                                                section.relative_path_lengths):
+          print("{} - {}".format(relative_path_length, diameter))
+
+Reading mithochondria from H5 files:
+
+.. code-block:: python
+
+    from morphio import Morphology
+
+    morpho = Morphology("file_with_mithochondria.h5")
+
+    for mitochondrial_section in morpho.mitochondria.root_sections:
+      print('{neurite_id}, {relative_path_lengths}, {diameters}'.format(
+            neurite_id=mitochondrial_section.neurite_section_ids,
+            relative_path_lengths=mitochondrial_section.relative_path_lengths,
+            diameters=mitochondrial_section.diameters))
+
+      print("Number of children: {}".format(len(mitochondrial_section.children)))