Tutorials

• 1: Application Programming Interfaces (APIs)
• 1.1: Hacking the connectome
• 1.1.1: Tool landscape
• 1.1.2: Introduction to connectomic data and tools
• 1.1.3: Discovery
• 1.1.4: Mapping
• 1.1.5: Visualisation
• 1.1.6: Connectomics
• 1.1.7: NBLAST
• 1.2: VFB connect API overview
• 1.3: Data types
• 1.4: Plotting
• 1.5: pymaid
• 1.6: NBLAST
• 1.7: neuprint

1 - Application Programming Interfaces (APIs)

1.1 - 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.

1.1.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.

1.1.2 - Introduction to connectomic data and tools

1.1.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)

1.1.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