Output Files

The PATH_TO_OUTPUT_DIR folder contains a logs and work folder for troubleshooting, but for most purposes all the outputs of interest will be in a subfolder called hippunfold with the following structure:

hippunfold/
└── sub-{subject}
    ├── anat
    ├── coords
    ├── qc
    ├── surf
    └── warps

Briefly, anat contains preprocessed volumetric input images and output segmentations in nifti format, surf contains surface data in gifti format, coords contain Laplace fields spanning the hippocampus, warps contains transformations between unfolded and native or 'unfolded' space, and qc contains snapshots and useful diagnostic information for quality control.

anat

This folder contains input anatomical images that have been non-uniformity corrected,
motion-corrected, and, where appropriate, averaged and registered.
In this example, a T1w image was used as a standard reference image, but a T2w was also registered and used in tissue segemntation:

sub-001
 └── anat
     ├── sub-001_desc-preproc_T1w.nii.gz
     ├── sub-001_space-T1w_desc-preproc_T2w.nii.gz
     ├── sub-001_hemi-R_space-T1w_desc-subfields_atlas-bigbrain_dseg.nii.gz
     ├── sub-001_hemi-R_space-cropT1w_desc-preproc_T2w.nii.gz
     └── sub-001_hemi-R_space-cropT1w_desc-subfields_atlas-bigbrain_dseg.nii.gz

As per BIDS guidelines, desc-preproc refers to preprocessed input images, space-T1w refers to the volume to which the image is registered, hemi refers to the left or right hemisphere (only shown for the right in this example), and dseg (discrete-segmentation) images with desc-subfields contains subfield labels (coded as integers as described in the included volumes.tsv file). The subfield atlas used will also be included, by default as atlas-bigbrain. Note that HippUnfold does most intermediate processing in an unshown (available in the work/ folder) space-corobl which is cropped, upsampled, and rotated. Downsampling to the original T1w space can thus degrade the results and so they are also provided in a higher resolution space-cropT1w space which is ideal for conducting volumetry or morphometry measures with high precision and detail.

For example, the following image shows a whole-brain T1w image, a
space-cropT1w overlay of the upsampled T2w image (centre square), and a similarly upsampled output
subfield segmentation (colour).

surf

surface meshes

Surface meshes (geometry files) are in .surf.gii format, and are
provided in both the native space (space-T1w) and the unfolded space
(space-unfolded). In each space, there are inner, midthickness,
and outer surfaces, which correspond to white, midthickness, and
pial for cortical surfaces:

sub-{subject}
 └── surf
     └── sub-001_hemi-R_space-{T1w,unfolded}_den-0p5mm_{inner,midthickness,outer}.surf.gii

The following shows surfaces inner, midthickness, and outer in
yellow, orange, and red, respectively.

surface densities

Surfaces are provided in different density configurations, and are
labelled based on the approximate vertex spacing in each. The default
density is 0p5mm, which has an approximate vertex spacing of 0.5mm. There are also
1mm and 2mm surfaces which have 1mm or 2mm spacing, respectively (suitable for
lower-resolution BOLD data). Previous versions of hippunfold exclusively
used a unfoldiso template surface, formed by a 254x126 grid in
the unfolded space, however a downside of this template is that it
results in very non-uniform vertex spacing when transformed to the
native space. The newer 0p5mm,
1mm and 2mm surfaces are designed to have
closer to uniform vertex spacing in native space, though vertex spacing will not remain uniform when unfolded.
This is illustrated in the the following den-1mm mesh in folded and
unfolded space.

All surfaces of the same density (e.g. 1mm), in both
space-T1w and space-unfolded, share the same mesh topology and have
corresponding vertices with each other. The vertex locations for
unfolded surfaces are identical for all subjects as well (note that this
of course is not the case for the space-T1w surfaces).

surface metrics

In addition to the geometry files, surface-based shape metrics are
provided in .shape.gii format. The thickness, curvature and surface
area are computed using the same methods as cortical surfaces, based on
the surface geometry files, and are provided in the T1w space. The
gyrification metric is the ratio of native to unfolded surface area, or
equivalently, the scaling or distortion factor when unfolding:

sub-{subject}
 └── surf
     └── sub-001_hemi-{L,R}_space-T1w_den-0p5mm_label-hipp_{thickness,curvature,gyrification}.shape.gii
     └── sub-001_hemi-{L,R}_space-T1w_den-0p5mm_label-dentate_{curvature,gyrification}.shape.gii

These metrics are shown in both folded and unfolded space in the images
below. Note that these results are from group-averaged data and so
individual subject maps may show considerably more variability.

surface labels

The subfield labels from unfolded atlases are also provided for each
subject, in .label.gii format. Analogous to the volume-based labels,
the name of the atlas (default: bigbrain) is in the file name.

