navis.nblast¶
- navis.nblast(query, target=None, scores='forward', normalized=True, use_alpha=False, smat='auto', limit_dist=None, approx_nn=False, precision=64, n_cores=1, progress=True, smat_kwargs={})[source]¶
NBLAST query against target neurons.
This implements the NBLAST algorithm from Costa et al. (2016) (see references) and mirror the implementation in R’s
nat.nblast
(https://github.com/natverse/nat.nblast).- Parameters:
query (Dotprops | NeuronList) – Query neuron(s) to NBLAST against the targets. Neurons should be in microns as NBLAST is optimized for that and have similar sampling resolutions.
target (Dotprops | NeuronList, optional) – Target neuron(s) to NBLAST against. Neurons should be in microns as NBLAST is optimized for that and have similar sampling resolutions. If not provided, will NBLAST queries against themselves.
scores ('forward' | 'mean' | 'min' | 'max' | 'both') –
Determines the final scores:
’forward’ (default) returns query->target scores
’mean’ returns the mean of query->target and target->query scores
’min’ returns the minium between query->target and target->query scores
’max’ returns the maximum between query->target and target->query scores
’both’ will return foward and reverse scores as multi-index DataFrame
use_alpha (bool, optional) – Emphasizes neurons’ straight parts (backbone) over parts that have lots of branches.
normalized (bool, optional) – Whether to return normalized NBLAST scores.
smat (str | pd.DataFrame | Callable) – Score matrix. If ‘auto’ (default), will use scoring matrices from FCWB. Same behaviour as in R’s nat.nblast implementation. If
smat='v1'
it uses the analytic formulation of the NBLAST scoring from Kohl et. al (2013). You can adjust parametersigma_scaling
(default to 10) usingsmat_kwargs
. IfCallable
given, it passes distance and dot products as first and second argument respectively. Ifsmat=None
the scores will be generated as the product of the distances and the dotproduct of the vectors of nearest-neighbor pairs.limit_dist (float | "auto" | None) – Sets the max distance for the nearest neighbor search (distance_upper_bound). Typically this should be the highest distance considered by the scoring function. If “auto”, will extract that value from the scoring matrix. While this can give a ~2X speed up, it will introduce slight inaccuracies because we won’t have a vector component for points without a nearest neighbour within the distance limits. The impact depends on the scoring function but with the default FCWB
smat
, this is typically limited to the third decimal (0.0086 +/- 0.0027 for an all-by-all of 1k neurons).approx_nn (bool) – If True, will use approximate nearest neighbors. This gives a >2X speed up but also produces only approximate scores. Impact depends on the use case - testing highly recommended!
n_cores (int, optional) – Max number of cores to use for nblasting. Default is
os.cpu_count() // 2
. This should ideally be an even number as that allows optimally splitting queries onto individual processes.precision (int [16, 32, 64] | str [e.g. "float64"] | np.dtype) – Precision for scores. Defaults to 64 bit (double) floats. This is useful to reduce the memory footprint for very large matrices. In real-world scenarios 32 bit (single)- and depending on the purpose even 16 bit (half) - are typically sufficient.
progress (bool) – Whether to show progress bars. This may cause some overhead, so switch off if you don’t really need it.
smat_kwargs (Dictionary with additional parameters passed to scoring) – functions.
- Returns:
scores – Matrix with NBLAST scores. Rows are query neurons, columns are targets. The order is the same as in
query
/target
and the labels are based on the neurons’.id
property.- Return type:
pandas.DataFrame
References
Costa M, Manton JD, Ostrovsky AD, Prohaska S, Jefferis GS. NBLAST: Rapid, Sensitive Comparison of Neuronal Structure and Construction of Neuron Family Databases. Neuron. 2016 Jul 20;91(2):293-311. doi: 10.1016/j.neuron.2016.06.012.
Examples
>>> import navis >>> nl = navis.example_neurons(n=5) >>> nl.units <Quantity([8 8 8 8 8], 'nanometer')> >>> # Convert to microns >>> nl_um = nl * (8 / 1000) >>> # Convert to dotprops >>> dps = navis.make_dotprops(nl_um) >>> # Run the nblast >>> scores = navis.nblast(dps[:3], dps[3:])
See also
navis.nblast_allbyall()
A more efficient way than
nblast(query=x, target=x)
.navis.nblast_smart()
A smart(er) NBLAST suited for very large NBLAST.
navis.synblast()
A synapse-based variant of NBLAST.