navis-flybrains

Transforms to map between different Drosophila template brains and datasets. Intended to be used with navis.

This library is analogous to Greg Jefferis' nat.templatebrains, nat.jrcbrains and nat.flybrains for R.

flybrains ships with:

• meta data + surface meshes for 31 light-level templates and connectome datasets
• Elastix transforms from/to the FANC and BANC connectomes and template spaces (by Jasper Phelps)
• various landmark-based transforms (e.g. between MANC and FANC or between BANC and FLYWIRE)
• mirror transforms for many brain spaces/datasets (e.g. FAFB14, FANC and BANC)

[!IMPORTANT] There are many additional transforms that need to be downloaded separately as a one-off (see below).

Installation

You can install flybrains from PyPI:

pip3 install flybrains

To install the dev version from Github:

pip3 install git+https://github.com/navis-org/navis-flybrains.git

External dependencies

In order to use the Jefferis lab or VFB transforms, you will need to have CMTK installed.

For FANC and BANC transforms, you will need to download elastix and make sure that the path to the binaries is in your PATH variable.

Usage

It's highly recommended that after install, you download the (optional) bridging transforms to map between template brains/nerve cords.

[!TIP] If you already have downloaded these registrations via nat.jrcbrains and/or nat.flybrains you can skip this: flybrains should be able to find the registrations downloaded via R and register them for you. See also code below for generating a report of available transforms.

>>> import flybrains

# This downloads (or updates) various CMTK bridging and mirror transforms
# generated or collated by the Jefferis lab - see docstring for details
>>> flybrains.download_jefferislab_transforms()

# This downloads H5 bridging transforms between Janelia brain datasets
# (templates and connectomes) - see docstring for details
>>> flybrains.download_jrc_transforms()

# This downloads H5 bridging transforms between Janelia ventral nerve cord (VNC)
# datasets (templates and connectomes) - see docstring for details
>>> flybrains.download_jrc_vnc_transforms()

# This downloads (or updates) various CMTK bridging and mirror transforms
# generated or collated by VirtualFlyBrain.org - see docstring for details
>>> flybrains.download_vfb_transforms()

# Register the transforms - this is only necessary if you just downloaded them.
# Alternatively, just restart your Python session and import flybrains again.
>>> flybrains.register_transforms()

[!CAUTION] The URL for the JRC2018F <-> JRC2018M transform (JRC2018U_JRC2018M.h5) was incorrect in flybrains version 0.2.6. If you downloaded it using that version of flybrains you need to manually remove the file, update flybrains and download again using a newer version.

In the future, simply importing flybrains is sufficient to make the transforms available to navis:

>>> import navis
>>> import flybrains
>>> import numpy as np
>>> points = np.array([[429536, 205240,  38400]])
>>> navis.xform_brain(points, source='FAFB', target='JRC2018F')
array([[241.53969657, 100.99399233,  35.96977733]])

Please see the transform tutorial for navis to learn how to transform more complex data.

To check which transforms are available (either downloaded or via R) you can run this:

>>> # Generate a report - note the mix of transforms downloaded via Python and R
>>> flybrains.report()
Flybrains Status Report
=======================
Data Home: /Users/philipps/flybrain-data

CMTK registrations (Jefferis lab/VFB): 45 of 45
H5 registrations (JRC/Saalfeld lab): 11 of 11

nat regdirs
-----------
~/Library/Application Support/rpkg-nat.templatebrains/regfolders: 41 CMTK | 0 H5 transforms
/Library/Frameworks/R.framework/Versions/3.6/Resources/library/nat.flybrains/extdata/bridgingregistrations: 5 CMTK | 0 H5 transforms
/Library/Frameworks/R.framework/Versions/3.6/Resources/library/nat.flybrains/extdata/mirroringregistrations: 5 CMTK | 0 H5 transforms
~/Library/Application Support/R/nat.jrcbrains: 0 CMTK | 5 H5 transforms

Meta data and surface meshes for the template brains/VNCs are readily accessible:

>>> flybrains.FAFB14
Template brain
--------------
Name: Full Adult Fly Brain
Short Name: FAFB14
Type: None
Sex:  female
Dimensions: 165372 x 80745 x 6730 voxels
Voxel size:
  x = 4 nanometers
  y = 4 nanometers
  z = 40 nanometers
Bounding box (nanometers):
  x = 192200, y = 75853, z = 2007,
  x = 853686, y = 398832, z = 271205,
Description: SSTEM volume comprising an entire female Drosophila brain was imaged at
 4x4x40nm by Zheng et al. (2018) and is availabe for download at
