Analyzing Large Connectome Graphs With BossDB Network Tools

Abstract

Modern connectomics enables large-scale, comparative network neuroscience across individuals, species, development, and evolution. The field now regularly produces extensive maps of neural connectivity exceeding hundreds of millions of synapses in continuous volumes. When connectomes are deposited in central archives such as BossDB with standardized metadata, researchers can pose previously intractable questions about neuronal networks. Here, we present step-by-step protocols for connectome dataset discovery and access, scalable graph construction and analysis, and reproducible comparative connectomics using BossDB, Motif Studio, DotMotif, Neuroglancer, neuPrint, and Python-based workflows. These protocols target bench neuroscientists and computational biologists and emphasize replicability, cloud-friendly options, and publication-quality visualization.

Basic Protocol 1:

Discovering connectome datasets and computing summary statistics with BossDB and Motif Studio

Basic Protocol 2:

Writing queries with DotMotif

Basic Protocol 3:

Querying known network motifs locally with DotMotif

Support Protocol 1:

Provisioning ad hoc graph databases for large-scale graph analysis

Support Protocol 2:

Querying structures and systems in the cloud with neuPrint

Basic Protocol 4:

Viewing anatomical motif features with BossDB and Neuroglancer

INTRODUCTION

Nanoscale connectomics, i.e., the mapping and analysis of complete neuronal wiring diagrams, provides an unprecedented opportunity to understand how neural circuits give rise to behavior, cognition, and development. With recent advances in high-throughput imaging, such as from volumetric electron microscopy (EM), automated image segmentation, and large-scale data archiving, it is now possible to reconstruct and publish entire connectomes for multiple organisms and developmental stages (Dorkenwald et al., 2023; Hider Jr et al., 2022; Matelsky, Norman-Tenazas, et al., 2021; Schlegel et al., 2024; Shapson-Coe et al., 2021; Witvliet et al., 2021; Yu et al., 2025). These datasets, often comprising millions of synaptic connections, enable comparative network neuroscience at a scale and resolution that was previously impossible.

Despite this progress, challenges remain in accessing, managing, and analyzing these large and complex graph datasets (Bishop et al., 2021; Hider Jr et al., 2022; Matelsky, Rodriguez, et al., 2021). Traditional network analysis tools were not designed to handle the scale or domain-specific queries of connectomics, and many laboratories lack the computational infrastructure to store, query, and visualize such data efficiently. Moreover, while several online repositories now host connectomes, their interfaces, application programming interfaces (APIs), and data formats vary, creating barriers to reproducible research (Abbott et al., 2020; Li et al., 2020; Matelsky et al., 2022; Scheffer et al., 2020).

The BossDB ecosystem (Hider Jr et al., 2022; Martinez et al., 2025), together with specialized tools, e.g., Motif Studio, DotMotif, and Grand (Matelsky et al., 2021), addresses these limitations by providing: scalable, cloud-hosted connectome storage; intuitive web-based query interfaces; flexible local computation options; and integration with widely used visualization platforms. These tools support both exploratory and hypothesis-driven research, allowing users to search for specific anatomical motifs, compute network statistics, and render publication-quality visualizations without requiring extensive local resources.

Central advantages of these protocols and associated tools include scalability to petabyte-scale datasets, compatibility with both cloud-based and local computing environments, reproducible workflows through standardized APIs, and interoperability with external analysis libraries in Python. Potential disadvantages, such as reliance on internet connectivity or the learning curve associated with mastering multiple tools in the ecosystem, are addressed in support protocols.

This collection contains the following protocols:

• Basic Protocol 1: Discovering connectome datasets and computing summary statistics with BossDB and Motif Studio. Search public datasets, retrieve metadata, and calculate key network statistics.

• Basic Protocol 2: Writing Queries with DotMotif. Use the DotMotif query language to compose queries for subgraphs in large networks.

• Basic Protocol 3: Querying known network motifs locally with DotMotif. Run motif searches against locally stored connectomes using a Python-based tool.

• Support Protocol 1: Provisioning ad hoc graph databases for large-scale graph analysis. Deploy temporary databases to support high-performance queries. Support Protocol 2: Querying structures and systems in the cloud with neuPrint. Use the neuPrint application to query connectomes stored in an online hosted graph database.

• Basic Protocol 4: Viewing anatomical motif features with BossDB and Neuroglancer. Identify and contrast motifs using interactive three-dimensional (3D) visualization.

BASIC PROTOCOL 1 - DISCOVERING CONNECTOME DATASETS AND COMPUTING SUMMARY STATISTICS WITH BossDB AND Motif Studio

