navis.xform_brain¶

navis.xform_brain(x, source, target, via=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 for details.

Notes

For Neurons only: whether there is a change in units during transformation (e.g. nm -> um) is inferred by comparing distances between x/y/z coordinates before and after transform. This guesstimate is then used to convert .units and node/soma radii. This 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).

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, optional) – Optional define an intermediate template. This can be helpful to force a specific transformation sequence.
affine_fallback (bool) – In same 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. Unless affine_fallback is True, in which case we will apply only the rigid affine part of the transformation to at least get close 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 tremendously speed things up at the cost of increased memory usage:
- False = no upfront cost, lower memory footprint
- True = 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') 