Contribution Guidelines

Contribute or update Virtual Fly Brain data/sites

1: Guide to adding new query properties to the VFBTerm object in the VFBConnect Library

Submitting new data to VFB

We integrate information from published papers and image data. See below for what to do if you have new data that could be incorporated into VFB.
The provenance of information, textual or image, is always acknowledged.

Tell us about your paper

Have you just had a paper published which describes new anatomical or expression information?
The best way to make us aware of your paper, and to put it on our curation list is to act on an email you will receive from FlyBase after your paper has been published. The link on the email points to the Fast-Track Your Paper Tool.
Using this tool you can provide information on what types of data your paper contains. If it has new anatomical or expression information you’ll need to fill the sections, Anatomical data or Expression, respectively, in addition to any other suitable ones.
You can also use this tool for any other, previously published paper.

Do you have image data that could be incorporated into VFB?

Email us, and we will be able to give you advice on image requirements.
Ideally, you should contact us when you are still in the planning stages. But if you already generated a dataset, we’ll still be able to provide advice.

How to register your image data

It is essential for successful registrations that the images are of good quality.

Follow this protocol to acquire stacks that can be used for registration.

Once you have the images, follow this protocol to register your images.

Information on publicly available template brains and bridging data is available here.

How to contribute to these docs

We use Hugo to format and generate these support pages, the Docsy theme for styling and site structure. Hugo is an open-source static site generator that provides us with templates, content organisation in a standard directory structure, and a website generation engine. You write the pages in Markdown (or HTML if you want), and Hugo wraps them up into a website.

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Updating a single page

If you’ve just spotted something you’d like to change while using the docs, Docsy has a shortcut for you:

Click Edit this page in the top right hand corner of the page.
If you don’t already have an up to date fork of the project repo, you are prompted to get one - click Fork this repository and propose changes or Update your Fork to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.

Creating an issue

If you’ve found a problem in the docs, but you’re not sure how to fix it yourself, please create an issue in the VirtualFlyBrain/VFB2 repo. You can also create an issue about a specific page by clicking the Create Issue button in the top right hand corner of the page.

Useful resources

Docsy user guide: All about Docsy, including how it manages navigation, look and feel, and multi-language support.
Hugo documentation: Comprehensive reference for Hugo.
Github Hello World!: A basic introduction to GitHub concepts and workflow.
nbcovert: A tool to convert jupyter notebooks into markdown (md) format.
HTML to Markdown Converter: It helps to convert your HTML to MD. This tool is super fast and processes conversion in the browser.
How to add new query properties to VFBConnect library

1 - Guide to adding new query properties to the VFBTerm object in the VFBConnect Library

An exploration of how an example query is added to the VFBTerm object under VFBconnect which provides a template for any future queries you may want to add add to vfb.term

Most of the queries in VFBTerm are built on previous older implementation queries so can be spread across multiple functions but as I just added a new query I thought this was a good example of a complex query (multiple steps combined) that is all in one function:

https://github.com/VirtualFlyBrain/VFB_connect/blob/master/src/vfb_connect/schema/vfb_term.py#L1709C5-L1735C78

def add_anatomy_type_properties(self):
        @property
        def transgene_expression(self):
            """
            Get the transgene expression data associated with this anatomy type term.
            """
            if self._transgene_expression is None:
                print("Loading transgene expression for the first time...") if self.debug else None
                subclasses = self.vfb.oc.get_subclasses(query=f"'{self.id}'", verbose=self.debug)
                print("Subclasses: ", subclasses) if self.debug else None
                overlapping_cells = self.vfb.oc.get_subclasses(query=f"'cell' that 'overlaps' some '{self.id}'", verbose=self.debug)
                print("Overlapping cells: ", overlapping_cells) if self.debug else None
                part_of = self.vfb.oc.get_subclasses(query=f"'is part of' some '{self.id}'", verbose=self.debug)
                print("Part of: ", part_of) if self.debug else None
                all_anatomy = subclasses + overlapping_cells + part_of + [self.id]
                print("All anatomy: ", all_anatomy) if self.debug else None
                result = dict_cursor(self.vfb.nc.commit_list([f"MATCH (ep:Class:Expression_pattern)<-[ar:overlaps|part_of]-(:Individual)-[:INSTANCEOF]->(anat:Class) WHERE anat.short_form in {all_anatomy} WITH DISTINCT collect(DISTINCT ar.pub[0]) as pubs, anat, ep OPTIONAL MATCH (pub:pub) WHERE pub.short_form IN pubs RETURN distinct ep.short_form as term, coalesce(ep.symbol, ep.label) as term_name, anat.short_form as type, coalesce(anat.symbol, anat.label) as type_name, collect(pub) as pubs"]))
                print("Result: ", result) if self.debug else None
                if result:
                    self._transgene_expression = ExpressionList([Expression(term=exp['term'], term_name=exp['term_name'], term_type='transgene', type=exp['type'], type_name=exp['type_name'], reference=[Publication(FlyBase=pub.get('FlyBase',''), PubMed=pub.get('PMID',''), DOI=pub.get('DOI', ''), core=MinimalEntityInfo(short_form=pub['short_form'], label=pub['label'], iri=pub['iri'], types=pub['label'], symbol=','.join(pub['miniref'][0].split(',')[:2])), description=pub['title']) for pub in exp['pubs']]) for exp in result])
                else:
                    self._transgene_expression = ExpressionList([])
                print(f"Transgene expression: {repr(self._transgene_expression)}") if self.debug else None
            return self._transgene_expression

        # Dynamically add the property to the instance
        setattr(self.__class__, 'transgene_expression', transgene_expression)

