docs: update API page and some docstrings

docs/source/api.rst

@@ -42,15 +42,14 @@ learn more!
 
 .. _api_neurons:
 
-Neuron/List
-+++++++++++
+Neurons & NeuronLists
++++++++++++++++++++++
 ``TreeNeurons``, ``MeshNeurons``, ``VoxelNeurons`` and ``Dotprops`` are neuron
 classes. ``NeuronLists`` are containers thereof.
 
 .. autosummary::
     :toctree: generated/
 
-    navis.BaseNeuron
     navis.TreeNeuron
     navis.MeshNeuron
     navis.VoxelNeuron
@@ -94,8 +93,9 @@ to all neurons:
 
 TreeNeurons
 -----------
-These are class methods available specific for ``TreeNeurons``. Most of them are
-simply short-hands for the other navis functions:
+A :class:`navis.TreeNeuron` is a skeletons. These are class methods available specific for
+this neuron type. Note that most of them are simply short-hands for the other
+``navis`` functions:
 
 .. autosummary::
     :toctree: generated/
@@ -116,7 +116,7 @@ simply short-hands for the other navis functions:
     ~navis.TreeNeuron.resample
     ~navis.TreeNeuron.snap
 
-In addition ``TreeNeurons`` have a range of different properties:
+In addition, a :class:`navis.TreeNeuron` has a range of different properties:
 
 .. autosummary::
     :toctree: generated/
@@ -143,25 +143,33 @@ In addition ``TreeNeurons`` have a range of different properties:
 
 MeshNeurons
 -----------
-These are methods and properties specific to ``MeshNeurons``.
+Properties specific to :class:`navis.MeshNeuron`:
 
 .. autosummary::
     :toctree: generated/
 
     ~navis.MeshNeuron.faces
     ~navis.MeshNeuron.vertices
-    ~navis.MeshNeuron.skeletonize
-    ~navis.MeshNeuron.snap
     ~navis.MeshNeuron.trimesh
     ~navis.MeshNeuron.volume
+    ~navis.MeshNeuron.sampling_resolution
+
+Methods specific to :class:`navis.MeshNeuron`:
+
+.. autosummary::
+    :toctree: generated/
+
+    ~navis.MeshNeuron.skeletonize
+    ~navis.MeshNeuron.snap
     ~navis.MeshNeuron.validate
 
 
 VoxelNeurons
 ------------
-VoxelNeurons (e.g. from confocal stacks) are a relatively new addition to
-navis and the interface might still change.
-These are methods and properties specific to ``VoxelNeurons``.
+:class:`navis.VoxelNeurons` (e.g. from confocal image stacks) are a relatively
+recet addition to navis and the interface might still change.
+
+These are methods and properties specific to ``VoxelNeurons``:
 
 .. autosummary::
     :toctree: generated/
@@ -174,7 +182,10 @@ These are methods and properties specific to ``VoxelNeurons``.
 
 Dotprops
 --------