This protocol describes how to locate, access, and summarize publicly available connectome datasets hosted in the BossDB data archive, using the BossDB website and the Motif Studio web interface. Users will learn how to search for datasets of interest, retrieve metadata, and generate summary statistics that characterize the network structure. These statistics can help determine the suitability of a dataset for a given research question and provide a baseline for comparative analysis.

BossDB is a cloud-native spatial database for large-scale neuroscience datasets, designed to store volumetric image data and associated annotations. Motif Studio is a web-based tool that integrates with BossDB to allow browsing, querying, and visualizing connectome graphs without the need for local data downloads. Together, these tools allow researchers to explore petabyte-scale connectome datasets directly in the cloud.

Materials

• Computer with a modern web browser and stable internet connection

• BossDB account (optional for public datasets; required for restricted data) (see Internet Resources)

Select a dataset for analysis and view summary statistics

• 1Navigate to https://bossdb.org/projects and use the filters on the left pane to select a dataset appropriate for your analysis. Datasets that have an associated connectome are indicated with a blue network icon (Fig. 1).

  You can apply a filter to only show datasets with queryable connectomes by clicking the teal network icon under the Data Type header in the filters panel.

• 2Click to enter the BossDB project page for your selected dataset. On the right side of the page, under the “Connectomes” card header, you can click through to “Query [Dataset Name] in Motif Studio”.
• 3Graph summary statistics are made immediately available in the “Graph Properties” panel of the Motif Studio web interface (Fig. 2D) without any further interaction required. Vertex and edge attributes also appear in the “Graph Properties” panel immediately.

Figure 1.

The BossDB.org “Projects” page with a search facet selected (teal) for datasets that include a connectome graph. Only datasets that have a queryable connectome are shown (indicated by a copy of the “connectome” icon in their dataset card). An example of the connectome icon is shown at top-right.

Figure 2.

The Motif Studio web interface. (A) The menu bar, which supports operations like opening and saving motif files, and adding motif primitive components to the current query editor. (B) The “Query Editor”, which is a code editor that supports both DotMotif and Cypher query languages. The syntax-highlighted editor is synchronized in real-time to the motif visualization pane on the right side of the screen. (C) The “Host Graph Selection” panel, which enables selection of BossDB-hosted connectomes, as well as uploading custom graphs from a user’s hard drive. (D) The “Graph Properties” panel, which illustrates common statistical properties of a graph, such as vertex and edge counts, as well as density. This panel also includes a list of node and edge attributes that can be accessed or used in motif queries, and a download pane that supports exporting the currently selected host graph. Supported download formats depend on the host graph. (E) The results panel shows a “Run Query” button when a query is pending and shows a table of results with export functionality to JSON or CSV after the query runs successfully.

Perform a motif query in the Motif Studio web interface

• 4Type your desired graph query into the Motif Studio “Query Editor” (Fig. 2B) or leave the standard query. The motif query will be drawn in real time on the right panel of the “Query Editor” for visual spot-checks.

  More details on formulating queries with the DotMotif query language are provided in Basic Protocol 2: Writing queries with DotMotif.

• 5Press the “Run Query” button in the “Results” panel (Fig. 2E). The button will be replaced with a loading indicator, followed by a table of results that are viewable or downloadable in JSON or CSV formats.

BASIC PROTOCOL 2 - WRITING QUERIES WITH DotMotif

This protocol describes how to compose and validate subgraph queries using the DotMotif query language. DotMotif is a domain-specific query language for searching large connectome graphs for user-defined “motifs,” i.e., patterns of neuron connectivity, neuron types, or synaptic arrangements (Matelsky, Reilly, et al., 2021).

Researchers can use DotMotif to formalize biological hypotheses as graph patterns, then search for matches in large-scale connectome datasets stored locally or in the cloud. This protocol focuses on writing and validating queries in the DotMotif format, preparing them for execution either in the Motif Studio web interface (Basic Protocol 1: Discovering connectome datasets and computing summary statistics with BossDB and Motif Studio) or in local workflows (Basic Protocol 3: Querying known network motifs locally with DotMotif).

Materials

• Computer with a modern web browser or Python runtime environment DotMotif installation (Python package) or access to Motif Studio (see Internet Resources)

• BossDB dataset containing a queryable connectome (see Basic Protocol 1 for dataset discovery)

• Text editor or integrated development environment (IDE) for writing queries (optional)

Define the biological question

• 1Identify the connectivity patterns or cells of interest. For example, “feed forward chains of excitatory neurons” or “reciprocal connections between inhibitory interneurons” or “pyramidal neurons synapsing onto a basket cell with more than 10 synapses”.
• 2Translate the biological entities into graph terms for the corresponding dataset.

  In general, vertices (nodes) represent neurons, and edges typically represent synaptic connections, though in some datasets, edges may also represent electrical connections or anatomical contact surface area. Attributes can be attached to both vertices and edges.

