{"id":20956566,"url":"https://github.com/bluebrain/morph-tool","last_synced_at":"2025-05-14T05:32:09.541Z","repository":{"id":37858552,"uuid":"246598161","full_name":"BlueBrain/morph-tool","owner":"BlueBrain","description":null,"archived":false,"fork":false,"pushed_at":"2024-03-20T12:10:48.000Z","size":2306,"stargazers_count":7,"open_issues_count":7,"forks_count":7,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-05-10T03:22:18.955Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BlueBrain.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.txt","dei":null}},"created_at":"2020-03-11T14:47:13.000Z","updated_at":"2024-03-25T20:05:57.000Z","dependencies_parsed_at":"2023-12-23T12:24:11.409Z","dependency_job_id":"ccb94da6-607c-4382-befe-4b47ff6e1b90","html_url":"https://github.com/BlueBrain/morph-tool","commit_stats":{"total_commits":152,"total_committers":19,"mean_commits":8.0,"dds":0.638157894736842,"last_synced_commit":"1f01e4391c055a2c1ba6bacb24d450e74a96952d"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueBrain%2Fmorph-tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueBrain%2Fmorph-tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueBrain%2Fmorph-tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueBrain%2Fmorph-tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BlueBrain","download_url":"https://codeload.github.com/BlueBrain/morph-tool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225277145,"owners_count":17448627,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-19T01:26:55.922Z","updated_at":"2025-05-14T05:32:09.527Z","avatar_url":"https://github.com/BlueBrain.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. warning::\n   The Blue Brain Project concluded in December 2024, so development has ceased under the BlueBrain GitHub organization.\n   Future development will take place at: https://github.com/openbraininstitute/morph-tool\n\n.. image:: doc/source/logo/BBP-Morph-Tool.jpg\n\n|docs|\n\nMorphTool\n=========\n\nA toolbox for morphology editing. It aims to provide small helper programs that perform simple tasks.\n\nCurrently MorphTool provides:\n\n- A morphology diffing tool (via CLI or python)\n- A file converter: to convert morphology files from/to the following formats: SWC, ASC, H5\n- A soma area calculator (as computed by NEURON, requires the NEURON python module)\n\nMorphIO v2 and NeuroM v1\n------------------------\nIf you want to work with old NeuroM v1 and MorphIO v2, use the version 2.4.7 of morph-tool.\n\nDocumentation\n-------------\n\nmorph-tool documentation is built and hosted on `readthedocs \u003chttps://morph-tool.readthedocs.org/\u003e`__.\n\n* `latest snapshot \u003chttps://morph-tool.readthedocs.org/en/latest/\u003e`_\n* `latest release \u003chttps://morph-tool.readthedocs.org/en/stable/\u003e`_\n\nInstallation\n------------\nIt is recommended to install in a fresh virtualenv.\n\nBase installation:\n\n.. code:: bash\n\n    pip install morph-tool\n\nIf plan to use `dendrogram` module:\n\n.. code:: bash\n\n    pip install morph-tool[plot]\n\nIf plan to use `nrnhines` module:\n\n.. code:: bash\n\n    pip install morph-tool[nrn]\n\nIf plan to convert folders of morphologies:\n\n.. code:: bash\n\n    pip install morph-tool[parallel]\n\nIf plan to use all available functionality:\n\n.. code:: bash\n\n    pip install morph-tool[all]\n\n\n\nUsage\n-----\n\nIn a shell, do:\n\n.. code:: bash\n\n    morph-tool --help\n\nCurrently the three sub-command are:\n\n.. code:: bash\n\n    morph-tool convert file input_file output_file\n    morph-tool diff morph1 morph2\n    morph-tool soma-surface input_file\n\nMorphology diffing\n------------------\nOne can compare two morphologies with the CLI\n\n.. code:: bash\n\n   morph-tool diff morph1 morph2\n\nwhose error code is 0 if morphologies are the same, else 1.\n\nMorphologies with different formats can be compared.\n\nMorphologies are considered different if one or more of the following properties differ:\n\n- number of root sections\n- sections type\n- sections point array\n- sections diameter array\n- sections perimeter array\n- sections number of children\n\nThe soma are *not* taken into consideration\n\nThe same functionality is also available through the python API:\n\n.. code:: python\n\n   from morph_tool import diff\n\n   # The result can be used as a boolean:\n   if diff(filename1, filename2):\n       print('morphologies differ')\n\n   # And also contains information about how morphologies differ\n   result = diff(filename1, filename2)\n   print(result.info)\n\n\nConverter\n---------\n\nWhat is supported ?\n~~~~~~~~~~~~~~~~~~~\n\nThe converter can be used to write morphology in different formats.\nCurrently, supported formats are ASC, SWC and H5.\n\nAs each format has its own specificities, data specific to a given\nformat will be discarded. This means the following will be lost during\nconversion:\n\n* spines (present in the ASC format)\n\n* all H5 metadata\n\n* the perimeter and mitochondrial data of the `H5 format \u003chttps://bbpteam.epfl.ch/documentation/Morphology%20Documentation-0.0.2/h5v1.html\u003e`__\n\nSoma intricacies\n~~~~~~~~~~~~~~~~\n\nMultiple formats are being used to represent somas (mainly) depending on\nthe file format. For more information about file format, see the `neuromorpho.org specification \u003chttp://neuromorpho.org/SomaFormat.html\u003e`__ or `MorphIO\nspecification \u003chttps://github.com/BlueBrain/MorphIO/blob/master/doc/specification.md#soma-formats\u003e`__\n\nBecause different soma format represent soma in different planes, soma\nformat conversion is not a bijective transformation. For example, it is\nnot possible to have an accurate conversion from a soma contour in the\nXY plane from a H5 file to a SWC soma which is represented as a cylinder\nalong Y.\n\nAs a result, it has been chosen to take the soma surface as an\ninvariant. This means soma surfaces of the input and output morphologies, as computed by NEURON, should be preserved.\n\nHere are the possible cases for the soma conversion:\n\n- SWC input file:\n\n  - SWC output file -\u003e no conversion\n  - H5 or ASC output file:\n\n    Depending on the original soma type:\n\n    - Soma stack of cylinders:\n      The soma is converted to a contour in the XY plane.\n      The points of the new contour are the outline of the soma stack projected in the XY plane.\n    - Soma three point cylinder:\n      The soma becomes a sphere of same surface. The contour made by the circle of biggest section in the XY plane is sampled in 20 points written to disk.\n    - Soma sphere (soma represented by a single point representing the center of a sphere and its radius): the contour made by the circle of biggest section in the XY plane is sampled in 20 points written to disk.\n    - other:\n      Not in SWC spec -\u003e not supported\n\n- H5 or ASC input file:\n\n  - H5 output file -\u003e no conversion needed\n  - ASC output file.\n\n    Depending on soma type:\n\n    - Soma single point sphere (soma represented by a single point representing the center of a sphere and its radius): the contour made by the circle of biggest section in the XY plane is sampled in 20 points written to disk.\n    - Soma contour: no conversion needed\n    - other: not in H5/ASC specs -\u003e not supported\n\n  - SWC:\n\n    Depending on soma format:\n\n    - Soma single point sphere: no conversion needed\n    - Soma contour: A soma stack of cylinder is generated.\n      Each cylinder of the stack has its center and its axis along the principal direction of the contour.\n      The radius of each stack is chosen such that it minimises the distance between the cylinder and the contour.\n    - other: not in H5/ASC specs -\u003e not supported\n\nExample:\n\n.. code:: python\n\n   from morph_tool import convert\n   convert(inputfile, outputfile)\n\n   # Additionally the morphology can be recentered or written according to the NEURON neurite order during the conversion\n   convert(inputfile, outputfile, recenter=True, nrn_order=True)\n\nThe same for bash\n\n.. code:: bash\n\n   morph-tool convert file ./inputfile ./outputfile\n   # with additional options\n   morph-tool convert file --recenter --nrn-order ./inputfile ./outputfile\n   # or an entire folder\n   morph-tool convert folder -ext SWC ./h5_input_folder ./swc_output_folder\n   # for more info use\n   morph-tool convert folder --help\n\nNRN simulator compartment coordinates\n-------------------------------------\n\nThe NRN simulator splits each section into chunks of equal length (equal only among a given section).\nThese compartments do not really exist in the physical world but we can remap them to paths\nalong the section. Each compartment can be associated to a path (a list of 3D points) such\nthat the path and the compartment have the same path-length.\n\nThe following function can be used to access the mapping NeuroM section ID -\u003e list of paths for the section:\n\n.. code:: python\n\n          morph_tool.nrnhines.NeuroM_section_to_NRN_compartment_paths\n\n\nExample (in 2D) for one section:\n\n.. code::\n\n                   (1, 2) ------ (2, 2)\n                      |\n                      |\n                      |\n                      |\n                      |\n                      |\n                      |\n                      |\n                      |\n    (0, 0) ------- (1, 0)\n\n\nSplitting this section into 3 compartments would results in the following paths:\n\n1.\n\n.. code::\n\n    [[0.        , 0.        ],\n     [1.        , 0.        ],\n     [1.        , 0.33333333]]\n\n2.\n\n.. code::\n\n   [[1.        , 0.33333333],\n    [1.        , 1.66666667]]\n\n3.\n\n.. code::\n\n   [[1.        , 1.66666667],\n    [1.        , 2.        ],\n    [2.        , 2.        ]]\n\n\nPlot morphologies with synapses\n-------------------------------\n\nThis functionality is available only when the package is installed with **plot** extras:\n\n.. code:: bash\n\n    pip install morph-tool[plot]\n\nDendrogram\n~~~~~~~~~~\n\nDraw NeuroM dendrogram with synapses on it. Synapses must be represented as a DataFrame. See\n`dendrogram \u003chttps://morph-tool.readthedocs.io/en/latest/morph_tool.plot.dendrogram.html\u003e`__.\n\nMorphology\n~~~~~~~~~~\n\nDraw NeuroM morphology with synapses on it. Synapses must be represented as a DataFrame. See\n`morphology \u003chttps://morph-tool.readthedocs.io/en/latest/morph_tool.plot.morphology.html\u003e`__.\n\nSimplification\n~~~~~~~~~~~~~~\n\nMorphTool can also be use to \"simplify\" morphologies.\nSee `morphology \u003chttps://morph-tool.readthedocs.io/en/latest/simplify.html\u003e`__.\n\n\nContributing\n------------\n\nIf you want to improve the project or you see any issue, every contribution is welcome.\nPlease check the `contribution guidelines \u003cCONTRIBUTING.md\u003e`__ for more information.\n\nAcknowledgements\n----------------\n\nThe 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.\n\nThis 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).\n\nLicense\n-------\n\nmorph-tool is licensed under the terms of the GNU Lesser General Public License version 3.\nRefer to COPYING.LESSER and COPYING for details.\n\nCopyright (c) 2018-2024 Blue Brain Project/EPFL\n\n.. |docs| image:: https://readthedocs.org/projects/morph-tool/badge/?version=latest\n             :target: https://morph-tool.readthedocs.io/\n             :alt: documentation status\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluebrain%2Fmorph-tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbluebrain%2Fmorph-tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluebrain%2Fmorph-tool/lists"}