NGLui: Neuroglancer States

TipVersion update

We have updated to v1926. Previous versions of this notebook are available from the repository history.

Programmatic Interaction with Neuroglancer States

Visualizing data in Neuroglancer is one of the easiest ways to explore it in its full context. The python package nglui was made to make it easy to generate Neuroglancer states from data, particularly pandas dataframes, in a progammatic manner. The package can be installed with pip install nglui.

The nglui package interacts prominantly with caveclient and annotations queried from the database. See the section on querying the database to learn more.

Parsing Neuroglancer states

The nglui.parser module offers a number of tools to get information about neuroglancer states out of the JSON format that neuroglancer uses. The recommended approach here is to pass a dictionary representation of the JSON object the StateParser class and build various kinds of dataframes from it.

The simplest way to parse the annotations in a Neuroglancer state is to first save the state using the ‘Share’ button, and then copy the state id (the last number in the URL). But you could also use the text you can download from the {} button in the viewer, and load this JSON into python.

In Neuroglancer, on the upper right, there is a ‘Share’ button.

When you click this link, you will be prompted for a google login. Use any google profile, but it is convenient to use the same as for this notebook.

This will upload the text of your neuroglancer state (the JSON format file, also accessed with the {} button) to a server, and returns a lookup number to access that state. The link with this state is automatically copied to your system’s clipboard.

When you paste it, you will see something like this:

https://neuroglancer.neuvue.io/?json_url=https://global.daf-apis.com/nglstate/api/v1/5560000195854336

for which the state id is 5560000195854336

You can then download the json and then use the annotation_dataframe function to generate a comprehensive dataframe of all the annotations in the state.

import os
from caveclient import CAVEclient
from nglui import parser

client = CAVEclient('minnie65_public')

state_id = 5560000195854336
state_json = client.state.get_state_json(state_id)
state = parser.StateParser(state_json)

You can now access different aspects of the state. For example, to get a list of all layers and their core info, you can use the layer_dataframe method.

state.layer_dataframe()
layer type source archived
0 img image precomputed://https://bossdb-open-data.s3.amaz... False
1 seg segmentation_with_graph graphene://https://minnie.microns-daf.com/segm... False
2 syns_in annotation None False
3 syns_out annotation None False

This will give you a table with a row for each layer and columns for layer name, type, source, and whether the layer is archived (i.e. visible) or not.

With parser you can get a list of all annotations with the annotation_dataframe method.

state.annotation_dataframe()
layer anno_type point pointB linked_segmentation tags anno_id group_id description
0 syns_in point [294095, 196476, 24560] NaN [864691136333760691] [] b832a0b7fe04a34195fef0fbc6743260e389e68e None None
1 syns_in point [294879, 196374, 24391] NaN [864691136333760691] [] 09ac4a97322131421d292d96a13ecbeb52dea50a None None
2 syns_in point [300246, 200562, 24297] NaN [864691136333760691] [] a9f1c484bbe037d3571525748455c19e6d792652 None None
3 syns_in point [300894, 201844, 24377] NaN [864691136333760691] [] 2efe4f45ad2b1f8e11da480a205a907ae5224c21 None None
4 syns_in point [294742, 199552, 23392] NaN [864691136333760691] [] 00661afd142462468d74167c2857c1d3f64b6870 None None
... ... ... ... ... ... ... ... ... ...
5272 syns_out point [277152, 200746, 22723] NaN [864691132294257136] [] 92fce4b77aa345ad0c5c9e7c2d568b5de9aaa274 None None
5273 syns_out point [298884, 189782, 21453] NaN [864691132135519710] [] 7aafe74e6a4be5daf64c4f21439ed1788faf0ef0 None None
5274 syns_out point [330182, 198986, 23862] NaN [864691132100215248] [] 7f250c09e29df2a498236b9177292c0c68ac36f1 None None
5275 syns_out point [326552, 186446, 24792] NaN [864691131892380409] [] 4199c5a222e64a13976d6628d91eea4807a4fd90 None None
5276 syns_out point [275784, 206898, 21524] NaN [864691131593914919] [] d5b20e52c362d6439304f713363162ef4832fc7c None None

5277 rows × 9 columns

This will give you a dataframe where each row is an annotation, and columns show layer name, point locations, annotation type, annotation id, descriptive text, linked segmentations, tags, etc.

If you have multiple annotation layers, each layer is specified by the layer column and all points across all layers are concatenated together.

The point coordinates are returned at the resolution of the neuroglancer view (default: 4x4x40 nm). You can change this resolution with argument point_resolution which will rescale the points to the requested resolution.

The description column populates with any text you have attached to the point.

Note that tags in the dataframe are stored as a list of integers, with each integer corresponding to one of the tags in the list.

To get the mapping between the tag index and the tag name for each layer, you can use the tag_dictionary function.

parser.tag_dictionary(state_json, layer_name='syns_out')
{1: 'targets_spine', 2: 'targets_shaft', 3: 'targets_soma'}

Alternately if you are using tags, the expand_tags=True argument will create a column for every tag and assign a boolean value to the row based on whether the tag is present in the annotation.

Another option that is sometimes useful is split_points=True, which will create a separate column for each x, y, or z coordinate in the annotation.

