Anatomy

From Heeger Lab Wiki

Contents 1 Introduction 2 Important points for working with anatomy directories 3 Note about using nifti images with surfrelax and mrLoadRet 4 Directory Structure 4.1 Top level anatomy directory 4.2 Individual subject directories 4.3 Anatomy/segmentation directories for each acquisition date 5 Naming conventions

[edit] Introduction

'/larmor.cbi.fas.nyu.edu/CBIV2/heegerlab/anatomy' is the official repository for all anatomy and segmentation data. Please place all anatomy and segmentation data here once segmentation is completed. This document describes the data and directory structure of the repository, and defines the naming conventions used.

[edit] Important points for working with anatomy directories

• If you are new to Unix, learn the basics before you try to add data to this database. There is no undo button, and it is very easy to inadvertently wreak havoc.

• It is absolutely vital that you follow this convention exactly, to the last letter. Really.

• NEVER USE UPPERCASE for file names - ALWAYS use lowercase. Though OS X can't tell the difference between upper and lowercase, Matlab and SurfRelax can, and will CRASH or fail in unexpected ways if the the same file is referred to with non-matching case. Also, tab-completion is much, much easier when you don't have to press 'shift' all the time.

• Don't store any files in here that aren't directly related to the anatomies/segmentations.

• Don't modify the official segmentation without consulting with other users, and only if there is a compelling need (e.g. a much better segmentation, errors in the existing one, etc).