This is based on the VFB site query https://github.com/VirtualFlyBrain/geppetto-vfb/tree/development/model#transgeneexpressionhere-reports-of-transgene-expression-in-name

To find any potential Transgenes in X it need to find all types that are subclasses (subtypes) + any overlapping cells + any parts of X plus the term X itself. These are all collected using OWLery query for the id’s of all these types using MANCHESTER syntax queries:

subclasses: '{self.id}' 

subclasses: 'cell' that 'overlaps' some '{self.id}'

subclasses: 'is part of' some '{self.id}'

This is added to the self.id to include the term itself and passed (as all_anatomy) to a neo4j cypher query running against the VFB PDB (Production DB):

MATCH (ep:Class:Expression_pattern)<-[ar:overlaps|part_of]-(:Individual)-[:INSTANCEOF]->(anat:Class) WHERE anat.short_form in {all_anatomy} WITH DISTINCT collect(DISTINCT ar.pub[0]) as pubs, anat, ep OPTIONAL MATCH (pub:pub) WHERE pub.short_form IN pubs RETURN distinct ep.short_form as term, coalesce(ep.symbol, ep.label) as term_name, anat.short_form as type, coalesce(anat.symbol, anat.label) as type_name, collect(pub) as pubs

the output of this is put through the dict_cursor to turn them into an easily accessible dictionary and then constructed as an Expression object into an ExpressionList:

ExpressionList(
    [Expression(
        term=exp['term'], 
        term_name=exp['term_name'], 
        term_type='transgene', type=exp['type'], 
        type_name=exp['type_name'], 
        reference=[
            Publication(
                FlyBase=pub.get('FlyBase',''), 
                PubMed=pub.get('PMID',''), 
                DOI=pub.get('DOI', ''), 
                core=MinimalEntityInfo(
                    short_form=pub['short_form'], 
                    label=pub['label'], 
                    iri=pub['iri'], 
                    types=pub['label'], 
                    symbol=','.join(pub['miniref'][0].split(',')[:2])), 
                description=pub['title']
            ) for pub in exp['pubs']
        ]
    ) for exp in result]
)

Note: the for X in Y simply iterates a list and as it’s inside [] it returns as a list

Note: the reason the name as well as the id is often passed is that these terms are themselves Lasy loaded and so passing the name prevents full loading needing to be done for just summary display.

Speaking of Lazy loading this is the reason for the @propery and the setattr(self.__class__, 'transgene_expression', transgene_expression) which (if add_anatomy_type_properties() is run) add transgene_expression to the term to be called as X.transgene_expression and the first time will run the query, cashing the results in self._transgene_expression for future calls.

The code here up in the VFBTerm __init__ adds this option only if the term is_type and has the tag for Anatomy:

if self.has_tag('Anatomy') and self.is_type:
                self._transgene_expression = None
                self.add_anatomy_type_properties()
                self._lineage_clones = None
                self._lineage_clone_types = None
                self.add_lineage_clone_properties()

https://github.com/VirtualFlyBrain/VFB_connect/blob/master/src/vfb_connect/schema/vfb_term.py#L1681C1-L1682C51

Initialising the cache: self._transgene_expression = None and calling the relevant properties: self.add_anatomy_type_properties()

Copying this procedure will allow you to add any query based on checked against tags or other checks.

Note: Tags are Neo4j ’labels’ (labels(n) as apposed to n.label) for the term and can be checked against using self.has_tag('X').

VFBconnect Docs: VFBConnect library.