Documentation

• 1: Overview
• 2: Getting Started
• 2.1: Starting to explore VFB
• 2.2: This is the Slice Viewer tab
• 2.3: This is the 3D Viewer tab
• 2.4: This is the Term Info tab
• 2.5: This is the Term Context tab
• 2.6: This is the Circuit Browser tab
• 2.7: How to Interpret VFB Thumbnails
• 2.8: Similarity Score Queries Guide
• 2.9: Bulk Image Download
• 2.10: Single cell RNAseq data
• 3: Examples
• 3.1: Circuit diagram of the mushroom body
• 4: Concepts
• 4.1: Transgene Expression
• 4.2: Split Expression
• 4.3: NBLAST
• 4.4: Templates
• 4.5: Bridging Registrations
• 4.6: Cell Types
• 4.7: Confidence Values
• 4.8: FlyLight Adult CNS Imaging Tiles
• 5: Tutorials
• 5.1: VFB Model Context Protocol (MCP) Tool Guide
• 5.2: Application Programming Interfaces (APIs)
• 5.2.1: Guide to Working with Images from Virtual Fly Brain (VFB) Using the VFBConnect Library
• 5.2.2: Hacking the connectome
• 5.2.2.1: Tool landscape
• 5.2.2.2: Introduction to connectomic data and tools
• 5.2.2.3: Discovery
• 5.2.2.4: Mapping
• 5.2.2.5: Visualisation
• 5.2.2.6: Connectomics
• 5.2.2.7: NBLAST
• 5.2.3: Downloading Images from VFB Using VFBconnect
• 5.2.4: VFB connect API overview
• 5.2.5: SOLR search example
• 5.2.6: Data types
• 5.2.7: Plotting
• 5.2.8: pymaid
• 5.2.9: NBLAST
• 5.2.10: neuprint
• 6: Contribution Guidelines
• 6.1: Guide to adding new query properties to the VFBTerm object in the VFBConnect Library
• 7: VFB APIs
• 7.1: Production Database (PDB) API
• 7.2: Knowledge Base (KB) API
• 7.3: Owlery API
• 7.4: SOLR Search API

1 - Overview

2 - Getting Started

Below are a few overview pages to help you get started using VFB:

2.1 - Starting to explore VFB

VFB integrates data curated from the literature with image data from many bulk sources. The search system allows you to search for neurons and neuroanatomical structures using almost any name found in the literature. The query system can identify neurons innervating any specified neuropil or fasciculating with any specified tract. It also allows queries for genes, transgenes and phenotypes expressed in any brain region or neuron. Search and query results combine referenced textual descriptions with 3D images and links to originating data sources. VFB features tens of thousands of 3D images of neurons, clones and expression patterns, registered to standard template brains. Any combination of these images can be viewed together. A BLAST-type query system (NBLAST) allows you to find similar neurons and drivers starting from a registered neuron.

Search for the item you’re interested in

Hover to explore brain regions in the Stack Viewer

Query for related terms and images

2.2 - This is the Slice Viewer tab

Hover to explore, click to list or shift + click to add painted anatomy

Use the arrow icons or scroll with the mouse to move through the stack

Home resets your view

Use the zoom icons or pinch gesture to zoom

Toggles through orthogonal views

Toggles the slice position on the 3D Viewer on/off

2.3 - This is the 3D Viewer tab

Point and click to select neurons/expression

Click and drag with the mouse or use the directional icons to rotate/move

Use the zoom icons or scroll with the mouse to zoom in/out

Home resets your view

The camera icon starts/stops a rotation animation of the scene

The sphere icon toggles wireframes on/off

2.4 - This is the Term Info tab

Click on thumbnails to add that image to the viewer

Click on terms to select them

Click on download items to begin downloading

Run term related queries

2.5 - This is the Term Context tab

Home resets your view

Use the zoom icons or scroll with the mouse to zoom in/out

Click to refresh to the current focus term

Select either the location or the classification for the current term

2.6 - This is the Circuit Browser tab

The ‘strongest’ paths are the shortest/highest weighted paths. Paths are arranged from the ‘strongest’ at the bottom to the ‘weakest’ at the top. A detailed explanation for the algorithm used to determine path strengths can be found here.

Search for the source neuron to start from (Note: query is directional)

Search for the target neuron

Maximum number of paths to return (only the ‘strongest’ paths will be returned)

A minimum weight for the synapse count of each connection can be applied, paths containing individual connections below this minimum will not be returned

2.7 - How to Interpret VFB Thumbnails

How to Interpret VFB Thumbnails

Here is a guide on how to interpret VFB thumbnails:

• Each pixel in a VFB thumbnail corresponds to a specific depth in the image stack.
• Brighter or more intense colors indicate higher intensity values at that depth.
• The color bar on the right side of the image provides additional context about the mapping between color and depth.
• Each color in the color bar corresponds to a specific depth in the image stack, and the intensity of the color represents the maximum intensity value at that depth.
• Users can use the color bar to identify the depth of the signal and gain insights into the distribution of intensity values across different depths in the image stack.

• Note the colour bar and hence the signal in the image uses nealy the whole of the available (Z) stack space.

• Note the colour bar and hence the signal in the image uses less of the available (Z) stack space.

• Note the colour bar and hence the signal in the image uses much less of the available (Z) stack space.