• Always document every processing step. Save segmentation commands as shell scripts from SurfRelax (don't ever run commands from GUI) and edit them if necessary to match the actual commands used. It should be possible for any user to start with the raw data and reproduce exactly the resulting files (except for manual editing) with the aid of this documentation. Be sure to date every documentation file, either by name or in the documentation itself.

• If you use any specific software tools to generate any data here, provide a link to that code so other users can replicate results. (e.g., if you used FreeSurfer, indicate what version, where to get it, and how you used it.)

• Volume data must be stored in Nifti pair (*.img/*.hdr) format, for backward compatibility. Make sure the default output type in FSL is this format (FSLOUTPUTTYPE=NIFTI_PAIR)

• Once you have finished installing and modifying a segmentation, write-protect all files in the directory using chmod ugo-w. You can always undo this operation if changes are needed. Don't write-protect the directories, as this will make it impossible for people to add new files (e.g. surface patches) to the repository.

• All dates are specified in standard international date format, that is year-month-day (YYMMDD or YYYYMMDD)

• Only validated anatomy data should be placed here. Data that is still being analyzed or has not been validated should be placed in the 'unarchived' subdirectory. 'Validated' means that the segmentation has been carefully checked to be as error-free as possible, and is in a final version (ie not being modified).

• Mac/OS X users beware. Do Not use the finder to copy files in these directories! (i.e don't drag-and-drop! The OS X finder modifies files in strange ways when copying and may render them unusable! Always use the terminal and copy with 'cp'. (Whether the same is true for Windows, I don't know). The anatomy directory should be mounted under /Volumes/CBIV2/Heegerlab/anatomy. To copy an entire local directory that you've created on your machine to this directory, just type

  cp -r <local directory name> /Volumes/CBIV2/Heegerlab/anatomy/<subject identifier>/<destination directory>

[edit] Note about using nifti images with surfrelax and mrLoadRet

SurfRelax and associated software does not at the time of writing (Dec 2006) fully support Nifti headers. It will read Nifti-style images, but ignores the Nifti orientation information in the headers, instead relying upon an unused (in the Analzye days) field in the Analyze header to store the origin of the image coordinate system. What this means is that surfaces extracted by SurfRelax will NOT be in Nifti coordinates, but in the 'native' SurfRelax (aka TFI) coordinate system. These coordinate systems are related by a simple rigid transform (rotation + translation).

These functions will convert coordinates from one format to the other:

 [link to conversion functions here when they exist]

The next release of SurfRelax, sometime in Spring 2007, will fully support Nifti and output surfaces in the Nifti (qform) coordinates. This release will come with a conversion utility to convert surfaces and images in the old SurfRelax format to Nifti coordinates. In the meantime, great care must be taken to make sure that the right images are used for extracting surface data:

• Any operations involving transforming data between surfaces and volumes must use the same volumes that were used to extract the surfaces. These volumes can be recognized by their names, which conform to the SurfRelax naming conventions described below. If in any doubt, display the surface in VolumeViewer overlaid on the volume; if they are in the same format, they should line up exactly with no transformation.

• The Nifti images in the raw subdirectory (see below) should only be used for alignment with mrAlign (ver > 4.0). These images *must not* be used to e.g. extract gray coordinates with surf2graph, etc.

To avoid having to rename files when entering data into the repository, use the default naming conventions of the automatic surface extraction script (SurfAndRelax.tcl) with the subject's initials as output basename:

   SurfAndRelax.tcl <input volume> <subject initials>

or by entering <subject initials> (e.g. jl) as output basename in the GUI will generate the correct naming structure. Consult the help for this function, and the official SurfRelax documentation, for description of the output files and their default names.

[edit] Directory Structure

In the following, $ROOTDIR means the top-level directory where the anatomy directory resides. As of the time of writing (11/30/2006) It is in:

   /Volumes/CBIV2/Heegerlab 

on larmor. The location may change in the future.

[edit] Top level anatomy directory

$ROOTDIR/anatomy

This file (README.txt), possibly additional info files (.txt) a directory with utility scripts, and top-level subject directories. The anatomy folder may also contain 'unarchived' directory, where anatomy data can be stored temporarily while being processed or organized to conform to the 'official' naming structure.

Do not put anything else in the top-level directory. Any other data that needs to be shared should be stored in the 'unarchived' folder. Individual subject directories are named <subject 2-letter initials, in lower case><date of birth in YYYYMMDD format>:

 ss19991231
 jl19670331
 jg19710606
 ds19740419

[edit] Individual subject directories

$ROOTDIR/anatomy/jl19670331

• Anatomy/segmentation directories one for each acquisition date. Format: <subject initials><acquisition date in YYMMDD format>

  Note that year is specified with 2 letters only, to clearly distinguish format from parent directory.
  e.g. jl030910

• A symbolic link to one of these directories that is the current "official" directory. Format: <subject initials>

  e.g. jl -> jl030910
  Create by typing
  ln -s <official directory> <subject initials>
  e.g., 
  ln -s jl030910 jl

NOTE: depending on how the $ROOTDIR drive is mounted, this may not be possible to do remotely. If you get 'permission denied', try to ssh into larmor and create the link locally on larmor. Note that the mounted volumes have different names on larmor than on the network, so that the drive named /Volumes/CBIV2/Heegerlab on the network is called /Volumes/V2/Heegerlab on larmor. By default, mrLoadRet will try to search for anatomy data in this directory based on the subject's initials.

[edit] Anatomy/segmentation directories for each acquisition date

$ROOTDIR/anatomy/jl19670331/jl030910

Five subdirectories named:

   -raw
   -volume
   -surface	
   -gray
   -auxfiles

• raw subdirectory

Contains the raw, unprocessed images as recovered from the scanner, plus the same images re-oriented to the default Nifti x-y-z format that should be named <file basename>_reorient.img. (These files must have been generated with cbiSwapNiftiDimensions, not avwswapdim, as the latter does not properly modify the Nifti header information.) You can tell whether a file is in this format by inspecting the qform44 matrix: it should have positive numbers along the diagonal, and any off-diagonal elements (except the last column) should be zero. Also contains any other data directly downloaded from the scanner, such as extracted DICOM header info text file, dicoms, etc., description of protocol used, etc.

Important: Segmentation and alignment should be done on the re-oriented images. Although the orientation of the image is coded in the Nifti header, SurfRelax currently requires images to be in x-y-z format to work.

• volume

Contains all processed volumes and segmentation data for the subject. This includes text files generated by SurfRelax.

• volume/alignment

Contains a link to the volume anatomy that should be used for alignment with mrAlign

• surface

Contains all surfaces generated from the segmentation, and associated data (e.g. cortical thickness vectors in .vff or .vec format)

• surface/patches

Contains cutout patches (flattened and/or folded) from the surface.

• gray

Contains gray graphs and associated volumes for the segmentation.

• gray/patches

Contains .coord and/or .mat files corresponding to the flattened cutout patches in surface/patches directory (see c.)

• retinotopy

Contains retinotopy directories

• auxfiles subdirectory

Contains all other files. Specifically, this is where the commands used to generate surfaces etc. should be stored, and any other documentation as applicable. This directory may also be used to store (temporarily) intermediate files and directories generated by SurfRelax.

[edit] Naming conventions

• Use the naming conventions provided by SurfRelax scripts and default naming structures. Type 'SurfAndRelax' for a description, and check the documentation.

• Use descriptive names for flat patches etc. Do not use names like 'largePatch', 'newFlat' etc. (Especially do not use 'new' or 'old' for anything!). For example, an occipital patch defined as everything within 100 mesh steps (~ 80 mm) from the pole, you could use something like

  jl_left_occpatch100_flat.off

and (importantly!) *document how the patch was generated in a text file with the same name*. (e.g. jl_left_occpatch100_flat.txt)

• Use as long names as needed to describe files.

• Make sure corresponding data are named identically, i.e. when exporting patches with surf2graph, use the same basename for the .coord and .off files (e.g., jl_left_occpatch100_flat.coord)

Eli 14:58, 13 February 2007 (EST)