Geodesic Distances

`navis_fastcore.geodesic_matrix(node_ids, parent_ids, directed=False, sources=None, targets=None, weights=None)`

Calculate geodesic ("along-the-arbor") distances.

Notes

Under-the-hood, this uses two different implementations depending on whether a full all-by-all or a partial (via sources/targets) matrix is requested. The partial implementation is faster and more memory efficient for small-ish subsets of nodes. However, for subsets that include a large portion of the nodes, it may be faster to calculate the full matrix and then subset it.

PARAMETER	DESCRIPTION
`node_ids`	`Array of node IDs.` TYPE: `(N, ) array`
`parent_ids`	`Array of parent IDs for each node. Root nodes' parents must be -1.` TYPE: `(N, ) array`
`directed`	If ``True`` will only return distances in the direction of the child -> parent (i.e. towards the root) relationship. TYPE: `bool` DEFAULT: `False`
`sources`	Source node IDs. If ``None`` all nodes are used as sources. TYPE: `iterable` DEFAULT: `None`
`targets`	Target node IDs. If ``None`` all nodes are used as targets. TYPE: `iterable` DEFAULT: `None`
`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
`matrix`	Geodesic distances. Unreachable nodes are set to -1. If `source` and/or `targets` are provided, the matrix will be ordered accordingly. TYPE: `float32 (single) 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])
>>> fastcore.geodesic_matrix(node_ids, parent_ids)
array([[0., 1., 2., 3., 2., 3., 4.],
       [1., 0., 1., 2., 1., 2., 3.],
       [2., 1., 0., 1., 2., 3., 4.],
       [3., 2., 1., 0., 3., 4., 5.],
       [2., 1., 2., 3., 0., 1., 2.],
       [3., 2., 3., 4., 1., 0., 1.],
       [4., 3., 4., 5., 2., 1., 0.]], dtype=float32)
>>> fastcore.geodesic_matrix(
...     node_ids, parent_ids,
...     sources=[0, 1], targets=[5, 6]
...     )
array([[3., 4.],
       [2., 3.]], dtype=float32)

`navis_fastcore.geodesic_pairs(node_ids, parent_ids, pairs, directed=False, weights=None)`

Calculate geodesic ("along-the-arbor") distances between pairs of nodes.

This uses a simple algorithm that calculates distances using brute force. It's fast because we parallelize the calculation of each pair of nodes.

PARAMETER	DESCRIPTION
`node_ids`	`Array of node IDs.` TYPE: `(N, ) array`
`parent_ids`	`Array of parent IDs for each node. Root nodes' parents must be -1.` TYPE: `(N, ) array`
`pairs`	`Pairs of node IDs for which to calculate distances.` TYPE: `(N, 2) array`
`directed`	If ``True`` will only return distances in the direction of the child -> parent (i.e. towards the root) relationship. TYPE: `bool` DEFAULT: `False`
`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
`matrix`	Geodesic distances. Unreachable nodes are set to -1. TYPE: `float32 (single) 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])
>>> pairs = np.array([(0, 1), (0, 2)])
>>> fastcore.geodesic_pairs(node_ids, parent_ids, pairs)