sub-{subject}
 └── surf
     └── sub-001_hemi-{L,R}_space-T1w_den-0p5mm_label-hipp_atlas-bigbrain_subfields.label.gii

cifti files

In addition to lateralized .shape.gii and .label.gii metrics and labels,
we also provide data mapped to hippocampi from hemispheres in a single
file using the corresponding CIFTI formats, .dscalar.nii and .dlabel.nii.
Note: since CIFTI does not support hippocampus
surfaces (yet), we make use of the CORTEX_LEFT and CORTEX_RIGHT labels for
the hippocampal surfaces.

sub-{subject}
 └── surf
     ├── sub-001_space-T1w_den-0p5mm_label-{hipp,dentate}_{thickness,curvature,gyrification}.dscalar.nii
     └── sub-001_space-T1w_den-0p5mm_label-hipp_atlas-bigbrain_subfields.dlabel.nii

spec files

Finally, these files are packaged together for easy viewing in
Connectome Workbench, wb_view, in the following .spec files, for
each hemisphere and structure separately, and combined:

sub-{subject}
 └── surf
     ├── sub-001_hemi-{L,R}_space-T1w_den-0p5mm_label-{hipp,dentate}_surfaces.spec
     └── sub-001_space-T1w_den-0p5mm_label-{hipp,dentate}_surfaces.spec

New: label-dentate

HippUnfold v1.0.0 introduces label-dentate files which represent a distinct surface making up the dentate gyrus (reflecting its distinct topology from the rest of the cortex). The rest of the surfaces are given the name label-hipp to differentiate them from these new files.

These are illustrated in the following image (orange represents the usual hippocampal midthickness surface, while violet shows the new dentate surface):

Note that the dentate uses the same unfolding methods as the rest of the hippocampus, but with several caveats. Given its small size, its boundaries are not easily deliminated and so inner, outer, and thickness gifti surfaces are omitted. Furthermore, Laplace coordinates and therefore vertex spacing are not guaranteed to be topologically equivalent as they are obtained through volumetric registration with the template shape injection step of this workflow.

Corresponding coords and warp files are also generated.

New: myelin maps

If your dataset has T1w and T2w images (and you are using --modality=T1w or --modality=T2w), then you can enable the generation of myelin maps as the ratio of T1w over T2w images. This division is done in the corobl space, and provides myelin.shape.gii surface metrics, and also includes these in the CIFTI and spec files.

This option is enabled with the --generate-myelin-maps command-line option.

coords

Hippunfold also provides images that represent anatomical gradients
along the 3 principal axes of the hippocampus, longitudinal from
anterior to posterior, lamellar from proximal (dentate gyrus) to distal
(subiculum), and laminar from inner (SRLM) to outer. These are provided
in the images suffixed with coords.nii.gz with the direction indicated
by dir-{direction} as AP, PD or IO, and intensities from 0 to 1,
e.g. 0 representing the Anterior end and 1 the Posterior end.

Here is an example showing coronal slices of the hippocampus with the
PD, IO, and AP (sagittal slice) overlaid.

Note that these images have been resampled to space-corobl which is
the space in which most processing is done internally. These can be seen
in the work/ output directory or specified as a possible output space.

warps

ITK transforms to warp images between the T1w space to the unfolded
space, are provided for each hippocampus:

sub-{subject}
 └── seg
     └── sub-001_hemi-R_from-T1w_to-unfold_mode-image_xfm.nii.gz
     └── sub-001_hemi-R_from-unfold_to-T1w_mode-image_xfm.nii.gz

These are ITK transforms that can transform any image that is in T1w
space (can be any resolution and FOV, as long as aligned to T1w), to
the unfolded hippocampal volume space, and vice-versa. You can use the
warp itself as a reference image, e.g.:

antsApplyTransforms -d 3 \
-i sub-001_space-T1w_FA.nii.gz \
-o sub-001_hemi-L_space-unfolded_FA.nii.gz \
-t sub-001_hemi-L_from-T1w_to-unfold_mode-image_xfm.nii.gz \
-r sub-001_space-unfolded_refvol.nii.gz

Additional Files

The top-level PATH_TO_OUTPUT_DIR contains additional folders:

├── hippunfold
├── logs
├── work
└── .snakemake

The hidden .snakemake folder contains a record of the code and parameters used,
and paths to the inputs.

Workflow steps that write logs to file are stored in the logs
subfolder, with file names based on the rule wildcards (e.g. subject,
hemi, etc..).

Intermediate files are stored in the work folder. These files and
folders, similar to results, are generally named according to BIDS. This
folder will have tar.gz files for each subject, unless the
--keep_work option is used.

If the app is run in workflow mode
(--workflow-mode/-W) which enables direct
use of the snakemake CLI to run hippunfold, the
hippunfold and work folders will be placed
in a results folder.