LEONARD PIPELINE

This help file explains what was done in each module of the pipeline in the order that the modules are arranged inside the pipeline. The first pipeline is responsible for getting the segmented, rf-corrected images from reslice space to sulcal space and then timelocked. The second pipeline is then responsible for taking those segmented images in timelocked sulcal space and outputting thickness files. Values and input files will be explicitly stated for each module and it is important to note that these values and input files are specified for the Leonard data only. Other datasets will require different files and values though the pipeline itself will remain the same. Also remember that it is VERY important when making the list files to keep the order of subjects in every list exactly the same. Mismatched lists will lead to mismatched subjects!

There are no intermediate files outputs in the pipeline unless specified to do so. Therefore, specified outputs are highlighted in BOLD and RED


Pipeline 1- getting the segmented images from reslice space to timelocked sulcal space.

Note: this pipeline is a generic pipeline that will work for all datasets to get segmented images from reslice to sulcal space. All that is needed to get this pipeline to work with another dataset is to:
    1) Copy the specified .list files below to your new dataset directory (prefereably a directory named 'LISTS')
    2) Alter these copied lists so that the files they point to reflect your dataset and not Leonard's
    3) Change the 'path' global variable to your dataset's LISTS directory
Everything else should be the same!

GLOBAL VARIABLES:

   sulcal_xfm-          list of the xfms that get the images from reslice to sulcal space
    output-                 list of names that you want the outputs to be named
    reslice_xfm-         list of xfms that get the images from 305 to reslice space
   air_input-             list of air files that get the images from reslice to 305 space
    mask_input-         list of mask files that will be used to get hemispheres from the whole brain segmented images
    timelocked_xfm-  list of xfms that get the images from sulcal space to timelocked sulcal space
    seg_input-             list of whole brain segmented images
    path-                      the path to where all the above .list files live

MASK VOLUME: This module takes 2 inputs: The hemisphere mask (R or L) and the segmented image in reslice space.
    Location of files:  Hemisphere masks:    /loni/edevel/leonard/{subjectnumber}/HEMISPHERES/{subjectnumber}_reslice_mask_1mm_addgreycsf_{L or R}_nocereb.mnc.gz
                                    Segmented image:     /loni/edevel/leonard/{subjectnumber}/{subjectnumber}_reslice_seg_rf_200it_brain_addgrey.mnc.gz
    Function:                Multiplies the segmented image by either mask.
    Outputs:                  R and L hemisphere of segmented image.

MINC TO ANALYZE IMAGE: This module takes 1 input: The output .mnc from the MASK VOLUME module.
    Note:                     Uses the command 'mnc2ana' to change the mnc file to a img file instead of the 'rawtominc' command that is used in the scripts.
    Function:               Changes an image from .mnc format to .img format.
    Outputs:                Image in .img format

RESLICE AIR: This module takes 3 inputs: An air file, a value for interpolation, and the output .img from the MINC TO ANALYZE IMAGE module.
    Location of files:    Air files:    /loni/edevel/leonard/{subjectnumber}/{subjectnumber}_avg_305_AIR1ord.air
    Values:                    Interpolation model: value is set to "0" which codes for 'nearest neighbour'
    Function:                Uses the AIR program to put the image through a specified transformation according to the input .air file. In this case, it is put into 305 space.
    Outputs:                  Segmented image in 305 space in .img format

ANALYZE IMAGE TO MINC: This module takes 2 inputs: A model volume and the output from the RESLICE AIR module.
    Location of files:     Model volume:    /loni/edevel/LEONARD_THICKNESS/LISTS/model_305.mnc
    Function:                 Changes an image from .img format to .mnc format. Uses the model volume to set the dimension size, dim order, and step of the output .mnc
    Outputs:                   Segmented image in 305 space in .mnc format

MINC RESAMPLE: 305 to Reslice. This module takes 3 inputs: The transform xfm, a model volume, and the output from the ANALYZE IMAGE TO MINC module.
    Location of files:    Transform xfm:    /loni/edevel/LEONARD_HEMISPHERE_SULCAL/CONCAT_XFMS/{subjectnumber}_original_305_to_reslice.xfm
                                    Model volume:     /icbm/MNI_DATA/templates/icbm_template_1.00mm.mnc
    Note:                       The check boxes for the short flag and nearest neighbour flag are turned on in this module.
    Function:                 Changes the image from 305 to reslice space. Uses the model volume to set dimension size, dim order, and step of the output .mnc
    Outputs:                   Segmented image in reslice space in .mnc format

MINC RESAMPLE: Reslice to Sulcal. This module takes 3 inputs: The transform xfm, a model volume, and the output from the MINC RESAMPLE: 305 to Reslice module.
    Location of files:    Transform xfm:    /loni/edevel/LEONARD_HEMISPHERE_SULCAL/FINAL_TAGS/{subjectnumber}_avg_YALE176_sulcal.xfm
                                     Model volume:     /icbm/MNI_DATA/templates/icbm_template_1.00mm.mnc
    Note:                       The check boxes for the short flag and nearest neighbour flag are turned on in this module.
    Function:                 Changes the image from reslice space to sulcal space.  Uses the model volume to set dimension size, dim order, and step of the output .mnc
    Outputs:                   Segmented image in sulcal space in .mnc format

