Transforms to map between different Drosophila template brains. 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 22 template brains and nerve cords
- an Elastix transform between
FANC
andJRCVNC2018F
kindly shared by Jasper Phelps - a landmark-based transform between
MANC
andFANC
- mirror transforms for
FAFB14
andFANC
There are plenty additional transforms that need to be downloaded separately (see below).
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
In order to use the Jefferis lab or VFB transforms, you will need to have CMTK installed.
For the FANC to JRCVNC2018F transform, you will need to download
elastix and make sure that the path
to the binaries is in your PATH
variable.
It's highly recommended that after install, you download the (optional) bridging transforms to map between template brains/nerve cords.
IMPORTANT: 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.
❗ If you already have downloaded these registrations via
nat.jrcbrains
and/ornat.flybrains
you can skip this:flybrains
should be able to find the registrations downloaded via R and register them for you (see also code at the bottom).
>>> 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 JRC brain templates
# (Saalfeld lab, Janelia Research Campus) - see docstring for details
>>> flybrains.download_jrc_transforms()
# This downloads H5 bridging transforms between JRC VNC templates
# (Saalfeld lab, Janelia Research Campus) - 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
>>> flybrains.register_transforms()
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): 41 of 45
H5 registrations (JRC/Saalfeld lab): 3 of 8
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)
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
- weights for
- improved the mirror transforms for
FAFB14
andFLYWIRE
based on a newJRC2018F-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
- potentially breaking as it may change transform paths:
0.2.11
(23/07/24): fixed bounding box forJRCFIB2022Mraw
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)
- added download for
0.2.9
(08/08/23): added MANC template brain and transform to/fromJRCVNC2018M
0.2.8
(02/04/23): added transform betweenJRCFIB2022M
(maleCNS) andFLYWIRE
0.2.7
(05/01/23): fixedJRC2018M
<->JRC2018U
transform download(YANKED)0.2.6
(06/09/22): addedJRC2018M
<->JRC2018U
transform0.2.5
(22/05/22): addedJRCFIB2022M
mesh and transform to/fromFAFB14
0.2.4
(12/05/22): addedFLYWIRE
template brain and landmark-based mirror transform0.2.0
(02/02/22): added VirtualFlyBrain.org's (CMTK) and Janelia's (H5) VNC transforms; renamed some download function0.1.14
(21/10/21): addedFANC
<->JRCVNC2018F
transform (requires Elastix and navis >=1.0.0)0.1.13
(14/10/21): add template and mirror transform for FANC0.1.12
(18/09/21): fixed directionality of Jefferis lab CMTK transforms0.1.11
(02/08/21): make downloads work if file size unknown0.1.10
(01/08/21): fix bug that led to warnings during transform registration on Windows systems0.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 libraries0.1.6
(25/03/21): fix bug that led to excessive recursive scanning of directories0.1.5
(03/03/21): fix bug that led to meshes not being packaged0.1.4
(24/02/21): added "hemibrain" alias for "JRCFIB2018F"; added hemibrain bounding box mesh0.1.3
(12/01/21): improved the warp mirror registration forFAFB14
0.1.2
(10/01/21): added a warp mirror registration forFAFB14
0.1.1
(06/01/21): addedum
(for microns) suffix toJRCFIB2018F
transforms; added affineJRCFIB2018Fraw
->JRCFIB2018F
->JRCFIB2018Fum
transforms0.1.0
(03/01/21): first working version
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.
If you use navis-flybrains
in for your research please make sure to cite us
(see Zenodo DOI badge at the top of this page), navis and 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 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
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.