navis.nblast_align¶
- navis.nblast_align(query, target=None, align_method='rigid', two_way_align=True, sample_align=None, scores='mean', normalized=True, use_alpha=False, smat='auto', limit_dist=None, approx_nn=False, precision=64, n_cores=1, progress=True, dotprop_kwargs={}, align_kwargs={}, smat_kwargs={})[source]¶
Run NBLAST on pairwise-aligned neurons.
Requires the pycpd library at least version 2.0.1 which at the time of writing is only available from Github (not PyPI):
- Parameters:
query (Neuron | 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 (Neuron | 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.
align_method ("rigid" | "deform" | "pca" | "rigid+deform") – Which method to use for alignment. Maps to the respective
navis.align_{method}
function.two_way_align (bool) – If True, will run the alignment + NBLAST in both, query->target as well as query->target direction. This is highly recommended because it reduces the chance that a single bad alignment will mess up your scores.
sample_align (float [0-1], optional) – If provided, will calculate an initial alignment on just a fraction of the points followed by a landmark transform to transform the rest. Use this to speed things up.
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 for the NBLAST.
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. Also note that due to multiple layers of concurrency using all available cores might not be the fastest option.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 (dict, optional) – Dictionary with additional parameters passed to scoring functions.
align_kwargs (dict, optional) – Dictionary with additional parameters passed to alignment function.
dotprop_kwargs (dict, optional) – Dictionary with additional parameters passed to
navis.make_dotprops
. Only relevant if inputs aren’t already dotprops.
- 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. Important to note that even whenq == t
and withscores=mean
the matrix will not be symmetrical because we run separate alignments for the forward and the reverse comparisons.- 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) >>> # Run the align nblast >>> scores = navis.nblast_align(nl_um[:3], nl_um[3:], ... dotprop_kwargs=dict(k=5), ... sample_align=.2)
See also
navis.nblast()
The vanilla version of NBLAST.
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.