Skip to content

Commit

Permalink
Clean doc warnings (#1124)
Browse files Browse the repository at this point in the history
* clean doc lints
  • Loading branch information
mgeplf authored Jun 11, 2024
1 parent bb39f2a commit 6705714
Show file tree
Hide file tree
Showing 17 changed files with 84 additions and 87 deletions.
7 changes: 3 additions & 4 deletions CHANGELOG.rst
Original file line number Diff line number Diff line change
Expand Up @@ -145,8 +145,8 @@ Version 2.3.1

Version 2.3.0
-------------
- Introduce a new method to calculate partition asymmetry by Uylings. See docstring of
:func:`neurom.features.neuritefunc.partition_asymmetries`.
- Introduce a new method to calculate partition asymmetry by Uylings.
See docstring of `neurom.features.neuritefunc.partition_asymmetries`.
- Follow the same morphology validation rules as in MorphIO. See the :ref:`doc page<validation>`
about it.
- Remove the cli command ``neurom features`` that listed all possible features. Instead a proper
Expand All @@ -161,8 +161,7 @@ Version 2.2.1
Version 2.2.0
-------------
- Don't force loading of neurons into memory for Population (#922). See new API of
:class:`Population<neurom.core.population.Population>` and
:func:`load_neurons<neurom.io.utils.load_neurons>`
:class:`Population<neurom.core.population.Population>` and `load_neurons<neurom.io.utils.load_neurons>`
- Move ``total_length`` feature to from ``neuritefunc`` to ``neuronfunc``. Use ``neurite_lengths``
feature for neurites
- Include morphology filename extension into Neuron's name
Expand Down
3 changes: 3 additions & 0 deletions doc/source/api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@ API Documentation
:nosignatures:
:toctree: _neurom_build

neurom
neurom.get
neurom.morphmath
neurom.features
neurom.features.population
Expand All @@ -53,6 +55,7 @@ API Documentation
neurom.core.soma
neurom.core.dataformat
neurom.io.utils
neurom.view
neurom.view.dendrogram
neurom.view.matplotlib_utils
neurom.view.matplotlib_impl
Expand Down
10 changes: 8 additions & 2 deletions doc/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,6 @@
# All configuration values have a default; values that are commented out
# serve to show the default.

import sys
import os
import importlib.metadata

VERSION = importlib.metadata.version('neurom')
Expand All @@ -63,6 +61,14 @@
'sphinx.ext.doctest',
]

