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)NGLui: Neuroglancer States
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.
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=1926The 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.
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.