-These are methods and properties specific to ``Dotprops``.
+:class:`navis.Dotprops`` are typically indirectly generated from e.g. skeletons or
+point clouds using :func:`navis.make_dotprops`.
+
+These are methods and properties specific to ``Dotprops``:
 
 .. autosummary::
     :toctree: generated/
@@ -185,9 +196,6 @@ These are methods and properties specific to ``Dotprops``.
     ~navis.Dotprops.to_skeleton
     ~navis.Dotprops.snap
 
-Dotprops are typically indirectly generated from e.g. skeletons or
-point clouds using :func:`navis.make_dotprops`.
-
 
 Conversion
 ----------
@@ -200,6 +208,8 @@ There are a couple functions to convert from one neuron type to another:
     navis.skeletonize
     navis.mesh
     navis.voxelize
+    navis.conversion.voxels2mesh
+    navis.conversion.tree2meshneuron
 
 
 NeuronList methods
@@ -237,6 +247,9 @@ Properties:
     ~navis.NeuronList.shape
     ~navis.NeuronList.types
 
+Please see the ref:`tutorial<neuron_overview>` on ``NeuronLists`` for more
+information, including how to index them.
+
 .. _api_plot:
 
 Visualization
@@ -420,7 +433,8 @@ Functions to calculate Euclidian and geodesic ("along-the-arbor") distances.
 
 Intersection
 ------------
-Functions to intersect points and neurons with volumes.
+Functions to intersect points and neurons with volumes. For example, if you'd
+like to know which part of a neuron is inside a certain brain region.
 
 .. autosummary::
     :toctree: generated/
@@ -432,8 +446,9 @@ Functions to intersect points and neurons with volumes.
 
 Transforming and Mirroring
 ++++++++++++++++++++++++++
-Functions to transform spatial data e.g. between template brains.
-Check out the :ref:`tutorials<example_gallery>` for examples on how to use them.
+Functions to transform spatial data, e.g. move neurons from one brain space to
+another. Check out the :ref:`tutorials<example_gallery>` for examples on how to
+use them.
 
 High-level functions:
 
@@ -470,10 +485,14 @@ The ``TemplateRegistry`` keeps track of template brains, transforms and such:
 
     ~navis.transforms.templates.TemplateRegistry
 
-This relevant instance of this class is ``navis.transforms.registry``. So to
-register a new transform you would for example do this::
+The relevant instance of this class is ``navis.transforms.registry``. So to
+register and use a new transform you would do this for example::
 
-  >>> navis.transforms.registry.register_transform(transform, ...)
+  >>> transform = navis.transforms.AffineTransform(...)
+  >>> navis.transforms.registry.register_transform(transform,
+  ...                                              source='brainA',
+  ...                                              target='brainB')
+  >>> xf = navis.xform_brain(data, 'brainA', 'brainB')
 
 These are the methods and properties of ``registry``:
 
@@ -508,7 +527,7 @@ Collection of functions to work with graphs and adjacency matrices.
 
 Graphs
 ------
-Functions to convert neurons and networkx to iGraph or networkX graphs.
+Functions to convert between neurons graph representation (networkx or iGraph).
 
 .. autosummary::
     :toctree: generated/
@@ -930,11 +949,11 @@ Neuron types and functions
 ++++++++++++++++++++++++++
 
 As you can imagine not all functions will work on all neuron types. For example
-it is currently not possible to find the longest neurite
-(:func:`navis.longest_neurite`) in a ``VoxelNeuron``. Conversely, some
+it is currently not possible to find the longest neurite via
+:func:`navis.longest_neurite` for a ``VoxelNeuron``. Conversely, some
 functionality like "smoothing" makes sense for multiple neuron types but the
 application is so vastly different between e.g. meshes and skeletons that
-there is no single function but one for each neuron type.
+there are specicialized functions for every neuron type.
 
 Below table has an overview for which functions work with which neuron types.
 

navis/conversion/converters.py

@@ -150,7 +150,7 @@ def mesh2skeleton(x: 'core.MeshNeuron',
     shave :     bool
                 Whether to "shave" the resulting skeleton to reduce bristles
                 on the backbone.
-    heal :      bool
+    heal :      bool | "LEAFS" | "ALL"
                 Whether to heal the resulting skeleton if it is fragmented.
                 For more control over the stitching set `heal=False` and use
                 :func:`navis.heal_skeleton` directly. Note that this

navis/core/base.py

@@ -338,7 +338,11 @@ def extents(self) -> np.ndarray:
 
     @property
     def id(self) -> Any:
-        """Hashable ID."""
+        """ID of the neuron.
+
+        Must be hashable. If not set, will assign a random unique identifier.
+        Can be indexed by using the ``NeuronList.idx[]`` locator.
+        """
         return getattr(self, '_id', None)
 
     @id.setter
@@ -412,7 +416,7 @@ def connectors(self, v):
 
     @property
     def presynapses(self):
-        """Table with presynapses.
+        """Table with presynapses (filtered from connectors table).
 
         Requires a "type" column in connector table. Will look for type labels
         that include "pre" or that equal 0 or "0".
@@ -433,7 +437,7 @@ def presynapses(self):
 
     @property
     def postsynapses(self):
-        """Table with postsynapses.
+        """Table with postsynapses (filtered from connectors table).
 
         Requires a "type" column in connector table. Will look for type labels
         that include "post" or that equal 1 or "1".

navis/core/dotprop.py

@@ -198,7 +198,7 @@ def __getstate__(self):
 
     @property
     def alpha(self):
-        """Alpha value for tangent vectors."""
+        """Alpha value for tangent vectors (optional)."""
         if isinstance(self._alpha, type(None)):
             if isinstance(self.k, type(None)) or (self.k <= 0):
                 raise ValueError('Unable to calculate `alpha` for Dotprops not '

navis/core/skeleton.py

@@ -458,7 +458,7 @@ def _set_connectors(self, v):
     @property
     @requires_nodes
     def cycles(self) -> Optional[List[int]]:
-        """Cycles in neuron if any.
+        """Cycles in neuron (if any).
 
         See also
         --------
@@ -477,11 +477,7 @@ def cycles(self) -> Optional[List[int]]:
 
     @property
     def simple(self) -> 'TreeNeuron':
-        """Return simple neuron representation.
-
-        Consists only of root, branch points and leafs.
-
-        """
+        """Simplified representation consisting only of root, branch points and leafs."""
         if not hasattr(self, '_simple'):
             self._simple = self.downsample(float('inf'),
                                            inplace=False)
@@ -594,6 +590,12 @@ def n_branches(self) -> Optional[int]:
         """Number of branch points."""
         return self.nodes[self.nodes.type == 'branch'].shape[0]
 
+    @property
+    @requires_nodes
+    def n_leafs(self) -> Optional[int]:
+        """Number of leaf nodes."""
+        return self.nodes[self.nodes.type == 'end'].shape[0]
+
     @temp_property
     def cable_length(self) -> Union[int, float]:
         """Cable length."""
@@ -675,7 +677,7 @@ def bbox(self) -> np.ndarray:
 
     @property
     def sampling_resolution(self) -> float:
-        """Average cable length between 2 nodes."""
+        """Average cable length between child -> parent nodes."""
         return self.cable_length / self.n_nodes
 
     @temp_property
@@ -710,7 +712,7 @@ def _get_segments(self,
 
     @property
     def n_skeletons(self) -> int:
-        """Return number of seperate skeletons in this neuron."""
+        """Number of seperate skeletons in this neuron."""
         return len(self.root)
 
     def _clear_temp_attr(self, exclude: list = []) -> None:

navis/morpho/fq.py

@@ -67,7 +67,8 @@ def form_factor(x: Union['core.TreeNeuron', 'core.MeshNeuron'],
                 Number of cores to use when ``x`` is a NeuronList and
                 ``parallel=True``. Even on a single core this function makes
                 heavy use of numpy which itself uses multiple threads - it is
-                therefore not
+                therefore not advisable to use all your cores as this would
+                create a bottleneck.
     progress :  bool
                 Whether to show a progress bar.
 
@@ -87,6 +88,7 @@ def form_factor(x: Union['core.TreeNeuron', 'core.MeshNeuron'],
     --------
     >>> import navis
     >>> nl = navis.example_neurons(3)
+    >>> nl = nl.convert_units('microns')
     >>> # Resample to 1 node / micron
     >>> rs = navis.resample_skeleton(nl, '1 micron')
     >>> # Calculate form factor

navis/morpho/mmetrics.py

@@ -632,17 +632,17 @@ def bending_flow(x: 'core.NeuronObject') -> 'core.NeuronObject':
     and counting the number of pre->post synapse paths that "flow" from one
     child branch to the other(s).
 
-    Parameters
-    ----------
-    x :         TreeNeuron | MeshNeuron | NeuronList
-                Neuron(s) to calculate bending flow for. Must have connectors!
-
     Notes
     -----
     This is algorithm appears to be more reliable than synapse flow
     centrality for identifying the main branch point for neurons that have
     incompletely annotated synapses.
 
+    Parameters
+    ----------
+    x :         TreeNeuron | MeshNeuron | NeuronList
+                Neuron(s) to calculate bending flow for. Must have connectors!
+
     Returns
     -------
     neuron