MINC RESAMPLE: Sulcal to timelocked_sulcal. This module takes 3 inputs: The transform xfm, a model volume, and the output from the MINC RESAMPLE: Reslice to Sulcal module.
    Location of files:    Transform xfm:    /loni/edevel/LEONARD_THICKNESS/REAL_AND_FAKE_TIMELOCKED_XFMS/timelock_{subjectnumber}_to_*.xfm
                                    Model volume:     /icbm/MNI_DATA/templates/icbm_template_1.00mm.mnc
    Note:                       The check boxes for the short flag and nearest neighbour flag are turned on in this module. Some of the xfms used are fake xfms because images scanned at
                                            Time 1 do not need to be timelocked. Time 1 scans go through the fake xfm transformation which in reality, does not transform the file at all.
                                            Uses the model volume to set dimension size, dim order, and step of the output .mnc
    Function:                 Changes the image from sulcal space to timelocked, sulcal space.
   Outputs:              Segmented image in timelocked sulcal space in .mnc format. Outputs to /loni/edevel/LEONARD_THICKNESS/SULCAL
 
 

Pipeline 2- getting the segmented images in timelocked sulcal space to thickness mncs and ucfs

Important note: Confusion may arise as to why autocrop is used twice in the pipeline. The goal of autocropping the image is to make the process of making the FLOATSEG
                         outputs much faster. Autocrop, however, will not work if the background has a value of anything but 0. Since we need the background to have a value
                                 of 10, this presents us with a problem. The solution to this problem is to use the autocrop module twice.
                              The first time it used, the image is cropped to the dimensions that we want. The background of that image is then clamped at 10. That image is then
                                   resampled back to its original dimensions. When it is resampled, the missing space in the cropped image is filled in with 0 values, so the resultant
                                   image has padding which has a value of 0, background with value of 10, gray =1, and white =2.
                              When autocrop is used the 2nd time, it will crop out all the 0's but leave the 10's, leaving us with a  cropped image of correct dimension size that will make
                            FloatSeg would work faster.
                                   And that, in the end, solves our problem!

GLOBAL VARIABLES:
   output_thickness_ucf-    will name the output thickness ucf the same name as the subject files listed in the  segmented_subject_minc list + _thickness.ucf
    subject_ucf-                       a list of the blend ucfs for each subject's hemisphere
    output_thickness_minc-   will name the output thickness mnc the same name as the subject files listed in the segmented_subject_minc list + _thickness.mnc
    segmented_subject_minc- a list of the timelocked sulcal segmented hemisphere images that will be the input of this pipeline

MINC MATH: White matter clamped. This module takes 1 input: the segmented image that is in timelocked, sulcal space.
    Location of files:    Segmented image in timelocked, sulcal space:
                                            /loni/edevel/LEONARD_THICKNESS/SULCAL/{subjectnumber}_timelocked_sulcal_seg_noclamp_(L or R).mnc
    Note:                        The range 256, 258 was used to clamp white matter.
    Function:                  The range specifies what signal value (tissue) will be clamped to 1. In this case white matter is clamped at 1 while all other signal values in mnc are 0.
    Outputs:                   Segmented image with white matter clamped at 1, all other tissues/background are 0.

MINC MATH: White matter x2. This module takes 1 input: the output from the MINC MATH: White matter clamped module.
    Note:                     The module uses one constant value that is set at '2'. The multiply checkbox is checked on.
    Function:                  Multiplies the white matter clamped segmented image by the constant '2' which makes all white matter have a value of '2' and the rest '0'.
    Outputs:                    Segmented image with white matter clamped at 2, all other tissues/background are 0.

MINC MATH: Gray matter. This module takes 1 input: the segmented image that is in timelocked, sulcal space.
    Location of files:    Segmented image in timelocked, sulcal space:
                                             /loni/edevel/LEONARD_THICKNESS/SULCAL/{subjectnumber}_timelocked_sulcal_seg_noclamp_(L or R).mnc
    Note:                        The range 500, 520 was used to clamp gray matter.
    Function:                 The range specifies what signal value (tissue) will be clamped to 1. In this case gray matter is clamped at 1 while all other signal values in mnc are 0.
    Outputs:                   Segmented image with white matter clamped at 1, all other tissues/background are 0.

MINC MATH: Add gray and white. This module takes 2 inputs: the output from MINC MATH: White matter x2 and MINC MATH: Gray matter
    Function:                  Adds the mnc with white matter clamped at 2 and mnc with gray matter clamped at 1 so we have a mnc with gray=1, white=2, rest =0.
    Outputs:                    Segmented image with gray matter clamped at 1, white matter clamped at 2, and the rest (csf and background) clamped at 0.

