Skip to content
This repository has been archived by the owner on Feb 26, 2025. It is now read-only.

Commit

Permalink
revise documentation (#917)
Browse files Browse the repository at this point in the history
  • Loading branch information
@asanin-epfl
asanin-epfl authored May 26, 2021
1 parent bea16be commit 19bfdf3
Show file tree
Hide file tree
Showing 15 changed files with 92 additions and 690 deletions.
156 changes: 12 additions & 144 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,156 +51,24 @@ NeuroM documentation is built and hosted on [readthedocs](https://readthedocs.or

Refer to [the doc page](https://neurom.readthedocs.io/en/latest/migration_v2.html) on this topic.

## Installation

It is recommended that you use [`pip`](https://pip.pypa.io/en/stable/) to install
`NeuroM` into a [`virtualenv`](https://virtualenv.pypa.io/en/stable/). The following
assumes a `virtualenv` named `nrm` has been set up and
activated. We will see three ways to install `NeuroM`


### 1. From the Python Package Index

```
(nrm)$ pip install neurom
```

### 2. From git repository

```
(nrm)$ pip install git+https://github.com/BlueBrain/NeuroM.git
```

### 3. From source

Clone the repository and install it:

```
(nrm)$ git clone https://github.com/BlueBrain/NeuroM.git
(nrm)$ pip install -e ./NeuroM
```

This installs `NeuroM` into your `virtualenv` in "editable" mode. That means changes
made to the source code are seen by the installation. To install in read-only mode, omit
the `-e`.

## Tutorial notebook

To gain an understanding of some of the capabilities of NeuroM, you can launch
the NeuroM tutorial on MyBinder. Click the badge to launch, no need to download or
install!

[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/BlueBrain/NeuroM.git/master?filepath=tutorial%2Fgetting_started.ipynb)

## Examples

- Extract morphometrics from one or many morphology files:

```
$ neurom stats some/path/morph.swc --full-config # single file
{
"some/path/morph.swc":{
"axon":{
"total_section_length":207.87975220908129,
"max_section_length":11.018460736176685,
"max_section_branch_order":10,
"total_section_volume":276.73857657289523
},
"all":{
"total_section_length":840.68521442251949,
"max_section_length":11.758281556059444,
"max_section_branch_order":10,
"total_section_volume":1104.9077419665782
},
"mean_soma_radius":0.17071067811865476,
"apical_dendrite":{
"total_section_length":214.37304577550353,
"max_section_length":11.758281556059444,
"max_section_branch_order":10,
"total_section_volume":271.9412385728449
},
"basal_dendrite":{
"total_section_length":418.43241643793476,
"max_section_length":11.652508126101711,
"max_section_branch_order":10,
"total_section_volume":556.22792682083821
}
}
}
$ neurom stats some/path --full-config # all files in directory
```

- Perform checks on neuron morphology files:

```
(nrm)$ neurom check some/data/path/morph_file.swc # single file
INFO: ========================================
INFO: File: some/data/path/morph_file.swc
INFO: Is single tree PASS
INFO: Has soma points PASS
INFO: Has sequential ids PASS
INFO: Has increasing ids PASS
INFO: Has valid soma PASS
INFO: Has valid neurites PASS
INFO: Has basal dendrite PASS
INFO: Has axon PASS
INFO: Has apical dendrite PASS
INFO: Has all nonzero segment lengths PASS
INFO: Has all nonzero section lengths PASS
INFO: Has all nonzero neurite radii PASS
INFO: Has nonzero soma radius PASS
INFO: ALL PASS
INFO: ========================================
(nrm)$ neurom check some/data/path # all files in directory
....
```

- Load a neuron and obtain some information from it:

```python
>>> import neurom as nm
>>> nrn = nm.load_neuron('some/data/path/morph_file.swc')
>>> apical_seg_lengths = nm.get('segment_lengths', nrn, neurite_type=nm.APICAL_DENDRITE)
>>> axon_sec_lengths = nm.get('section_lengths', nrn, neurite_type=nm.AXON)
```


- Visualize a neuronal morphology:

```python
>>> # Initialize nrn as above
>>> from neurom import viewer
>>> fig, ax = viewer.draw(nrn)
>>> fig.show()
>>> fig, ax = viewer.draw(nrn, mode='3d') # valid modes '2d', '3d', 'dendrogram'
>>> fig.show()
```


## Dependencies

The build-time and runtime dependencies of NeuroM are:

* [numpy](http://www.numpy.org/)
* [h5py](http://www.h5py.org/)
* [scipy](http://www.scipy.org/)
* [matplotlib](http://www.matplotlib.org/)
* [enum-compat](https://pypi.python.org/pypi/enum-compat/)
* [pyyaml](http://www.pyyaml.org/)


## Reporting issues

Issues should be reported to the
[NeuroM github repository issue tracker](https://github.com/BlueBrain/NeuroM/issues).
The ability and speed with which issues can be resolved depends on how complete and
succinct the report is. For this reason, it is recommended that reports be accompanied
with a minimal but self-contained code sample that reproduces the issue, the observed and
expected output, and if possible, the commit ID of the version used. If reporting a
regression, the commit ID of the change that introduced the problem is also extremely valuable
information.
with
* A minimal but self-contained code sample that reproduces the issue. Minimal means no
code that is irrelevant to the issue should be included. Self-contained means it should
be possible to run the code without modifications and reproduce the problem.
* The observed and expected output and/or behaviour. If the issue is an error, the python
error stack trace is extremely useful.
* The commit ID of the version used. This is particularly important if reporting an error
from an older version of NeuroM.
* If reporting a regression, the commit ID of the change that introduced the problem
* If the issue depends on data, a data sample which reproduces the problem should be
up-loaded. But check first whether the error can be reproduced with any of the data
samples available in the `tests/data` directory.

## Funding & Acknowledgements

Expand Down
5 changes: 3 additions & 2 deletions doc/source/api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Code Documentation
==================
API Documentation
=================

.. toctree::
:hidden:
Expand All @@ -53,3 +53,4 @@ Code Documentation
neurom.view
neurom.view.common
neurom.view.view
neurom.viewer
18 changes: 16 additions & 2 deletions doc/source/apps.rst → doc/source/cli.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Applications
************
Command Line Interface
**********************

NeuroM ships with configurable command line applications for commonly needed
functionality. These are convenience tools which leverage ``NeuroM`` library functionality
Expand All @@ -36,6 +36,20 @@ configuration scripts. These command-line tools are installed as executable scri
``NeuroM``. The tools are designed to be used in batch mode, i.e. they do not require any
user interactivity upon launch, and do not require access to a display.

For more information type in your terminal.

.. code-block:: bash
neurom --help
Also pay attention that logging options must be set immediately after ``neurom``. A single ``-v``
is used by default and outputs WARNING messages. ``-vv`` adds INFO messages. ``-vvv`` adds DEBUG
messages.

.. code-block:: bash
neurom -vvv <command> # example of DEBUG invocation
.. toctree::
:hidden:

Expand Down
44 changes: 6 additions & 38 deletions doc/source/definitions.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,39 +32,18 @@
NeuroM morphology definitions
=============================

These are ``NeuroM`` specific working definitions of various components of
neuron morphologies.
``NeuroM`` specific working definitions of various components of neuron morphologies.


.. _point-label:

Point
-----

A point is a vector of numbers **[X, Y, Z, R, TYPE, ID, PID]** where the components are
A point is a ``numpy`` array of numbers **[X, Y, Z, R]** where the components are

* X, Y, Z: Cartesian coordinates of position
* R: Radius
* TYPE: One of the :py:class:`NeuroM valid point types<neurom.core.dataformat.POINT_TYPE>`
* ID: Unique identifier of the point.
* PID: ID of the parent of the point.

Typically only the first four or five components are of interest to morphology analysis.
The rest are used to construct the soma and hierarchical tree structures of the neuron,
and to check its semantic validity.

In ``NeuroM`` a point is represented as an iterable of floating point numbers, usually
a ``numpy`` array.

.. note::
For most of what follows, it suffices to consider a
**point** as a vector of **[X, Y, Z, R, TYPE]**. The remaining
components **ID** and **PID** can be considered book-keeping.

.. todo::
Point types may need to be restricted to align SWC with H5. This is dependent on
future H5 specs.


.. _segment-label:

Expand All @@ -74,16 +53,15 @@ Segment
A segment consists of two consecutive :ref:`points<point-label>` belonging to
the same :ref:`neurite<neurite-label>` and :ref:`section<section-label>`.

In ``NeuroM`` a segment is represented as a length 2 tuple or ``numpy`` array of
`points<point-label>`.
In ``NeuroM`` a segment is represented as a tuple or a ``numpy`` array of two `points<point-label>`.


.. _section-label:

Section
-------

A section is a tree node containing a series of two or more :ref:`points<point-label>`
A section is a node of morphology tree containing a series of two or more :ref:`points<point-label>`
whose first and last element are any of the following combinations:

* root node, forking point
Expand All @@ -94,24 +72,14 @@ whose first and last element are any of the following combinations:
The first point of a section is a duplicate of the last point of its parent section,
unless the latter is a soma section.

In ``NeuroM``, a section is represented by class :py:class:`Section<neurom.core.Section>`.
This pseudocode shows the relevant parts of the section class:

.. code-block:: python
section = {
section_id,
points,
parent,
children
}
In ``NeuroM``, a section is represented by class :class:`Section<neurom.core.neuron.Section>`.

.. _soma-label:

Soma
----

A soma can be represented by one, three or more :ref:`points<point-label>`.
A soma can be represented by one or more :ref:`points<point-label>`.
The soma is classified solely based on the number of points it contains thus:

* Type A: 1 point defining the center and radius.
Expand Down
68 changes: 0 additions & 68 deletions doc/source/dependencies.rst
View file

This file was deleted.

Loading

0 comments on commit 19bfdf3

Please sign in to comment.