| Title: | Re-implementation of nat core functions in Rust |
|---|---|
| Description: | A re-implementation of core 'nat' (Neuroanatomy Toolbox) functions in Rust for speed. Provides fast skeleton/tree (DAG) operations (geodesic distances, Strahler order, segment generation, twig pruning, synapse flow centrality, node classification, skeleton healing), mesh connected components, and NBLAST/synNBLAST neuron similarity scoring, exposed to R via extendr. |
| Authors: | Philipp Schlegel [aut, cre] (ORCID: <https://orcid.org/0000-0002-5633-1314>) |
| Maintainer: | Philipp Schlegel <[email protected]> |
| License: | GPL-3 |
| Version: | 0.5.0 |
| Built: | 2026-07-11 08:01:56 UTC |
| Source: | https://github.com/schlegelp/fastcore-rs |
Compute all distances to root.
all_dists_to_root(parents, sources, weights)all_dists_to_root(parents, sources, weights)
parents |
Integer vector of 0-based parent indices (roots are |
sources |
Optional integer vector of node indices to measure from;
|
weights |
Optional numeric vector of child-to-parent edge weights;
|
Numeric vector of distances to the root for each requested node.
Break the tree into its linear segments (one integer vector per segment).
break_segments(parents)break_segments(parents)
parents |
Integer vector of 0-based parent indices (roots are |
List of integer vectors, one per linear segment.
Calculate child -> parent distances.
child_to_parent_dists(parents, x, y, z)child_to_parent_dists(parents, x, y, z)
parents |
Integer vector of 0-based parent indices (roots are |
x, y, z
|
Numeric vectors of node coordinates, one entry per node. |
Numeric vector of Euclidean child-to-parent distances (0 for roots).
Classify nodes into roots (0), leaves (1), branch points (2) and slabs (3).
classify_nodes(parents)classify_nodes(parents)
parents |
Integer vector of 0-based parent indices (roots are |
Integer vector: 0 root, 1 leaf, 2 branch point, 3 slab.
Connected components.
connected_components(parents)connected_components(parents)
parents |
Integer vector of 0-based parent indices (roots are |
Integer vector assigning each node a component id.
Return path length from a single node to the root.
dist_to_root(parents, node)dist_to_root(parents, node)
parents |
Integer vector of 0-based parent indices (roots are |
node |
Integer index of the node to measure from. |
Numeric path length (edge count) from node to its root.
Returns a list with segments (a list of integer vectors, one per segment)
and lengths (per-segment lengths, or NULL if no weights were supplied).
generate_segments(parents, weights)generate_segments(parents, weights)
parents |
Integer vector of 0-based parent indices (roots are |
weights |
Optional numeric vector of edge weights; |
List with segments (list of integer node-index vectors) and
lengths (numeric per-segment lengths, or NULL).
Geodesic distances between nodes.
geodesic_distances(parents, sources, targets, weights, directed)geodesic_distances(parents, sources, targets, weights, directed)
parents |
Integer vector of 0-based parent indices (roots are |
sources |
Optional integer vector of source node indices; |
targets |
Optional integer vector of target node indices; |
weights |
Optional numeric vector of edge weights; |
directed |
Logical; if |
Numeric matrix of geodesic distances (sources in rows, targets in columns).
Memory-efficient companion to geodesic_distances that never materialises the
full distance matrix. Returns a list with distances (distance to the nearest
target) and nearest (index of that target); sources without a reachable
target get -1.
geodesic_nearest(parents, sources, targets, weights, directed)geodesic_nearest(parents, sources, targets, weights, directed)
parents |
Integer vector of 0-based parent indices (roots are |
sources |
Optional integer vector of source node indices; |
targets |
Optional integer vector of target node indices; |
weights |
Optional numeric vector of edge weights; |
directed |
Logical; if |
List with distances (numeric, distance to the nearest target) and
nearest (integer target index, -1 when unreachable).
sources and targets are parallel arrays of node indices; the returned
vector holds the distance between each (source, target) pair.
geodesic_pairs(parents, sources, targets, weights, directed)geodesic_pairs(parents, sources, targets, weights, directed)
parents |
Integer vector of 0-based parent indices (roots are |
sources |
Integer vector of source node indices. |
targets |
Integer vector of target node indices (same length as
|
weights |
Optional numeric vector of edge weights; |
directed |
Logical; if |
Numeric vector with the distance of each (source, target) pair.
Check whether the tree contains cycles.
has_cycles(parents)has_cycles(parents)
parents |
Integer vector of 0-based parent indices (roots are |
Logical; TRUE if the parent structure contains a cycle.
Convenience wrapper that finds the minimal-length set of new edges between the
skeleton's connected components (see stitch_fragments()) and regenerates a
single rooted tree from them (see reroot_rewire()).
heal_skeleton( parents, x, y, z, method, max_dist, min_size, mask, radius, use_radius )heal_skeleton( parents, x, y, z, method, max_dist, min_size, mask, radius, use_radius )
parents |
Integer vector of 0-based parent indices (roots are |
x, y, z
|
Numeric vectors of node coordinates, one entry per node. |
method |
Character; |
max_dist |
Optional numeric maximum length for any single new edge; gaps
larger than this are left unhealed, so the result may stay fragmented. |
min_size |
Optional integer; fragments with fewer than this many nodes are
excluded from healing and stay disconnected. |
mask |
Optional logical vector restricting which nodes may be used as
endpoints for a new edge; combined with |
radius |
Optional numeric vector of node radii, one entry per node. Only
required when |
use_radius |
|
Integer vector of new 0-based parent indices (roots are -1). If the
skeleton could be fully healed this is a single tree with one root.
faces is an (N, 3) matrix of vertex indices. Returns an integer vector of
length n_vertices assigning each vertex the root-vertex index of its
component.
mesh_connected_components(faces, n_vertices)mesh_connected_components(faces, n_vertices)
faces |
Integer or numeric |
n_vertices |
Integer; total number of vertices in the mesh. |
Integer vector of length n_vertices giving each vertex the
root-vertex index of its component.
Returns an (n_query, n_target) score matrix.
nblast( q_points, q_vects, t_points, t_vects, q_alphas, t_alphas, smat_values, dist_edges, dot_edges, normalize, limit_dist, n_cores, precision, progress )nblast( q_points, q_vects, t_points, t_vects, q_alphas, t_alphas, smat_values, dist_edges, dot_edges, normalize, limit_dist, n_cores, precision, progress )
q_points |
List of |
q_vects |
List of |
t_points |
List of |
t_vects |
List of |
q_alphas |
Optional list of per-point alpha vectors for the queries;
|
t_alphas |
Optional list of per-point alpha vectors for the targets. |
smat_values |
Numeric scoring matrix, or |
dist_edges |
Numeric vector of distance bin edges for |
dot_edges |
Numeric vector of dot-product bin edges for |
normalize |
Logical; normalise each score by the query self-match score. |
limit_dist |
Optional numeric distance cut-off; |
n_cores |
Optional integer thread count; |
precision |
Integer; compute in 32- or 64-bit floats. |
progress |
Logical; display a progress bar. |
Numeric (n_query, n_target) score matrix.
points/vects are lists of (N, 3) matrices (one per neuron). Returns an
(n, n) score matrix; cell (i, j) is query i against target j.
nblast_allbyall( points, vects, alphas, smat_values, dist_edges, dot_edges, normalize, limit_dist, n_cores, precision, progress )nblast_allbyall( points, vects, alphas, smat_values, dist_edges, dot_edges, normalize, limit_dist, n_cores, precision, progress )
points |
List of |
vects |
List of |
alphas |
Optional list of per-point alpha (anisotropy) vectors; |
smat_values |
Numeric scoring matrix, or |
dist_edges |
Numeric vector of distance bin edges for |
dot_edges |
Numeric vector of dot-product bin edges for |
normalize |
Logical; normalise each score by the query self-match score. |
limit_dist |
Optional numeric distance cut-off; |
n_cores |
Optional integer thread count; |
precision |
Integer; compute in 32- or 64-bit floats. |
progress |
Logical; display a progress bar. |
Numeric (n, n) score matrix; cell (i, j) is query i vs target j.
(query, target) index pairs.q_idx/t_idx are 0-based indices into the query/target lists; element k of
the result is query q_idx[k] against target t_idx[k].
nblast_pairs( q_points, q_vects, t_points, t_vects, q_idx, t_idx, q_alphas, t_alphas, smat_values, dist_edges, dot_edges, normalize, limit_dist, n_cores, precision, progress )nblast_pairs( q_points, q_vects, t_points, t_vects, q_idx, t_idx, q_alphas, t_alphas, smat_values, dist_edges, dot_edges, normalize, limit_dist, n_cores, precision, progress )
q_points |
List of |
q_vects |
List of |
t_points |
List of |
t_vects |
List of |
q_idx |
Integer vector of 0-based query indices, one per pair. |
t_idx |
Integer vector of 0-based target indices (same length as |
q_alphas |
Optional list of per-point alpha vectors for the queries;
|
t_alphas |
Optional list of per-point alpha vectors for the targets. |
smat_values |
Numeric scoring matrix, or |
dist_edges |
Numeric vector of distance bin edges for |
dot_edges |
Numeric vector of dot-product bin edges for |
normalize |
Logical; normalise each score by the query self-match score. |
limit_dist |
Optional numeric distance cut-off; |
n_cores |
Optional integer thread count; |
precision |
Integer; compute in 32- or 64-bit floats. |
progress |
Logical; display a progress bar. |
Numeric vector of scores, one per (query, target) pair.
parents find its index in nodes.Importantly this is 0-indexed to match indexing in Rust. Roots will have parent index -1.
node_indices(nodes, parents)node_indices(nodes, parents)
nodes |
Integer vector of node IDs. |
parents |
Integer vector of parent IDs, one per node; roots use their own ID or a negative value. |
Integer vector of 0-based parent indices (-1 for roots).
Returns indices of nodes to keep.
prune_twigs(parents, threshold, weights)prune_twigs(parents, threshold, weights)
parents |
Integer vector of 0-based parent indices (roots are |
threshold |
Numeric length threshold; twigs shorter than this are pruned. |
weights |
Optional numeric vector of edge weights; |
Integer vector of node indices to keep.
Turns an edited edge set back into a valid rooted tree: the undirected
adjacency is built from the original child -> parent edges plus the new
from/to edges, then oriented away from root by breadth-first search.
reroot_rewire(parents, from, to, root)reroot_rewire(parents, from, to, root)
parents |
Integer vector of 0-based parent indices (roots are |
from, to
|
Integer vectors of 0-based node indices giving the undirected
edges to add, e.g. the |
root |
Integer 0-based index of the preferred root; its whole component is rooted there. Use a negative value to auto-pick (lowest index per component). |
Integer vector of new 0-based parent indices (roots are -1). Any
component not reachable from root is rooted at its lowest-index node, so the
result is valid even when the skeleton could not be fully healed.
limit_dist="auto" value for a scoring matrix.The limit_dist="auto" value for a scoring matrix.
smat_auto_limit(smat_values, dist_edges, dot_edges, use_alpha)smat_auto_limit(smat_values, dist_edges, dot_edges, use_alpha)
smat_values |
Numeric scoring matrix, or |
dist_edges |
Numeric vector of distance bin edges for |
dot_edges |
Numeric vector of dot-product bin edges for |
use_alpha |
Logical; when falling back to the built-in matrix, use the alpha-weighted variant. |
Numeric limit_dist value implied by the scoring matrix.
Given a per-node component label and node coordinates, this returns the set of
new edges that would join the fragments into a single tree while minimising the
total added length (a minimum spanning tree over the fragments). It does not
modify the skeleton — see heal_skeleton for the one-shot version.
stitch_fragments(components, x, y, z, w, mask, max_dist)stitch_fragments(components, x, y, z, w, mask, max_dist)
components |
Integer vector giving each node's connected component, e.g.
the output of |
x, y, z
|
Numeric vectors of node coordinates, one entry per node. |
w |
Optional numeric vector giving a 4th coordinate, one entry per node.
The search then happens in 4D, so nodes with similar |
mask |
Optional logical vector marking the nodes that may be used as
endpoints for a new edge; |
max_dist |
Optional numeric upper bound on the length of any single new
edge; |
List with from and to (integer vectors of 0-based node indices, one
pair per new edge) and dist (numeric edge lengths). At most
(#fragments - 1) edges.
Calculate Strahler Index.
strahler_index(parents, greedy, to_ignore, min_twig_size)strahler_index(parents, greedy, to_ignore, min_twig_size)
parents |
Integer vector of 0-based parent indices (roots are |
greedy |
Logical; use the greedy variant of the algorithm. |
to_ignore |
Optional integer vector of node indices to skip. |
min_twig_size |
Optional integer; ignore twigs shorter than this. |
Integer vector with the Strahler index of each node.
presynapses/postsynapses give the number of pre-/post-synapses at each node.
mode is one of "centrifugal", "centripetal" or "sum".
synapse_flow_centrality(parents, presynapses, postsynapses, mode)synapse_flow_centrality(parents, presynapses, postsynapses, mode)
parents |
Integer vector of 0-based parent indices (roots are |
presynapses |
Integer vector: number of presynapses at each node. |
postsynapses |
Integer vector: number of postsynapses at each node. |
mode |
Character; one of |
Integer vector with the synapse flow centrality of each node.
Returns an (n_query, n_target) score matrix.
synblast( q_points, q_types, t_points, t_types, smat_values, dist_edges, dot_edges, normalize, n_cores, precision, progress )synblast( q_points, q_types, t_points, t_types, smat_values, dist_edges, dot_edges, normalize, n_cores, precision, progress )
q_points |
List of |
q_types |
List of integer vectors of query per-connector type ids. |
t_points |
List of |
t_types |
List of integer vectors of target per-connector type ids. |
smat_values |
Numeric scoring matrix, or |
dist_edges |
Numeric vector of distance bin edges for |
dot_edges |
Numeric vector of dot-product bin edges for |
normalize |
Logical; normalise each score by the query self-match score. |
n_cores |
Optional integer thread count; |
precision |
Integer; compute in 32- or 64-bit floats. |
progress |
Logical; display a progress bar. |
Numeric (n_query, n_target) score matrix.
points are lists of (N, 3) connector coordinate matrices and types the
matching per-connector integer type ids. Returns an (n, n) score matrix.
synblast_allbyall( points, types, smat_values, dist_edges, dot_edges, normalize, n_cores, precision, progress )synblast_allbyall( points, types, smat_values, dist_edges, dot_edges, normalize, n_cores, precision, progress )
points |
List of |
types |
List of integer vectors of per-connector type ids, aligned with
|
smat_values |
Numeric scoring matrix, or |
dist_edges |
Numeric vector of distance bin edges for |
dot_edges |
Numeric vector of dot-product bin edges for |
normalize |
Logical; normalise each score by the query self-match score. |
n_cores |
Optional integer thread count; |
precision |
Integer; compute in 32- or 64-bit floats. |
progress |
Logical; display a progress bar. |
Numeric (n, n) score matrix; cell (i, j) is query i vs target j.