Output Files

The PATH_TO_OUTPUT_DIR folder contains a logs and config folder for troubleshooting, but for most purposes all the outputs of interest will be in subje t folders with the following structure:

sub-1425/
├── anat
├── surf
├── metric
├── cifti
└── qc

Briefly, anat contains preprocessed volumetric input images and output segmentations in nifti format, surf contains surface meshes in gifti format along with aggregate spec files, metric contains scalar metrics and labels in gifti format, cifti contains metrics aggregated over hemispheres, 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-multihist7_dseg.nii.gz
     ├── sub-001_hemi-R_space-cropT1w_desc-preproc_T2w.nii.gz
     ├── sub-001_hemi-R_space-cropT1w_desc-subfields_atlas-multihist7_dseg.nii.gz
     └── sub-001_space-cropT1w_desc-subfields_atlas-multihist7_volumes.tsv

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 space-corobl which is cropped, upsampled, and rotated (available with --output-space corobl. 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 anatomical space (space=T1w, space=corobl) and the unfolded space (space-unfold). 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,unfold,corobl}_den-8k_{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 number of vertices in the hippocampus surface. The default density is 8k, which has an approximate vertex spacing of 0.5mm. Note that the dentate surface always has 1/4 the number of vertices, e.g. the dentate 8k surface actually has 2k vertices.

There are also 2k and 512 surfaces which have 1mm or 2mm spacing, respectively (suitable for lower-resolution BOLD data).

All surfaces of the same density (e.g. 8k), in both space-T1w and space-unfold, 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 anatomical space=T1w,corobl surfaces).

label-dentate

HippUnfold v1.0.0 introduced label-dentate files which represent a distinct surface making up the dentate gyrus (reflecting its distinct topology from the rest of the cortex).

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

spec files

These files, along with the below metric and cifti files are packaged together for easy viewing in Connectome Workbench, wb_view, in a density-specific .spec file:

TODO: should remove space-T1w from spec file (isn’t needed).. sub-{subject} └── surf └── sub-001_space-T1w_den-0p5mm_surfaces.spec

metrics

shape 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 methods analogous to those used for cortical surfaces, based on the surface geometry files, and are applicable to surfaces of the same density in any space. The gyrification metric is the ratio of native to unfolded surface area, or equivalently, the scaling or distortion factor when unfolding:

sub-{subject}
 └── metric
     └── sub-001_hemi-{L,R}_den-8k_label-hipp_{thickness,curvature,gyrification}.shape.gii
     └── sub-001_hemi-{L,R}_den-8k_label-dentate_{curvature,gyrification}.shape.gii

These metrics are shown in both anatomical 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.

**TODO: update this image to show an individual example?

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

TODO add surf-based coords to the spec/target rules

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 metrics suffixed with coords.shape.gii 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.

TODO: update to show surface coords

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: multihist7) is in the file name.

sub-{subject}
 └── surf
     └── sub-001_hemi-{L,R}_den-8k_label-hipp_atlas-multihist7_subfields.label.gii

cifti

In addition to lateralized .shape.gii and .label.gii metrics and labels, we also provide data mapped from hemispheres in a single file using the corresponding CIFTI formats, .dscalar.nii and .dlabel.nii.

sub-{subject}
 └── surf
     ├── sub-001_den-8k_label-{hipp,dentate}_{thickness,curvature,gyrification}.dscalar.nii
     └── sub-001_den-0p5mm_label-hipp_atlas-multihist7_subfields.dlabel.nii

TODO update this figure

Additional Files

The top-level PATH_TO_OUTPUT_DIR contains additional folders:

├── logs
├── config
└── .snakemake

The config folder contains the parameters as translated from the command-line interface, and passed along to the snakemake workflow by snakebids.

The hidden .snakemake folder is created by snakemake, and 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 folders based on the rule name, and file names based on the wildcards (e.g. subject, hemi, etc..).