CIVET 2.1.0 - Outputs of CIVET

General BIC-wiki
1

The results for CIVET are created in the directory targetdir , as specified in the command-line options. The file References.txt in this directory gives a list of references to cite in your paper. These references describe the various algorithms and modules used in your CIVET run. Please acknowlege the work of these researchers in your publications using CIVET.

CIVET organizes the results for each subject in targetdir/id where id is the identifier of the subject. Note that the presence of some files may be activated by your choice of parameters. The prefix is optional and may not be present

Listing of Output Folders / Files

  • native : images in native space
    • prefix_id_t1.mnc : original t1 image, regular spacing, mnc2
    • prefix_id_t1_nuc.mnc : t1 image partially corrected for non-uniformities

If t2/pd used as input:

  • prefix_id_t2.mnc : original t2 image, regular spacing, mnc2

  • prefix_id_t2_nuc.mnc : t2 image partially corrected for non-uniformities

  • prefix_id_pd.mnc : original pd image, regular spacing, mnc2

  • prefix_id_pd_nuc.mnc : pd image partially corrected for non-uniformities

  • final : images in stereotaxic space

    • prefix_id_t1_tal.mnc : original t1 image transformed in stereotaxic space
    • prefix_id_t1_final.mnc : original t1 image transformed in stereotaxic space, fully corrected for non-uniformities (with mask)

If t2/pd used as input:

  • prefix_id_t2_tal.mnc : original t2 image transformed in stereotaxic space

  • prefix_id_t2_final.mnc : original t2 image transformed in stereotaxic space, fully corrected for non-uniformities (with mask)

  • prefix_id_pd_tal.mnc : original pd image transformed in stereotaxic space

  • prefix_id_pd_final.mnc : original pd image transformed in stereotaxic space, fully corrected for non-uniformities (with mask)

  • transforms/linear : linear transformations

    • prefix_id_t1_tal.xfm : linear transformation from t1 native to stereotaxic space
    • prefix_id_t1_tal_to_6.xfm : linear transformation from stereotaxic space to 6 parameter space
    • prefix_id_t1_tal_to_7.xfm : linear transformation from stereotaxic space to 7 parameter space

