navis.nblast_allbyall¶

navis.nblast_allbyall(x, normalized=True, use_alpha=False, smat='auto', limit_dist=None, approx_nn=False, precision=64, n_cores=1, progress=True, smat_kwargs={})[source]¶

All-by-all NBLAST of inputs neurons.

A more efficient way than running nblast(query=x, target=x).

Parameters:

x (Dotprops | NeuronList) – Neuron(s) to NBLAST against each other. Neurons should be in microns as NBLAST is optimized for that and have similar sampling resolutions.
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.
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, optional) –
Score matrix/function:
- If smat='auto' (default), will use scoring matrices based on flycircuit data. Same behaviour as in R’s nat.nblast implementation.
- For smat='v1', uses the analytic formulation of the NBLAST scoring from Kohl et. al (2013). You can adjust parameter sigma_scaling (default to 10) using smat_kwargs.
- For smat=None the scores will be generated as the product of the distances and the dotproduct of the vectors of nearest-neighbor pairs.
- If function, must consume distance and dot products as first and second argument, respectively and return float.
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!
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 cause may 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 x 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)
>>> # Make dotprops
>>> dps = navis.make_dotprops(nl_um)
>>> # Run the nblast
>>> scores = navis.nblast_allbyall(dps)