navis.nblast_smart¶
- navis.nblast_smart(query, target=None, t=90, criterion='percentile', scores='forward', return_mask=False, normalized=True, use_alpha=False, smat='auto', limit_dist='auto', approx_nn=False, precision=64, n_cores=1, progress=True, smat_kwargs={})[source]¶
Smart(er) NBLAST query against target neurons.
In contrast to
navis.nblast()
this function will first run a “pre-NBLAST” in which only 10% of the query dotprops’ points are used. Using those initial scores, we select for each query the highest scoring targets and run the full NBLAST only on those query-target pairs (seet
andcriterion
for fine-tuning).- 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.
t (int | float) – Determines for which pairs we will run a full NBLAST. See
criterion
parameter for details.criterion ("percentile" | "score" | "N") –
- Criterion for selecting query-target pairs for full NBLAST:
”percentile” runs full NBLAST on the
t
-th percentile”score” runs full NBLAST on all scores above
t
”N” runs full NBLAST on top
t
targets
return_mask (bool) – If True, will also return a boolean mask that shows which scores are based on a full NBLAST and which ones only on the pre-NBLAST.
scores ('forward' | 'mean' | 'min' | 'max') –
- 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
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
. Ifsmat=None
the scores will be generated as the product of the distances and the dotproduct of the vectors of nearest-neighbor pairs. IfCallable
given, it passes distance and dot products as first and second argument respectively.smat_kwargs (Dictionary with additional parameters passed to scoring) – functions.
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.
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.progress (bool) – Whether to show progress bars.
- Returns:
scores (pandas.DataFrame) – 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.mask (np.ndarray) – Only if
return_mask=True
: a boolean mask with same shape asscores
that shows which scores are based on a full NBLAST and which ones only on the pre-NBLAST.
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 a NBLAST where only the top target from the pre-NBLAST is run >>> # through a full NBLAST >>> scores = navis.nblast_smart(dps[:3], dps[3:], t=1, criterion='N')
See also
navis.nblast()
The conventional full NBLAST.
navis.nblast_allbyall()
A more efficient way than
nblast(query=x, target=x)
.navis.synblast()
A synapse-based variant of NBLAST.