Running NeuroAnalytica
NeuroAnalytica can be run several ways, but the easiest way is the single command:
workupScan (path to where you want the results) (path to the T1 image)
The path to where you want the results must exist, and a new folder containing the workup (10_AUTO.309BIA_T1) will be created in that folder.
The path to the T1 image must be the full path to the image if you are using analyze or nifti images, and if you are using DICOM images it must be the full path to the folder containing the DICOM images. DICOM images will be converted to NIFTI in the first step of processing.
We feel it is best to include an official patient ID and scan ID in the path to the workup, and NeuroAnalytica uses the path information to create patient ID and scan ID labels for the workup. Therefore it is best to have your folders organized in this fashion. For instance, we typically have a folder for each subject, and inside that folder there are folders for each of that subject's scans, possibly labeled with the dates of each scan. The full path to the scan date is where we place the output from the workup. NeuroAnalytical uses the name of the last subfolder of the path as the prefix for the names of many of the images, so it is useful to ensure it is a meaningful name. The name of the folder above the last subfolder will be listed as the PatientID in the measurement files, so using our naming scheme unsures the measurements will have identifiers for both the subject and the scan, to ensure you can easily combine many measurement files into one when collecting study results.
Example:
/mnt/data/My_MR/Patient2403/10-23-2011
In this case the data files will contain Patient2403 as the patientID and 10-23-2011 as the scanID. In the examples on this WIKI we will use a generic ${scanid} to refer to the last folder in the path where the workup output is placed, with the assumption that you are following this convention. Many of the images in the workup folder will also use the scanID, in this case 10-23-2011, as the prefix for the files.
Final images that may be of use to you are listed below. We suggest you view the images and segmentations in your favorite viewer, such as slicer, freeview, fslview, mricro, mricron, etc.
${scanid}_ACPC_T1_norm.nii.gz - The ACPC oriented, inhomogeneity corrected and intensity normalized T1 image.
${scanid}_ACPC_Class.nii.gz - The continuous classified image.
${scanid}_ACPC_Discrete_Class.nii.gz - The discrete classified image.
${scanid}_BRAINSABC_Brain.nii.gz - A mask of the intracranial volume.
${scanid}_Code_BIA_ADNI_ANN.nii.gz - A code image with subcortical structures, with a lookup table of the
same name and extension of .txt. Easy to load in a number of packages, including freeview, slicer, itksnap, etc.
${scanid}_Class_Segmented_Code.nii.gz - A code image with the above subcortical structures as well as
cerebral lobe tissues, ventricles, surface CSF, etc.
${scanid}_ClassSegCode.csv - This contains the full set of measures using the latest methods. The most valid
methods for definitions of the cerebral lobes and ventricles are used in creation of this data, and it is
directly measured from the ${scanid}_Class_Segmented_Code.nii.gz image.
${scanid}_BrainsAnnMeasurements.csv - This contains the subcortical ANN generated measures, with are also in
the above file.
${scanid}_BrainsClassMeasurements.csv - This contains the legacy BRAINS type measures, based on the Talairach atlas.
Using the segmenations in different image spaces
In the first major step of AutoWorkup the T1 image is reoriented into ACPC alignment, just as the Talairach brain is. There is no scaling into Talairach space, or spatial normalization of any kind. If you wish to use the segmentations in a different space (such as seed points for tractography in DTI space or ROI methods of fMRI processing) you need to resample them into that space. In the following example I use the tools available in NeuroAnalytica. These tools are also available in Slicer and as standalone programs in BRAINSTools, and development on them continues at the University of Iowa. If you use versions other than that in NeuroAnalytica the specific options and syntax may be different, but the general procedure and options available are the same. In addition to this method you may have other tools you are more accustomed to.
In the following example the full path to each file is denoted with the variables ${ACPCDirPath} and ${FMRIDirPath}. It is generally safest to give the full path, but if you use relative paths or have all the files in the same directory and run the commands in the directory where all the files are and will be located, you can omit it. The options used in these examples are just a few of the many command line options available.
The first command, BRAINSFit, creates a transform to bring the ACPC oriented T1 image into your fMRI image space. If you have run /opt/BRAINS3/bin/brains3_setup.sh (or .csh) you don't need to give the full path to the command. The order of the options is irrelevant. The commands are shown split into several lines for ease of reading. You need to specify which image is moving (where the segmentations are coming from), which image is fixed (where you want the final segmentations to be) and a transform file in which to place the output transform (containing translations and rotations to move from one image space to another). A number of options are specified that generally produce excellent results. You can see the full list of options available with the command "BRAINSFit -h". The option "--maskProcessingMode ROIAUTO" creates a mask that will exclude the background of the images from being considered during the coregistration, resulting in more accurate and faster coregistrations. The option "--maskInferiorCutOffFromCenter 45" is used to cut off the mask at the neck, useful if your scan space includes the neck and shoulders. The option "--initializeTransformMode useCenterOfHeadAlign" finds the center of the head in each image by using a hatband approach, then starts the coregistration by placing the center of the head of the moving volume directly on the center of head of the fixed volume. That saves many iterations of the coregistration by estimating the translations needed to put the images on top of one another. The option "--transformType Rigid" specifies that there will be no stretching, shrinking, or warping done in this coregistration, since the images are both from the same subject. The TimeIndex options are useful if you are working with four dimensional images, such as DTI and FMRI, to select with time point to use.
The second command, BRAINSResample, will take the transform that was created by fitting the T1 to the fMRI data and use it to bring the left hippocampus into the orientation and image spacing of your fMRI data. The option "--pixelType binary" is the best one to use for this purpose because it will greatly reduce the interpolation errors associated with resampling a binary image, composed of only 1's and 0's. The much faster nearest-neighbor resampling is often used on 8-bit images for this purpose, but this causes a structure to change in size to a larger degree during resampling.
/opt/BRAINS3/bin/BRAINSFit \
--movingVolume ${ACPCDirPath}/${scanID}_ACPC_T1_BFC_norm.nii.gz \
--fixedVolume ${FMRIDirPath}/FMRI_Image.nii.gz \
--outputTransform ${ACPCDirPath}/T1toFMRI.mat \
--maskProcessingMode ROIAUTO \
--initializeTransformMode useCenterOfHeadAlign \
--maskInferiorCutOffFromCenter 45 \
--transformType Rigid \
--movingVolumeTimeIndex 0 \
--fixedVolumeTimeIndex 0
BRAINSResample \
--warpTransform ${ACPCDirPath}/T1toFMRI.mat \
--outputVolume ${FMRIDirPath}/${scanID}_l_hippocampus.nii.gz \
--referenceVolume ${FMRIDirPath}/FMRI.nii.gz \
--inputVolume ${FMIRDirPath}/${scanID}_l_hippocampus_BIA_ADNI_ANN.nii.gz \
--pixelType binary
Resampling into native T1 image space
Since the transform already exists for resampling the raw T1 into ACPC orientation, you can use BRAINSResample to bring the segmentations back into native T1 space.
The transform from raw T1 space to ACPC space is 10_AUTO.309BIA_T1/Stage1/${scanid}_SCAN0_T1_ACPC.mat, and you can use the -- inverseTransform 1 option on BRAINSResample to have it use the inverse transform.
referenceVolume is the image space you want the results to end up in, so you will specify the raw T1 image for it. If you used a dicom directory as t1 input, you will need to use the nifti version of it as the reference, which is 10_AUTO.309BIA_T1/Stage0/${scanid}_SCAN0_T1.nii.gz.
To resample a full code image back into native space you will use nearest neighbor for interpolationMode, and pixelType will be uchar. However, if your input image is a single structure, I suggest using binary as the pixelType (do not specify anything for the interpolationMode). This will compute a more accurate resampled image, as it uses a signed distance image during the resampling process. Binary resampling creates an output segmentation that is closer in volume to the original ACPC volume, but only works for single structures where the image is composed of 1’s and 0’s.