BALSA File Types

Main About BALSA Submitting Data


BALSA supports a variety of file types used by Connectome Workbench. One category includes several standardized (community-endorsed) formats: NIFTI (volumetric), GIFTI (surface), and CIFTI (‘grayordinate’ surface + volume) types. Another category includes various formats customized for Workbench, but not generally readable by other platforms.


Standard (multi-platform) files:

NIfTI Volume Format (*.nii)

NIFTI volume files consist of a rectangular 3D grid of voxels, and often a 4th dimension of timepoints or maps. Connectome Workbench only supports volume files in NIfTI format, but accepts volumes in NIfTI-2 format as well as NIfTI-1, as NIfTI-2 avoids the dimension size limit of 32,767 in NIfTI-1.

Workbench can also create and view volume files that contain label data instead of continuous values (see gifti label files below). Other software can read the data values in these label volume files, but will display them like any other type of data value, ignoring the area names and colors.

For further details of the NIFTI format, see http://nifti.nimh.nih.gov/


GIFTI format (*.gii)

GIFTI is an established data file format designed for surface-based data. Its three major subtypes represent surface geometry (vertices), continuous values for each vertex, and integer label data for each vertex.

Note that some software platforms may put data arrays (e.g., the equivalent of a metric file) into the same file as the geometry information. Workbench does not support this kind of combined format; you must use other tools to separate the data array from the geometry (e.g., mris_convert in FreeSurfer).

For further details of the GIFTI format, see http://www.nitrc.org/projects/gifti/


CIFTI format (*.nii)

CIFTI files are designed to handle data contained in multiple disjoint anatomical structures, such as both hemispheres of cerebral cortex (vertex-based surface data) and/or specific subcortical structures (gray matter voxels). Structures not of interest for the analysis at hand can be excluded (e.g., white matter, CSF, “medial wall”), thereby making the representation more compact. The vertices and voxels used in a CIFTI file are generically referred to as 'brainordinates' and as 'grayordinates' for the specific case of 'all gray matter locations'.

A CIFTI file is a single rectangular data matrix (usually 2 dimensions, but supports 3). Each dimension is described using one of five available 'mapping types', and it is their combinations that give rise to the diversity of CIFTI file types. Each mapping contains all information needed to figure out what every index along the dimension means. A mapping of type 'brain models' (also known as 'dense') can represent both hemispheres and all subcortical structures concurrently, thus allowing one dimension to represent over a dozen structures, both surface-based and voxel-based. CIFTI supports an alternative spatial mapping (i.e., allowing display on surfaces and/or in the volume) that is based on ‘parcels’ (e.g., cortical areas, subcortical nuclei); parcels group related brainordinates into areas, resulting in much smaller data files by having fewer values to store (per parcel instead of per vertex/voxel). CIFTI also supports three non-spatial mapping types:

The common types of cifti files and the mapping types they use are:

For futher details of the CIFTI format, see http://www.nitrc.org/projects/cifti/


Customized Workbench (wb_view) files:

Scene file (*.scene)

A scene file contains one or more scenes; each scene is effectively a snapshot of the internal state of wb_view at the time it was saved. This includes information about which files were loaded, how they were displayed, how the tabs were configured (what surfaces are selected, what file is selected in each layer, which layers are turned on, what view rotation, palette settings, tile tabs, etc), and what annotations (text, arrows, circles, etc) were added over them. Opening a scene from a scene file restores the exact state of wb_view, allowing further exploration of the data or modification of the annotations or view setup. These capabilities allow publication-ready figures to be set up entirely in wb_view, for capture to image format, and to be modified subsequently with minimal hassle.

Workbench can create a zip archive of a scene file and all the data files that are used by its scenes. While this can be useful by itself for sharing data, BALSA builds on this ability by making a public repository for scene files and related data files, organized by publication and figure, where web browsers can view scene previews and information about the data files, as well as download the files.

Spec file (*.spec)

A spec (‘specification’) file is a list of data files that can be concurrently viewed in wb_view. It is useful for organizing sets of related files, such that they can easily be opened together.

Border file (*.border)

A border file contains one or more borders (usually many). Each border is a sequence of points on a surface, which may or may not have a connection from the final point back to the starting point ("closed" versus "open" borders). Borders can be viewed on different surface configurations (e.g., anatomical vs inflated surfaces). Borders can represent many types of surface contour and are often used to denote the boundary between regions or areas.

Foci (*.foci)

A foci file contains one or more foci (foci is plural of focus).  Required properties of a focus include: (1) a stereotaxic (3D) coordinate that may also be projected to a barycentric coordinate (relative to a particular triangle in a surface); (2) a name with an associated color; (3) a class with an associated color.  The class may be used to group related foci.  Optional properties of a focus include area, comment, geography, extent, ROI, and statistic.

Trajectory file (*.trajTEMP.wbsparse)

A trajectory file contains probabilistic trajectories constructed using probabilistic tractography applied to fiber orientation data (fiberTEMP.nii files). For each seed point, the file contains the counts of how often each voxel was used by a probabilistic streamline.

Annotation (*.annot)

Annotations consist of text labels, images, or symbols viewable in a wb_view window allowing one to create figures for use in publications without having to use another application (GIMP, Photoshop). For more information about annotations, see the Guide to WB Annotations.


Miscellaneous

Assorted other file types that can be included in a study or reference dataset. Examples include .png files (images) and .txt file (raw text).