Cortical thickness with ANTsPyNet
Install a complete runnable container from Docker Hub.
For non-containerized installation (not recommended), first install the system requirements ANTs, c3d, and trim_neck.sh. Then install with pip
git clone https://github.com/ftdc-picsl/antsnetct
pip install antsnetct
All users must set the environment variable TEMPLATEFLOW_HOME
to a location containing
the template to be used. You can use any template as long as it has both a _T1w.nii.gz
file and an associated brain mask.
The default is a single thread for all operations. Multi-threading of ITK can be enabled
by setting the environment variable ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS
. Set
ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS=0
to use all available cores, or 8 threads,
whichever is smaller. Multi-threading of tensorflow operations in ANTsPyNet processes is
controlled by the TF_NUM_INTRAOP_THREADS
and TF_NUM_INTEROP_THREADS
variables.
docker run --rm -it -v /path/to/local/templateflow:/opt/templateflow \
-e TEMPLATEFLOW_HOME=/opt/templateflow \
-e ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS=2 \
antsnetct:latest --help
Because singularity does not allow the container to set its user, additional options are required.
export SINGULARITYENV_ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS=2
export SINGULARITYENV_TEMPLATEFLOW_HOME=/opt/templateflow
singularity run --cleanenv --no-home --home /home/antspyuser \
-B /path/to/local/templateflow:/opt/templateflow \
antsnetct_latest.sif --help
Basic pipeline
- Conform to standard orientation.
- Trim neck (optional).
- Brain extraction (done by antspynet, or supply your own brain mask dataset, or have one in the input dataset).
- Segmentation and bias correction. Priors can come from deep_atropos or user-supplied priors. Priors can be used as input to antsAtroposN4.sh, or used directly as the final segmentation.
- Denoise and bias-correct T1w using the segmentation.
- Thickness computation. Same as antsCorticalThickness.sh.
- Warp to template - similar to antsCorticalThickness.sh
- Generate template space derivatives, Jacobian, GMP, thickness, etc.
See antsnetct --help
for current usage.
Output is prefixed with the source entities, which uniquely identifies each T1w input. Some files have metadate stored in a JSON sidecar.
File | Description |
---|---|
desc-biascorrbrain_T1w.nii.gz | Bias-corrected and denoised image, masked with the brain mask. |
desc-biascorr_T1w.nii.gz | Bias-corrected and denoised image, with the skull on. |
desc-brain_mask.nii.gz | Binary brain mask for the T1w. |
desc-preproc_T1w.nii.gz | The input T1w after preprocessing but before any antsnetct processing. Currently, the only preprocessing is neck trimming. |
from-{template}_to-T1w_mode-image_xfm.h5 | Composite transform for warping images from the template space to the space of the T1w. |
from-T1w_to-{template}_mode-image_xfm.h5 | Composite transform for warping images from the T1w space to the template. |
seg-antsnetct_desc-thickness.nii.gz | Cortical thickness in mm. |
seg-antsnetct_dseg.nii.gz | Six-class brain segmentation, using BIDS common derived segmentation labels. |
seg-antsnetct_label-{label}_probseg.nii.gz | Probability image for each segmentation label. |
space-{template}[_res-{template_res}]_desc-biascorrbrain_T1w.nii.gz | Bias-corrected, denoised image in the template space. |
space-{template}[_res-{template_res}]_desc-logjacobian.nii.gz | Log jacobian of the nonlinear component of the warp to the template, for analysis of nonlinear volume change. |
space-{template}[_res-{template_res}]_desc-thickness.nii.gz | Cortical thickness in the template space. |
space-ADNINormalAgingANTs_res-01_label-CGM_probseg.nii.gz | Cortical gray matter probability in the template space, for VBM. |
First run the cross-sectional (cx) pipeline on all time points.
Defaults to running all session T1w images, but user can input a custom list.
The SST is built from the processed T1w images (ie, desc-biascorr
) but the longitudinal
segmentation is done with the preprocessed T1w images (ie, desc-preproc
), which is oriented
and optionally neck-trimmed, but not denoised or bias-corrected.
Pipeline overview:
- Build SST from the cx-processed T1w
- Define a common brain mask from the cx sessions (basically the union of the session masks in SST space)
- Segment SST with ANTsPyNet
- Register SST to group template (optional)
For each session image:
- Register to SST
- Warp SST segmentation to each session space
- Run denoising / N4 / Atropos on session T1w, using SST segmentation as priors.
- Compute cortical thickness on session T1w
- Warp derivatives to SST / group template space
See antsnetct --longitudinal --help
for current usage.
Under sub-subjeclabel/anat
, subject-level output files are prefixed with sub-JP01
. The
T1w image in this folder is the single-subject template (SST).
File | Description |
---|---|
desc-brain_mask.nii.gz | Brain mask for the SST. |
File | Description |
desc-brain_T1w.nii.gz | Brain-extracted SST. |
from-{template}_to-T1w_mode-image_xfm.h5 | Transform from the group template to the SST. |
from-T1w_to-{template}_mode-image_xfm.h5 | Transform from the SST to the group template. |
seg-antsnetct_dseg.nii.gz | Segmentatation of the SST. |
seg-antsnetct_label-{label}_probseg.nii.gz | Probability images from the segmentation. These are used as priors for session-level segmentation. |
T1w.nii.gz | The SST image. |
Session-level output is similar to the cross-sectional output, except that the transforms map to the SST space, not the group template space. To warp images to the group template, combine the warps, for example:
antsApplyTransforms \
-d 3 \
-i sub-01_ses-01_desc-biascorrbrain_T1w.nii.gz \
-r tpl-group_T1w.nii.gz \
-o sub-01_ses-01_space-group_desc-biascorrbrain_T1w.nii.gz \
-t sub-01_from-T1w_to-group_template_mode-image_xfm.h5 sub-01_ses-01_from-T1w_to-sst_mode-image_xfm.h5