Pipeline Details

This section describes the HippUnfold workflow, that is, the steps taken to produce the intermediate and final files. HippUnfold is a Snakemake workflow, and thus the workflow is a directed acyclic graph (DAG) that is automatically configured based on a set of rules.

Overall workflow

Below is a example simplified visualization of the workflow DAG for the --modality T1w workflow. Each rounded rectangle in the DAG represents a rule, that is, some code or script that produces output file(s), and the arrows represent file inputs and outputs to these rules. It is simplified in that multiple instances of each rule are not shown, e.g. the run_inference rule runs on both left and right hemispheres (hemi=L, hemi=R), but only one run_inference box is shown here.

Although it may still look very complex (click on the image to enlarge), it is also organized into groups of rules, each representing the main phases of the workflow. Each grouped set of rules also exist in separate rule files, which can be found in the rules sub-folder
in the workflow source. For example, the preproc_t1 file contains the rules related to pre-processing the T1w images, and these are grouped together in the above diagram by a blue rectangle labelled preproc_t1.

The main phases of the workflow are described in the sections below, zooming in on the rules used in each blue rectangle, one at a time.

Pre-processing

The pre-processing workflow for HippUnfold is generated based on the input data (e.g. whether there are multiple T2w images or a single T2w image), what modality is used (e.g. --modality T1w or --modality T2w), and what optional arguments are specified (e.g. --t1-reg-template).

T1w pre-processing

T1w images are imported, intensity-corrected using N4, and linearly registered to the template image (default: CITI168 - an HCP T1w template). An existing transformation to align the images in a coronal oblique (space-corobl) orientation is concatenated, and this space is used to define the left and right hippocampus bounding boxes in 0.3mm isotropic space. The left hippocampus subvolume is left-right flipped at this stage too (subsequent steps in the corobl space operate on both the hemi-R and hemi-Lflip images).

T1w workflow preproc t1

T2w pre-processing

T2w images are processed similarly, except the T2w version of the template is used. If multiple T2w images exist, these are motion-corrected and averaged prior to N4 correction. The diagram below shows the T2w pre- processing workflow for a dataset with three T2w runs.

T2w multi preproc_t2

T2w with T1w template registration

For T2w images where template registration is failing (e.g. because the T2w images have a limited FOV), the --t1-reg-template option can be used, and will perform template registration with the T1w images, along with a within-subject registration of the T2w to the T1w, concatenating all the transforms. This is shown in the diagrams below (with a single T2w image in this case):

T2w t1-reg-template preproc_t1

T2w t1-reg-template preproc_t2

Note that these are not the only workflow configurations possible, several other variants exist by using the command-line flags. For example, if you have T1w and T2w images that are already pre-processed and co-registered (e.g. HCP processed data), then you should use the --skip-preproc and --skip-coreg options to skip N4 and T1w/T2w co-registration.

U-net segmentation

The U-net segmentation is performed on the cropped, space-corobl images, producing tissue segmentations (gray matter, SRLM, and anatomical landmarks for unfolding). This step is done in a single rule, which runs inference on the image using the corresponding nnU-net model based on the modality chosen. This is done on the R and Lflip hippocampus images, and the Lflip is subsequently unflipped.

U-net workflow

Template-based shape injection

Since the nnU-net segmentation may possibly contain topological errors that can cause issues when the Laplace-based coordinates, we perform an additional registration-based correction step, a shape injection, where we perform non-linear registration of a template hippocampus segmentation and the U-net segmentation, to warp the template shape. Regularization from the registration ensures topology from the template is preserved while it is warped to match the subject hippocampus. In addition to the segmentation, we also propagate Laplace coordinates to serve as an initialization to the next step.