[1]:
!pip install -r ../../../requirements.txt --quiet
!pip install ../../../ --quiet

VFBTerm and VFBTerms Class Demonstration

This notebook demonstrates the usage of the vfb.term and vfb.terms methods for accessing VFB term information. We’ll explore how to create VFBTerm objects, access related terms, images, and use advanced features like lazy loading of parents and manipulating collections of terms with VFBTerms.

[2]:
# Import the VFBConnect class
from vfb_connect import vfb
Welcome to the Virtual Fly Brain API
See the documentation at: https://virtualflybrain.org/docs/tutorials/apis/

Establishing connections to https://VirtualFlyBrain.org services...
Session Established!

Type vfb. and press tab to see available queries. You can run help against any query e.g. help(vfb.terms)

Creating and Exploring VFBTerm Objects

We’ll start by creating a VFBTerm object using the vfb.term method.

[3]:
# Example of creating a VFBTerm object using a term name
vfb_term = vfb.term('medulla')
vfb_term
[3]:
VFBTerm(term=Term(term=MinimalEntityInfo(name=medulla, short_form=FBbt_00003748), link=https://n2t.net/vfb:FBbt_00003748))

Accessing Term Information

You can access various details about the term, including its name, description, and related terms.

[4]:
# Accessing term details
print(f"Name: {vfb_term.name}")
print(f"ID: {vfb_term.id}")
print(f"Description: {vfb_term.description}")
print(f"Related Terms: {vfb_term.related_terms}")
Name: medulla
ID: FBbt_00003748
Description: The second optic neuropil, sandwiched between the lamina and the lobula complex. It is divided into 10 layers: 1-6 make up the outer (distal) medulla, the seventh (or serpentine) layer exhibits a distinct architecture and layers 8-10 make up the inner (proximal) medulla (Ito et al., 2014).
Related Terms: Relations(Rel(relation=MinimalEdgeInfo(label=develops from, type=develops_from), object=VFBTerm(term=Term(term=MinimalEntityInfo(name=medulla anlage, short_form=FBbt_00001935), link=https://n2t.net/vfb:FBbt_00001935)), confidence=None), Rel(relation=MinimalEdgeInfo(label=is part of, type=part_of), object=VFBTerm(term=Term(term=MinimalEntityInfo(name=adult optic lobe, short_form=FBbt_00003701), link=https://n2t.net/vfb:FBbt_00003701)), confidence=None))

Lazy Loading of Parents

The VFBTerm class supports lazy loading for parents. The parents are only loaded when accessed (for the first time) since parents are themselves fully featured VFBTerms annd hence have their own parents etc.

[5]:
# Accessing parents (lazy loading)
parents = vfb_term.parents
print(f"Parents: {parents}")
Parents: VFBTerms(['synaptic neuropil domain', 'anterior ectoderm derivative'])

Working with Multiple Terms using vfb.terms

You can work with multiple terms at once using the vfb.terms method. Let’s see how to create a VFBTerms object and perform operations on it.

[6]:
# Example of creating a VFBTerms object using a list of term names
vfb_terms = vfb.terms(['medulla', 'nodulus'])
vfb_terms
[6]:
VFBTerms(terms=[VFBTerm(term=Term(term=MinimalEntityInfo(name=medulla, short_form=FBbt_00003748), link=https://n2t.net/vfb:FBbt_00003748)), VFBTerm(term=Term(term=MinimalEntityInfo(name=nodulus, short_form=FBbt_00003680), link=https://n2t.net/vfb:FBbt_00003680))])

Accessing Multiple Terms

You can iterate over VFBTerms to access individual VFBTerm objects.

[7]:
# Iterating over VFBTerms
for term in vfb_terms:
    print(term.name)

# though several methods exist to speed up common requirements like this:
print(f"names: {vfb_terms.get_names()}")
print(f"ids: {vfb_terms.get_ids()}")

medulla
nodulus
names: ['medulla', 'nodulus']
ids: ['FBbt_00003748', 'FBbt_00003680']

Additional Features

The vfb object provides several other methods for interacting with terms, such as get_summaries, load_skeletons, and plot3d. These can be explored similarly using the vfb.term and vfb.terms methods.

[8]:
print(f"summary of all: {vfb_terms.get_summaries()}")
summary of all:               ID     Name                                        Description  \
0  FBbt_00003748  medulla  The second optic neuropil, sandwiched between ...
1  FBbt_00003680  nodulus  Paired synaptic neuropil domain of the adult b...

                                 URL  \
0  https://n2t.net/vfb:FBbt_00003748
1  https://n2t.net/vfb:FBbt_00003680

                                       Related Terms  \
0  [Rel(relation=MinimalEdgeInfo(label=develops f...
1  [Rel(relation=MinimalEdgeInfo(label=develops f...

                                             Parents  \
0  [synaptic neuropil domain, anterior ectoderm d...
1      [synaptic neuropil domain, anatomical entity]

                                        Publications  \
0  [Ito et al., 2014, Neuron 81(4): 755--765, Nér...
1  [Wolff et al., 2015, J. Comp. Neurol. 523(7): ...

                                Cross References
0  [https://insectbraindb.org/app/structures/38]
1  [https://insectbraindb.org/app/structures/41]
[9]:
vfb_terms.plot3d()
Nothing found to plot

plot3d needs to be applied to instances rather than types

[10]:
vfb_regions = vfb.terms(['medulla on JRC2018Unisex adult brain', 'nodulus on JRC2018Unisex adult brain'])

print(f"summary of all: {vfb_regions.get_summaries()}")

vfb_regions.plot3d()
summary of all:              ID                             Name Description  \
0  VFB_00102107  ME on JRC2018Unisex adult brain
1  VFB_00102282  NO on JRC2018Unisex adult brain

                                URL    Parents Publications          License  \
0  https://n2t.net/vfb:VFB_00102107  [medulla]           []  CC-BY-NC-SA_4.0
1  https://n2t.net/vfb:VFB_00102282  [nodulus]           []  CC-BY-NC-SA_4.0

                      Datasets
0  [JRC 2018 templates & ROIs]
1  [JRC 2018 templates & ROIs]
Defaulting to JRC2018Unisex template
Defaulting to JRC2018Unisex template
Enforcing the display template space as JRC2018Unisex from the first mesh found. Specify a template to avoid this.
Plotting 3D representation of 2 items

Data type cannot be displayed: application/vnd.plotly.v1+json

Next we might want to add some neurons using the queries we learn in the other turorials.

[11]:
vfb_neurons = vfb.owl_instances("'neuron' that 'has synaptic terminal in' some 'nodulus' and 'has synaptic terminal in' some 'medulla'", limit = 10)
print(f"summary of all: {vfb_neurons.get_summaries()}")
Limiting to 10 instances out of 1
summary of all:              ID         Name                           Description  \
0  VFB_jrchk542  SIFa(PDM34)  tracing status-Traced, cropped-False

                                URL  \
0  https://n2t.net/vfb:VFB_jrchk542

                                       Related Terms  \
0  [Rel(relation=MinimalEdgeInfo(label=capable of...

                                             Parents    License  \
0  [mushroom body octopaminergic neuron, SIFa, ad...  CC-BY_4.0

                                    Cross References  \
0  [https://neuprint.janelia.org/results?dataset=...

                                    Datasets
0  [JRC_FlyEM_Hemibrain neurons Version 1.1]

We can add and subtract VFBTerms from each other (uniqueness is enforced by id)

[12]:
# So to plot both the regions and the neurons in the same plot:
plot_terms = vfb_regions + vfb_neurons
plot_terms.plot3d()
Defaulting to JRC2018Unisex template
Enforcing the display template space as JRC2018Unisex from the first mesh found. Specify a template to avoid this.
Plotting 3D representation of 3 items

Data type cannot be displayed: application/vnd.plotly.v1+json

Note: some of the neurons exist in mutiple templates so it is good practice to specify the template space you want to work in otherwise the first template space plotted is enforced:

Note: Although navis.plot3d() method we use can cope with hundreds of skeletons to avoid the risk of cooking your GPU you can limit your plots to a subset ([:10] - first 10) or sample ([::50] - every 50th) etc.

[13]:
terms = vfb.owl_instances("'neuron' that 'has presynaptic terminals in' some 'nodulus'", return_dataframe=False, limit=10)
terms[0:10].plot3d(template='JRC2018Unisex')
Limiting to 10 instances out of 589
Plotting 3D representation of 10 items

Data type cannot be displayed: application/vnd.plotly.v1+json

It’s often handy to include the template mesh for conntext to see where the above neurons are located:

[14]:

terms[0:10].plot3d(template='JRC2018Unisex', include_template=True)
Plotting 3D representation of 10 items
Adding template VFB_00101567 to the plot
Defaulting to JRC2018Unisex template

Data type cannot be displayed: application/vnd.plotly.v1+json

If a template has painted regions then these can also be accessed as VFBTerms object via template.regions:

[15]:
template=vfb.term('JRC2018Unisex')

colours=vfb.generate_lab_colors(len(template.regions))

subregions=template.regions[::5] # Just to speed up the plotting selecting every 5th region

subregions.plot3d(template=template, color=colours, hover_name=True)
Loading terms: 100%|██████████| 47/47 [01:05<00:00,  1.39s/it]
Plotting 3D representation of 10 items

Data type cannot be displayed: application/vnd.plotly.v1+json

[16]:
med = vfb_terms[0] # grabing the medulla type term we had earlier

med.instances #pulling all instances of that type
Loading instances for the first time...
[16]:
VFBTerms(terms=[VFBTerm(term=Term(term=MinimalEntityInfo(name=medulla on adult brain template Ito2014, short_form=VFB_00030810), link=https://n2t.net/vfb:VFB_00030810)), VFBTerm(term=Term(term=MinimalEntityInfo(name=ME on JRC2018Unisex adult brain, short_form=VFB_00102107), link=https://n2t.net/vfb:VFB_00102107)), VFBTerm(term=Term(term=MinimalEntityInfo(name=medulla on adult brain template JFRC2, short_form=VFB_00030624), link=https://n2t.net/vfb:VFB_00030624)), VFBTerm(term=Term(term=MinimalEntityInfo(name=ME(R) on JRC_FlyEM_Hemibrain, short_form=VFB_00101385), link=https://n2t.net/vfb:VFB_00101385))])
[17]:
med.instances.plot3d() #plotting all instances of that type. Note: without a template specified the first instance loaded will fix the template space and block the rest as they belong in different templates.
Enforcing the display template space as adult brain template Ito2014 from the first mesh found. Specify a template to avoid this.
Plotting 3D representation of 1 items

Data type cannot be displayed: application/vnd.plotly.v1+json

Please see VFBTerm DataSet Notebook for examples of how to work with whole datasets