Segments

For some operations (e.g. plotting) it is useful to break the graph into its linear components. You can do so by simply "breaking" the graph at each branch point, effectively producing linear segments that connect leafs, branch points and roots. Alternatively, you can try to make as few cuts as possible resulting in fewer and longer linear segments.

Figure 1: Breaking neurons into linear components with as few cuts as possible. The alternative would be to introduce a break at node 2 resulting in 3 separate segments. This is the same toy skeleton used in the code examples below.

Generate Segments

`navis_fastcore.generate_segments(node_ids, parent_ids, weights=None)`

Generate linear segments maximizing segment lengths.

PARAMETER	DESCRIPTION
`node_ids`	`Array node IDs.` TYPE: `(N, ) array`
`parent_ids`	`Array of parent IDs for each node. Root nodes' parents must be -1.` TYPE: `(N, ) array`
`weights`	Array of distances for each child -> parent connection. If ``None`` all node-to-node distances are set to 1. TYPE: `(N, ) float32 array` DEFAULT: `None`

RETURNS	DESCRIPTION
`segments`	Segments as list of arrays, sorted from longest to shortest. Each segment starts with a leaf and stops with a branch point or root node. TYPE: `list of arrays`
`lengths`	Length for each segment. If `weights` is provided this will be the physical length. Otherwise it will be the number of nodes. TYPE: `array`

Examples:

>>> import navis_fastcore as fastcore
>>> import numpy as np
>>> node_ids = np.arange(7)
>>> parent_ids = np.array([-1, 0, 1, 2, 1, 4, 5])
>>> segs, length = fastcore.generate_segments(node_ids, parent_ids)
>>> segs
[array([6, 5, 4, 1, 0]), array([3, 2, 1])]
>>> length
array([5, 3], dtype=int32)

`navis_fastcore.break_segments(node_ids, parent_ids)`

Break neuron into linear segments connecting ends, branches and root.

PARAMETER	DESCRIPTION
`node_ids`	`Array node IDs.` TYPE: `(N, ) array`
`parent_ids`	`Array of parent IDs for each node. Root nodes' parents must be -1.` TYPE: `(N, ) array`

RETURNS	DESCRIPTION
`segments`	Segments as list of arrays. TYPE: `list of arrays`

Examples:

>>> import navis_fastcore as fastcore
>>> import numpy as np
>>> node_ids = np.arange(7)
>>> parent_ids = np.array([-1, 0, 1, 2, 1, 4, 5])
>>> fastcore.break_segments(node_ids, parent_ids)
[array([1, 0]), array([3, 2]), array([6, 5, 4])]

Segment Coordinates

`navis_fastcore.segment_coords(node_ids, parent_ids, coords, weights=None, node_colors=None)`

Generate coordinates for linear segments.

This is useful for plotting the skeleton of a neuron.

PARAMETER	DESCRIPTION
`node_ids`	`Array node IDs.` TYPE: `(N, ) array`
`parent_ids`	`Array of parent IDs for each node. Root nodes' parents must be -1.` TYPE: `(N, ) array`
`coords`	`Array of coordinates for each node.` TYPE: `(N, 3) array`
`node_colors`	A color for each node in `node_ids`. If provided, will also return a list of colors sorted to match coordinates. TYPE: `(N, ) numpy.ndarray` DEFAULT: `None`

RETURNS	DESCRIPTION
`seg_coords`	TYPE: `list of arrays`
`colors`	If `node_colors` provided will return a copy of it sorted to match `seg_coords`. TYPE: `list of colors`

Examples:

>>> import navis_fastcore as fastcore
>>> import numpy as np
>>> node_ids = np.arange(7)
>>> parent_ids = np.array([-1, 0, 1, 2, 1, 4, 5])
>>> coords = np.random.rand(7, 3)
>>> fastcore.segment_coords(node_ids, parent_ids, coords)
[array([[5.30713899e-01, 8.26450947e-01, 2.46805326e-01],
        [1.54144332e-04, 9.07823578e-01, 3.20199043e-01],
        [6.64580597e-01, 3.23724555e-01, 3.18361918e-01],
        [7.16579499e-01, 8.65568868e-02, 7.15686948e-01],
        [5.94874740e-01, 5.95528161e-01, 8.14234930e-01]]),
array([[0.47814894, 0.84468164, 0.2765942 ],
        [0.21748528, 0.36673489, 0.81449368],
        [0.7165795 , 0.08655689, 0.71568695]])]