If t2/pd used as input:

  • prefix_id_t2pd_t1.xfm : 6-param linear transformation from t2/pd to t1

  • prefix_id_t2pd_tal.xfm : linear transformation from t2/pd to stereotaxic space

  • transforms/nonlinear : non-linear transformations

    • prefix_id_nlfit_It.xfm : non-linear transformation from linear stereotaxic space to stereotaxic space
    • prefix_id_nlfit_It_grid_0.mnc : deformation field for non-linear transformation

  • transforms/surfreg : surface transformations

    • prefix_id_left_surfmap.sm
      prefix_id_right_surfmap.sm : surface maps for left/right hemispheres to surface model

  • mask : brain masks in stereotaxic space

    • prefix_id_skull_mask.mnc : brain mask of cerebrum + cerebellum and brain stem
    • prefix_id_brain_mask.mnc : brain mask without cerebellum and brain stem

  • classify : classified image in stereotaxic space

    • prefix_id_cls_clean.mnc : masked discrete tissue classification (ANN algorithm)
    • prefix_id_cls_volumes.dat : total volume of tissue types in native space (masked, containing cerebrum only, no cerebellum or brainstem, in mm3: 1 = all CSF; 2 = cortical GM; 3 = all WM; 4 = sub-cortical GM). If no sub-cortical tissue class, 4 is combined with 2.
    • prefix_id_pve_disc.mnc : pure and mixed tissue classes (0 = BG; 1 = CSF; 2 = GM; 3 = WM; 4 = sub-cortical GM; 5 = mixed CSF-GM; 6 = mixed GM-WM; 7 = mixed BG-CSF; 8 = mixed sub-cortical GM-WM; 9 = mixed sub-cortical GM-GM)
    • prefix_id_pve_exactcsf.mnc : partial volume estimates for csf
    • prefix_id_pve_exactgm.mnc : partial volume estimates for cortical gray matter
    • prefix_id_pve_exactwm.mnc : partial volume estimates for white matter
    • prefix_id_pve_exactsc.mnc : partial volume estimates for sub-cortical gray
    • prefix_id_pve_classify.mnc : final discrete tissue classification after correction for partial volumes

  • surfaces : surfaces and related files in stereotaxic space

    • prefix_id_white_surface.obj :
      prefix_id_white_surface_left_81920.obj :
      prefix_id_white_surface_right_81920.obj : final white matter surfaces after t1-gradient correction (if hires option selected, there will additionally be versions with the suffix *_327680.obj )
    • prefix_id_white_surface_rsl.obj :
      prefix_id_white_surface_rsl_left_81920.obj :
      prefix_id_white_surface_rsl_right_81920.obj : final white matter surfaces, resampled to MNI ICBM152 surface model or other selected model (if hires option selected, there will only be versions with the suffix *_327680.obj )
    • prefix_id_gray_surface.obj :
      prefix_id_gray_surface_left_81920.obj :
      prefix_id_gray_surface_right_81920.obj : final gray matter (pial) surfaces (if hires option selected, there will additionally be versions with the suffix *_327680.obj )
    • prefix_id_gray_surface_rsl.obj :
      prefix_id_gray_surface_rsl_left_81920.obj :
      prefix_id_gray_surface_rsl_right_81920.obj : final gray matter surfaces, resampled to MNI ICBM152 surface model or other selected model (if hires option selected, there will only be versions with the suffix *_327680.obj )
    • prefix_id_mid_surface.obj :
      prefix_id_mid_surface_left_81920.obj :
      prefix_id_mid_surface_right_81920.obj : final mid surfaces, halfway between white and gray (if hires option selected, there will only be versions with the suffix *_327680.obj )
    • prefix_id_mid_surface_rsl.obj :
      prefix_id_mid_surface_rsl_left_81920.obj :
      prefix_id_mid_surface_rsl_right_81920.obj : final mid surfaces, resampled to MNI ICBM152 surface model or other selected model (if hires option selected, there will only be versions with the suffix *_327680.obj )
    • prefix_id_native_pos_rsl_asym_full.txt :
      prefix_id_native_pos_rsl_asym_hemi.txt : asymmetry maps for position on mid resampled surfaces, whole brain or by hemisphere
    • prefix_id_mid_surface_rsl_left_native_area_40mm.txt :
      prefix_id_mid_surface_rsl_right_native_area_40mm.txt : vertex-based elementary areas on resampled hemispheric surfaces (default = 40,962 vertices per hemi, hires = 163,842 vertices per hemi)
    • prefix_id_surface_rsl_left_native_volume_40mm.txt :
      prefix_id_surface_rsl_right_native_volume_40mm.txt : vertex-based elementary volumes on resampled hemispheric surfaces (default = 40,962 vertices per hemi, hires = 163,842 vertices per hemi)
    • prefix_id_gi.dat :
      prefix_id_gi_left.dat :
      prefix_id_gi_right.dat : gyrification index for gray, white, mid surfaces
    • prefix_id_ atlas lobe_thickness tmethod _30mm_left.dat :
      prefix_id_lobe_thickness_ tmethod _30mm_right.dat : regional average cortical thickness (collapsed across vertices per region) at this (30mm) fwhm; depends on parcellation selected (basic lobes, AAL, or DKT40, tmethod =tlink, tfs, tlaplace)
    • prefix_id_ atlas _lobe_volumes_40mm_left.dat :
      prefix_id_lobe_volumes_40mm_right.dat : regional average volumes (collapsed across vertices per region) at this (40mm) fwhm; depends on parcellation selected (basic lobes, AAL, or DKT40, tmethod =tlink, tfs, tlaplace)
    • prefix_id_ atlas _lobe_areas_40mm_left.dat :
      prefix_id_lobe_areas_40mm_right.dat : regional average areas (collapsed across vertices per region) at this (40mm) fwhm of the resampled mid surface, in native space; depends on parcellation selected (basic lobes, AAL, or DKT40)
    • prefix_id_ atlas _lobe_native_cortex_area_left.dat :
      prefix_id_lobe_native_cortex_area_right.dat : regional average areas (collapsed across vertices per region) of the resampled gray surface, in native space; depends on parcellation selected (basic lobes, AAL, or DKT40)

  • thickness : cortical thickness maps

    • prefix_id_cerebral_volume.dat : total volume of cortex in native space (masked, containing cerebrum only, in mm3: 1 = CSF outside pial surface only (without ventricles); 2 = cortical GM only (no subcortical); 3 = WM + subcortical gray + filled-in ventricles)
    • prefix_id_native_rms_ tmethod _30mm.txt :
      prefix_id_native_rms_ tmethod _30mm_left.txt :
      prefix_id_native_rms_ tmethod _30mm_right.txt : native cortical thickness, blurred at this (30mm) fwhm, tmethod =tlaplace, tfs, tlink (default = 40,962 vertices per hemi, hires = 163,842 vertices per hemi)
    • prefix_id_native_rms_rsl_ tmethod _30mm.txt :
      prefix_id_native_rms_rsl_ tmethod _30mm_left.txt :
      prefix_id_native_rms_rsl_ tmethod _30mm_right.txt : native cortical thickness, resampled to MNI ICBM152 surface model or other selected model, blurred at this (30mm) fwhm, tmethod =tlaplace, tfs, tlink (default = 40,962 vertices per hemi, hires = 163,842 vertices per hemi)
    • prefix_id_native_rms_rsl_ tmethod _30mm_asym.txt :
      prefix_id_native_rms_rsl_ tmethod _30mm_asym_hemi.txt : asymmetry maps for cortical thickness, resampled to MNI ICBM152 surface model or other selected model, blurred at this (30mm) fwhm, tmethod =tlaplace, tfs, tlink (resampled left-right, default = 40,962 vertices per hemi, hires = 163,842 vertices per hemi)

