Introduction

External annotations are stored in spreadsheets, managed by the spreadsheet owner, and synchronized in regular (usualy hourly) time intervals with the BrainCircuits.io platform. You can keep full control of the content of the spreadsheet and what annotations you want to provide to the system. Updates to the spreadsheet, such as adding or removing records, or changing annotations, become accessible via the BrainCircuits.io user interface e.g. for searching segments or as metadata e.g. in the context of graph visualization.

We currently support Google Spreadsheets and Seatable as data sources. Please let us know if you have the need for additionaly data sources (such as Airtable etc.) and we provide the connector. The following step-by-step tutorial explains how to create the spreadsheet - we are using Google Spreadsheets as an example - and how to specify a configuration object that defines the connection parameters for synchronization.

Procedure

1. Create a new Google Spreadsheet
2. Share your spreadsheet with the user braincircuitsspreadsheet@braincircuits.iam.gserviceaccount.com with Editor permissions. This is a Google service account managed by BrainCircuits.io to access the spreadsheet.
3. Define the configuration JSON object, see below.
4. Send the configuration JSON object to info@braincircuits.io. It will then be integrated into the BrainCircuits.io backend.
5. Test if you can successfully retrieve your annotation (and the associated segments) via text-based search for your annotation in the Segments widget in the respective dataset.

Configuration Object

There are two types of dataset in BrainCircuits.io

1. static datasets
2. dynamic datasets

Static datasets do not change over time and identifiers remain the same, e.g. for segment/bodies/neurons. For these datasets, annotations can directly reference these IDs. However, for dynamic datasets, such as the FlyWire/FAFB or FANC datasets that are backed by the CAVE-backend to support an community and ongoing proofreading, identifiers can change. Thus, we need to use spatial locations in the dataset to anchor an annotation. Those spatial locations are translated into thei respective supervoxel and segment/root IDs in regular time intervals (currently in hourly interverals). So you do not need to store them in the table, as they may become outdated quickly as people split and merge segments.

In the following, we describe two ways to store the coordinates:

1. In a single column. When copying locations from Neuroglancer, the xyz coordinates are retireved as a comma-separated list.
2. In three columns for each coordinate x,y and z.

Here's an example configuration object for case 2.

{
    # the source type. leave as is
    'source': 'google_spreadsheet',
    # an identifier for this particular data source
    'source_name': 'fafb_annotations',
    # the name/title of the spreadsheet in the top bar
    'base': {
        'name': "FAFB Annotations",
    },
    # the name/title of the table
    'table': {
        'name': 'Test Annotations'
    },
    # definition of column semantics in the table
    'columns': {
        # specification of the columns that hold the coordinats
        'coords': [
            {'index': 0, 'name': 'A', 'target': 'x'},
            {'index': 1, 'name': 'B', 'target': 'y'},
            {'index': 2, 'name': 'C', 'target': 'z'},
        ],
        # a list of columns that are integrated as annotations
        'fields': [
            {
                'index': 3,
                'name': 'D',
                # what is the label / meaning of this annotation column
                'name': 'cell_name',
                # leave the annotation_type column as is
                'annotation_type': 'annotation'
            },
        ]
    },
},

If coordinates are in only one column, the coords field would read like this:

'coords': [
    {'index': 0, 'name': 'A', 'target': 'xyz'},
],

Annotation Data Visibility

For cave-backed datasets, the annotations you provide this way will be visible/accessible for every users that has view permission of the segmentation data. More granular permission / visibility control will be implemented later.