Compose the DotMotif query

• 3Write the node and edge declarations to describe the query structure.
  By convention, top-level variable names start with an uppercase letter and are written in “CamelCase”. For example, to specify a three-node directed loop, use the -> operator. Comments can be specified with #.

  # A three-vertex loop:
  A -> B
  B -> C
  C -> A
  

  Negative edges, which are explicit annotations of an edge that must not exist in the matched motif result, are indicated with the “!>” operator:

  # No reverse edges:
  B !> A
  C !> B
  A !> C
  

• 4
  Add vertex and edge attributes as appropriate, using either dot notation or with edge aliases denoted with the as operator.

  # This vertex is excitatory: 
  A.valence = “excitatory” 
  # This vertex is not excitatory: 
  B.valence != “excitatory” 
  # This vertex has a “size” greater than or equal to 10 and less than 100: 
  C.size ≥ 10 
  C.size < 100 
  # This vertex has “pyr” in its type: 
  A.type contains “pyr” 
  # Name will match “PyC” or “BC”: 
  A.name in “PyC,BC”
  

  DotMotif provides a lot of flexibility in defining queries, and there may be multiple potential approaches to accomplishing the same query result. The following two options perform identically, and filter for an edge with a weight attribute >0.5:

  # Option 1, bracket notation: 
  A -> B [weight > 0.5] 
  # Option 2, alias notation: 
  A -> B as MyEdge 
  MyEdge.weight > 0.5
  

  One can also perform multiple comparisons at the same time in bracket notation:

  A -> B [weight > 0.5, weight < 0.8]
  

  One can also compare attributes of two entities:

  # A and B must have the same “type” attribute: 
  A.type = B.type 
  # Triangles with “descending” weight: 
  A -> B as AB 
  B -> C as BC 
  C -> A as CA 
  AB.weight > BC.weight 
  BC.weight > CA.weight
  

  These constraints can dramatically improve query performance because most DotMotif query executors will use these to narrow down the network search space prior to conducting the NP-hard subgraph search (especially important for large connectomes exceeding millions of edges).

• 5Refactor the DotMotif query to take advantage of reusable components. Macros are one of the most useful features of the DotMotif language and can be declared and invoked much like functions in procedural programming languages. By convention, macros start with a capital letter, and their arguments start with a lowercase letter.
  For example, the two following queries are identical:

  # 1. Clockwise triangle, no backward edges: 
  A -> B as AB 
  AB.weight > 0.5 
  B !> A 
  B -> C as BC 
  BC.weight > 0.5
  C !> B 
  C -> A as CA 
  CA.weight > 0.5 
  A !> C 
  # 2. Clockwise triangle, no backward edges, using macros: 
  Oneway(a, b) { 
  a -> b [weight > 0.5] 
  b !> a 
  } 
  Oneway(A, B) 
  Oneway(B, C) 
  Oneway(C, A)
  

  Macros can also be nested:

  Excitatory(a) { 
  a.valence = “excitatory” 
  } 
  Pyramidal(a) { 
  Excitatory(a) 
  a.type contains “Pyr” 
  }
  

• 6Validate the query.

  In most DotMotif executors, this will be done automatically prior to execution: The DotMotif Python package (see Basic Protocol 3: Querying known network motifs locally with DotMotif) runs a small set of basic validators before search, and the Motif Studio web interface runs validation in real time as you write a query in the “Query Editor”. These validators are available in the open-source Motif Studio documentation.

  These validators search for disagreeing edges and attributes, even within nested macros.

  ExampleBreak(a, b) { 
  a -> b 
  b !> a 
  } 
  ExampleBreak(A, B) 
  B -> A 
  # This query will throw a “DisagreeingEdgesValidationError”.
  

• 7If your query executes but returns zero results, test it with progressively relaxed constraints to isolate overly restrictive conditions.

BASIC PROTOCOL 3 - QUERYING KNOWN NETWORK MOTIFS LOCALLY WITH DotMotif

This protocol describes how to execute motif searches against locally stored connectome graphs using the DotMotif Python package. Running queries locally enables users to work with private datasets, perform computationally intensive searches without internet latency, and integrate motif search results directly into custom Python workflows for downstream analysis.

Researchers who have composed motif queries in Basic Protocol 2 can use this procedure to run those queries against graph data stored in memory or on disk, using network analysis backends, e.g., NetworkX, Neo4j, or Grand (Matelsky et al., 2022). This protocol assumes the user has a basic familiarity with Python and access to a workstation or server capable of storing the target graph dataset.

Materials

