glossary - jaybgager/tracertools GitHub Wiki

Some terms used in the function descriptions are either uncommon or are used here to mean something very specific in the context of this package. These are defined below:

alignment

An alignment is a particular "stitching together" of a dataset's raw images. A dataset is produced as a series of discrete images, each of which only captures a small portion of the whole sample. These must be connected together before they can be used. This process can be done in different ways, and with different goals in mind. Because of this, one dataset may have multiple alignments associated with it. In the same way, one alignment may be associated with multiple datastacks. For example, the minnie65_public datastack uses the minnie65_phase3 alignment of the minnie65 dataset.

array

An array is a general term for a data structure where information is organized in a pattern of repeated elements of the same size. In Python, most people create arrays using the numpy package. For this reason, when code calls for an array, it's often understood to mean a numpy array specifically.

Arrays are similar to lists, and can be created from them as long as each dimension of the list has the same number of elements. However, for reasons related to how the two types of data structure are stored in your computer's memory, arrays are much faster to access and perform operations on. Because of this, they're the preferred way to store a lot of backend data, and so are worth learning to work with. The w3schools numpy tutorial is a good way to get familiar with numpy arrays.

Arrays are said to have "shape", which refers to the size of each dimension of the arry. For example, the array

[1,2]

has a shape of (2) because it's a single list of 2 elements. Likewise, the array

[
    [
        [1,2,3],
        [4,5,6],
        [7,8,9],
        [10,11,12],    
    ],
    [
        [13,14,15],
        [16,17,18],
        [19,20,21],
        [22,23,24],
    ],
]

has a shape of (2,4,3) because it's a list of 2 elements, each of which is a list of 4 elements, each of which is a list of 3 elements.