AUTOCROP VOLUME1: This module takes 1 input: the output from the MINC MATH: Add gray and white module.
    Function:                   Crops out extra parts of background around the brain in the segmented, clamped image. This makes processing go faster.
    Outputs:                    Cropped segmented image with gray matter clamped at 1, white matter clamped at 2, and the rest (csf and background) clamped at 0.

FLIP VOLUME (for right hemisphere ONLY): This module takes 1 input: the output from the AUTOCROP VOLUME1 module.
    Note:                          This is done to right hemisphere only. Floatseg module fails if the hemisphere is in right hem space so it the right hem is flipped to left hem space.
                                            The right hem also needs to be flipped into left hem space for analysis.
    Function:                    Takes the input image and flips it into opposite space.
    Outputs:                     An duplicate image of the original input that is in the exact opposite space of that input.

MINC MATH: clamp background. This module takes 1 input: the output from the AUTOCROP VOLUME1 module.
    Note:                      The constant value is set to '0.5' and the 'Less than' checkbox is checked on.
    Function:                   Everything with a signal value of less than 0.5 will be clamped to 1. In this case, csf and background will be clamped to 0.
    Outputs:                    Segmented image with csf and background clamped at 1 and the rest (white and gray matter) at 0.

MINC MATH: mult by 10. This module takes 1 input: the output from the MINC MATH: clamp background module.
    Note:                        The constant value is set to '10' and the 'multiply' checkbox is checked on.
    Function:                  Multiplies the input by 10 which results in all csf and background having the value of 10 and the rest (white and gray) at 0.
    Outputs:                    Segmented image with csf and background clamped at 10 and the rest (white and gray matter) at 0.

MINC MATH: add. This module takes 2 inputs: the output from MINC MATH: mult by 10 and AUTOCROP VOLUME1.
    Function:                   Adds the image with gray and white clamped at 1 and 2, respectively, and image with csf and background clamped at 10 together.
    Outputs:                    Segmented image with csf and background at 10, gray at 1, and white at 2.

MINC RESAMPLE: Resample back to to be like previous. This module takes 2 inputs: the output from MINC MATH: add and MINC MATH: Add gray and white.
    Function:                   Resamples the cropped segmented image  (background=10, gray=1, white=2) to it's original dimensions.
    Outputs:                    Segmented image with original dimensions (background=10, gray=1, white=2, padding=0)

MINC RESAMPLE: Resample to have floats and thirds. This module takes 1 input: the output from MINC RESAMPLE: Resample back to to be like previous.
    Note:                        The 'float' and 'nearest neighbour' checkboxes are turned on. The Xdim, Ydim, Zdim values are 543, 651, 543, respectively. The xstep, ystep, zstep
                                                are all set to the value '0.333'.
    Function:                 Takes the input and forces it to have floating numbers for values, and resamples it to have 0.333 step sizes, and user specified dimensions.
    Outputs:                    Segmented image with "third-size' dimensions, forced float number values, and step sizes of 0.333 (one-third of millimeter).

AUTOCROP VOLUME2: This module takes 1 input: the output from the MINC RESAMPLE: Resample to have floats and thirds module.
    Function:                 Takes the input and crops the excess background out of the image. This makes FLOATSEG work faster.
    Outputs:                   Cropped image

FLOATSEG: This module has 1 input: the output from the AUTOCROP VOLUME2 module.
    Note:                        The value for 'Max thickness' is set at 10. The white matter 'min' and 'max' values are set at 1.5 and 2.5 respectively. This function takes a LONG
                                           time.
    Function:                  Takes the input and outputs a thickness image.
    Outputs:                 Thickness mnc to /loni/edevel/LEONARD_THICKNESS/SULCAL

MINC MATH: clamp gray. This module takes 1 input: the output from the AUTOCROP VOLUME2 module.
    Note:                        The constant values are set at 0.98 and 1.1.
    Function:                  Clamps the gray matter signal values making their value equal to 1 and the rest 0.
    Outputs:                  Segmented image file with gray matter = 1 and the rest = 0.

MASK VOLUME: gray only in thickness.mnc. This module takes 2 inputs: the outputs from FLOATSEG and MINC MATH: clamp gray.
    Function:                   Multiplies the thickness mnc with the gray matter mask to obtain a gray matter only thickness map.
    Outputs:                    Thickness mnc that is gray matter only.

SOFTMEAN onto UCF DBL: double thickness.mnc and make ucfs. This module takes 1 input: The putput from MASK VOLUME: gray only in thickness.mnc.
    Note:                           The kernel value is set to 15. The min and max thickness values are set to 0.3 and 10 respectively.
    Function:                    Takes the input and runs a smoothing kernel over the surface averaging cortical thickness at points on the hemisphere. Outputs each point's average
                                                   to the 4th dimension of a ucf file.
    Outputs:                   Ucf files for each subject's hemisphere with average cortical thickness in the 4th dimension. Outputs to /loni/edevel/LEONARD_THICKNESS/SULCAL