If -mean-curvature option selected:

  • prefix_id_native_mc_30mm_gray.txt :
    prefix_id_native_mc_30mm_gray_left.txt :
    prefix_id_native_mc_30mm_gray_right.txt : mean surface curvature for GM surface, blurred at this (30mm) fwhm (default = 40,962 vertices per hemi, hires = 163,842 vertices per hemi)

  • prefix_id_native_mc_30mm_mid.txt :
    prefix_id_native_mc_30mm_mid_left.txt :
    prefix_id_native_mc_30mm_mid_right.txt : mean surface curvature for mid surface, blurred at this (30mm) fwhm (default = 40,962 vertices per hemi, hires = 163,842 vertices per hemi)

  • prefix_id_native_mc_30mm_white.txt :
    prefix_id_native_mc_30mm_white_left.txt :
    prefix_id_native_mc_30mm_white_right.txt : mean surface curvature for WM surface, blurred at this (30mm) fwhm (default = 40,962 vertices per hemi, hires = 163,842 vertices per hemi)

  • prefix_id_native_mc_rsl_30mm_gray.txt :
    prefix_id_native_mc_rsl_30mm_gray_left.txt :
    prefix_id_native_mc_rsl_30mm_gray_right.txt : mean surface curvature, resampled to MNI ICBM152 surface model or other selected model, blurred at this (30mm) fwhm (default = 40,962 vertices per hemi, hires = 163,842 vertices per hemi)

  • prefix_id_native_mc_rsl_30mm_mid.txt :
    prefix_id_native_mc_rsl_30mm_mid_left.txt :
    prefix_id_native_mc_rsl_30mm_mid_right.txt : mean surface curvature, resampled to MNI ICBM152 surface model or other selected model, blurred at this (30mm) fwhm (default = 40,962 vertices per hemi, hires = 163,842 vertices per hemi)

  • prefix_id_native_mc_rsl_30mm_white.txt :
    prefix_id_native_mc_rsl_30mm_white_left.txt :
    prefix_id_native_mc_rsl_30mm_white_right.txt : mean surface curvature, resampled to MNI ICBM152 surface model or other selected model, blurred at this (30mm) fwhm (default = 40,962 vertices per hemi, hires = 163,842 vertices per hemi)

  • VBM : non-modulated VBM maps in stereotaxic space (if -VBM selected)

    • prefix_id_smooth_8mm_csf.mnc :
      prefix_id_smooth_8mm_gm.mnc :
      prefix_id_smooth_8mm_wm.mnc : VBM maps for CSF, gray matter, or white matter, blurred at 8mm

If -VBM-symmetry option selected:

  • prefix_id_smooth_8mm_csf_sym.mnc :
    prefix_id_smooth_8mm_gm_sym.mnc :
    prefix_id_smooth_8mm_wm_sym.mnc : right/left differences of blurred VBM maps for CSF, gray matter, or white matter

  • segment : ANIMAL segmentation (if -animal selected)

    • prefix_id_animal_labels.mnc : ANIMAL segmentation, unmasked
    • prefix_id_animal_labels_masked.mnc : ANIMAL segmentation, masked
    • prefix_id_lobes.dat : regional segmented volumes, in native space, mm3 (See bottom of page here for ANIMAL label list)

  • temp : temporary working files (not documented)

  • verify : quality control images

    • prefix_id_angles.png : quality control image for mesh distortion angle between white and gray surfaces
    • prefix_id_atlas.png : quality control image for surface registration and lobar segmentation
    • prefix_id_clasp.png : quality control image for surface extraction
    • prefix_id_converg.png : quality control image for white/gray surface convergence
    • prefix_id_gradient.png : quality control image for t1-gradient at position of calibrated white surface
    • prefix_id_laplace.png : quality control image for gray surface expansion
    • prefix_id_surfsurf.png : quality control image for surface-surface intersections
    • prefix_id_verify.png : quality control image for registration and classification
    • prefix_id_classify_qc.txt : classified tissue percentages
    • prefix_id_surface_qc.txt : error for white and gray surfaces
    • prefix_id_civet_qc.txt : list of values of processing variables for populating the QC table

  • logs : execution log and status for stages

    • id.stage_name.log : log of commands for stage
    • id.stage_name.lock : lock file (indicates if a subject is being processed)
    • id.stage_name.running : status file (indicates if a stage is ready to run or is running)
    • id.stage_name.failed : status file (indicates if a stage has failed)
    • id.stage_name.finished : status file (indicates if a stage has completed successfully)
    • id.options : options and settings used to process subject

