Skip to content

Site Configuration

Abstract

TLDR: Use site_utils to set default configurations for your StateBuilder objects. After your imports, the recommended default code is: site_utils.set_default_config(target_site='spelunker')

Using site_utils to configure your StateBuilder

The site_utils submodule of statebuilder is intended to access and change the baseline configuration of StateBuilder sites. This will let you configure a target site, url, and caveclient to use as defaults throughout your analysis without further specification.

The first thing to note is the options within the default configuration. You can see this via

from nglui import statebuilder

statebuilder.site_utils.get_default_config()

This will return a dictionary with a number of variables:

{
    'target_site': 'seunglab',
    'target_url': 'https://neuromancer-seung-import.appspot.com/',
    'seunglab_fallback_url': 'https://neuromancer-seung-import.appspot.com/',
    'mainline_fallback_url': 'https://spelunker.cave-explorer.org/',
    'caveclient': None,
    'datastack_name': None
}

Each of these has a specific purpose:

  • target_site: The Neuroglancer version to use. This can be either seunglab or mainline/spelunker/cave-explorer (all refer to the same state). This establishes the broad category of Neuroglancer to use, and states for one type do not work with the other.
  • target_url: A URL to the deployment of Neuroglancer to use. The target_url should be a deployment of the same version as target_site.
  • seunglab_fallback_url: A URL to the deployment of Neuroglancer to use if the target site is seunglab and no target URL is specified.
  • mainline_fallback_url: A URL to the deployment of Neuroglancer to use if the target site is mainline and no target URL is specified.
  • caveclient: A CAVEclient object to use for specifying layers and metadata. This is optional, but if you have a CAVEclient object, you can specify it here and it will be used as the default for all StateBuilder objects. Will be set automatically if a datastack_name is specified.
  • datastack_name: The name of the datastack to use. This is optional and will be set if a CAVEclient is specified.

If you build a StateBuilder object without specifying things like target_site or target_url, these are the values that will be used. For example, if you run the following code using a small dataset from the Kasthuri et al:

img = statebuilder.ImageLayerConfig("precomputed://gs://neuroglancer-public-data/kasthuri2011/image")
seg = statebuilder.SegmentationLayerConfig("precomputed://gs://neuroglancer-public-data/kasthuri2011/image_color_corrected")
sb = statebuilder.StateBuilder([img, seg])
sb.render_state()

the result will be a url that is based on the value in target_url and is constructed for a seunglab deployment of Neuroglancer.

You can change any of these values through the set_default_config method. For example, to change the target site to spelunker, you can use

statebuilder.site_utils.set_default_config(target_site='spelunker')

If you run this and then check the default config again, you will see that the target_site has changed to spelunker and the target_url has changed to https://spelunker.cave-explorer.org/ the value that was shown in mainline_fallback_url. Now if you run the same code as above, the url will be constructed for a spelunker Neuroglancer and be based on the value in the mainline_fallback_url, which is the default for spelunker. This change occured because of the change in the default configuration, and will continue to apply for any statebuilder runs until the configuration is changed again.

You can also set a caveclient object here directly or via a datastack_name. For example, to set the default datastack to minnie65_public (the public MICrONs dataset), you can use

statebuilder.site_utils.set_default_config(datastack_name='minnie65_public')

This is particularly useful when working with spelunker datasets in particular, as they require a resolution to be specified to work properly and the CAVEclient object can provide this value.

While nglui will attempt to look up which version is associated with a given url, that that you will need to include a caveclient to do so. You may see a warning if you do not include a caveclient object, but the code will still run. If the resulting state does not work, you may need to specify the version of Neuroglancer you are using or add a caveclient.

Why are there different types of Neuroglancer?

Neuroglancer is a webapp for viewing large scale 3d image datasets that has been developed over many years. At one point, there was a major fork by the lab of Sebastian Seung to allow proofreading of connectomics data, which led to the development of the seunglab version of Neuroglancer. More recently, many of the features that were developed for the seunglab version have been integrated into the main version of Neuroglancer, which is sometimes referred to as mainline. Unfortunately the states generated by the two versions are not compatible, so it is important to specify which version you are using when generating states.

What about spelunker/cave-explorer?

Neuroglancer is a webapp where the same code can be deployed to many different URLs with different configurations. Each configuration sets things like key commands and state loading options. Meanwhile, we continue to add features to the mainline version of Neuroglancer, and the spelunker version is a deployment of the mainline version as well as the bleeding edge features that are almost ready to be added to the mainline version. The states generated by the spelunker version are compatible with the mainline version, but the spelunker version might have additional features that are not yet available in the mainline version. The default URL for all of mainline, spelunker, and cave-explorer is a deployment of the spelunker code, but you can specify a different URL if you want to use a different deployment.

What version should I use?

If you are not sure, you should use the spelunker version. This will give you the most features and the most up-to-date version of Neuroglancer. It will also be the default in an upcoming release.

The simplest way to do this is to set the default configuration to spelunker as shown above:

statebuilder.site_utils.set_default_config(target_site='spelunker')