• Computer with Python 3.10+ installed (https://www.python.org/downloads)

• DotMotif Python package (pip install dotmotif)

• Backend graph analysis library (e.g., NetworkX, Neo4j, Grand)

• Local connectome graph file in a supported format (e.g., CSV edge list, GraphML, or backend-specific database)

• Motif query created in Basic Protocol 2

NOTE: See the Troubleshooting section in the Commentary below for protocol-specific notes and troubleshooting instructions.

Install and configure DotMotif

• 1
  Open a terminal (or Python kernel, or notebook environment) and install DotMotif and the chosen backend library. For example, with NetworkX:

  uv add dotmotif network
  

  While it is generally recommended to use an environment management tool like uv, it is also possible to install the tools in the currently active environment with pip install dotmotif networkx.

• 2
  Load the local connectome dataset. With a GraphML-formatted file, this can be done with NetworkX:

  import networkx as nx 
  G = nx.read_graphml(“connectome.graphml”)
  

  It is possible to download a connectome from Motif Studio either through the web interface [by selecting a host graph in the “Host Selection” pane (Fig. 2C) and clicking the “GraphML” button in the “Graph Properties” pane (Fig. 2D)]; or programmatically, using the motifstudio_client Python package.

Perform the motif search using a DotMotif Executor

• 3
  Construct the motif using DotMotif’s “Motif” object. The check for validation errors happens automatically.

  from dotmotif import Motif 
  motif = Motif(“““ 
  # Put your motif query from Protocol 2 here. 
  # This is an invalid motif to illustrate validation: 
  A -> B 
  A !> B 
  ”””)
  

  This errorful motif throws a DisagreeingEdgesValidationError.

• 4Select and construct an appropriate “Executor” to wrap the connectome graph.
  For NetworkX graphs stored in memory (or in Grand graph abstractions), the GrandIso executor is recommended, as it outperforms the default NetworkXExecutor. There are also Neo4jExecutor and NeuPrintExecutor options.

  from dotmotif import GrandIsoExecutor 
  executor = GrandIsoExecutor(graph=G) 
  results = executor.find(motif)
  

  The last line above may take some time to run, as this is performing the subgraph search.

• 5
  Inspect the results or save them for future analysis. The results are returned as a list[dict[MotifVertexID, HostVertexID]], where motif and host vertex IDs are of type str, and each element of the list contains a complete monomorphic mapping of motif vertices to host vertices.

  import csv 
  with open(“matches.csv”, “w”) as f: 
  writer = csv.DictWriter(f, fieldnames=results[0].keys()) 
  writer.writeheader() 
  writer.writerows(results)
  

SUPPORT PROTOCOL 1 - PROVISIONING AD HOC GRAPH DATABASES FOR LARGE-SCALE GRAPH ANALYSIS

This protocol describes how to deploy a temporary (“ad hoc”) graph database to run large-scale motif searches when working with connectome datasets too large to fit into local memory. By using scalable backends such as Neo4j or Grand, researchers can execute complex DotMotif queries efficiently while avoiding the performance limitations of in-memory processing (Matelsky et al., 2022).

This approach is useful for collaborative projects, cloud-based analyses, or one-time processing tasks, where installing and maintaining a permanent graph database is unnecessary. The procedure uses containerized deployments to simplify set up and tear down, ensuring reproducibility and minimal system configuration. Provisioning graph databases can be done through tools like Tamarind (that coordinate graph databases, credentials, and ports using Docker containers), using Docker itself (as shown below), or using a graph database daemon directly.

Materials

• Computer or cloud instance with Docker installed (Linux, macOS, or Windows)

• ≥16 GB RAM for medium-scale datasets; more for billion-edge graphs

• Local or cloud-accessible connectome dataset in CSV, GraphML, or Parquet format

• Backend-specific Python driver (e.g., neo4j for Neo4j, grand-graph for Grand)

NOTE: See the Troubleshooting section in the Commentary below for protocol-specific notes and troubleshooting instructions.

Deploy a temporary Neo4j instance with Docker

• 1
  Download the Neo4j Docker image and start a Neo4j container in detached mode.

  docker run \ 
  --name neo4j-connectome \ 
  -p 7474:7474 -p 7687:7687 \ 
  -d \ 
  -e NEO4J_AUTH=neo4j/password \ 
  neo4j:5.14
  

  Set a more secure username and password pair if this graph contains sensitive data, or if it may be exposed to the public internet.

• 2Wait for the service to initialize. This may take up to 1 min, depending on local compute resources. After initialization, you will be able to access the Neo4j browser interface at http://localhost:7474 for direct interaction with the container.

Ingest the connectome dataset

• 3Convert the dataset into a Neo4j-compatible CSV if it is not already in that format. The grand-cypher-io and grandlite Python package can help with this process.
  This bash command reads the file called connectome.graphml and exports (in the neo4j CSV format, specified with -o) vertices to the my-vertices.csv file and edges to the myedges.csv file in the current working directory. Note that this operation may need to be run from inside the Neo4j docker container, or the files may need to be moved into the container after it is initialized, in order for the Neo4j Browser or Cypher Shell to be able to see the files.

  grandlite --convert “vertex:my-vertices.csv;edge:my-edges.csv” -o neo4j connectome.graphml
  

• 4Use the Neo4j LOAD CSV command (run in the Neo4j Browser or via Cypher-shell) to import data.
  This import operation illustrates code for if the neurons have a “type” attribute and the synapses have a “weight” attribute.

  LOAD CSV WITH HEADERS FROM ‘file:///my-vertices.csv’ AS row 
  CREATE (:Neuron {id: row.id, type: row.type}); 
  LOAD CSV WITH HEADERS FROM ‘file:///my-edges.csv’ AS row 
  MATCH (a:Neuron {id: row.source}) 
  MATCH (b:Neuron {id: row.target}) 
  CREATE (a)-[:Synapse {weight: toFloat(row.weight)}]->(b);
  

Configure DotMotif to use the database

• 5
  In Python, connect DotMotif to the Neo4j backend.

  from dotmotif.executors import Neo4jExecutor 
  from dotmotif import Motif 
  motif = … 
  executor = Neo4jExecutor(
  db_bolt_uri=“bolt://localhost:7687”, 
  user=“neo4j”, 
  password=“password” 
  ) 
  results = executor.find(motif) 
  print(len(results), “matches found”)
  

• 6Shut down the database after use to free resources. Use the docker stop neo4j-connectome command to end the container process.

SUPPORT PROTOCOL 2 - QUERYING STRUCTURES AND SYSTEMS IN THE CLOUD WITH neuPrint

NeuPrint is a connectome query engine that enables analysis of large neural graphs. Common searches target connections between specific cells and metadata categories of cells. NeuPrint was originally written by the FlyEM team at HHMI Janelia (Scheffer et al., 2020) and is hosted as a web resource for BossDB connectomes at: https://neuprint.bossdb.io. This protocol shows how to use the neuPrint website and shows three example searches. For information on accessing connectomes programmatically using neuprint-python, visit the BossDB Cookbook at: https://github.com/aplbrain/bossdb_cookbook.

Materials

• Computer with internet access and web browser

• Google account

• 1Visit https://bossdb.org. Use the “Tools” option in the navbar to select the tool neuPrint. NeuPrint is directly accessible at https://neuprint.bossdb.io.
• 2Use the “Login” button at the top right to log in with a Google account.
• 3The “witvliet_dataset1” connectome is automatically loaded in the dropdown located in the navbar. To explore a different connectome, choose it from this dropdown.

  If no other options appear in the dropdown, refresh the page. The remainder of this protocol will work with any of the Witvliet datasets.

• 4Choose the “Search” button in the left navbar.

Example search 1: List neurons in a specific brain region

• 5When the “Search” button is clicked, the “Find Neurons” sidebar appears. Click the “Input Brain Regions” dropdown and choose “Head”. Then click “Submit”.
• 6The search results will load in the main screen, containing a list of all neurons located in the region “Head”. Many will be co-located in other brain regions as well since regions are not mutually exclusive.
• 7To see the name of each neuron, not just the unique ID, click “Columns Visible” and ensure that the box for “Instance” is checked.
• 8To filter the list further, continue refining the search using the “Find Neurons” sidebar.

Example search 2: List neurons of a specific cell type

• 9When the “Search” button is clicked, the “Find Neurons” sidebar appears. Click the “Change Query Type” button to access a long list of search varieties. Choose the search variety “Cell Types”.
• 10The cell types in the Witvliet et al. (2021) datasets are denoted by single letters. For example, “s” denotes a sensory neuron and “m” denotes a motor neuron. Neurons that perform multiple functions are typed using multiple letters, e.g., “sm” denotes a sensorimotor neuron. In the “Cell Type Name” box, input “sm”. Then, click “Submit”.
• 11The search results will show the number of sensorimotor neurons in the dataset, as well as statistics like inputs, outputs, and connectivity patterns for one sensorimotor neuron.

Example search 3: Visualize a neuron using Neuroglancer

• 12When the “Search” button is clicked, the “Find Neurons” sidebar appears. Click the “Change Query Type” button to access a long list of search varieties. Under the “Visualization” dropdown, choose the search variety “Neuroglancer”.
• 13Type in any neuron ID and click “Submit”. An embedded Neuroglancer window will load with the mesh of the chosen neuron ID pre-selected.

BASIC PROTOCOL 4 - VIEWING ANATOMICAL MOTIF FEATURES WITH BossDB AND Neuroglancer

This protocol describes how to use Neuroglancer (see Internet Resources), i.e., a browser-based 3D viewer, to visualize and compare neurons or motifs discovered through motif searches in BossDB-hosted connectomes. Neuroglancer enables interactive navigation of volumetric image data alongside segmentation meshes, allowing researchers to examine structural features, such as dendritic arborization, axonal projections, soma positions, and synaptic arrangements.

Using neuron or segment IDs obtained from earlier protocols (Basic Protocols 1 to 3 or Support Protocol 2), researchers can load specific cells into Neuroglancer, adjust visualization parameters, and perform qualitative anatomical comparisons.

Materials

• Computer with a modern WebGL-enabled web browser (e.g., Chrome, Firefox)

• Stable internet connection

• BossDB-hosted connectome dataset with Neuroglancer integration (accessible from the BossDB project page or Motif Studio) (see Internet Resources)

• Neuron IDs or segment IDs from motif query results

• Spreadsheet or text file containing IDs of motifs to compare, optional

NOTE: See the Troubleshooting section in the Commentary below for protocol-specific notes and troubleshooting instructions.

Open Neuroglancer for the desired dataset

• 1From the BossDB “Projects” page (https://bossdb.org/projects), locate your dataset of interest.

  Datasets with segmentation layers suitable for motif visualization typically display segmentation and connectome icons (Fig. 3).

• 2On the dataset’s project page, click the “Neuroglancer” link within the dataset details or description (Fig. 4A), in the “View on Neuroglancer” panel (Fig. 4B), and/or the “Links” panel (Fig. 4C).

  In Motif Studio, after running a query (Fig. 2E), the instance rows in the “Results” panel (Fig. 5) each include a Neuroglancer link. This link may also be available from the “Graph Properties” panel.

Figure 3.

The BossDB.org “Projects” page with a search facet selected (teal) for datasets that include segmentation and connectome data types (red), suitable for motif visualization. Only datasets with these data types are shown.

Figure 4.

A relevant Neuroglancer link for the project may be found in multiple places on the BossDB.org “Projects” page. (A) Some projects include multiple datasets and include information and details, such as the Neuroglancer link, for each. (B) The visualization panel includes a Neuroglancer widget that links to the Neuroglancer link. (C) Some projects include a “Links” panel, including relevant links, such as associated Neuroglancer links.

Figure 5.

The Motif Studio “Results” panel following a successful query execution. Each instance row in the results table corresponds to a detected motif instance and includes a Neuroglancer link (red), which opens the corresponding region of interest in Neuroglancer. The panel also supports export of query results to JSON or CSV formats.

Load a neuron or motif instance

• 3In Neuroglancer, ensure the segmentation layer for the connectome is visible in the “Layers” panel (Fig. 6).
• 4Locate the segment IDs or neuron IDs in your motif query results (CSV or JSON) (Fig. 7).
• 5Paste one or more IDs into the “Add segment(s)” input box in the segmentation layer’s “Seg.” panel. Press ENTER to load. The loaded neurons will appear as colored meshes in the 3D view (Fig. 8A).

  IDs can also be loaded via a state link that encodes the selected segments. Such a link will be automatically generated when accessing Neuroglancer from the links in the “Results” panel in Motif Studio (Fig. 6).

Figure 6.

Neuroglancer “Layers” panel. (A) The “Layers” panel can be opened by clicking the layer icon in the top-right corner of the Neuroglancer view. (B) The “Layers” panel lists all available layers, and the visibility of each layer can be toggled using the eye icon.

Figure 7.

Motif query results in JSON format. The “Run Query” operation in Motif Studio uses DotMotif to identify subgraphs of the form A → B, where neuron A synapses onto neuron B. The resulting JSON file records these motif instances as key–value pairs, with each entry representing a neuron pair (A → B) in dictionary form. For each neuron, the corresponding segmentation ID and related attributes are included in the JSON structure.

Figure 8.

Visualizing a motif instance in Neuroglancer. (A) Segmentation IDs corresponding to a single motif (A → B) are obtained from the JSON query results and entered into the segmentation layer. Only the neurons with these IDs are displayed as highlighted segments in the view. (B) The 3D rendering of the selected neurons, visualized through orthogonal slice views, enables inspection of their spatial relationship within the EM volume.

Navigate and inspect anatomical features

• 6Use the mouse and keyboard controls to rotate, zoom, and pan the 3D view.
• 7Hold the left mouse button to pan; scroll wheel to scrub in z; SHIFT + right mouse button to rotate; and CTRL + scroll wheel to zoom.
• 8View orthogonal slice views to examine the underlying EM volume or annotation layers in cross-section (Fig. 8B).
• 9Adjust mesh colors in the segmentation layer’s “Render” panel to clearly distinguish neurons in the motif (Fig. 9).

Figure 9.

The “Render” panel of a segmentation layer in Neuroglancer, used to adjust color, opacity, and other visualization properties to distinguish neurons within a motif instance.

Compare multiple motifs

• 10To compare different motif instances:

Option A

• 10a.Load all relevant neuron IDs into the same Neuroglancer session, assign distinct colors, and visually inspect relative positions and morphologies (Fig. 10).

Figure 10.

Visualization of two motif instances (A → B) in a single Neuroglancer session. Distinct segmentation IDs are loaded and colored separately for each motif instance, enabling comparison of the relative positions and morphologies of both motif pairs within the EM volume.

Option B

• 10b.Open multiple Neuroglancer split views, each with a different motif instance loaded, and arrange side-by-side for detailed comparison (Fig. 11).

Figure 11.

Split Neuroglancer view showing two motif instances (A → B) side by side. Each panel displays a distinct motif pair, where neurons A share the same class and neurons B share the same class, enabling comparison of structural similarities across motif instances.

Use the Split View feature to simultaneously display multiple motif instances

• 11Open a single motif in Neuroglancer, using steps 1 to 5.
• 12Split the Neuroglancer view by dragging the imagery layer tab to the side of the view panel until the boundary turns blue (Fig. 12).
• 13Add a segmentation layer to both splits and right click on the segmentation tab to open the layer properties pane on the right side of the screen. Select the “Seg.” tab and apply the segmentation IDs for the second motif (Fig. 11).

Figure 12.

Splitting the Neuroglancer view into multiple co-registered panels. Each panel displays the same image layer but can show different segmentation IDs, allowing side-by-side comparison of separate motif instances. A new view is created by dragging the image layer tab to the panel edge until the boundary highlights in blue, then adding or copying segmentation layers as needed.

Document and share findings

• 14When you have arranged the view appropriately, copy the URL to generate a unique Neuroglancer-based “state link”. The state link preserves values in the Neuroglancer window for camera position, zoom level, loaded layers, colors, and segment IDs. Paste this link into lab notebooks, publications, or collaboration messages to ensure reproducibility.
• 15Take high-resolution screenshots for figures or presentations using the Neuroglancer screenshot feature or the operating system’s screen capture tool (Fig. 13).

Figure 13.

The Neuroglancer screenshot feature for capturing high-resolution images. (A) The camera icon in the top-right toolbar opens the screenshot interface. (B) The “Screenshot” panel allows configuration of settings, such as name, scale factor, and resolution.

COMMENTARY

Critical Parameters

Successful execution of these protocols depends on careful attention to data compatibility, computational scale, and the logical consistency of graph queries. The BossDB ecosystem and its associated tools are tightly interlinked, and some errors might arise from inconsistencies in metadata, attribute naming (e.g., neuron cell types), or mismatched dataset versions.

Data integrity and compatibility

All workflows assume that connectome data are stored in BossDB with properly formatted metadata and node/edge attributes. Because attribute naming conventions differ among datasets (e.g., cell_type vs type, weight vs n_synapses), users should inspect the dataset’s attribute schema before formulating queries. Misaligned attribute names or inconsistent capitalization are among the most common sources of silent query failures.

Standardization of these attributes is an is anticipated that ongoing effort, and it future connectome releases will include standardized-form data as well (Bishop et al., 2021).

Query design and logical validity

DotMotif’s declarative language allows biological hypotheses to be expressed as subgraph constraints. However, overly restrictive conditions or contradictory statements (e.g., requiring both A -> B and A !> B) will prevent matches. Queries should be built incrementally, validated often, and parameterized where possible using macros for reuse. The Motif Studio interface performs live validation, helping users detect conflicts before execution.

Scalability and backend choice

Large connectome graphs often exceed in-memory limits. The choice of backend (NetworkX or GrandIso for small-to-moderate datasets, Neo4j or Grand for large or distributed queries) strongly influences performance and reproducibility. Researchers should document backend versions and configurations, including available memory and CPU cores, to ensure comparable and reproducible runtime conditions across analyses.

Visualization and ID mapping

Segment IDs used in motif query results must correspond to segmentation layers from BossDB. Loading mismatched IDs in Neuroglancer will result in blank or inaccurate meshes. Before exporting results from Motif Studio or neuPrint for visualization, confirm that the target dataset’s segmentation source matches the query source.

Performance and resource management

Query runtime can grow combinatorially with motif size and attribute constraints. For exploratory analyses, prefer small motifs (3 to 5 nodes) before searching for much larger patterns. More commentary on motif search computational complexity is available in Matelsky, Reilly, et al. (2021).

Troubleshooting

See Table 1 for a troubleshooting guide for analyzing large connectome graphs with BossDB network tools. Below are protocol-specific notes and troubleshooting instructions.

Table 1.

Troubleshooting Guide for Analyzing Large Connectome Graphs With BossDB Network Tools

Problem	Possible cause	Solution
DotMotif validation error	Conflicting edges or attributes	Simplify query; re-run with minimal motif and add constraints gradually
Zero matches returned	Overly strict constraints or case mismatch	Relax thresholds; use looser constraints; check attribute capitalization; often it is useful to remove attribute constraints to debug a query
Local search crashes or is slow	Graph too large for memory	Use Neo4j or Grand out-of-core backends
Neuroglancer view blank	Segment IDs do not match dataset segmentation	Load matching segmentation layer; verify dataset channel linkages from the BossDB management console; note that linkages declared in Motif Studio are already confirmed to work
Inconsistent results across tools	Mixed graph versions or directedness differences	Document dataset version; confirm directed versus undirected graph semantics

Basic Protocol 3

Performance tips

For large datasets (>1M edges), consider using a graph database backend, such as Grand or Neo4j (see Support Protocol 1: Provisioning ad hoc graph databases for large-scale graph analysis) to reduce memory overhead and enable parallel search. One may also use the count() function call instead of the find() function call to return an integer count of motifs rather than an enumeration of all instances; this is beneficial if the scientific question requires only a quantity, since it will have the effect of freeing the memory otherwise required by the results array.

Data format compatibility

Ensure that node and edge attributes in your local dataset match the attribute names used in your DotMotif query.

Zero match issue

If your query returns no matches, confirm that attribute filters match dataset conventions and capitalization (e.g., “excitatory” vs “Excitatory”). It may also be useful to progressively remove constraints from the motif query to identify the constraint that is eliminating matches.

Support Protocol 1

Scaling tips

For very large graphs, run Neo4j on a high-memory cloud instance (≥64 GB RAM) and place CSV files in the container’s/import directory for faster ingest.

Alternate backends

The Grand backend supports both in-memory and distributed execution, making it a flexible alternative for ad hoc use.

Security

Use a strong password if the database will be exposed beyond localhost.

Temporary storage

Containers are ephemeral; if you need to retain data, mount a persistent volume with the -v flag when running docker run.

Basic Protocol 4

Performance

Loading large neuron meshes may cause delays or high GPU usage. Disable unused layers and reduce the number of simultaneously visible segments to improve responsiveness.

Attribute matching

Segment IDs from motif queries must match the segmentation layer in Neuroglancer; mismatches will result in blank or missing meshes.

Statistical Analysis

Quantitative analyses of connectome graphs should follow the data-driven framework described in Matelsky et al. (2023), which details robust motif counting, null model construction, and statistical comparisons across connectomes of differing scale and completeness.

Briefly, motif counts should be normalized by network size or synapse count, and enrichment significance should be assessed against degree-preserving randomized graphs. For motif families or multiple cell-type categories, apply false discovery rate (FDR) correction. Effect sizes (e.g., enrichment ratios) provide more interpretable measures of biological importance than raw p-values. When feasible, report both absolute motif counts and normalized enrichment statistics following the methodology in Matelsky et al. (2023).

Understanding Results

Each protocol produces intermediate results that together form a complete analytical workflow, from dataset discovery to publication-quality visualization. Expect graph-level metrics (node/edge count, density, degree distribution) from Motif Studio’s “Graph Properties” panel. Disproportionately sparse or disconnected graphs may indicate incomplete reconstructions.

Valid DotMotif queries yield structured tables mapping motif variables (e.g., A, B) to neuron IDs. In Motif Studio and neuPrint, these can be exported as JSON or CSV. When using the Python API, a typical result is a list of dictionaries, each representing one motif instance. The number of mappings equals the number of detected subgraphs.

During visualization, Neuroglancer renders of these IDs should reveal distinct neuron meshes with expected spatial relationships (e.g., feed-forward chain, reciprocal pair). Comparative renderings across motifs or species can expose structural invariants or developmental trends.

Time Considerations

The complete workflow can be completed within a single working day for small datasets, though runtime scales with dataset size and motif complexity. With adequate compute resources, motif searches can be parallelized across cores or across compute nodes. In general, motif search computational complexity scales exponentially with the number of edges in the host graph, and so it is always faster to search in two smaller connectome host networks than one large one.

For this reason, motif searches in small connectomes of hundreds of thousands of synapses can be searched within milliseconds. Searches within larger graphs, with millions to hundreds of millions of synapses, can take several hours to days. These workflows do not run on the GPU and therefore CPU-heavy compute resources are recommended.

Data Availability Statement

All data discussed in this article is freely available to the public and licensed under a creative commons license. Data and tools may be accessed at: https://bossdb.org.