In summary, VFB thumbnails provide a simplified way to visualize complex 3D image data. Each pixel’s color and intensity represent the maximum intensity value at a specific depth, and the color bar provides additional context about the mapping between color and depth. By interpreting the colors and using the color bar, users can gain insights into the distribution of intensity values across the image stack.

2.8 - Similarity Score Queries Guide

Scores Availability

The similarity scores are calculated using NBLAST or other third-party scores (e.g. NeuronBridge). Only queries with above-threshold scores will appear in the ‘Find similar…’ menu.

Step 1: Select a Neuron or Expression Pattern

Navigate to the VFB browser and select a neuron or expression pattern of interest so it’s information is shown in the Term Info panel

Step 2: Open the ‘Find similar…’ Menu under the ‘Query For’ section

Under the ‘Query For’ section, locate the ‘Find similar…’ expandable menu. This menu will only appear if an above-threshold score is available for the selected neuron or expression pattern.

Step 3: Run a Similarity Score Query

Inside the ‘Find similar…’ menu, you will find queries to find morphologically similar neurons or expression patterns. Select a query to run it. The results will display neurons or expression patterns that are similar to your selected neuron or expression pattern.

Note: We recalculate these scores shortly after new data is added, so new matches may appear if you check back a few months later.

2.9 - Bulk Image Download

Using the Bulk Image Download Tool

Follow these steps to download multiple files from VirtualFlyBrain using the bulk download tool:

Step 1: Open the Images

Navigate to the VFB Browser and open all the images you are interested in downloading. You can do this by searching for specific images and opening their respective pages.

Step 2: Open the Bulk Download Tool

Once you have all the images open, locate the bulk download icon in the top right. Click on this icon to open the bulk download tool.

Step 3: Select the Data Type

In the bulk download tool, select the type of data you want to download. The options are OBJ, SWC, NRRD, and References.

Step 4: Select the Variables

If applicable, select specific variables related to the data type you have chosen.

Step 5: Download the Data

After making your selections, click the ‘Download’ button to start the download. The data will be downloaded in a zip file named “VFB Files.zip”.

Step 6: Unzip the File

Once the download is complete, locate the zip file in your downloads folder and unzip it to access the data.

Step 7: Open the Data

Finally, open the data in your chosen software. For example, if you chose OBJ, you could open the data in a 3D modeling program.

Note: If something goes wrong during the download, an error message will be displayed and you will be prompted to try again. If no entries are found for the selected types and variables, a message will be displayed to inform you.

2.10 - Single cell RNAseq data

Finding gene expression data on VFB

Finding cell type clusters

Cell types with available scRNAseq data can be identified using the ‘Has scRNAseq data filter’ when searching.

Clusters for a cell type of interest can be found via the ‘Single cell transcriptomics data for…’ query.

Gene expression data

After selecting a cluster, gene expression can be retrieved via the ‘Genes expressed in…’ query.

Expression level is the mean counts per million reads of all cells in the cell type cluster that express the given gene. Expression extent is the proportion of cells within the cluster that express the given gene. VFB only shows genes that are expressed in at least 20% of cells in the cluster (Extent > 0.2).

Gene semantic tags

We add semantic tags to genes to allow quick searching and filtering of results (‘Function’ column of gene expression data). These tags are based on FlyBase Gene Group membership and GO annotations, which are all sourced from FlyBase. A full list of gene tags with their associated Gene group and GO terms can be found here.

API

Data can also be retrieved using VFB_connect.

Tutorial

Documentation

Data sources and processing

1. Raw scRNAseq data is ingested by the EBI Single Cell Expression Atlas (SCEA). Where possible, cells are linked to cell types from the Drosophila Anatomy Ontology based on author annotations. Data is reprocessed, filtered and reclustered.
2. FlyBase takes data from EBI, keeping only cells that are linked to ontology terms and generating summary expression data for each cell type (cluster).
3. VFB takes control/wild type expression data from FlyBase for datasets where at least one nervous system cell type is present and filter out any genes expressed in less than 20% of cells per cluster.

Database schema

A simplified schema showing how scRNAseq data is stored in the VFB Neo4j database is shown below:

Cell types are classes from the Drosophila Anatomy Ontology and are also linked to several other types of data in VFB, such as images, connectomics and driver expression information.

3 - Examples

3.1 - Circuit diagram of the mushroom body

https://doi.org/10.7554/eLife.04580.003

4 - Concepts

4.1 - Transgene Expression

Here we present details of how single transgenes are curated

Expression of single transgenes are curated from the published literature into FlyBase as expression statements. Virtual Fly Brain (VFB) combines hosted images with neuroanatomical, expression and genetic data from FlyBase in Neo4j and maps them onto Central Nervious System (CNS) templates where they can be queried using Web Ontology Language (OWL) and Solr.

4.2 - Split Expression

Thousands of hemi-driver transgenes are now available, meaning that millions of combinations/splits are possible, each targeting some precise subset of the 10s-100s of thousands of neurons in a fly Central Nervous System (CNS). Finding the right combination for an experiment is a serious bottleneck for researchers.