nitpicky = True
nitpick_ignore = [
("py:class", "Path"),
("py:class", "morphio.Morphology"),
("py:class", "morphio.mut.Morphology"),
("py:class", "morphio.Section"),
("py:class", "morphio.Soma"),
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Expand Down
9 changes: 4 additions & 5 deletions doc/source/morph_stats.rst
Original file line number Diff line number Diff line change
Expand Up @@ -86,8 +86,7 @@ Here, there are two feature categories,
2. ``neuron``: these are morphometrics that can be applied to a whole morphology, e.g. the soma radius,
the trunk radii, etc.

Each category sub-item (section_lengths, soma_radius, etc) corresponds to a
:py:func:`neurom.get` feature, and each one of its sub-items corresponds to a statistic aggregating
Each category sub-item (section_lengths, soma_radius, etc) corresponds to a :py:func:`neurom.get` feature, and each one of its sub-items corresponds to a statistic aggregating
function, e.g.

* ``raw``: array of raw values
Expand Down Expand Up @@ -140,9 +139,9 @@ The new format:
- requires to use ``sum`` instead of ``total`` statistic aggregating function.
- allows to specify features arguments.

For example, ``partition_asymmetry`` feature has additional arguments like ``method`` and
``variant`` (see :py:func:`neurom.features.neurite.partition_asymmetries`). Before it wasn't
possible to set them. Here is how you can set them now:
For example, ``partition_asymmetry`` feature has additional arguments like ``method`` and ``variant``.
Before it wasn't possible to set them.
Here is how you can set them now:

.. code-block:: yaml
Expand Down
6 changes: 3 additions & 3 deletions doc/source/quickstart.rst
Original file line number Diff line number Diff line change
Expand Up @@ -85,13 +85,13 @@ we apply a simple user defined function to the apical dendrites in a population:

stuff = [x for x in nm.iter_neurites(pop, user_func, lambda n : n.type == nm.APICAL_DENDRITE)]

View morphologies with :mod:`neurom.viewer`
View morphologies with :mod:`neurom.view`
-------------------------------------------

There are also helper functions to plot a morphology in 2 and 3 dimensions.

:func:`neurom.viewer.draw` function allows the user to make two and three-dimensional
plots of neurites, somata and morphologies. It also has a dendrogram morphology plotting mode.
:func:`neurom.view` function allows the user to make two and three-dimensional plots of neurites, somata and morphologies.
It also has a dendrogram morphology plotting mode.


Extract morphometrics into JSON files
Expand Down
18 changes: 8 additions & 10 deletions neurom/check/morphology_checks.py
Original file line number Diff line number Diff line change
Expand Up @@ -98,8 +98,8 @@ def has_no_flat_neurites(morph, tol=0.1, method='ratio'):
Arguments:
morph(Morphology): The morphology object to test
tol(float): tolerance
method(string): way of determining flatness, 'tolerance', 'ratio' \
as described in :meth:`neurom.check.morphtree.get_flat_neurites`
method(str): way of determining flatness, 'tolerance', 'ratio'
as described in :meth:`neurom.check.morphtree.get_flat_neurites`
Returns:
CheckResult with result
Expand Down Expand Up @@ -184,8 +184,7 @@ def has_no_jumps(morph, max_distance=30.0, axis='z'):
Arguments:
morph(Morphology): the morphology to test
max_distance(float): value above which consecutive z-values are
considered a jump
max_distance(float): value above which consecutive z-values are considered a jump
axis(str): one of x/y/z, which axis to check for jumps
Returns:
Expand Down Expand Up @@ -228,11 +227,11 @@ def has_no_fat_ends(morph, multiple_of_mean=2.0, final_point_count=5):
Arguments:
morph(Morphology): the morphology to test
multiple_of_mean(float): how many times larger the final radius
has to be compared to the mean of the final points
has to be compared to the mean of the final points
final_point_count(int): how many points to include in the mean
Returns:
CheckResult with result list of ids of bad sections
CheckResult with a list of all ids of bad sections
Note:
A fat end is defined as a leaf segment whose last point is larger
Expand Down Expand Up @@ -321,14 +320,13 @@ def has_no_narrow_neurite_section(
Arguments:
morph(Morphology): the morphology to test
neurite_filter(callable): filter the neurites by this callable
neurite_filter(Callable): filter the neurites by this callable
radius_threshold(float): radii below this are considered narro
considered_section_min_length(float): sections with length below
this are not taken into account
this are not taken into account
Returns:
CheckResult with result. `result.info` contains the narrow section ids and their
first point
CheckResult with result. `result.info` contains the narrow section ids and their first point
"""
considered_sections = (
sec
Expand Down
6 changes: 3 additions & 3 deletions neurom/check/morphtree.py
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ def is_flat(neurite, tol, method='tolerance'):
Args:
neurite(Neurite): neurite to operate on
tol(float): tolerance
method(string): the method of flatness estimation:
method(str): the method of flatness estimation:
'tolerance' returns true if any extent of the tree is smaller
than the given tolerance
'ratio' returns true if the ratio of the smallest directions
Expand Down Expand Up @@ -196,7 +196,7 @@ def is_back_tracking(neurite):
neurite(Neurite): neurite to operate on
Returns:
True Under the following scenaria:
bool: True when;
1. A segment endpoint falls back and overlaps with a previous segment's point
2. The geometry of a segment overlaps with a previous one in the section
"""
Expand Down Expand Up @@ -270,7 +270,7 @@ def get_flat_neurites(morph, tol=0.1, method='ratio'):
Args:
morph(Morphology): morphology to operate on
tol(float): the tolerance or the ratio
method(string): 'tolerance' or 'ratio' described in :meth:`is_flat`
method(str): 'tolerance' or 'ratio' described in :meth:`is_flat`
Returns:
Bool list corresponding to the flatness check for each neurite
Expand Down
2 changes: 1 addition & 1 deletion neurom/core/population.py
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ def __init__(
"""Construct a morphology population.
Arguments:
files (collections.abc.Sequence[str|Path|Morphology]): collection of morphology files or
files (Sequence[str|Morphology|Path]): collection of morphology files or
paths to them or instances of ``Morphology``.
name (str): Optional name for this Population
ignored_exceptions (tuple): NeuroM and MorphIO exceptions that you want to ignore when
Expand Down
3 changes: 1 addition & 2 deletions neurom/core/types.py
Original file line number Diff line number Diff line change
Expand Up @@ -184,8 +184,7 @@ def tree_type_checker(*ref):
"""Tree type checker functor.
Args:
*ref(NeuriteType|tuple): Either a single NeuriteType or a variable list of them or a tuple
of them.
*ref(NeuriteType|tuple): Either a single NeuriteType, list of them or a tuple of them.
Returns:
Functor that takes a tree, and returns true if that tree matches any of
Expand Down
9 changes: 4 additions & 5 deletions neurom/features/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,6 @@
>>> ax_sec_len = features.get('section_lengths', m, neurite_type=neurom.AXON)
"""

import inspect
import operator
from enum import Enum
from functools import partial, reduce, wraps
Expand Down Expand Up @@ -174,12 +173,12 @@ def get(feature_name, obj, **kwargs):
For Population features see :mod:`neurom.features.population`.
Arguments:
feature_name(string): feature to extract
feature_name(str): feature to extract
obj: a morphology, a morphology population or a neurite tree
kwargs: parameters to forward to underlying worker functions
Returns:
List|Number: feature value as a list or a single number.
List|float: feature value as a list or a single number.
"""
return _get_feature_value_and_func(feature_name, obj, **kwargs)[0]

Expand Down Expand Up @@ -214,8 +213,8 @@ def feature(shape, namespace: NameSpace, name=None):
Arguments:
shape(tuple): the expected shape of the feature values
namespace(string): a namespace, see :class:`NameSpace`
name(string): name of the feature, used to access the feature via `neurom.features.get()`.
namespace(str): a namespace, see :class:`NameSpace`
name(str): name of the feature, used to access the feature via `neurom.features.get()`.
"""

def inner(func):
Expand Down
6 changes: 3 additions & 3 deletions neurom/features/morphology.py
Original file line number Diff line number Diff line change
Expand Up @@ -595,7 +595,7 @@ def sholl_crossings(morph, neurite_type=NeuriteType.all, center=None, radii=None
morph(Morphology|list): morphology or a list of neurites
neurite_type(NeuriteType): Type of neurite to use. By default ``NeuriteType.all`` is used.
center(Point): center point, if None then soma center is taken
radii(iterable of floats): radii for which crossings will be counted,
radii: iterable of floats for which crossings will be counted,
if None then soma radius is taken
Returns:
Expand Down Expand Up @@ -658,8 +658,8 @@ def sholl_frequency(morph, neurite_type=NeuriteType.all, step_size=10, bins=None
morph(Morphology): a morphology
neurite_type(NeuriteType): which neurites to operate on
step_size(float): step size between Sholl radii
bins(iterable of floats): custom binning to use for the Sholl radii. If None, it uses
intervals of step_size between min and max radii of ``morphologies``.
bins: iterable of floats defining custom binning to use for the Sholl radii.
If None, it uses intervals of step_size between min and max radii of ``morphologies``.
Note:
Given a morphology, the soma center is used for the concentric circles,
Expand Down
3 changes: 1 addition & 2 deletions neurom/features/neurite.py
Original file line number Diff line number Diff line change
Expand Up @@ -317,8 +317,7 @@ def partition_asymmetry(
Variant: length is a different definition, as the absolute difference in
downstream path lenghts, relative to the total neurite path length
Method: 'petilla' or 'uylings'. The former is default. The latter uses ``-2`` shift. See
:func:`neurom.features.bifurcationfunc.partition_asymmetry`
Method: 'petilla' or 'uylings'. The former is default. The latter uses ``-2`` shift.
"""
if variant not in {'branch-order', 'length'}:
raise ValueError(
Expand Down
4 changes: 2 additions & 2 deletions neurom/features/population.py
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,8 @@ def sholl_frequency(morphs, neurite_type=NeuriteType.all, step_size=10, bins=Non
morphs(list|Population): list of morphologies or morphology population
neurite_type(NeuriteType): which neurites to operate on
step_size(float): step size between Sholl radii
bins(iterable of floats): custom binning to use for the Sholl radii. If None, it uses
intervals of step_size between min and max radii of ``morphs``.
bins(Iterable[float]): custom binning to use for the Sholl radii.
If None, it uses intervals of step_size between min and max radii of ``morphs``.
use_subtrees (bool): Enable mixed subtree processing.
Note:
Expand Down
30 changes: 12 additions & 18 deletions neurom/morphmath.py
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,7 @@ def vector(p1, p2):
"""Compute vector between two 3D points.
Args:
p1, p2: indexable objects with
indices 0, 1, 2 corresponding to 3D cartesian coordinates.
p1, p2: indexable objects with indices 0, 1, 2 corresponding to 3D cartesian coordinates.
Returns:
3-vector from p1 - p2
Expand Down Expand Up @@ -120,7 +119,7 @@ def path_fraction_id_offset(points, fraction, relative_offset=False):
Args:
points: an iterable of indexable objects with indices
0, 1, 2 correspoding to 3D cartesian coordinates
0, 1, 2 correspoding to 3D cartesian coordinates
fraction: path length fraction (0.0 <= fraction <= 1.0)
relative_offset: return absolute or relative segment distance
Expand Down Expand Up @@ -149,7 +148,7 @@ def path_fraction_point(points, fraction):
Args:
points: an iterable of indexable objects with indices
0, 1, 2 correspoding to 3D cartesian coordinates
0, 1, 2 correspoding to 3D cartesian coordinates
fraction: path length fraction (0 <= fraction <= 1)
Returns:
Expand All @@ -163,8 +162,7 @@ def scalar_projection(v1, v2):
"""Compute the scalar projection of v1 upon v2.
Args:
v1, v2: iterable
indices 0, 1, 2 corresponding to cartesian coordinates
v1, v2: iterable indices 0, 1, 2 corresponding to cartesian coordinates
Returns:
3-vector of the projection of point p onto the direction of v
Expand All @@ -176,8 +174,7 @@ def vector_projection(v1, v2):
"""Compute the vector projection of v1 upon v2.
Args:
v1, v2: iterable
indices 0, 1, 2 corresponding to cartesian coordinates
v1, v2: iterable indices 0, 1, 2 corresponding to cartesian coordinates
Returns:
3-vector of the projection of point p onto the direction of v
Expand Down Expand Up @@ -206,8 +203,7 @@ def point_dist2(p1, p2):
"""Compute the square of the euclidian distance between two 3D points.
Args:
p1, p2: indexable objects with
indices 0, 1, 2 corresponding to 3D cartesian coordinates.
p1, p2: indexable objects with indices 0, 1, 2 corresponding to 3D cartesian coordinates.
Returns:
The square of the euclidian distance between the points.
Expand All @@ -220,8 +216,7 @@ def point_dist(p1, p2):
"""Compute the euclidian distance between two 3D points.
Args:
p1, p2: indexable objects with
indices 0, 1, 2 corresponding to 3D cartesian coordinates.
p1, p2: indexable objects with indices 0, 1, 2 corresponding to 3D cartesian coordinates.
Returns:
The euclidian distance between the points.
Expand All @@ -236,7 +231,7 @@ def angle_3points(p0, p1, p2):
Args:
p0, p1, p2: indexable objects with
indices 0, 1, 2 corresponding to 3D cartesian coordinates.
indices 0, 1, 2 corresponding to 3D cartesian coordinates.
Returns:
Angle in radians between (p1-p0) and (p2-p0).
Expand Down Expand Up @@ -392,9 +387,8 @@ def segment_radial_dist(seg, pos):
Arguments:
seg: tree segment
pos: origin to which distances are measured. It must have at lease 3
components. The first 3 components are (x, y, z).
pos: origin to which distances are measured.
It must have at lease 3 components. The first 3 components are (x, y, z).
"""
return point_dist(pos, np.divide(np.add(seg[0], seg[1]), 2.0))

Expand Down Expand Up @@ -475,10 +469,10 @@ def principal_direction_extent(points):
directions of the covariance matrix of the points.
Args:
points : a 2D numpy array of points with 2 or 3 columns for (x, y, z)
points: a 2D numpy array of points with 2 or 3 columns for (x, y, z)
Returns:
extents : the extents for each of the eigenvectors of the cov matrix
the extents for each of the eigenvectors of the cov matrix
Note:
Direction extents are ordered from largest to smallest.
Expand Down
Loading

0 comments on commit 6705714

Please sign in to comment.