Adding a brain atlas to NeuroInfo

Required content and configuration of atlas files

Note that the atlas files installed with NeuroInfo provide good examples of atlas-file requirements.

Atlas orientation and links to other files (.xml file)

This file defines the atlas name, its coordinate system, and where NeuroInfo can find the other atlas files.

The XML file must reside in the following location: C:\ProgramData\MBF Bioscience\Atlases.

It should contain the following elements and information:

• <atlas> the root element for all atlas data

• <name> the atlas name that will be visible in NeuroInfo

• <version> atlas version

• <description> description of the atlas

• <orientation> for each axis, defines the direction in which the coordinate values are positive numbers, using conventional medical imaging terminology

  Note that NeuroInfo assumes that the atlas defines a right-handed coordinate space where the principal anatomic directions align with the image axes

  Example: For the coronal atlas installed with NeuroInfo, the orientation is defined as follows:

  • <x-axis> "left" (indicating that the x-axis points towards the left of the brain)

  • <y-axis> “ventral” (indicating that the y-axis points towards the ventral side of the brain)

  • <z-axis> “caudal” direction within the brain has positive coordinate values (rather than negative values)

• <reference-image> two images are used for reference: one for display in NeuroInfo and a binary mask image that delineates where the tissue is and is not

  • <name> a custom name for the atlas image that will be displayed in the lower-left registration view pane in NeuroInfo.

  • <modality> the imaging modality used to acquire the image (ex. “two-photon fluorescence”)

  • <image> relative path to the histology reference image file (this is the image that users will see in the NeuroInfo atlas views in registration mode)

  • <mask> relative path to the masked version of the reference image file (not displayed in NeuroInfo)

• <annotation> information about the delineation of regions and supporting files

  • <anatomy-image> relative path to the image in which the value of each pixel corresponds to the ID of its region or subregion

  • <mesh-path> relative path to the folder that contains the 3D model files (.vtk) of all regions and subregions

  • <region-ids> comma-separated list, in increasing numerical order, of each region and subregion ID present in the anatomy-image. This list should match column A in the ontology.csv file, in increasing order. This is optional, but including it will make some operations progress faster.

• <ontology> relative path to the ontology file

• <midsagittal-plane> specifies the location and orientation of the midsagittal plane within the atlas. This property is optional and may be omitted, for example in an asymmetrical atlas that cannot be cleanly divided by a single plane.

  • <point> x, y, and z coordinates of a point that lies on the midsagittal plane (ex. x="5700.0" y="0.0" z="0.0")

  • <normal> a unit vector normal to the midsagittal plane and pointing along the left direction of the X axis (ex. x="1.0" y="0.0" z="0.0").

Ontological information (.csv file)

This file includes a row with names and ID numbers for each brain region and subregion in the atlas arranged in hierarchical order and containing different types of information in specific locations in the rows. We recommend using a spreadsheet software to view, change, or create this file because it is much easier to view in table format than in a text editor, where it appears as lines of comma-separated values.

• Order of rows in the file:

  • The first row (or line of text) in the file is expected to be the title of the column and is not used

  • The second row must be the "root" region that represents the entire brain, including all regions/subregions.

    The root region must be at the top of the hierarchy, meaning no value should appear in Column I, Parent ID.

  • The remaining rows each include information about one brain region or subregion

  • Each subregion must be located below its parent region/subregion in the file (i.e., subregions must be located in rows with higher row numbers than their parent region in the file).

• Order of information within each row: Following the convention established by the Allen CCF, the following information about the region must be included in the indicated position in the row, represented as columns when viewed in a spreadsheet software (as recommended):

  • Column A: ID number of the region—each region/subregion (including the “root”) must have unique positive integer ID

  • Column C: Name—A full name that clearly identifies the region/subregion, without any abbreviations (i.e., as it would appear when it is first used in a publication)

  • Column D: Acronym—An abbreviated name that also refers to the region/subregion (ex. “SVZ” for subventricular zone)

  • Column I: Parent ID—The ID number of the immediate parent of the region or subregion (from the parent’s column A). For regions at the very top level of the ontology hierarchy, this will be the ID of the "root"; for regions that are low in the hierarchy, list the ID of the subregion that is one level higher in the hierarchy.

  • Column N: Hexadecimal Color—Each region/subregion (including the “root”) must have a color specified as a hexadecimal triplet. These do not necessarily need to be unique, but we advise that, if colors are to be repeated, then sibling subregions (i.e., subregions which share the same parent) should share the same color.

  • All other columns: User-Defined—Use any of the other columns (apart from columns A, C, D, I, and N) as you wish; they will not be used by NeuroInfo.

Example: These are specifications for the "caudoputamen" region in the Allen CCF:

• Column A: ID—"672"

• Column C: Name—"Caudoputamen"

• Column D: Short Name / Acronym—"CP"

• Column I: Parent ID—"485"

• Column N: Hexadecimal Color—"98D6F9"

Reference images (.nrrd files)

The following image-stack files in .nrrd format must be available in the locations defined in the XML file (see above). They are different views of the same brain-volume image.

*When constructing the histology images, do not apply smoothing as that would blur the lines between the anatomical regions.

File	Description/purpose	Data type
Histology reference image*	Image stack showing the brain-atlas histology that will be visible in NeuroInfo	16-bit, unsigned integer
Histology image mask*	Image stack with a binary mask to indicate where there is tissue (full intensity) and where there is empty space (zero intensity) in the histology reference image	8-bit, unsigned integer
Anatomy/annotation reference image	Image stack that uses the IDs specified in the ontology .csv (column A) to delineate each region/subregion visible in the histology reference image	16 or 32-bit, unsigned integer

3D mesh models (.vtk files)

Optional, but provides 3D visualization of anatomic regions in the atlas

• There must be a 3D model in .vtk file format for each region and subregion in the ontology file.

• The 3D models must have been created using the polydata type and be defined using points and triangle strips

• .vtk file names must reference the brain region Acronym (column D in the ontology .csv file), followed by an underscore character and the ID number of the region/subregion (column A in the ontology .csv file) as follows: “Acronym_ID.vtk”. For example, the caudoputamen file name is "CP_672.vtk".