FlyBase & Virtual Fly Brain (VFB) solve this problem by curating information and images recording where expression is driven by combinations of hemi-drivers. Each combination gets a standard name on VFB reflecting the names of the component hemidrivers (see figure below) and is also associated with any short names for the combination used in the literature (e.g. “P{VT017411-GAL4.DBD} ∩ P{VT019018-p65.AD} expression pattern” has_exact_synonym: SS02256")

We use programmatic methods to generate expression statements for hemi-driver combinations with FlyLight image data hosted by VFB. Combinations are validated against a local copy of the FlyLight dataset and a structured user readable comment is generated as part of the expression statement. These hyperlink to the partner hemi-driver in FlyBase, contain the strain designation (where available) and can be automatically parsed by Virtual Fly Brain to attach expression and genetic data to a node representing the intersection.

4.3 - NBLAST

What is NBLAST?

NBLAST (Costa et al., 2016) is a computational method to quantify morphological similarity between neurons. It provides an objective way to compare neuron shapes and identify morphologically similar cells within and across datasets.

How NBLAST works

NBLAST operates on “dotprops” - a representation of neurons as tangent vectors that capture the local geometry of neuronal arbors. The algorithm:

1. Converts neurons to dotprops: Each neuron is represented as a set of points with associated directional vectors
2. Compares vector pairs: For each tangent vector in a query neuron, NBLAST finds the closest tangent vector in the target neuron
3. Calculates similarity scores: Scores are computed based on both the distance between vectors and their directional similarity (dot product)
4. Normalizes results: Final scores are typically normalized to a self-self comparison, where a perfect match equals 1

NBLAST on VFB

VFB provides precomputed NBLAST scores for all neurons in its database, making morphological similarity searches fast and accessible without requiring computational expertise.

What’s included

VFB NBLAST scores cover:

• All individual neurons from major connectome datasets including:

  • FAFB-FlyWire
  • Male-CNS optic lobe
  • Hemibrain
  • FlyCircuit
  • FAFB-CATMAID datasets

• Split-GAL4 expression patterns from FlyLight, enabling discovery of potential driver lines that label specific morphological types

Types of comparisons

1. Neuron-to-neuron: Find morphologically similar neurons within or across datasets
2. Neuron-to-expression pattern: Identify split-GAL4 lines that might label neurons similar to those in connectome datasets

Using NBLAST on VFB

Accessing NBLAST queries

NBLAST similarity searches are available directly in the VFB interface:

1. Navigate to any individual neuron or split-GAL4 image page
2. Scroll to the term info panel
3. Look for NBLAST query options (only appears if results are available)
4. Click to see ranked lists of morphologically similar items

Interpreting results

NBLAST scores range from -1 to 1:

• 1.0: Perfect match (identical morphology)
• 0.5-1.0: High similarity
• 0.0-0.5: Moderate similarity
• Below 0.0: Low similarity or dissimilar morphologies

Results are typically ranked by score, with the most similar items appearing first.

Applications

Research applications

• Cell type classification: Group neurons by morphological similarity
• Cross-dataset comparison: Find corresponding cell types across different connectomes
• Driver line selection: Identify genetic tools for targeting specific morphological types
• Evolutionary studies: Compare homologous neurons across species

Workflow integration

NBLAST results on VFB can be:

• Exported for further analysis
• Used to build custom neuron collections
• Combined with other search criteria (anatomy, connectivity)
• Accessed programmatically via VFB APIs

Technical considerations

Optimization for VFB

• All neurons are standardized to common template spaces
• Consistent spatial resolution across datasets
• Normalized scoring for cross-dataset comparisons
• Regular updates as new data becomes available

Limitations

• Focuses purely on morphological similarity
• May not capture functional relationships
• Sensitive to differences in reconstruction quality
• Template registration accuracy affects cross-dataset comparisons

Further reading

• NBLAST tutorial - Detailed programming tutorial
• Original NBLAST paper - Costa et al., 2016
• VFB NBLAST announcement - Recent updates and expanded coverage

4.4 - Templates

Many central nervious system (CNS) templates exist for Drosophila, below we provide a summary of those used in VFB.

Central Nervious System from Janelia Research Campus JRC2018

VFB displays data aligned to either the JRC 2018 unisex brain template for cephalic or JRC 2018 unisex Ventral Nerve Cord (VNC) for non-cephalic data.

Bogovic et al., “An unbiased template of the Drosophila brain and ventral nerve cord”

We recomend downloading templates from the VFB browser or the links below however the original files are available from Janelia: JRC 2018 Brain templates

Adult Brain from Janelia Research Campus/VFB (JFRC2010/JFRC2)

Superceeded by JRC2018

Template brain created by Arnim Jenett (Janelia Research Campus), Kazunori Shinomiya and Kei Ito (Tokyo University) from a staining with the neuropil marker nc82.

The voxel size is 0.62x0.62x0.62 micron.

The files are available here.

Painted domains/regions in the available templates

4.5 - Bridging Registrations

Many transforms to map between different Drosophila template brains are available.

You can see how to use the above in python using navis-flybrains or in R using nat.flybrains

4.6 - Cell Types

Neurons on VFB are annotated with cell types from the Drosophila Anatomy Ontology (FBbt).

Why do we use ontology terms?

• Each term represents a concept of a cell type, with a definition based on referenced publications:
• As well as a label, each term has a collection of synonyms, facilitating identification even when the same type has been referred to by different names in different sources:
• Hierarchical – e.g. specific terms for MBON01, MBON02 etc., but also grouped by a general MBON term and all under ‘adult neuron’
• Neurons of the same type in multiple datasets can be linked to the same ontology term
• Persistent, resolvable identifiers to uniquely identify cell types e.g. http://virtualflybrain.org/reports/FBbt_00100234

We also use terms from the Drosophila Anatomy Ontology to annotate CNS regions (for the Template ROI Browser tool and neuron connectivity per region query) and other anatomical features.

4.7 - Confidence Values

Some annotations on VFB are based on predictions, for example, predicted neurotransmitters for neurons in electron microscopy datasets (see below). Where available, we include the confidence of these predictions (as a badge next to the annotation), as well as a link to the publication - in the example below, this would be by clicking on the ‘DOI’ badge.

Neurotransmitter Prediction Confidence Values

Neurotransmitter predictions for neurons in the FlyWire FAFB and Hemibrain datasets are the ‘conf_nt’ predictions from Eckstein et al. (2024). MANC, optic-lobe and BANC predictions are from Takemura et al. (2023), Nern et al. (2025) and Bates et al. (2025), respectively, using the methodology of Eckstein et al. (2024). This analysis only investigated a limited set of neurotransmitters and assumed a single neurotransmitter per neuron (see publications for further detail). Neurons with fewer than 100 presynapses are excluded.

4.8 - FlyLight Adult CNS Imaging Tiles

While most first-generation FlyLight expression pattern images are single 20x objective acquisitions, many Split-GAL4 lines were imaged using 63x or 40x objectives. This requires multiple image acquisitions to cover the CNS regions of interest. VFB integrates only the combined images derived from these tiles and lists the tiles used to create these combined images in the comment section for each image, for example: “tile(s): ’left_dorsal, right_dorsal, ventral”. These tiles do not necessarily cover the entire brain or VNC, which complicates the assessment of the specificity of these lines. VFB notes in the comment where the combined tiles do not provide full coverage. For further information refer to Figure 4 Supplemental File 1 from ‘A split-GAL4 driver line resource for Drosophila CNS cell types’ direct link. This is a preprint and may be updated.

Sets of tiles from FlyLight (Meissner et al., 2024):

5 - Tutorials

5.1 - VFB Model Context Protocol (MCP) Tool Guide

Overview

The Virtual Fly Brain Model Context Protocol (MCP) Tool enables you to query VFB data through Large Language Models like Claude using natural language. This guide shows you how to get started and provides examples of common queries.

What is MCP?

The Model Context Protocol is a standard that allows LLMs to interact with external data sources and tools. The VFB MCP tool follows this standard, providing your LLM with access to VFB’s neuroanatomical databases, NBLAST similarity scores, and term information.

Accessing the Tool

The VFB MCP tool is available at: vfb3-mcp.virtualflybrain.org

Quick Start

Use the Live Service (Recommended)

The easiest way to use VFB3-MCP is through our hosted service. This requires no installation or setup on your machine.

Claude Desktop Setup

1. Open Claude Desktop and go to Settings
2. Navigate to the MCP section
3. Add a new MCP server with these settings:
   • Server Name: virtual-fly-brain (or any name you prefer)
   • Type: HTTP
   • Server URL: https://vfb3-mcp.virtualflybrain.org

Configuration JSON (alternative method):

{
  "mcpServers": {
    "virtual-fly-brain": {
      "type": "http",
      "url": "https://vfb3-mcp.virtualflybrain.org",
      "tools": ["*"]
    }
  }
}

Claude Code Setup

1. Locate your Claude configuration file:
   • macOS/Linux: ~/.claude.json
   • Windows: %USERPROFILE%\.claude.json
2. Add the VFB3-MCP server to your configuration:

{
  "mcpServers": {
    "virtual-fly-brain": {
      "type": "http",
      "url": "https://vfb3-mcp.virtualflybrain.org",
      "tools": ["*"]
    }
  }
}

3. Restart Claude Code for changes to take effect

GitHub Copilot Setup

1. Open VS Code with GitHub Copilot installed
2. Open Settings (Ctrl/Cmd + ,)
3. Search for “MCP” in the settings search
4. Find the MCP Servers setting
5. Add the server URL: https://vfb3-mcp.virtualflybrain.org
6. Give it a name like “Virtual Fly Brain”

Alternative JSON configuration (in mcp.json):

{
  "servers": {
    "virtual-fly-brain": {
      "type": "http",
      "url": "https://vfb3-mcp.virtualflybrain.org"
    }
  }
}

Visual Studio Code (with MCP Extension)

1. Install the MCP extension for VS Code from the marketplace
2. Open the Command Palette (Ctrl/Cmd + Shift + P)
3. Type “MCP: Add server” and select it
4. Choose “HTTP” as the server type
5. Enter the server details:
   • Name: virtual-fly-brain
   • URL: https://vfb3-mcp.virtualflybrain.org
6. Save and restart VS Code if prompted

Other MCP Clients

For any MCP-compatible client that supports HTTP servers:

{
  "mcpServers": {
    "virtual-fly-brain": {
      "type": "http",
      "url": "https://vfb3-mcp.virtualflybrain.org",
      "tools": ["*"]
    }
  }
}

Gemini Setup

To use the Virtual Fly Brain (VFB) Model Context Protocol (MCP) server with Google Gemini, you can connect through custom Python/Node.js clients that support MCP.

Note: Direct Gemini web interface integration with MCP is not currently supported. Developer tools are needed to connect the two.

Option 1: Using Python

For application development, use the mcp and google-genai libraries to connect.

Setup: pip install google-genai mcp

Implementation: Use an SSEClientTransport to connect to the VFB URL, list its tools, and pass their schemas to the Gemini model as Function Declarations.

Testing the Connection

Once configured, you can test that VFB3-MCP is working by asking your AI assistant questions like:

Basic Queries:

• “Get information about the neuron VFB_jrcv0i43”
• “Search for terms related to medulla in the fly brain”
• “What neurons are in the antennal lobe?”

Advanced Queries:

• “Find all neurons that connect to the mushroom body”
• “Show me expression patterns for gene repo”
• “What brain regions are involved in olfactory processing?”
• “Run a connectivity analysis for neuron VFB_00101567”

Search Examples:

• “Search for adult neurons in the visual system”
• “Find genes expressed in the central complex”
• “Show me all templates available in VFB”

If you see responses with VirtualFlyBrain data, including neuron names, brain regions, gene expressions, or connectivity information, the setup is successful!

For more detailed usage examples and API calls, see examples.md.

Local Installation

If you prefer to run the MCP server locally, see the VFB3-MCP repository README for detailed installation instructions.

Core Features

The tool provides access to three main capabilities:

1. Term Information Queries (get_term_info)

Retrieve detailed information about any VFB term using its VFB ID.

Example Query:

"What is the medulla? Please get the full definition and structure."

Returns:

• Term definition and synonyms
• Classification and type information
• Anatomical relationships (part of, develops from, innervates, etc.)
• Associated neurons and expression patterns
• Related images and connectivity data

2. Term Search (search_terms)

Search for VFB terms using keywords and filters.

Example Query:

"Find neurons in the medulla"

Advanced Filtering Options:

• Filter by entity type: neuron, muscle, glia, anatomical region
• Filter by nervous system component: visual system, olfactory system, sensory neuron, motor neuron, etc.
• Filter by nervous system property: cholinergic, GABAergic, glutamatergic, dopaminergic, peptidergic, etc.
• Filter by dataset: FAFB, FlyCircuit, hemibrain, neuprint, flycircuit, etc.

3. Query Execution (run_query)

Execute specific queries on VFB terms, including NBLAST similarity analysis.

Example Query:

"What neurons are morphologically similar to IN02A049?"

Example Use Cases

Case 1: Exploring a Transgenic Construct

User Question: “What is P{E(spl)m8-HLH-2.61} and where is it used?”

Tool Actions:

1. Search for the construct in VFB
2. Retrieve full term information
3. Return detailed description including:
   • FlyBase ID (FBtp0004163)
   • Gene involved: E(spl)m8
   • Type: Transgenic construct (reporter for gene expression)
   • Expression patterns and research use
   • Related constructs and variants

Result: You get comprehensive information about the transgenic reporter, its purpose, and research applications.

Case 2: Understanding a Neuroblast Population

User Question: “What is the Medulla Forming Neuroblast and what role does it play?”

Tool Actions:

1. Search for “medulla forming neuroblast”
2. Get term info for FBbt_00001938
3. Return:
   • Cell type classification (neuroblast)
   • Location in the larval optic anlage
   • Developmental fate (produces medulla neurons)
   • Marker genes (dpn, ase)
   • Number of neurons produced (~54,000 secondary neurons)
   • Available scRNAseq and expression data

Result: Understand the neuroblast’s role in developing the adult medulla’s neural circuitry.

Case 3: Discovering Neuron Types

User Question: “What types of neurons are in the medulla?”

Tool Actions:

1. Search for “neuron” with filter for medulla
2. Return 472 neuron types with parts in the medulla, organized by category:
   • Medulla intrinsic neurons (Mi): columnar neurons with confined processes
   • Central medulla intrinsic neurons (Cm): arborizing in central/serpentine layer
   • Medulla tangential neurons (Mt): wide-field spanning neurons
   • Medulla visual projection neurons (MeVP): tangential projection neurons
   • Medulla columnar neurons (MC): connecting medulla to tubercle
   • Plus many more specialized types

Result: Get a comprehensive overview of medulla neuron diversity and organization.

Case 4: Morphological Similarity Queries

User Question: “Show me what the IN02A049 neuron looks like and find similar neurons.”

Tool Actions:

1. Get term info for IN02A049 (specific instance from MANC connectome)
2. Execute NBLAST query for morphologically similar neurons
3. Return:
   • 3D visualization of the neuron
   • Classification and properties
   • Synaptic inputs (neurotransmitter types and counts)
   • Morphologically similar neurons with NBLAST scores
   • Cross-connectome comparisons

Result: Discover morphologically similar neurons for comparative analysis.

Case 5: Understanding NBLAST Scores

User Question: “How are NBLAST scores calculated?”

Tool Actions:

1. Search for “NBLAST”
2. Return detailed explanation including:
   • Algorithm basis (Costa et al. 2016)
   • How neurons are represented (point skeletons with direction vectors)
   • Scoring mechanism (Euclidean distance + direction similarity)
   • Normalization approach (comparison to self-match)
   • Asymmetry property and symmetrical variants
   • Available datasets (FAFB-FlyWire, Male-CNS optic lobe, FlyCircuit, Hemibrain, FAFB-CATMAID)

Result: Understand the methodology behind VFB’s morphological similarity analysis.

Tips for Effective Queries

1. Use VFB IDs When Known

If you know the VFB ID of a term, use it directly:

"Get me detailed information about FBbt_00003748 (the medulla)"

2. Combine Search and Query

Use search first to find relevant terms, then query them:

"Find all cholinergic neurons in the visual system, 
then tell me about the top 5"

3. Filter Strategically

Use filters to narrow results:

"Show me motor neurons from the male-CNS optic lobe dataset"

4. Explore Relationships

Ask about anatomical and functional relationships:

"What neurons innervate the medulla? 
What brain regions do they come from?"

5. Cross-Dataset Comparisons

Compare neurons across different connectome datasets:

"Find the equivalent of this FAFB neuron in the hemibrain dataset"

Available Datasets

The VFB MCP tool provides access to neurons and data from:

• FAFB-FlyWire (v783) - Large-scale adult brain connectome
• Male-CNS optic lobe (v1.0.1) - Focused optic lobe connectome
• FlyCircuit (1.0) - Single-neuron morphology database
• Hemibrain (1.2.1) - Subset of adult brain connectome
• FAFB-CATMAID - Manually traced EM data
• FlyLight Split-GAL4 - Driver line expression images
• scRNAseq data - Transcriptomic information

Understanding VFB IDs

VFB terms use standardized identifiers:

• FBbt_ - Drosophila anatomy terms (e.g., FBbt_00003748 = medulla)
• FBgn_ - FlyBase genes (e.g., FBgn0000137 = ase gene)
• FBtp_ - FlyBase transgenic constructs (e.g., FBtp0004163 = P{E(spl)m8-HLH-2.61})
• VFB_ - VirtualFlyBrain-specific IDs for individuals and images

Next Steps

• Explore the tool: Visit vfb3-mcp.virtualflybrain.org
• Read more about NBLAST: See our NBLAST concepts page
• Learn about VFB APIs: Check our API overview
• Browse VFB directly: Visit the main Virtual Fly Brain site

Common Questions

Q: Do I need to install anything? A: No, if you’re using Claude or another MCP-compatible LLM with the integration already set up, just start asking questions.

Q: Can I download the data I find? A: Yes, many results include links to download images, neuron skeletons, and connectivity data. Check the API documentation for programmatic access.

Q: What if I don’t know the VFB ID? A: The search tool can find terms by name or keyword. The LLM will help you locate the right term.

Q: Can I combine VFB queries with other analyses? A: Absolutely! You can ask your LLM to retrieve VFB data and then perform additional analyses, create visualizations, or integrate with other tools.

Happy exploring! If you have questions or suggestions about the VFB MCP tool, please reach out to the VFB team.

5.2 - Application Programming Interfaces (APIs)

5.2.1 - Guide to Working with Images from Virtual Fly Brain (VFB) Using the VFBConnect Library

Prerequisites

Before starting, ensure you have the VFBConnect library installed. The recommended Python version is 3.10.14, as this version is tested against the library.

pip install vfb-connect

Importing the VFBConnect Library

Start by importing the VFBConnect library. This library provides a simple interface to interact with neuron data from the Virtual Fly Brain.

from vfb_connect import vfb

Retrieving Neuron Data

To work with specific neurons, you can use the vfb.term() function. This function takes a unique identifier (e.g., ID, label, synonym) for the neuron.

Example: Retrieving a Single Neuron

neuron = vfb.term('5th s-LNv (FlyEM-HB:511051477)')

The neuron variable now holds data about the neuron identified by the given term.

Working with Neuron Data

The retrieved neuron object can provide different representations of neuron data, such as its skeleton, mesh, and volume. These representations can be visualized using various plotting methods.

# Access the skeleton representation
neuron_skeleton = neuron.skeleton

# Check the type of the skeleton representation
print(type(neuron_skeleton))  # Output: <class 'navis.neuron.Neuron'>

# Plot the skeleton in 2D
neuron_skeleton.plot2d()

# Access the mesh representation
neuron_mesh = neuron.mesh

# Access the volume representation
neuron_volume = neuron.volume

Retrieving Multiple Neurons

You can retrieve multiple neurons using the vfb.terms() function, which accepts a list of neuron identifiers.

Example: Retrieving Multiple Neurons

neurons = vfb.terms(['5th s-LNv', 'fru-M-300008', 'catmaid_fafb:8876600'])

This command retrieves multiple neurons, which can then be visualized or manipulated collectively.

Flexible Matching Capabilities

One of the key features of the VFBConnect library is its flexible matching capability. The vfb.terms() function can accept a variety of identifiers, such as:

• IDs: Unique identifiers assigned to each neuron.
• Xref (Cross-references): External references that relate to other datasets.
• Labels: Human-readable names for neurons.
• Symbols: Abbreviated names or symbols used to represent neurons.
• Synonyms: Alternative names by which a neuron might be known.
• Partial Matching: You can provide a partial name, and VFBConnect will attempt to find the best match.
• Case Insensitive Matching: Matching is case insensitive, so if an exact match isn’t found, ‘5th s-LNv’ and ‘5TH S-LNV’ are treated the same. This allows for more flexible querying without worrying about exact case matching.

Example: Using Flexible Matching

neurons = vfb.terms('5th s-LN')

If an exact match isn’t found, VFBConnect will provide potential matches. This feature ensures that even with partial or approximate information, you can still retrieve the relevant neuron data.

Output Example:

Notice: No exact match found, but potential matches starting with '5th s-LN': 
'5th s-LNv (FlyEM-HB:511051477)': 'VFB_jrchk8e0', 
'5th s-LNv': 'VFB_jrchk8e0'

This notice will help you identify the correct neuron based on the closest matches.

Visualizing Neurons

VFBConnect provides various methods to visualize neuron data, both individually and collectively.

3D Visualization

To plot neurons in 3D, use the plot3d() method. This is useful for visualizing the spatial structure of neurons.

neurons.plot3d()

2D Visualization

For 2D visualization, use the plot2d() method.

neurons.plot2d()

Viewing Merged Templates

VFBConnect also allows viewing merged templates of neurons, combining multiple neuron structures into a single view.

neurons.show()

Opening Neurons in VFB

To open the neurons directly in Virtual Fly Brain, use the open() method. This will launch a browser window displaying the neurons in the VFB interface.

neurons.open()

Summary

• Use vfb.term() to retrieve single neuron data.
• Use vfb.terms() to retrieve multiple neurons with support for partial, case-insensitive, and flexible matching (IDs, labels, symbols, synonyms, etc.).
• Access different data representations (skeleton, mesh, volume) via neuron objects.
• Visualize neuron data in 2D and 3D.
• Use the show() method to view merged neuron templates.
• Open neuron data directly in Virtual Fly Brain with the open() method.

These examples provide a foundation for working with neuron data from Virtual Fly Brain using the VFBConnect library. By exploring different neuron representations and visualization methods, you can analyze and understand neuron structures more effectively.

5.2.2 - Hacking the connectome

Below you can watch the recorded introduction session of our workshop and follow along with the workshop notebooks we work through to show examples of how you can use the available {{ ref “tools.md” tools }} to explore and analyse the published connectomes available on VFB.

5.2.2.1 - Tool landscape

Below are brief descriptions of the libraries/packages. For details, I defer to their respective (excellent) documentations.

Querying VFB

Queries against VFB’s REST API are easiest with vfb_connect for Python. For R there is a vfb_connect wrapper, vfbconnectr. See also David’s presentation for details.

R

In R, the natverse is your one-stop-shop for all things neuron: it’s a collection of various R packages that are built on top of the neuroanatomy toolbox, nat. Of particular relevance for this workshop:

1. nat is a general purpose library for working with morphological neuron data. In this workshop, we make heavy use of nat’s plotting capabilities but its capabilities extend far beyond that. If you want to run any morphological analysis, I highly recommend you have a look at the “Articles” in nat’s doc.
2. neuprintr and hemibrainr provide an interface with neuprint and the Janelia hemibrain dataset (link). The former lets you run queries against neuprint’s neo4j database while the latter contains meta data and various convenience functions to work with the hemibrain dataset.
3. rcatmaid provides an interface with CATMAID servers such as those the VFB uses to host published from the FAFB or larval fruit fly dataset. rcatmaid is built on top of nat and you can use nat functions with neurons pulled via rcatmaid.

Python

In Python, we find packages analogous to those in R:

1. navis is nat’s serpentine sibling: a general purpose neuron library for visualization and analysis of neuronal morphologies. It also features interfaces e.g. with Blender 3D and the natverse via rpy2.
2. python-neuprint is a Python library to interface with neuprint maintained by Janelia. Note that navis wraps this library and adds some convenience functions. See this tutorial.
3. pymaid lets you interface with CATMAID servers. Critically, it’s built on top of navis and you can natively use navis functions with pymaid neurons. Note that due to a name clash the library is called python-catmaid on PyPI.

Noteworthy mentions

There are a few more packages/functions that you might hear of over the course of the workshop.

NBLAST

NBLAST is an algorithm that computes morphological similarity between neurons (Costa et al., 2016). This has proven incredibly useful to find similar neurons across datasets but also to cluster neurons into cell types.

On the R side the algorithm is implemented in nat.nblast and in Python it is part of navis (see this tutorial).

Transforms

You will note that neurons pulled from VFB are typically in the same template space which makes co-visualization of neurons from different datasets a breeze. If you want to transform spatial data between template brains, e.g. from FAFB (“FAFB14”) to hemibrain (“JRCFIB2018F”), you should look for nat.flybrains & nat.jrcbrains in R and navis-flybrains in Python.

5.2.2.2 - Introduction to connectomic data and tools

5.2.2.3 - Discovery

Required packages: vfb-connect and python-catmaid (pymaid & navis)

!pip install vfb-connect --upgrade
!pip install python-catmaid --upgrade

A note on using these notebooks

This is designed as an interactive tutorial. Feel free to add code cells below each example to try out variations of your own.

How to find neurons across datasets

VirtualFlyBrain integrates images and connectomics profiles of neurons from many sources. It classifies and records their properties using a standard, queryable classification (The Drosophila Anatomy Ontology). This standardises the names of neuron types across sources, so you don’t need to worry about differences in nomenclature uses and supports queries for neurons by their classification.

# Import libs and initialise API objects
from vfb_connect.cross_server_tools import VfbConnect
import pandas as pd
vc = VfbConnect()

import pymaid
import navis

navis.set_pbars(jupyter=False)
pymaid.set_pbars(jupyter=False)

# Connect to the VFB CATMAID server hosting the FAFB data
rm = pymaid.connect_catmaid(server="https://fafb.catmaid.virtualflybrain.org/", api_token=None, max_threads=10)

# Test call to see if connection works 
print(f'Server is running CATMAID version {rm.catmaid_version}')

WARNING: Could not load OpenGL library.
INFO  : Global CATMAID instance set. Caching is ON. (pymaid)
Server is running CATMAID version 2020.02.15-905-g93a969b37

Finds neurons by type (classification) across datasets

We can use the vc.get_instances method in combination with the name of a neuron type on VFB to find individual neurons from multiple sources.

Use the search tool on VFB to find neuron types by name or synonym:

Use either the full name or the Symbol to query for neurons:

DA3adPN = vc.get_instances("adult Drosulfakinin neuron", summary=True)
pd.DataFrame.from_records(DA3adPN)

Find neurons by location

We can use the same method to search for neurons by location, using simple queries.

# Find neurons by location. The following query works across multiple data sources and both sides of the brain.  
# Results may be incomplete & may include minor overlap inferred from low synapse counts

neurons_in_DA3 = vc.get_instances("'neuron' that 'overlaps' some 'antennal lobe glomerulus DA3'", summary=True)
neurons_in_DA3_tab = pd.DataFrame.from_records(neurons_in_DA3)
neurons_in_DA3_tab[0:5]

Running query: FBbt:00005106 that RO:0002131 some FBbt:00003934
Query URL: http://owl.virtualflybrain.org/kbs/vfb/instances?object=FBbt%3A00005106+that+RO%3A0002131+some+FBbt%3A00003934&prefixes=%7B%22FBbt%22%3A+%22http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FFBbt_%22%2C+%22RO%22%3A+%22http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_%22%2C+%22BFO%22%3A+%22http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FBFO_%22%7D&direct=False
Query results: 158

# Find local interneurons (intrinsic neurons) of the AL, overlapping DA3:

local_in_DA3 = vc.get_instances("'local interneuron of adult antennal lobe' that 'overlaps' some 'antennal lobe glomerulus DA3'",
                                summary=True)
local_in_DA3_tab = pd.DataFrame.from_records(local_in_DA3)
local_in_DA3_tab

Running query: FBbt:00007390 that RO:0002131 some FBbt:00003934
Query URL: http://owl.virtualflybrain.org/kbs/vfb/instances?object=FBbt%3A00007390+that+RO%3A0002131+some+FBbt%3A00003934&prefixes=%7B%22FBbt%22%3A+%22http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FFBbt_%22%2C+%22RO%22%3A+%22http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_%22%2C+%22BFO%22%3A+%22http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FBFO_%22%7D&direct=False
Query results: 53

# Find neurons by dataset/paper - on CATMAID

bates = pymaid.find_neurons(annotations='Paper: Bates and Schlegel et al 2020')
bates

INFO  : Found 583 neurons matching the search parameters (pymaid)

# Inspect what datasets are available on VFB

ds = vc.neo_query_wrapper.get_datasets(summary=True)
ds_tab = pd.DataFrame.from_records(ds)
ds_tab.sort_values(by=['id'])

sayin_tab = pd.DataFrame.from_records(vc.get_instances_by_dataset('Sayin2019', summary=True))
sayin_tab

vc.get_connected_neurons_by_type(upstream_type='LNd', downstream_type='adult descending neuron', weight=20)

# Intra pacemaker neuron neuron connections

vc.get_connected_neurons_by_type(upstream_type='pacemaker neuron', downstream_type='pacemaker neuron', weight=20)

vc.get_connected_neurons_by_type(upstream_type='adult neuron', downstream_type='adult Drosulfakinin neuron', weight=20)

5.2.2.4 - Mapping

!pip install vfb-connect --upgrade

# Import libs and initialise API objects
from vfb_connect.cross_server_tools import VfbConnect
import pandas as pd

vc = VfbConnect()

import pymaid
import navis

navis.set_pbars(jupyter=False)
pymaid.set_pbars(jupyter=False)

# Connect to the VFB CATMAID server hosting the FAFB data
rm = pymaid.connect_catmaid(server="https://fafb.catmaid.virtualflybrain.org/", api_token=None, max_threads=10)

# Test call to see if connection works 
print(f'Server is running CATMAID version {rm.catmaid_version}')

# Many functions return JSON-compatible nested data structures. This function coverts them to DataFrame.
def summary_2_df(summary, sort=None):
    """Convert summary to DataFrame.  Optionally specify a set of columns to sort as a list of strings"""
    if sort:
        return pd.DataFrame.from_records(summary).sort_values(sort)
    else:
        return pd.DataFrame.from_records(summary)

WARNING: Could not load OpenGL library.
INFO  : Global CATMAID instance set. Caching is ON. (pymaid)
Server is running CATMAID version 2020.02.15-925-gf56795c9c

Mapping

Use case: If I have a single neuron, how can I find other neurons of the same or similar type within or between data sources?

Mapping via common parent type

# lets take some examples from a discovery query on the previous spreadhseet
sayin_tab = pd.DataFrame.from_records(vc.get_instances_by_dataset('Sayin2019', summary=True))
sayin_tab

oct_VPM3 = summary_2_df(vc.get_instances('octopaminergic VPM3 neuron', summary=True))
oct_VPM3

oct_VPM3_images = vc.neo_query_wrapper.get_images(oct_VPM3['id'], stomp=True, template='JRC2018Unisex', image_folder = 'oct_VPM3b')
oct_VPM3_images

oct_VPM3_images = vc.get_images_by_type('octopaminergic VPM3 neuron', stomp=True, template='JRC2018Unisex', image_folder = 'oct_VPM3')
nl = navis.read_swc('./oct_VPM3')
navis.plot3d(nl)

Running query: FBbt:00110151
Query URL: http://owl.virtualflybrain.org/kbs/vfb/instances?object=FBbt%3A00110151&prefixes=%7B%22FBbt%22%3A+%22http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FFBbt_%22%2C+%22RO%22%3A+%22http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FRO_%22%2C+%22BFO%22%3A+%22http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FBFO_%22%7D&direct=False
Query results: 3