navis.xform_brain¶
- navis.xform_brain(x, source, target, via=None, avoid=None, affine_fallback=True, caching=True, verbose=True)[source]¶
Transform 3D data between template brains.
This requires the appropriate transforms to be registered with
navis
. See the docs/tutorials for details.Notes
For Neurons only: transforms can introduce a change in the units (e.g. if the transform goes from micron to nanometer space). Some template brains have their units hard-coded in their meta data (as
_navis_units
). If that’s not the case we fall-back to trying to infer any change in units by comparing distances between x/y/z coordinate before and after the transform. That approach works reasonably well with base 10 increments (e.g. nm -> um) but may be off with odd changes in units (e.g. physical -> voxel space). Regardless of whether hard-coded or inferred, any change in units is used to update the.units
property and node/soma radii for TreeNeurons.- Parameters:
x (Neuron/List | numpy.ndarray | pandas.DataFrame) – Data to transform. Dataframe must contain
['x', 'y', 'z']
columns. Numpy array must be shape(N, 3)
.source (str) – Source template brain that the data currently is in.
target (str) – Target template brain that the data should be transformed into.
via (str | list thereof, optional) – Optionally set intermediate template(s). This can be helpful to force a specific transformation sequence.
avoid (str | list thereof, optional) – Prohibit going through specific intermediate template(s).
affine_fallback (bool) – In some cases the non-rigid transformation of points can fail - for example if points are outside the deformation field. If that happens, they will be returned as
NaN
. Ifaffine_fallback=True
we will apply only the rigid affine part of the transformation to those points to get as close as possible to the correct coordinates.caching (bool) –
If True, will (pre-)cache data for transforms whenever possible. Depending on the data and the type of transforms this can speed things up significantly at the cost of increased memory usage:
False
= no upfront cost, lower memory footprintTrue
= higher upfront cost, most definitely faster
Only applies if input is NeuronList and if transforms include H5 transform.
verbose (bool) – If True, will print some useful info on transform.
- Returns:
Copy of input with transformed coordinates.
- Return type:
same type as
x
Examples
This example requires the flybrains library to be installed:
pip3 install flybrains
Also, if you haven’t already, you will need to have the optional Saalfeld lab (Janelia Research Campus) transforms installed (this is a one-off):
>>> import flybrains >>> flybrains.download_jrc_transforms()
Once
flybrains
is installed and you have downloaded the registrations, you can run this:>>> import navis >>> import flybrains >>> # navis example neurons are in raw (8nm voxel) hemibrain (JRCFIB2018Fraw) space >>> n = navis.example_neurons(1) >>> # Transform to FAFB14 space >>> xf = navis.xform_brain(n, source='JRCFIB2018Fraw', target='FAFB14')
See also
navis.xform()
Lower level entry point that takes data and applies a given transform or sequence thereof.
navis.mirror_brain()
Uses non-rigid transforms to mirror neurons from the left to the right side of given template brain and vice versa.