Meaning of vertex-wise surface area (and volumes)

What is the correct interpretation of the vertex-wise areas and volumes?

The vertex-wise area is obtained by resampling each triangle on the surface template and calculating the area of these triangles on the resampled surface in native space. One third of the area of each triangle is given to each of the three vertices making up the triangle. This gives a measurement of local mesh contraction/stretching relative to the template.

Suppose you use the AAL or DKT parcellation atlas. Each ROI has a mean cortical thickness, a total area, and a cortical volume associated to it. Per subject. You would like to compare the characteristics of your population within an ROI and also compare all ROIs against one another. You can compare the mean cortical thickness in a ROI across all your subjects. For that ROI, you would get the population mean and its standard deviation. Similarly, you can treat the ROIs as independent degrees of freedom and regress them against behavioral data. This would describe your population. You may observe that ROI-1 has a thicker cortex than ROI-2, larger area and volume. That’s fine. This is a result of how your parcellation atlas has been defined. If you have a small number of ROIs, like AAL and DKT, you will likely report your results in a histogram or a table.

The next question is how to relate within-ROI distributions against all ROIs over the whole brain? Let’s assume that each ROI is a vertex. This would be the ultimate surface parcellation for plotting results over the whole brain. At each vertex, you can associate a local area or volume. If you were to average ROI-based area across all subjects over the whole brain for the DKT atlas, it would look patchy because the ROIs have different meanings, shapes, sizes. The same holds true for ROIs defined per vertex. If you attempt to plot vertex-wise areas over the whole brain, they will appear as being noisy where in fact they are not, because the data have not been normalized to account for the surface area of each triangle in the surface template. In such a case, the vertex-wise coefficient of variation (CV = standard deviation normalized by mean at a given vertex) can be used, because it characterizes the normalized variability in your population and CV will represent a continuous variable over the whole brain (but not mean nor standard deviation individually). Similary, you can regress vertex-wise areas against any behavioral trait. p-values, RFT values, etc, which would all be smooth across the cortex regardless of the unit size of each ROI.

Note that CV on vertex-wise areas will not tell you if the area has expanded or contracted within an ROI or at a vertex. CV will tell you if there is low or high variability in that region (vertex). For such analysis, one needs to look at the local stretching/contraction area ratio of the surface. The stretching/contraction area ratio is not provided in the current version of CIVET. The stretching/contraction area ratio is also a continuous map.

If vertex-wise areas cannot be blurred over the whole cortex (in analogy of not blurring across ROIs), then why do I need to blur the vertex-wise areas (and volumes) computed in CIVET? For areas, for example, CIVET blurs the local stretching/contraction ratio, which is a continuous field at the vertices and then normalizes the blurred ratio by the associated areas on the average surface model for the population. The fwhm must be chosen to remove numerical noise. Because of the way the vertex-wise areas are derived from the stretching/contraction area ratio in CIVET, looking at the coefficient of variation for the stretching/contraction area ratio would be equivalent at looking at the coefficient of variation for the vertex-wise surfaces areas. Moreover, the area ratio would give extra information on local mesh expansion and contraction, which areas alone cannot provide.

Vertex-wise surface volumes can be analysed in the same context as surface areas.

Understanding CIVET errors

The log files are useful to determine the completion status of CIVET. After completion, one should check for the presence of .failed and .running files. A leftover .running means that the CIVET run is incomplete, likely due to some unexpected interruption (power failure?). A .failed file means that a stage has failed. In such a case, examine the corresponding .log file for that stage to try to understand the cause of the error. Note that there are usually leftover .running files for the unfinished stages after a failure. Sometimes, you may also have to manually erase the .lock files after a crash if their presence prevents you from restarting CIVET. Common errors are:

  • t1 image in non-standard orientation (often after conversion from NIfTI to minc). If your image originates from DICOM, make sure to use the -usecoordinates option in the dcm2mnc converter. If you are converting from NIfTI, make sure that you have used the latest version of the nii2mnc converter.
  • empty brain mask causing tissue classification to be undefined
  • incorrect linear registration to stereotaxic space
  • incomplete cortical surfaces due to self-intersections of the white marching-cubes surface following surface registration (usually nothing to do except check for the presence of blood vessels, and re-run with option -mask-blood-vessels )

Whenever such an error occurs, it is helpful to view the MR input and processed images in a minc viewer (BIC tools register , Display , or BrainBrowser) to understand the source of the error.