Sometimes the term "n" is used to refer to a type of array with a variable number of elements in a particular dimension. For example, an (n,2,3)-shape array is a common storage format for neuron skeletons, which can store any number of bones (n), each of which is a list of 2 elements (the bone's endpoints), each of which is a list of 3 elements (the x,y,z point coordinates). Similarly, meshes are often stored as (n,3,3)-shape arrays, since they can have any number of triangular faces (n), each of which is a list of 3 elements (the corners of the triangle), each of which is a list of 3 elements (the x,y,z point coordinates).

backbone (neuron)

A general collective term for the larger processes of a given neuron. Exact definitional criteria vary from source to source, but often requires microtubules to be visible in imaging where this is possible. Contrast to "twig". Frequently used as a proofreading standard for cell completion (e.g. "backbone_proofread"), as attaching every twig to a neuron is typically cost-prohibitive due to the difficulty and unnecessary due to biological redundancy between connected neurons.

bone

A skeleton's "bones" are the individual edges that connect its vertices. Synonymous with skeleton "edges". Summing the lengths of a skeleton's bones gives you its cable length. Bones are usually stored as pairs of endpoint coordinates, but may sometimes be stored as pairs of index numbers that refer to a list of vertices. They're represented in neuroglancer by line annotations.

break

A segmentation error where the path of a neuronal process ends prematurely. Factors that increase the chances are thin diameter of the process and 2D imaging errors like dislocations, missing data, warping, or blurred focus. Often distinguishable in 3D by an abrupt end to a process with no tapering or branching, sometimes accompanied by jagged mesh (potentially with concavities) at the break site. Requires manual merging with the missing process(es) by a proofreader. with Contrast with "merger".

bucket

A server where files can be stored and accessed remotely. Often used for publicly hosting neuroglancer volumes containing meshes, annotation layers, or electron microscope (EM) image layers. Can also be used to host data tables for things like cell type labels, proofreading status, or synapse data. The functions that begin with the prefix bucket_ relate to reading from and writing to buckets using the cloudfiles Python package.

cable length

A segment's cable length is the sum of the lengths of the bones in the segment's skeleton. Generally this information is given in nanometers. It's often used alongside information like 3D volume and synapse counts to rank neurons by size or compare a neuron at various stages of proofreading.

CAVE / caveclient

Connectome Annotation Versioning Engine, the software used to manage and interact with backend information about datastacks. This is done with the caveclient Python package, thorough documentation for which can be found here.

changelog / tabular changelog

The changelog is a backend CAVE table of every single edit made to a datastack's segmentation graph. It's accessible as a Pandas DataFrame object with a row for each edit and columns for timestamp, editor username, ID, and affiliation, whether the edit was a split or merge, and the segment IDs before and after the edit. This makes it possible to reconstruct the exact process of a segment's proofreading history and measure how much proofreading each user contributed to the current version. It's similar to, but different from, the operation details table.

chunkedgraph / pychunkedgraph / pcg / cg

The chunkedgraph is an organizational structure that holds the information about which supervoxels belong to which segments. It's created and managed by the pychunkedgraph (pcg) Python package. Individual supervoxels are always considered to belong to the lowest layer, making them the "level 1 nodes", or "L1 nodes" for short. All the supervoxels belonging to a segment within a given cube of space, referred to as a "chunk", will be grouped together into a level 2 (L2) node.

Multiple L2 nodes are grouped into an L3 node and so on until you reach a layer that contains all the supervoxels in the whole segment. For a more detailed explanation, read this description. Working with different layers can have advantages. For example, the L1 layer (usually just referred to as "the supervoxels") can provide detailed information at the cost of computational power, while the L2 nodes can provide information faster for less processing power, like cached 3D volume measurements - at the cost of being less reliable in certain contexts.

cloudvolume

A Python package that allows reading and writing of neuroglancer volumes directly in RAM without having to write to a hard drive, documentation for which can be found here. Used in a number of processes including mesh-related operations, creating and hosting volumes both locally or on a bucket, and spatial segment lookup.

comparison view

Within the context of neuroglancer, a comparison view is a common method for structuring a neuroglancer state to quickly see the differences between multiple segments. It generally contains two segments corresponding to the initial and final states of a neuron before and after proofreading.

The initial segment is colored red #ff0000 and the final is colored cyan #00ffff with the 3D rendering opacity set to 0.99 to display them both as slightly translucent. This configuration causes regions of overlap to appear grey, representing the unchanged portion of the initial retained by the final. Likewise, any regions removed from the initial will appear as red, while regions added during proofreading will appear as cyan. This can actually be done with any two directly complementary colors, but red-cyan is conventional.

Comparison views may also include annotation layers with the coordinates of edit sites and/or synapses that were added or removed during proofreading.

DataFrame / df

A type of Python object generated using the Pandas Python package. Similar to a table or spreadsheet, but with various optimizations for searching and performing calculations on the data it contains. Commonly used as the storage format for CAVE tables of annotations, edits, or segment information. Often abbreviated "df".

dataset

The original set of image data (usually in the form of raw electron microscope images) for a specific brain (or other piece of tissue). Often identified by a descriptive acronym (e.g. BANC for Brain and Nerve Cord) or by the name of the organism that the tissue came from (e.g. Minnie65). One dataset can have multiple alignments, each of which can have multiple datastacks. For example, the minnie65_public datastack uses the minnie65_phase3 alignment of the minnie65 dataset.

datastack

All the data associated with a particular project associated with a specific alignment of a specific dataset. Multiple datastacks can be associated with the same alignment. For example, the minnie65_public and minnie65_phase3_v1 datastacks both use the minnie65_phase3 alignment of the minnie65 dataset. The terms

This can include aligned EM images, 3D segmentation data, and tables of information for things like synapses, cell type labels, or nucleus locations. It may also include neuron skeletons, neuropil mesh layers, and other stack-specific information. This term is sometimes used interchangeably with "dataset" in other media, but won't be here.

edge (graph)

A general term for the connection between two nodes in a graph. This could be a synapse, a link between supervoxels in the same segment, or the overall connectivity between two neurons. Edges are often stored as two numbers that in some way reference the ID of their endpoints in a list or as sets of spatial coordinates. They may also store information about direction (whether a relationship between the two nodes goes one way or both, as is the case with a synapse) or weight (how strong a connection the two nodes have, important when looking at overall connectivity).

edge (mesh)

The lines connecting a mesh's vertices, representing the places where the mesh surface changes direction. Stored as pairs of index numbers pointing to the position of their endpoints in the mesh's list of vertices (e.g. [vertex A index #, vertex B index #])

edge (skeleton)

Synonymous with bone.

face

The flat planes that make up the surface of a 3D mesh. Can be any shape, but generally stored as triangles (sometimes called "tris") for rendering and mathematical analysis purposes. Can be stored either as lists/arrays of 3 points or 3 edges, depending on usage. May also be associated with a normal.

fresh (segment ID)

A fresh segment ID is one that's currently in use in a live production datastack. It represents the most current information about a neuron or other structure. Any time an edit (split or merge) is made to a segment (in the case of splits) or segments (in the case of merges), the resulting segments (in the case of splits) or segment (in the case of merges) will be given a new unique ID (in the case of merges) or two new IDs (in the case of splits). A fresh ID is the one that all the supervoxels associated with it will register as currently belonging to. Interchangeable with "current", "latest", and "most recent". Contrast with "stale".

graphene

A data format backed by pychunkedgraph, used by cloudvolume and the Seung Lab's custom version of neuroglancer, documentation for which can be found here. If you see the term "graphene" in the address for a segmentation layer, it generally indicates that it's linked to the chunkedgraph in some way and will therefore show up as a "painted" overlay in the 2D window of neuroglancer, allowing a user to show or hide segments by double-clicking within them in 2D. Contrast with the term "precomputed", which generally indicates a static mesh that isn't connected to the chunkedgraph and therefore won't show up as a "painted" overlay in the 2D window of neuroglancer.

image layer

In neuroglancer, the image layer, often referred to as the "2D" or "EM" (electron microscopy) layer, is the layer containing the imagery that a segmentation is based on. Usually this will be a stack of electron microscope images stitched together in a particular alignment. The hosting address of the image layer is usually referred to as the "image source". By convention, the image layer is generally the first one present in a neuroglancer state.

JSON / JSON state / state JSON

JavaScript Object Notation, abbreviated JSON, is a data format commonly used to store information in a structure similar to a Python dictionary, where there are "key" strings paired with values. The values can themselves be dictionary-like structures, creating multiple layers of nesting to allow for granular information storage. JSON format is often used for storing "state" information, or the information related to a specific configuration of settings that allows for saving and loading of specific setups for various programs, particularly on the internet.

Neuroglancer uses JSON states to store all the information about a given snapshot of the user interface (UI) at a point in time. This might include the windows that are open, the layers that are present and their visibility, which segments are selected, the position of any annotations, the 3d view position and angle, and many other pieces of information. You can view the JSON state of a neuroglancer instance at any time by clicking on the {} icon in the top-right of the UI window. Clicking on the dropdown arrows expands the various sections.

This state can be downloaded as a JSON state file on your local machine, from which all the information pertaining to that configuration of neuroglancer can be pulled if you know the methods and terms to use. When referring to an instance of this data type, the terms "JSON state" and "state JSON" are often used interchangeably. This package will always use "JSON state".

local

A term used to refer to something stored on the actual computer that you're using (e.g. your hard drive). Derived terms include "local path" / "local directory", "local machine", and "local host(ing)". Contrast with "remote".

merge

An edit operation in neuroglancer that combines two segments into one new segment. This is done by manually placing a single line annotation with one end in each segment to be connected. Generally used during proofreading to attach missing branches or other structures to a neauron. Plural "merges". Contrast with "split". Not to be confused with "merger".

merger

A single segment that is made of structures that actually belong to two or more different neurons or other tissue types, and which therefore requires splitting by a proofreader. Derived terms include "glial merger", "synapse site merger", and "z-plane merger". Plural "mergers". Contrast with "break". Not to be confused with "merge".

mesh

A 3-dimensional shape, often representing a neuron, but sometimes used to depict other structures like organelles, nuclei, neuropils, or simply regions of space. Stored in literal terms as a collection of vertices, edges, and faces. A mesh is considered "watertight" if all its triangular faces are connected to exactly 3 other triangular faces (i.e. there are no "holes"). Many formats for storing mesh information exist, but this package primarily uses either those found in neuroglancer volumes or sometimes OBJ files. Meshes are how the segmentation is represented in 3D.

neuroglancer / NG

A user interface (UI) for interacting with the 3D segmentation and rendering of neurons and other biological structures, the documentation for which can be found here. There are multiple branches of NG for specific purposes, like FlyWire or Spelunker. Most of the functions in this package are built for use with Spelunker, the Seung Lab's current customized version of NG.

node

A node is a general term for an element in a graph that can be connected to other nodes. This could be neurons in a circuit diagram, vertices in a mesh, supervoxels connected together in the chunkedgraph to form a segment, or pages in a wiki connected by links.

normal (mesh)

A ray (line with a direction) aimed perpendicular (sometimes referred to as "orthogonal") to a flat plane. Often used to indicate what direction a mesh face is oriented for the purposes of rendering lighting (i.e. which side of the face is the "outside" of the mesh).

numpy / np / numpy array

A Python package commonly used for various data storage and mathematical tasks, often abbreviated as "np". Numpy arrays are similar to lists, but are faster to access and run analysis on at the cost of a more rigid structure. Because of this they're often used for backend data storage.

OBJ / Wavefront file

OBJ files are a popular open file format for storing simple 3-dimensional meshes. Stores vertices as lists of x,y,z coordinates. Stores edges as pairs of index numbers referring to their endpoints' positions in the list of vertices. Stores faces as trios of index numbers referring to their corners' position in the list of vertices. Sometimes referred to as "Wavefront OBJ" after the now-defunct company that first developed it.

operation details table / opdeets

This is a backend CAVE table detailing each operation (split or merge) performed in a given datastack. It's similar to the tabular changelog, but contains more detailed edit information like point coordinates for the source and sink of each edit and the IDs of chunkedgraph edges created by each operation.

path swap

A specific type of merger where the path of one neuronal process suddenly switches to follow the path of another. Particularly common when 2D image dislocation errors occur in parallel bundles. Can be quite hard to spot visually, but often shows up as unexpected patterns of connectivity compared to typical cells of the same type during synaptic analyses.

parallel bundle

A biological structure where the paths of multiple neuronal processes run parallel and adjacent to one another for long stretches. Often the diameter of the processes can be quite thin, increasing the risk of path swaps or breaks if there are any defects in the 2D imagery.

precomputed

A common type of formatting for neuroglancer data layers that relies on doing complex mathematical operations ahead of time (pre-computing) to allow faster use by the end user.

If you see the term precomputed in the address for a segmentation layer, it generally indicates that it's a static mesh that isn't connected to the chunkedgraph and therefore won't show up as a "painted" overlay in the 2D window of neuroglancer.

Contrast with the term graphene, which indicates that a mesh is linked to the chunkedgraph in some way and will therefore show up as a "painted" overlay in the 2D window of neuroglancer, allowing a user to show or hide segments by double-clicking within them in 2D.

process (neuron)

A general umbrella term for the long, thin structures that extend (or "proceed") from the cell body of a typical neuron or from other processes. Often used interchangeably with "tract", "neurite", "path", and "branch". "Backbones", "twigs", "axons", and "dendrites" would all be considered types of processes. Usage can sometimes overlap with "arbor", though that term more correctly refers to a collection of multiple processes branching out from a single initial process.

remote

A term used to refer to something stored on a computer other than the one you're actually using. This could be another user's machine, a university-run server, or cloud server run by a private company (e.g. Google Cloud / Amazon Web Services). Derived terms include "remote host(ing)", "remote bucket", and "remote machine". Things that are hosted remotely will often require some kind of verification process in order to access (e.g. security tokens, SSH keys, password protection etc.).Contrast with local.

resolution

The actual, physical dimensions in nanometers represented by one "unit" in the x, y, and z directions of a 3D coordinate system, stored as a list/array of 3 numbers (e.g. [4, 4, 45] for the voxel dimensions in the "brain and nerve_cord" datastack).

Common derived terms include "viewer resolution" (the default voxel resolution used when viewing a datastack in neuroglancer), "mip0 resolution" (the voxel resolution of the raw electron microscope images for a dataset), and "nanometer resolution" (where the x-, y-, and z-resolutions are all 1 nanometer, often used for backend spatial information storage and mathematical calculations).

root ID

An umbrella term that can refer to the numeric identifier attached to a single supervoxel, chunkedgraph node, or segment. Appropriate to use when the entity in question can't be known ahead of time, as in the get_roots_from_points function, which can return either a segment or supervoxel ID dependingon the user's input. Often used in other sources interchangeably with the term "segment ID", but won't be here.

segment / segmentation / seg

The term "segment" refers to a group of supervoxels and how they're connected together. Each segment is associated with a unique 18-digit numeric identifier ("segment ID" / "seg ID"). If a segment is edited by merging or splitting the resulting segment(s)'s ID(s) will be different, as the new collection(s) of supervoxels will be considered distinct. Each segment, therefore acts as a snapshot in time of a aprticular structure, typically a neuron, and is often associated with various other metrics like synapse counts, 3D volume, and cable length. The terms "segment" and "segment ID" are often used interchangeably with the terms "root" and "root ID" respectively in other sources, but won't be here, as those terms are more broad and can encompass other things like supervoxels or L2 nodes.

The term "segmentation" is a bit more broad, and can refer to either the entire set of all segments in a datastack (e.g. the "segmentation layer" in neuroglancer), or to the current way in which a segment is constructed for a particular structure (e.g. "the segmentation of a neuron").

Both "segment" and "segmentation" are often used casually to refer to the 3D mesh in a neuroglancer window, though this is technically inaccurate. The mesh is actually a simplified, smoothed rendering of the true segmentation, which would have a more jagged, blocky, "voxellated" look to it if rendered in 3D. However, this usage is still accurate when looking at the segmentation overlay in the 2D view, which preserves the true shape of each supervoxel.

skeleton

A segment's "skeleton" refers to a programmatically-generated representation of it as a series of vertices connected by edges (often called bones). Structurally, this is stored as a list or array of pairs of endpoint coordinates for each bone. This structure is much simpler to store and faster to run analysis on for a number of tasks. The sum of a skeleton's bones is its cable length. Within tracertools functions, skeletons are generated with the osteoid Python package. Skeletons are often rendered in neuroglancer as a series of line annotations, but may also be viewed using microviewer with the visualize_skeletons tracertools function.

split

An edit operation in neuroglancer that separates one segment into two new segments. This is usually done with an automated tool, and is typically associated with multiple line annotations generated by said tool. Typically used to separate two structures that belong to different neurons (see "merger"). Contrast with "merge".

stale (segment ID)

A stale segment ID is one that's no longer in use in a live production datastack. It represents archival information about a neuron or other structure at a certain point in time. Any time an edit (split or merge) is made to a segment (in the case of splits) or segments (in the case of merges), the resulting segments (in the case of splits) or segment (in the case of merges) will be given a new unique ID (in the case of merges) or two new IDs (in the case of splits). A stale ID acts as a record of all the supervoxels associated with a given segment at a specific point in time, even though those supervoxels won't register as belonging to it anymore when queried. Stale IDs are useful for comparative analyses of the proofreading process, as they allow lookup of historical data associate with that particular timepoint, including synapse counts, 3D volume, cable length, and other metrics. Interchangeable with "old", "outdated", and "historic". Contrast with "fresh".

supervoxel

The smallest rearrangeable unit of a 3D segment, made up of multiple voxels. Not a consistent size. Sometimes referred to as the "watershed" layer because of the type of algorithm that led to their creation. Supervoxels cannot be broken apart, a quality sometimes referred to as being "atomic" (i.e. the smallest unbreakable constituent part of something). When referencing the "nodes"/"leaves"/"layers" of the chunkedgraph, supervoxels are L1 - the foundational level. At any given time, a supervoxel will "belong to" a specific segment (and will therefore be associated with that segment's ID), but this assignment will change if that segment is edited.

swamp

A swamp is the colloquial name for a region of a datastack known to have issues that make it particularly difficult to proofread or prone to segmentation errors (mergers or break sites). This can be caused by any number of issues, from biological or physical ones like cracks, folds, cell blowouts, over- or under-staining, dark cytoplasm, or membrane swirls to imaging errors like over- or under-exposure, focal blur, and inconsistent contrast. These regions are manually added to a list by proofreaders during the proofreading process, and so will beceom more fully mapped as a dataset's proofreading progresses. A volume with meshes for each swamp can be found in the datatack's tracertools config dictionary under the key swamp_source_url using the get_config function.

twig (neuron)

A general term for the smaller, more peripheral processes of a neuron. Exact definitional criteria vary from source to source, but often rely on a lack of visible microtubules in visualizations where these can be seen. Contrast with "backbone". Twigs are often ignored during the proofreading process, as attaching every twig to a neuron is typically cost-prohibitive due to the difficulty and uneccessary due to biological redundancy between connected neurons.

vertex

A single point in 3D space connected to other points. Used to represent the boundaries of a 3D mesh. Stored as a list or array of 3 numbers (e.g. [1,2,3]) corresponding to the point's x, y, and z coordinates, either in nanometers, or in voxels - the measurements for which may change depending on the voxel resolution of the datastack you're working with. Plural vertices.

volume

A collection of neuroglancer-related assets that can include 2D image layers, 3D segmentation and meshing, segment skeletons, and annotations. Stored in a single folder/directory, often named image. Several formats exist depending on the type of mesh being used, more documentation about which can be found here. Some formats require colons : in several file names in order to function properly. This makes them incompatible with Windows OS, which reserves colons for Drive names and therefore forbids their use in file names.

voxel

One unit of 3D space, shaped like a rectangular prism, the actual spatial dimensions of which vary from datastack to datastack. Compare to a 2-dimensional pixel. Multiple voxels are grouped together to form a supervoxel.