state.annotation_dataframe(expand_tags=True, split_points=True, point_resolution=[1,1,1])
layer anno_type point linked_segmentation tags anno_id group_id description point_x point_y point_z pointB_x pointB_y pointB_z targets_spine targets_shaft targets_soma
0 syns_in point NaN [864691136333760691] [] b832a0b7fe04a34195fef0fbc6743260e389e68e None None 1176380.0 785904.0 982400.0 NaN NaN NaN NaN NaN NaN
1 syns_in point NaN [864691136333760691] [] 09ac4a97322131421d292d96a13ecbeb52dea50a None None 1179516.0 785496.0 975640.0 NaN NaN NaN NaN NaN NaN
2 syns_in point NaN [864691136333760691] [] a9f1c484bbe037d3571525748455c19e6d792652 None None 1200984.0 802248.0 971880.0 NaN NaN NaN NaN NaN NaN
3 syns_in point NaN [864691136333760691] [] 2efe4f45ad2b1f8e11da480a205a907ae5224c21 None None 1203576.0 807376.0 975080.0 NaN NaN NaN NaN NaN NaN
4 syns_in point NaN [864691136333760691] [] 00661afd142462468d74167c2857c1d3f64b6870 None None 1178968.0 798208.0 935680.0 NaN NaN NaN NaN NaN NaN
... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...
5272 syns_out point NaN [864691132294257136] [] 92fce4b77aa345ad0c5c9e7c2d568b5de9aaa274 None None 1108608.0 802984.0 908920.0 NaN NaN NaN False False False
5273 syns_out point NaN [864691132135519710] [] 7aafe74e6a4be5daf64c4f21439ed1788faf0ef0 None None 1195536.0 759128.0 858120.0 NaN NaN NaN False False False
5274 syns_out point NaN [864691132100215248] [] 7f250c09e29df2a498236b9177292c0c68ac36f1 None None 1320728.0 795944.0 954480.0 NaN NaN NaN False False False
5275 syns_out point NaN [864691131892380409] [] 4199c5a222e64a13976d6628d91eea4807a4fd90 None None 1306208.0 745784.0 991680.0 NaN NaN NaN False False False
5276 syns_out point NaN [864691131593914919] [] d5b20e52c362d6439304f713363162ef4832fc7c None None 1103136.0 827592.0 860960.0 NaN NaN NaN False False False

5277 rows × 17 columns

Generating Neuroglancer States from Data

The nglui.statebuilder package is used to build Neuroglancer states that express arbitrary data.

The Site Configuration options determine the default configurations for your states. We will set this to spelunker, and set the materialization version to 1926 for reproducibility.

from nglui import statebuilder
statebuilder.site_utils.set_default_neuroglancer_site('spelunker')

client.version=1926

The general pattern is that one makes a “StateBuilder” object that has rules for how to build a Neuroglancer state layer by layer, including selecting certain neurons, and populate layers of annotations.
You then pass a DataFrame to the StateBuilder, and the rules tell it how to render the DataFrame into a Neuroglancer link. The same set of rules can be used on similar dataframes but with different data, such as synapses from different neurons.

To understand the detailed use of the package, please see the tutorial.

However, a number of basic helper functions allow nglui to be used for common functions in just a few lines.

For example, to generate a Neuroglancer state that shows a neuron and its synaptic inputs and outputs, we can use the make_neuron_neuroglancer_link helper function.

from nglui.statebuilder import helpers

statebuilder.helpers.make_neuron_neuroglancer_link(
    client,
    864691135410116041,
    show_inputs=True,
    show_outputs=True,
    shorten=True,
    return_as='url'
)
'https://spelunker.cave-explorer.org/#!middleauth+https://global.daf-apis.com/nglstate/api/v1/6066004552056832'

The main helper functions are:

  • make_neuron_neuroglancer_link - Shows one or more neurons and, optionally, synaptic inputs and/or outputs.
  • make_point_state - Map a dataframe of points (by default, formatted like a cell types table) to a Neuroglancer state.
  • make_segment_state / make_segment_link - Show a set of segment (root) ids.
  • make_connectivity_state_map - Build states showing connectivity between neurons.

In all cases, please look at the docstrings for more information on how to use the functions.

Uploading local annotations to neuroglancer

NGLUI also has many functions for turning data into neuroglancer states. As a toy example, lets reupload the points from the parser example.

Tip

Here we generate the state for the spelunker Neuroglancer deployment. See the NGLUI documentation on site configuration for more options.

data_df = state.annotation_dataframe()[['point','description','linked_segmentation']]

# add tag columns and populated with boolean False
tagcols = ['targets_spine', 'targets_shaft', 'targets_soma']
data_df[tagcols] = bool(False)

data_df.head(3)
point description linked_segmentation targets_spine targets_shaft targets_soma
0 [294095, 196476, 24560] None [864691136333760691] False False False
1 [294879, 196374, 24391] None [864691136333760691] False False False
2 [300246, 200562, 24297] None [864691136333760691] False False False
from nglui.statebuilder import ViewerState, site_utils

state = (
    ViewerState()
    .add_layers_from_client(client)              # imagery + segmentation
    .add_points(
        data_df.head(50),
        name='synapse_targets',
        point_column='point',
        segment_column='linked_segmentation',
        tag_bools=tagcols,                        # tag write, boolean columns
        tags=tagcols,                             # declare the tag set
        data_resolution=[4, 4, 40],
    )
)
state.to_url(client=client, shorten=True)
'https://spelunker.cave-explorer.org/#!middleauth+https://global.daf-apis.com/nglstate/api/v1/6161237046460416'

Here, make_point_state builds a complete Neuroglancer state from a dataframe of points in just a few lines: it adds imagery and segmentation layers from the client, plus an annotation layer whose points come from the point_column.

segment_column links each point to a root id in the segmentation, description_column attaches descriptive text, and tag_column together with tags applies the annotation tags. Because the points in data_df are in voxel units, we pass data_resolution=[4, 4, 40] so they are interpreted correctly.

The state is rendered in the final line with to_link(client=client, shorten=True), which uploads the state and returns a shortened hyperlink. Related methods on the returned ViewerState include to_url() for a full (un-shortened) link, to_dict() for the raw JSON state, and to_clipboard() to copy the link directly.

Back to top