From dacfa1fc9886fd591df1649e27599917feeafcab Mon Sep 17 00:00:00 2001 From: Philip Cook Date: Fri, 12 Mar 2021 10:43:02 -0500 Subject: [PATCH 1/3] DOC: Update antsCorticalThickness.sh usage --- Scripts/antsCorticalThickness.sh | 103 +++++++++++++++++++++---------- 1 file changed, 69 insertions(+), 34 deletions(-) diff --git a/Scripts/antsCorticalThickness.sh b/Scripts/antsCorticalThickness.sh index 422dd28da..6deff1229 100755 --- a/Scripts/antsCorticalThickness.sh +++ b/Scripts/antsCorticalThickness.sh @@ -60,17 +60,18 @@ We use *probability* to denote a probability image with values in range 0 to 1. We use *label* to denote a label image with values in range 0 to N. -d: Image dimension 2 or 3 (for 2- or 3-dimensional image) + -a: Anatomical image Structural *intensity* image, typically T1. If more than one anatomical image is specified, subsequently specified images are used during the segmentation process. However, only the first image is used in the registration of priors. - Our suggestion would be to specify the T1 as the first image. - -e: Brain template Anatomical *intensity* template (possibly created using a population - data set with buildtemplateparallel.sh in ANTs). This template is - *not* skull-stripped. - -m: Brain extraction probability mask Brain *probability* mask created using e.g. LPBA40 labels which - have brain masks defined, and warped to anatomical template and - averaged resulting in a probability image. + We recommend using the T1 as the first image. + + -e: Brain template Anatomical *intensity* template This template is *not* skull-stripped. + + -m: Brain extraction probability mask Brain *probability* mask. A binary mask is an acceptable probability + image. + -p: Brain segmentation priors Tissue *probability* priors corresponding to the image specified with the -e option. Specified using c-style formatting, e.g. -p labelsPriors%02d.nii.gz. We assume that the first four priors @@ -79,7 +80,8 @@ We use *label* to denote a label image with values in range 0 to N. 2: cortical gm 3: wm 4: deep gm - -o: Output prefix The following images are created: + + -o: Output prefix A partial list of output images: * ${OUTPUT_PREFIX}BrainExtractionMask.${OUTPUT_SUFFIX} * ${OUTPUT_PREFIX}BrainSegmentation.${OUTPUT_SUFFIX} * ${OUTPUT_PREFIX}BrainSegmentation*N4.${OUTPUT_SUFFIX} One for each anatomical input @@ -91,35 +93,61 @@ We use *label* to denote a label image with values in range 0 to N. * ${OUTPUT_PREFIX}BrainSegmentationPosteriors*N.${OUTPUT_SUFFIX} where there are N priors * Number formatting of posteriors matches that of the priors. * ${OUTPUT_PREFIX}CorticalThickness.${OUTPUT_SUFFIX} + More information on the output can be found on the ANTs Wiki + https://github.com/ANTsX/ANTs/wiki. Optional arguments: -s: image file suffix Any of the standard ITK IO formats e.g. nrrd, nii.gz (default), mhd - -t: template for t1 registration Anatomical *intensity* template (assumed to be skull-stripped). A common - use case would be where this would be the same template as specified in the - -e option which is not skull stripped. - We perform the registration (fixed image = individual subject - and moving image = template) to produce the files. + + -t: template for t1 registration Anatomical *intensity* template. This template *must* be skull-stripped. + This template is used to produce a final, high-quality registration between + the bias-corrected, skull-stripped subject anatomical image and the template. + This template will commonly be a skull-stripped version of the template passed + with -e. We perform the registration with fixed image = this template + and moving image = input anatomical image. The output from this step is - * ${OUTPUT_PREFIX}TemplateToSubject0GenericAffine.mat - * ${OUTPUT_PREFIX}TemplateToSubject1Warp.nii.gz - * ${OUTPUT_PREFIX}TemplateToSubject1InverseWarp.nii.gz - * ${OUTPUT_PREFIX}TemplateToSubjectLogJacobian.${OUTPUT_SUFFIX} - -f: extraction registration mask Mask (defined in the template space) used during registration - for brain extraction. + * Forward warps: + - ${OUTPUT_PREFIX}SubjectToTemplate1Warp.nii.gz + - ${OUTPUT_PREFIX}SubjectToTemplate0GenericAffine.mat + * Inverse warps: + - ${OUTPUT_PREFIX}TemplateToSubject1GenericAffine.mat + - ${OUTPUT_PREFIX}TemplateToSubject0Warp.nii.gz + * Jacobian: + - ${OUTPUT_PREFIX}SubjectToTemplateLogJacobian.${OUTPUT_SUFFIX} + + More information on the how to use these images can be found on the ANTs Wiki + https://github.com/ANTsX/ANTs/wiki. + + -f: extraction registration mask Binary metric mask defined in the brain template space (-e), used during registration + for brain extraction. During the registration, the similarity metric is only computed + within this mask. + -k: keep temporary files Keep brain extraction/segmentation warps, etc (default = 0). + -g: denoise anatomical images Denoise anatomical images (default = 0). - -i: max iterations for registration ANTS registration max iterations (default = 100x100x70x20) - -w: Atropos prior segmentation weight Atropos spatial prior *probability* weight for the segmentation (default = 0.25) - -n: number of segmentation iterations N4 -> Atropos -> N4 iterations during segmentation (default = 3) + + -i: max iterations for registration ANTS registration max iterations (default = 100x100x70x20). + + -w: Atropos prior segmentation weight Atropos spatial prior *probability* weight for the segmentation (default = 0.25). + + -n: number of segmentation iterations N4 -> Atropos -> N4 iterations during segmentation (default = 3). + -b: posterior formulation Atropos posterior formulation and whether or not to use mixture model proportions. e.g 'Socrates[ 1 ]' (default) or 'Aristotle[ 1 ]'. Choose the latter if you want use the distance priors (see also the -l option for label propagation control). - -j: use floating-point precision Use floating point precision in registrations (default = 0) - -u: use random seeding Use random number generated from system clock in Atropos (default = 1) - -v: use b-spline smoothing Use B-spline SyN for registrations and B-spline exponential mapping in DiReCT. - -r: cortical label image Cortical ROI labels to use as a prior for ATITH. + + -j: use floating-point precision Use single float precision in registrations (default = 0). + + -u: use random seeding Use random number generated from system clock in Atropos (default = 1). + + -v: use b-spline smoothing Use B-spline SyN for registrations and B-spline exponential mapping in DiReCT (default = 0). + + -r: cortical thickness prior image Cortical thickness prior image in the template space, which contains an estimated + upper limit to the cortical thickness at each voxel. If not specified, the prior is + set to 10mm throughout the brain. + -l: label propagation Incorporate a distance prior one the posterior formulation. Should be of the form 'label[ lambda,boundaryProbability ]' where label is a value of 1,2,3,... denoting label ID. The label probability for anything @@ -130,18 +158,24 @@ Optional arguments: Intuitively, smaller lambda values will increase the spatial capture range of the distance prior. To apply to all label values, simply omit specifying the label, i.e. '-l "[ lambda,boundaryProbability ]"'. - -c Add prior combination to combined gray and white matters. For example, - when calling KK for normal subjects, we combine the deep gray matter - segmentation/posteriors with the white matter segmentation/posteriors. - An additional example would be performing cortical thickness in the presence - of white matter lesions. We can accommodate this by specifying a lesion mask + + -c: Additional priors for thickness Add segmentation priors to be treated as gray or white matter for thickness + computation. For example, when calling KellyKapowski for normal subjects, we + combine the deep gray matter segmentation/posteriors (class 4) with the white + matter segmentation/posteriors (class 3). + Another example would be computing cortical thickness in the presence + of white matter lesions. We can accommodate this by specifying a lesion mask posterior as an additional posterior (suppose label '7'), and then combine this with white matter by specifying '-c "WM[ 7 ]"' or '-c "3[ 7 ]"'. + -q: Use quick registration parameters If = 1, use antsRegistrationSyNQuick.sh as the basis for registration during brain extraction, brain segmentation, and (optional) normalization - to a template. Otherwise use antsRegistrationSyN.sh (default = 0). - -x: Number of iterations within Atropos (default 5). - -y: Which stage of ACT to run (default = 0, run all). Tries to split in 2 hour chunks. + to a template. Otherwise use a slower registration comparable to + antsRegistrationSyN.sh (default = 0). + + -x: Atropos iterations Number of iterations within Atropos (default 5). + + -y: Script stage to run Which stage of ACT to run (default = 0, run all). Tries to split in 2 hour chunks. Will produce OutputNameACTStageNComplete.txt for each completed stage. 1: brain extraction 2: template registration @@ -149,6 +183,7 @@ Optional arguments: 4: template registration (improved, optional) 5: DiReCT cortical thickness 6: qc, quality control and summary measurements + -z: Test / debug mode If > 0, runs a faster version of the script. Only for testing. Implies -u 0. Requires single thread computation for complete reproducibility. USAGE From a23e0eed7f61b8366e510d53bd877736e212123f Mon Sep 17 00:00:00 2001 From: Philip Cook Date: Fri, 12 Mar 2021 11:15:52 -0500 Subject: [PATCH 2/3] DOC: Few more updates to antsCorticalThickness.sh usage --- Scripts/antsCorticalThickness.sh | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/Scripts/antsCorticalThickness.sh b/Scripts/antsCorticalThickness.sh index 6deff1229..559eef6c1 100755 --- a/Scripts/antsCorticalThickness.sh +++ b/Scripts/antsCorticalThickness.sh @@ -67,10 +67,17 @@ We use *label* to denote a label image with values in range 0 to N. only the first image is used in the registration of priors. We recommend using the T1 as the first image. - -e: Brain template Anatomical *intensity* template This template is *not* skull-stripped. - - -m: Brain extraction probability mask Brain *probability* mask. A binary mask is an acceptable probability - image. + -e: Brain segmentation template Anatomical *intensity* template. This template is *not* skull-stripped. + The following images must be in the same space as this template: + * Brain probability mask (-m) + * Segmentation priors (-p). + If used, the following optional images must also be in the same space as + this template: + * Registration metric mask (-f) + * Thickness prior image (-r). + + -m: Brain extraction probability mask Brain *probability* mask in the segmentation template space. A binary mask + is an acceptable probability image. -p: Brain segmentation priors Tissue *probability* priors corresponding to the image specified with the -e option. Specified using c-style formatting, e.g. @@ -98,7 +105,7 @@ We use *label* to denote a label image with values in range 0 to N. Optional arguments: - -s: image file suffix Any of the standard ITK IO formats e.g. nrrd, nii.gz (default), mhd + -s: image file suffix Any of the standard ITK IO formats e.g. nrrd, nii.gz (default), mhd. -t: template for t1 registration Anatomical *intensity* template. This template *must* be skull-stripped. This template is used to produce a final, high-quality registration between @@ -119,9 +126,9 @@ Optional arguments: More information on the how to use these images can be found on the ANTs Wiki https://github.com/ANTsX/ANTs/wiki. - -f: extraction registration mask Binary metric mask defined in the brain template space (-e), used during registration - for brain extraction. During the registration, the similarity metric is only computed - within this mask. + -f: extraction registration mask Binary metric mask defined in the segmentation template space (-e). During the + registration for brain extraction, the similarity metric is only computed within + this mask. -k: keep temporary files Keep brain extraction/segmentation warps, etc (default = 0). @@ -159,14 +166,15 @@ Optional arguments: range of the distance prior. To apply to all label values, simply omit specifying the label, i.e. '-l "[ lambda,boundaryProbability ]"'. - -c: Additional priors for thickness Add segmentation priors to be treated as gray or white matter for thickness - computation. For example, when calling KellyKapowski for normal subjects, we + -c: Additional priors for thickness Add segmentation classes to be treated as gray or white matter for thickness + estimation. For example, when calling KellyKapowski for normal subjects, we combine the deep gray matter segmentation/posteriors (class 4) with the white matter segmentation/posteriors (class 3). Another example would be computing cortical thickness in the presence of white matter lesions. We can accommodate this by specifying a lesion mask - posterior as an additional posterior (suppose label '7'), and then combine - this with white matter by specifying '-c "WM[ 7 ]"' or '-c "3[ 7 ]"'. + posterior as an additional posterior (suppose label '7'), combining this with + normal white matter in the thickness estimation by specifying '-c "WM[ 7 ]"' + or '-c "3[ 7 ]"'. -q: Use quick registration parameters If = 1, use antsRegistrationSyNQuick.sh as the basis for registration during brain extraction, brain segmentation, and (optional) normalization From ef7b598bafe0c97e7942af7eb97cece467f061c5 Mon Sep 17 00:00:00 2001 From: Philip Cook Date: Fri, 12 Mar 2021 14:36:51 -0500 Subject: [PATCH 3/3] DOC: Update usage for cortical thickness scripts --- Scripts/antsCorticalThickness.sh | 4 +- Scripts/antsLongitudinalCorticalThickness.sh | 113 ++++++++++++------- 2 files changed, 75 insertions(+), 42 deletions(-) diff --git a/Scripts/antsCorticalThickness.sh b/Scripts/antsCorticalThickness.sh index 559eef6c1..ee4f7a489 100755 --- a/Scripts/antsCorticalThickness.sh +++ b/Scripts/antsCorticalThickness.sh @@ -111,8 +111,8 @@ Optional arguments: This template is used to produce a final, high-quality registration between the bias-corrected, skull-stripped subject anatomical image and the template. This template will commonly be a skull-stripped version of the template passed - with -e. We perform the registration with fixed image = this template - and moving image = input anatomical image. + with -e. We perform the registration with fixed image = (this template) + and moving image = (input anatomical image). The output from this step is * Forward warps: - ${OUTPUT_PREFIX}SubjectToTemplate1Warp.nii.gz diff --git a/Scripts/antsLongitudinalCorticalThickness.sh b/Scripts/antsLongitudinalCorticalThickness.sh index 12117a9e7..03ba1c6f5 100755 --- a/Scripts/antsLongitudinalCorticalThickness.sh +++ b/Scripts/antsLongitudinalCorticalThickness.sh @@ -32,16 +32,19 @@ function Usage { `basename $0` performs a longitudinal cortical thickness estimation. The following steps are performed: - 1. Create a single-subject template (SST) from all the data + 1. Create a single-subject template (SST) from all the anatomical images. 2. Create priors for the SST - a. Run the SST through the individual cortical thickness pipeline. + a. Run the SST through the individual cortical thickness pipeline using the group + template and associated priors. b. The brain extraction SST prior is created by smoothing the brain extraction mask created during 2a. c. If labeled atlases are not provided, we smooth the posteriors from 2a to create the SST segmentation priors, otherwise we use antsJointFusion to create a set of posteriors (https://github.com/ntustison/antsCookTemplatePriorsExample). - 3. Using the SST + priors, we run each subject through the antsCorticalThickness + 3. Using the SST + priors, we run each time point image through the antsCorticalThickness pipeline. + 4. Compose (time point) -> SST and SST -> (group template) warps to deform images from the + native anatomical space to the group template. Usage: @@ -60,12 +63,18 @@ Example: Required arguments: -d: Image dimension 2 or 3 (for 2- or 3-dimensional image) - -e: Brain template Anatomical *intensity* template (possibly created using a population - data set with buildtemplateparallel.sh in ANTs). This template is - *not* skull-stripped. - -m: Brain extraction probability mask Brain *probability* mask created using e.g. LPBA40 labels which - have brain masks defined, and warped to anatomical template and - averaged resulting in a probability image. + + -e: Brain segmentation template Anatomical *intensity* template. This template is *not* skull-stripped. + The following images must be in the same space as this template: + * Brain probability mask (-m) + * Segmentation priors (-p). + If used, the following optional images must also be in the same space as + this template: + * Registration metric mask (-f). + + -m: Brain extraction probability mask Brain *probability* mask in the segmentation template space. A binary mask + is an acceptable probability image. + -p: Brain segmentation priors Tissue *probability* priors corresponding to the image specified with the -e option. Specified using c-style formatting, e.g. -p labelsPriors%02d.nii.gz. We assume that the first four priors @@ -73,11 +82,13 @@ Required arguments: 1: csf 2: cortical gm 3: wm - 4: deep gm + 4: deep gm. + -o: Output prefix The following subdirectory and images are created for the single subject template * \${OUTPUT_PREFIX}SingleSubjectTemplate/ * \${OUTPUT_PREFIX}SingleSubjectTemplate/T_template*.nii.gz + A subdirectory is created for each anatomical image. anatomical images Set of multimodal input data assumed to be specified ordered as follows: @@ -88,63 +99,85 @@ Required arguments: . \${timeN_modality1} ... - A single modality is expected by default, in which case the input images - are simply ordered by time: + A single modality is expected by default, in which case the input images + are simply ordered by time: - \${time1_modality1} \${time2_modality1} ... \${timeN_modality1} + \${time1_modality1} \${time2_modality1} ... \${timeN_modality1} - If there are multiple modalities, use the -k option to specify how many. + If there are multiple modalities, use the -k option to specify how many. Optional arguments: -s: image file suffix Any of the standard ITK IO formats e.g. nrrd, nii.gz (default), mhd + -c: control type Control for parallel computation (default 0): 0 = run serially 1 = SGE qsub 2 = use PEXEC (localhost) 3 = Apple XGrid 4 = PBS qsub - 5 = SLURM - -t: template for t1 registration Anatomical *intensity* template (assumed to be skull-stripped). A common - use case would be where this would be the same template as specified in the - -e option which is not skull stripped. - -a: Atlases (assumed to be skull-stripped) used to cook template priors. If atlases + 5 = SLURM. + + -t: template for t1 registration Anatomical *intensity* template. This template *must* be skull-stripped. + This template is used to produce a final, high-quality registration between + the skull-stripped single-subject template and this template. + + -a: Atlases (assumed to be skull-stripped) used to cook template priors. If atlases aren't used then we simply smooth the single-subject template posteriors after passing through antsCorticalThickness.sh. Example: - -a atlas1.nii.gz -a atlas2.nii.gz ... -a atlasN.nii.gz + -a atlas1.nii.gz -a atlas2.nii.gz ... -a atlasN.nii.gz -l: Labels associated with each atlas, in the same order as they are specified - with the -a option. The number of labels in each image is assumed to be equal + with the -a option. The number of labels in each image is assumed to be equal to the number of priors. - -f: extraction registration mask Mask (defined in the template space) used during registration - for brain extraction. + + -f: extraction registration mask Binary metric mask defined in the segmentation template space (-e). During the + registration for brain extraction, the similarity metric is only computed within + this mask. + -g: denoise anatomical images Denoise anatomical images (default = 0). - -j: number of cpu cores Number of cpu cores to use locally for pexec option (default 2; requires "-c 2") + + -j: number of cpu cores Number of cpu cores to use locally for pexec option (default 2; requires "-c 2"). + -k: number of modalities Number of modalities used to construct the template (default 1): For example, if one wanted to use multiple modalities consisting of T1, T2, and FA components ("-k 3"). + -n: use SST cortical thickness prior If set to '1', the cortical thickness map from the single-subject template is used as a prior constraint for each of the individual calls to antsCorticalThickness.sh (default = 0). - -u: use floating-point precision Use floating point precision in registrations (default = 0) - -v: Atropos segmentation weight (SST) Atropos spatial prior *probability* weight for the segmentation for the single - subject template (default = 0.25) - -w: Atropos segmentation weight (Indiv.) Atropos spatial prior *probability* weight for the segmentation for the individual - time points (default = 0.5) + + -u: use single float precision If 1, use single float precision in registrations (default = 0). + + -v: Atropos segmentation weight (SST) Atropos spatial prior *probability* weight for the segmentation of the + single-subject template (default = 0.25). + + -w: Atropos segmentation weight (Indiv.) Atropos spatial prior *probability* weight for the segmentation of the individual + time points (default = 0.5). + -x: Number of iterations within Atropos (default 5). - -q: Use quick registration parameters If 'yes' then we use antsRegistrationSyNQuick.sh as the basis for registration. - Otherwise use antsRegistrationSyN.sh. The options are as follows: - '-q 0' = antsRegistrationSyN for everything (default) - '-q 1' = Fast antsCorticalThickness to SST - '-q 2' = Fast JLF cooking - '-q 3' = Fast everything - -r: rigid alignment to SST This option dictates if the individual subjects are registered to the single - subject template before running through antsCorticalThickness. This potentially - reduces bias caused by subject orientation and voxel spacing (default = 0). + + -q: Use quick registration parameters Use antsRegistrationSyNQuick.sh for some or all of the registrations. + The higher the number, the more registrations are performed quickly. The options are + as follows: + '-q 0' = antsRegistrationSyN.sh for everything (default) + '-q 1' = Quick registration of time points to the SST + '-q 2' = Adds quick registrations for prior cooking + '-q 3' = Quick registrations throughout. + + -r: rigid alignment to SST If 1, register anatomical images to the single-subject template before processing + with antsCorticalThickness. This potentially reduces bias caused by variable + orientation and voxel spacing (default = 0). + -b: keep temporary files Keep brain extraction/segmentation warps, etc (default = 0). - -y: averge rigid transform component Update the template with the full affine transform (default 0). If 1, the rigid - component of the affine transform will be used to update the template. + + -y: rigid template update component Update the single-subject template with the full affine transform (default 0). + If 1, the rigid component of the affine transform will be used to update the + template. Using the rigid component is desireable to reduce bias, but variations + in the origin or head position across time points can cause the template head to + drift out of the field of view. + -z: Test / debug mode If > 0, runs a faster version of the script. Only for testing. Implies -u 0 in the antsCorticalThickness.sh script (i.e., no random seeding). Requires single thread computation for complete reproducibility.