Add endoplasmic reticulum API for morphio.mut (#174)

BlueBrain · Mar 12, 2020 · 5447b32 · 5447b32
1 parent 33f69c7
commit 5447b32
Show file tree

Hide file tree

Showing 17 changed files with 348 additions and 51 deletions.
diff --git a/README.md b/README.md
@@ -22,6 +22,7 @@
       * [Creating morphologies](#creating-morphologies)
    * [Opening flags](#opening-flags)
    * [Mitochondria](#mitochondria)
+   * [Endoplasmic reticulum](#endoplasmic-reticulum)
    * [Tips](#tips)
       * [Maximum number of warnings](#maximum-number-of-warnings)
 * [Specification](#specification)
@@ -310,16 +311,16 @@ morpho.write("outfile.h5")
 When opening the file, modifier flags can be passed to alter the morphology representation.
 The following flags are supported:
 
-- `morphio::NO\_MODIFIER`:
+- `morphio::NO_MODIFIER`:
 This is the default flag, it will do nothing.
-- `morphio::TWO\_POINTS\_SECTIONS`:
+- `morphio::TWO_POINTS_SECTIONS`:
 Each section gets reduce to a line made of the first and last point.
-- `morphio::SOMA\_SPHERE`:
+- `morphio::SOMA_SPHERE`:
 The soma is reduced to a sphere which is the center of gravity of the real soma.
-- `morphio::NO\_DUPLICATES`:
+- `morphio::NO_DUPLICATES`:
 The duplicate point are not present. It means the first point of each section
 is no longer the last point of the parent section.
-- `morphio::NRN\_ORDER`:
+- `morphio::NRN_ORDER`:
 Neurite are reordered according to the
 [NEURON simulator ordering](https://github.com/neuronsimulator/nrn/blob/2dbf2ebf95f1f8e5a9f0565272c18b1c87b2e54c/share/lib/hoc/import3d/import3d_gui.hoc#L874)
 
@@ -402,6 +403,53 @@ for mitochondrial_section in morpho.mitochondria.root_sections:
 
     print("Number of children: {}".format(len(mitochondrial_section.children)))
 ```
+### Endoplasmic reticulum
+
+Endoplasmic reticulum can also be stored and written to H5 file.
+The specification is part of the [BBP morphology documentation](https://bbpteam.epfl.ch/documentation/projects/Morphology%20Documentation/latest/h5v1.html)
+There is one endoplasmic reticulum object per morphology. It contains 4 attributes. Each attribute is an array and each line
+refers to the value of the attribute for a specific neuronal section.
+
+- section_index:
+Each row of this dataset represents the index of a neuronal section. Each row of the other properties (eg. volume) refer to the part of the reticulum
+present in the corresponding section for each row.
+
+- volume:
+One column dataset indexed by section_index. Contains volumes of the reticulum per each corresponding section it lies in.
+
+- surface_area:
+Similar to the volume dataset, this dataset represents the surface area of the reticulum in each section in the section_index dataset.
+
+- filament_count:
+This 1 column dataset is composed of integers that represent the number of filaments in the segment of the reticulum lying in the section referenced by the corresponding row in the section_index dataset.
+
+
+#### Reading endoplasmic reticula from H5 files
+
+```python
+from morphio import Morphology
+
+morpho = Morphology('/my/file')
+reticulum = morpho.endoplasmic_reticulum
+print('{indices}, {volumes}, {areas}, {counts}'.format(
+    indices=reticulum.section_indices,
+    volumes=reticulum.volumes,
+    areas=reticulum.surface_areas,
+    counts=reticulum.filament_counts))
+```
+
+#### Writing endoplasmic reticula from H5 files
+
+```python
+neuron = Morphology()
+
+reticulum = neuron.endoplasmic_reticulum
+reticulum.section_indices = [1, 1]
+reticulum.volumes = [2, 2]
+reticulum.surface_areas = [3, 3]
+reticulum.filament_counts = [4, 4]
+neuron.write('/my/out/file.h5')  # Has to be written to h5
+```
 
 ### Tips
 #### Maximum number of warnings

diff --git a/binds/python/bind_mutable.cpp b/binds/python/bind_mutable.cpp
@@ -4,6 +4,8 @@
 #include <pybind11/numpy.h>
 #include <pybind11/pybind11.h>
 
+#include <morphio/endoplasmic_reticulum.h>
+#include <morphio/mut/endoplasmic_reticulum.h>
 #include <morphio/mut/mitochondria.h>
 #include <morphio/mut/morphology.h>
 
@@ -17,6 +19,7 @@ namespace py = pybind11;
 void bind_mutable_module(py::module& m) {
     using namespace py::literals;
 
+
     py::class_<morphio::mut::Morphology>(m, "Morphology")
         .def(py::init<>())
         .def(py::init<const std::string&, unsigned int>(),
@@ -59,6 +62,11 @@ void bind_mutable_module(py::module& m) {
             static_cast<morphio::mut::Mitochondria& (morphio::mut::Morphology::*) ()>(
                 &morphio::mut::Morphology::mitochondria),
             "Returns a reference to the mitochondria container class")
+        .def_property_readonly(
+            "endoplasmic_reticulum",
+            static_cast<morphio::mut::EndoplasmicReticulum& (morphio::mut::Morphology::*) ()>(
+                &morphio::mut::Morphology::endoplasmicReticulum),
+            "Returns a reference to the endoplasmic reticulum container class")
         .def_property_readonly("annotations",
                                &morphio::mut::Morphology::annotations,
                                "Returns a list of annotations")
@@ -454,4 +462,56 @@ void bind_mutable_module(py::module& m) {
             "center",
             [](morphio::mut::Soma* soma) { return py::array(3, soma->center().data()); },
             "Returns the center of gravity of the soma points");
+
+    py::class_<morphio::mut::EndoplasmicReticulum>(m, "EndoplasmicReticulum")
+        .def(py::init<>())
+        .def(py::init<const std::vector<uint32_t>&,
+                      const std::vector<float>&,
+                      const std::vector<float>&,
+                      const std::vector<uint32_t>&>())
+        .def(py::init<const morphio::EndoplasmicReticulum&>())
+        .def(py::init<const morphio::mut::EndoplasmicReticulum&>())
+
+        .def_property(
+            "section_indices",
+            [](morphio::mut::EndoplasmicReticulum* reticulum) {
+                return py::array(static_cast<py::ssize_t>(reticulum->sectionIndices().size()),
+                                 reticulum->sectionIndices().data());
+            },
+            [](morphio::mut::EndoplasmicReticulum* reticulum, py::array_t<uint32_t> indices) {
+                reticulum->sectionIndices() = indices.cast<std::vector<uint32_t>>();
+            },
+            "Returns the list of neuronal section indices")
+        .def_property(
+            "volumes",
+            [](morphio::mut::EndoplasmicReticulum* reticulum) {
+                return py::array(static_cast<py::ssize_t>(reticulum->volumes().size()),
+                                 reticulum->volumes().data());
+            },
+            [](morphio::mut::EndoplasmicReticulum* reticulum, py::array_t<float> volumes) {
+                reticulum->volumes() = volumes.cast<std::vector<float>>();
+            },
+            "Returns the volumes for each neuronal section")
+
+        .def_property(
+            "surface_areas",
+            [](morphio::mut::EndoplasmicReticulum* reticulum) {
+                return py::array(static_cast<py::ssize_t>(reticulum->surfaceAreas().size()),
+                                 reticulum->surfaceAreas().data());
+            },
+            [](morphio::mut::EndoplasmicReticulum* reticulum, py::array_t<float> areas) {
+                reticulum->surfaceAreas() = areas.cast<std::vector<float>>();
+            },
+            "Returns the surface areas for each neuronal section")
+
+        .def_property(
+            "filament_counts",
+            [](morphio::mut::EndoplasmicReticulum* reticulum) {
+                return py::array(static_cast<py::ssize_t>(reticulum->filamentCounts().size()),
+                                 reticulum->filamentCounts().data());
+            },
+            [](morphio::mut::EndoplasmicReticulum* reticulum, py::array_t<uint32_t> counts) {
+                reticulum->filamentCounts() = counts.cast<std::vector<uint32_t>>();
+            },
+            "Returns the number of filaments for each neuronal section");
 }
diff --git a/include/morphio/endoplasmic_reticulum.h b/include/morphio/endoplasmic_reticulum.h
@@ -37,5 +37,6 @@ class EndoplasmicReticulum
     std::shared_ptr<Property::Properties> _properties;
 
     friend class Morphology;
+    friend class morphio::mut::EndoplasmicReticulum;
 };
 }  // namespace morphio
diff --git a/include/morphio/mut/endoplasmic_reticulum.h b/include/morphio/mut/endoplasmic_reticulum.h
@@ -0,0 +1,54 @@
+#pragma once
+
+#include <morphio/properties.h>
+#include <morphio/types.h>
+
+namespace morphio {
+namespace mut {
+/**
+ * The entry-point class to access endoplasmic reticulum data
+ *
+ * Spec https://bbpteam.epfl.ch/documentation/projects/Morphology%20Documentation/latest/h5v1.html
+ **/
+class EndoplasmicReticulum
+{
+  public:
+    EndoplasmicReticulum() = default;
+    EndoplasmicReticulum(const std::vector<uint32_t>& sectionIndices,
+                         const std::vector<float>& volumes,
+                         const std::vector<float>& surfaceAreas,
+                         const std::vector<uint32_t>& filamentCounts);
+    EndoplasmicReticulum(const EndoplasmicReticulum& endoplasmicReticulum);
+    EndoplasmicReticulum(const morphio::EndoplasmicReticulum& endoplasmicReticulum);
+
+
+    /**
+       Returns the list of neuronal section indices
+    **/
+    const std::vector<uint32_t>& sectionIndices() const noexcept;
+    std::vector<uint32_t>& sectionIndices() noexcept;
+
+    /**
+       Returns the volumes for each neuronal section
+    **/
+    const std::vector<float>& volumes() const noexcept;
+    std::vector<float>& volumes() noexcept;
+
+    /**
+       Returns the surface areas for each neuronal section
+    **/
+    const std::vector<float>& surfaceAreas() const noexcept;
+    std::vector<float>& surfaceAreas() noexcept;
+
+    /**
+       Returns the number of filaments for each neuronal section
+    **/
+    const std::vector<uint32_t>& filamentCounts() const noexcept;
+    std::vector<uint32_t>& filamentCounts() noexcept;
+
+  private:
+    morphio::Property::EndoplasmicReticulumLevel _properties;
+    EndoplasmicReticulum(const morphio::Property::EndoplasmicReticulumLevel&);
+};
+}  // namespace mut
+}  // namespace morphio
diff --git a/include/morphio/mut/morphology.h b/include/morphio/mut/morphology.h
@@ -11,6 +11,7 @@
 
 #include <morphio/errorMessages.h>
 #include <morphio/exceptions.h>
+#include <morphio/mut/endoplasmic_reticulum.h>
 #include <morphio/mut/mitochondria.h>
 #include <morphio/mut/soma.h>
 #include <morphio/properties.h>
@@ -86,6 +87,16 @@ class Morphology
      * Return the mitochondria container class
      **/
     inline const Mitochondria& mitochondria() const noexcept;
+
+    /**
+     * Return the endoplasmic reticulum container class
+     **/
+    inline EndoplasmicReticulum& endoplasmicReticulum() noexcept;
+    /**
+     * Return the endoplasmic reticulum container class
+     **/
+    inline const EndoplasmicReticulum& endoplasmicReticulum() const noexcept;
+
     /**
      * Return the annotation object
      **/
@@ -212,6 +223,7 @@ class Morphology
     std::map<uint32_t, std::shared_ptr<Section>> _sections;
     std::vector<morphio::Property::Annotation> _annotations;
     Mitochondria _mitochondria;
+    EndoplasmicReticulum _endoplasmicReticulum;
 
     std::map<uint32_t, uint32_t> _parent;
     std::map<uint32_t, std::vector<std::shared_ptr<Section>>> _children;
@@ -241,6 +253,14 @@ inline const Mitochondria& Morphology::mitochondria() const noexcept {
     return _mitochondria;
 }
 
+inline EndoplasmicReticulum& Morphology::endoplasmicReticulum() noexcept {
+    return _endoplasmicReticulum;
+}
+
+inline const EndoplasmicReticulum& Morphology::endoplasmicReticulum() const noexcept {
+    return _endoplasmicReticulum;
+}
+
 inline const std::vector<Property::Annotation>& Morphology::annotations() const noexcept {
     return _annotations;
 }

diff --git a/include/morphio/mut/writers.h b/include/morphio/mut/writers.h
@@ -1,4 +1,3 @@
-#include <morphio/mut/mitochondria.h>
 #include <morphio/mut/morphology.h>
 
 namespace morphio {

diff --git a/include/morphio/properties.h b/include/morphio/properties.h
@@ -135,10 +135,10 @@ struct MitochondriaSectionLevel {
 };
 
 struct EndoplasmicReticulumLevel {
-    std::vector<uint32_t> _sectionIndex;
-    std::vector<float> _volume;
-    std::vector<float> _surfaceArea;
-    std::vector<uint32_t> _filamentCount;
+    std::vector<uint32_t> _sectionIndices;
+    std::vector<float> _volumes;
+    std::vector<float> _surfaceAreas;
+    std::vector<uint32_t> _filamentCounts;
 };
 
 struct Annotation {

diff --git a/include/morphio/types.h b/include/morphio/types.h
@@ -14,13 +14,13 @@
 namespace morphio {
 
 using namespace enums;
+class EndoplasmicReticulum;
+class MitoSection;
+class Mitochondria;
 class Morphology;
+class Section;
 template <class T>
 class SectionBase;
-class Section;
-class MitoSection;
-class Mitochondria;
-class EndoplasmicReticulum;
 class Soma;
 
 namespace Property {
@@ -38,11 +38,12 @@ class ErrorMessages;
 }  // namespace readers
 
 namespace mut {
-class Section;
+class EndoplasmicReticulum;
 class MitoSection;
-class Soma;
-class Morphology;
 class Mitochondria;
+class Morphology;
+class Section;
+class Soma;
 }  // namespace mut
 
 using SectionRange = std::pair<size_t, size_t>;

diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
@@ -6,25 +6,26 @@ set(MORPHIO_SOURCES
     mitochondria.cpp
     morphology.cpp
     morphology.cpp
-    properties.cpp
-    section.cpp
-    soma.cpp
-    vector_utils.cpp
-    version.cpp
+    mut/endoplasmic_reticulum.cpp
     mut/mito_section.cpp
+    mut/mitochondria.cpp
+    mut/modifiers.cpp
+    mut/morphology.cpp
     mut/section.cpp
     mut/soma.cpp
-    mut/morphology.cpp
-    mut/mitochondria.cpp
     mut/writers.cpp
-    mut/modifiers.cpp
+    properties.cpp
+    readers/morphologyASC.cpp
     readers/morphologyHDF5.cpp
     readers/morphologySWC.cpp
-    readers/morphologyASC.cpp
     readers/vasculatureHDF5.cpp
+    section.cpp
+    soma.cpp
+    vasc/properties.cpp
     vasc/section.cpp
     vasc/vasculature.cpp
-    vasc/properties.cpp
+    vector_utils.cpp
+    version.cpp
     )
 
 if(NOT MORPHIO_VERSION_STRING)

diff --git a/src/endoplasmic_reticulum.cpp b/src/endoplasmic_reticulum.cpp
@@ -3,19 +3,19 @@
 
 namespace morphio {
 const std::vector<uint32_t>& EndoplasmicReticulum::sectionIndices() const {
-    return _properties->_endoplasmicReticulumLevel._sectionIndex;
+    return _properties->_endoplasmicReticulumLevel._sectionIndices;
 }
 
 const std::vector<float>& EndoplasmicReticulum::volumes() const {
-    return _properties->_endoplasmicReticulumLevel._volume;
+    return _properties->_endoplasmicReticulumLevel._volumes;
 }
 
 const std::vector<float>& EndoplasmicReticulum::surfaceAreas() const {
-    return _properties->_endoplasmicReticulumLevel._surfaceArea;
+    return _properties->_endoplasmicReticulumLevel._surfaceAreas;
 }
 
 const std::vector<uint32_t>& EndoplasmicReticulum::filamentCounts() const {
-    return _properties->_endoplasmicReticulumLevel._filamentCount;
+    return _properties->_endoplasmicReticulumLevel._filamentCounts;
 }
 
 }  // namespace morphio