https://temca2data.org/. The meta data and associated mesh represent
version 14 (FAFB14) of this data set.
DOI: 10.1016/j.cell.2018.06.019

Most templates come with a mesh e.g. for plotting via navis:

>>> flybrains.FAFB14.mesh
<trimesh.Trimesh(vertices.shape=(25047, 3), faces.shape=(50416, 3))>
>>> # You can pass the template object directly to navis' plotting functions
>>> navis.plot3d(flybrains.FAFB14)

Changes

• 0.6.0 (29/10/25):
  • added the BANC (brain and nerve cord) connectome: template, meshes, transforms to/from JFCR2018F and maleCNS, mirror transform
  • fix normals for the Male CNS VNC mesh
• 0.5.2 (08/08/25):
  • renamed JRCFIB2022Mtilt -> JRCFIB2022Mplot
  • improved JRCFIB2022Mplot transform to also correct for a tilt along the z-axis
• 0.5.1 (17/07/25):
  • small fix for FANC transform weights
• 0.5.0 (17/07/25):
  • added a JRCFIB2022Mtilt mesh + transform where the VNC is tilted forward for visualization
  • reduced weights for internal FANC transform (fixes #15)
• 0.4.0 (19/05/25):
  • improved the FLYWIRE/FAFB14 <-> JRCFIB2022M (maleCNS) transform
  • added support for two-step CMTK transforms
• 0.3.0 (01/08/24):
  • potentially breaking as it may change transform paths:
    • weights for AliasTransforms are now set to 0 (i.e. no cost)
    • weights for simple AffineTransforms are set to 0.1
  • improved the mirror transforms for FAFB14 and FLYWIRE based on a new JRC2018F-FLYWIRE CMTK transform (S. Cachero, Jefferis lab)
  • added a symmetrizing transform for FLYWIRE
  • added VNC mesh to JRCFIB2022M; it now has .mesh, .mesh_brain, .mesh_vnc
  • fixed stray vertex in FLYWIRE.mesh_whole_brain
  • some under-the-hood refactoring
• 0.2.11 (23/07/24): fixed bounding box for JRCFIB2022Mraw
• 0.2.10 (16/04/24):
  • added download for JRCFIB2022M (maleCNS) <-> JRC2018M transform (via Saalfeld lab)
  • added mirror transform for JRCFIB2022M (maleCNS)
  • dropped VFB transforms between JRC VNC templates (use Saalfeld transforms instead)
• 0.2.9 (08/08/23): added MANC template brain and transform to/from JRCVNC2018M
• 0.2.8 (02/04/23): added transform between JRCFIB2022M (maleCNS) and FLYWIRE
• 0.2.7 (05/01/23): fixed JRC2018M <-> JRC2018U transform download
• 0.2.6 (06/09/22): added JRC2018M <-> JRC2018U transform (YANKED)
• 0.2.5 (22/05/22): added JRCFIB2022M mesh and transform to/from FAFB14
• 0.2.4 (12/05/22): added FLYWIRE template brain and landmark-based mirror transform
• 0.2.0 (02/02/22): added VirtualFlyBrain.org's (CMTK) and Janelia's (H5) VNC transforms; renamed some download function
• 0.1.14 (21/10/21): added FANC <-> JRCVNC2018F transform (requires Elastix and navis >=1.0.0)
• 0.1.13 (14/10/21): add template and mirror transform for FANC
• 0.1.12 (18/09/21): fixed directionality of Jefferis lab CMTK transforms
• 0.1.11 (02/08/21): make downloads work if file size unknown
• 0.1.10 (01/08/21): fix bug that led to warnings during transform registration on Windows systems
• 0.1.9 (05/05/21): fixed mesh normals; fixed JRCFIB2018F units to nm and added JRCFIB2018Fum template;
• 0.1.8 (10/04/21): add a simple symmetrization transform for FAFB: FAFB14sym
• 0.1.7 (30/03/21): better deal with systems without nat libraries
• 0.1.6 (25/03/21): fix bug that led to excessive recursive scanning of directories
• 0.1.5 (03/03/21): fix bug that led to meshes not being packaged
• 0.1.4 (24/02/21): added "hemibrain" alias for "JRCFIB2018F"; added hemibrain bounding box mesh
• 0.1.3 (12/01/21): improved the warp mirror registration for FAFB14
• 0.1.2 (10/01/21): added a warp mirror registration for FAFB14
• 0.1.1 (06/01/21): added um (for microns) suffix to JRCFIB2018F transforms; added affine JRCFIB2018Fraw -> JRCFIB2018F -> JRCFIB2018Fum transforms
• 0.1.0 (03/01/21): first working version

Contributing

Contributions are very welcome! Want to use navis-flybrains to distribute your own transforms, meshes or templates? Found a bug, bad transform or incorrect information? Feel free to open a pull request or an issue to discuss details!

Acknowledgements

navis-flybrains is critically based on nat.flybrains and nat.jrcbrains by Greg Jefferis et al. for both inspiration regarding the implementation as well as template brain meta data.

Citing

If you use navis-flybrains in your research please make sure to cite us (see Zenodo DOI badge at the top of this page), navis and most importantly the people who generated the meshes & registrations distributed with flybrains!

As reference for the Jefferis lab registrations please use:

The natverse, a versatile toolbox for combining and analysing neuroanatomical data.
A.S. Bates, J.D. Manton, S.R. Jagannathan, M. Costa, P. Schlegel, T. Rohlfing, G.S. Jefferis
eLife (2020); doi: https://doi:10.7554/eLife.53350

As (partial) reference for the Saalfeld lab registrations please see:

An unbiased template of the Drosophila brain and ventral nerve cord.
John A Bogovic, Hideo Otsuna, Larissa Heinrich, Masayoshi Ito, Jennifer Jeter, Geoffrey Meissner, Aljoscha Nern, Jennifer Colonell, Oz Malkesman, Kei Ito, Stephan Saalfeld
PLOS One (2018); doi: https://doi.org/10.1371/journal.pone.0236495

As reference for the JRCFIB022M registrations please use:

Sexual dimorphism in the complete connectome of the Drosophila male central nervous system
Stuart Berg, Isabella R Beckett, Marta Costa, Philipp Schlegel, [...] Gerald M Rubin, Gregory SXE Jefferis
bioRxiv 2025.10.09.680999; doi: https://doi.org/10.1101/2025.10.09.680999

As reference for the VFB CMTK transforms please use:

A Systematic Nomenclature for the Drosophila Ventral Nerve Cord.
Robert Court, Shigehiro Namiki, J. Douglas Armstrong, Jana Börner, Gwyneth Card, Marta Costa, Michael Dickinson, Carsten Duch, Wyatt Korff, Richard Mann, David Merritt, Rod K. Murphey, Andrew M. Seeds, Troy Shirangi, Julie H. Simpson, James W. Truman, John C. Tuthill, Darren W. Williams, David Shepherd
Neuron (2020); doi: https://doi.org/10.1016/j.neuron.2020.08.005.

As reference for the FANC<->JRCVNC2018F transform by Jasper Phelps please use:

Reconstruction of motor control circuits in adult Drosophila using automated transmission electron microscopy.
Phelps JS, Hildebrand DGC, Graham BJ, Kuan AT, Thomas LA, Nguyen TM, Buhmann J, Azevedo AW, Sustar A, Agrawal S, Liu M, Shanny BL, Funke J, Tuthill JC, Lee WA
Cell (2021); doi: 10.1016/j.cell.2020.12.013

As reference for the BANC<->JRC2018F/JRCVNC2018F transforms by Jasper Phelps please use:

Distributed control circuits across a brain-and-cord connectome
Alexander Shakeel Bates, Jasper S. Phelps, Minsu Kim, Helen H. Yang, [...] Rachel I. Wilson, Wei-Chung Allen Lee
bioRxiv 2025.07.31.667571; doi: https://doi.org/10.1101/2025.07.31.667571

For references on individual template brains, please see their docstrings:

>>> help(flybrains.IBN)

When in doubt, feel free to open an issue to ask for advice.

Troubleshooting

OSError when reading HDF5 deformation fields

OSError: Can't synchronously read data (minimum number of bits exceeds size of type)

conda create -n hdf5_112 \
  -c conda-forge \
  python=3.11 \
  hdf5=1.12.* \
  h5py=3.12.1

Downloads fail on Google Colab (and other cloud machines)

requests.exceptions.HTTPError: Server returned an HTML page instead of a file for
https://ndownloader.figshare.com/files/... This typically means the request was blocked [...]

!curl -sL "https://ndownloader.figshare.com/files/42106125" -o /dev/null -D - -r 0-99 | head

import os
from google.colab import drive
drive.mount('/content/drive')

# NOTE: this must be set *before* importing flybrains
os.environ['FLYBRAINS_DATA'] = '/content/drive/MyDrive/flybrain-data'

import flybrains