Command-line interface

HippUnfold Command-line interface

HippUnfold expects to parse all required files from all subjects in a BIDS directory. Thus a typical HippUnfold could simply be:

hippunfold /PATH/TO/YOUR/DATA /PATH/TO/OUTPUT participant --modality T1w

However, HippUnfold also has many flags that can be used to customize both the workflow and the input files being parsed. These can be seen by entering hippunfold -h into your terminal, which returns the following:

usage: hippunfold [-h] --modality {T1w,T2w,hippb500,dsegtissue}
                  [--template {CITI168,dHCP,MBMv3,CIVM,ABAv3}]
                  [--inject_template {upenn,dHCP,MBMv3,CIVM,ABAv3}]
                  [--use-template-seg]
                  [--template_seg_smoothing_factor TEMPLATE_SEG_SMOOTHING_FACTOR]
                  [--skip-preproc] [--skip_coreg]
                  [--skip_inject_template_labels]
                  [--inject-template-smoothing-factor INJECT_TEMPLATE_SMOOTHING_FACTOR]
                  [--rigid-reg-template] [--no-reg-template]
                  [--t1-reg-template] [--crop_res CROP_RES]
                  [--crop_box CROP_BOX]
                  [--resample-dsegtissue RESAMPLE_DSEGTISSUE]
                  [--laminar_coords_res_hipp LAMINAR_COORDS_RES_HIPP]
                  [--laminar-coords-res-dentate LAMINAR_COORDS_RES_DENTATE]
                  [--no-unfolded-reg] [--generate-myelin-map] [--use-gpu]
                  [--nnunet-enable-tta]
                  [--output_spaces {T1w,corobl} [{T1w,corobl} ...]]
                  [--hemi {L,R} [{L,R} ...]]
                  [--laminar_coords_method {laplace,equivol,equidist}]
                  [--autotop_labels {hipp,dentate} [{hipp,dentate} ...]]
                  [--force-nnunet-model {T1w,T2w,T1T2w,b1000,trimodal,hippb500,neonateT1w,synthseg_v0.1,synthseg_v0.2,neonateT1w_v2,neonateT2w_v2,neonateT12w_v2,ADNI_T1w_v1,neonate_synthseg}]
                  [--enable_bids_validation] [--version]
                  [--participant-label LABEL [LABEL ...]]
                  [--exclude-participant-label LABEL [LABEL ...]]
                  [--derivatives [PATH ...]] [--pybidsdb-dir PATH]
                  [--pybidsdb-reset] [--atlas ATLAS]
                  [--output-density {native,512,2k,8k,18k} [{native,512,2k,8k,18k} ...]]
                  [--new_atlas_name NEW_ATLAS_NAME]
                  [--new_atlas_subfields_from {unfoldreg,native}]
                  [--new-atlas-metrics {curvature,gyrification,thickness,myelin} [{curvature,gyrification,thickness,myelin} ...]]
                  [--filter-T2w ENTITY[:METHOD][=VALUE]
                  [ENTITY[:METHOD][=VALUE] ...]]
                  [--filter-hippb500 ENTITY[:METHOD][=VALUE]
                  [ENTITY[:METHOD][=VALUE] ...]]
                  [--filter-T1w ENTITY[:METHOD][=VALUE]
                  [ENTITY[:METHOD][=VALUE] ...]]
                  [--filter-dsegtissue ENTITY[:METHOD][=VALUE]
                  [ENTITY[:METHOD][=VALUE] ...]]
                  [--filter-dsegsubfields ENTITY[:METHOD][=VALUE]
                  [ENTITY[:METHOD][=VALUE] ...]]
                  [--wildcards-T2w WILDCARD [WILDCARD ...]]
                  [--wildcards-hippb500 WILDCARD [WILDCARD ...]]
                  [--wildcards-T1w WILDCARD [WILDCARD ...]]
                  [--wildcards-dsegtissue WILDCARD [WILDCARD ...]]
                  [--wildcards-dsegsubfields WILDCARD [WILDCARD ...]]
                  [--path-T2w PATH] [--path-hippb500 PATH] [--path-T1w PATH]
                  [--path-dsegtissue PATH] [--path-dsegsubfields PATH]
                  [--help-snakemake] [--force-output]
                  bids_dir output_dir {participant,group_create_atlas,group}

Positional Arguments

bids_dir

The directory with the input dataset formatted according to the BIDS standard.

output_dir

The directory where the output files should be stored. If you are running group level analysis this folder should be prepopulated with the results of the participant level analysis.

analysis_level

Possible choices: participant, group_create_atlas, group

Level of the analysis that will be performed.

Named Arguments

--modality

Possible choices: T1w, T2w, hippb500, dsegtissue

Type of image to run hippunfold on. For dsegtissue and be sure to match the label scheme applied in the look up table (lut) online. For best performance, please also make sure the input is approximately aligned to the template space, with separate hemi-L|R in the name(s). (default: None)

--template

Possible choices: CITI168, dHCP, MBMv3, CIVM, ABAv3

Set the template to use for registration to coronal oblique (and optionally for template-based segmentation if –use-template-seg is enabled). CITI168 is for adult human data, dHCP is for neonatal human data, MBMv3 is for marmoset data, CIVM is for in vivo macaque data, and ABAv3 is for mouse data. When using a non-human template, consider using a corresponding atlas. (default: “CITI168”)

Default: “CITI168”

--inject_template, --inject-template

Possible choices: upenn, dHCP, MBMv3, CIVM, ABAv3

Set the template to use for shape injection. (default: “upenn”)

Default: “upenn”

--use-template-seg, --use_template_seg

Use template-based segmentation for hippocampal tissue instead of nnUnet and shape injection. This is only to be used if nnUnet models are not trained for the data you are using, e.g. for non-human primate data with the MBMv3 (marmoset) or CIVM (macaque) template. (default: False)

Default: False

--template_seg_smoothing_factor, --template-seg-smoothing-factor

Scales the default smoothing sigma for gradient and warp in greedy registration for template-based segmentation. Using a value higher than 1 will use result in a smoother warp. (default: 2.0)

Default: 2.0

--skip-preproc, --skip_preproc

Set this flag if your inputs (e.g. T2w, dwi) are already pre-processed (default: False)

Default: False

--skip_coreg, --skip-coreg

Set this flag if your inputs (e.g. T2w, dwi) are already registered to T1w space (default: False)

Default: False

--skip_inject_template_labels, --skip-inject-template-labels

Set this flag to skip post-processing template injection into CNN segmentation. Note this will disable generation of DG surfaces. (default: False)

Default: False

--inject-template-smoothing-factor, --inject_template_smoothing_factor

Scales the default smoothing sigma for gradient and warp in template shape injection. Using a value higher than 1 will use result in a smoother warp, and greater capacity to patch larger holes in segmentations. Try setting to 2 if nnunet segmentations have large holes. Note: the better solution is to re-train network on the data you are using (default: 1.0)

Default: 1.0

--rigid-reg-template, --rigid_reg_template

Use rigid instead of affine for registration to template. Try this if your images are reduced FOV (default: False)

Default: False

--no-reg-template, --no_reg_template

Use if input data is already in space-CITI168 (default: False)

Default: False

--t1-reg-template, --t1_reg_template

Use T1w to register to template space, instead of the segmentation modality. Note: this was the default behavior prior to v1.0.0. (default: False)

Default: False

--crop_res, --crop-res

Sets the bounding box resolution for the crop original modality (e.g. cropT1w space). Under the hood, hippUnfold operates at higher resolution than the original image, so this tries to preserve some of that detail. (default: “0.2x0.2x0.2mm”)

Default: “0.2x0.2x0.2mm”

--crop_box, --crop-box

Sets the bounding box size for the crop original modality (e.g. cropT1w space). Make this larger if your hippocampi in crop{T1w,T2w} space are getting cut-off. This must be in voxels (vox) not millimeters (mm). (default: “256x256x256vox”)

Default: “256x256x256vox”

--resample-dsegtissue, --resample_dsegtissue

Resample the manual segmentation (for –modality dsegtissue), keeping the bounding box the same, but changing the number of voxels in the image. This can be specified as voxels (“300x300x300”), or a percentage (“20%”) or percentage in each direction (“20x20x40%”). Note: the segmentation will always be subsequently cropped around the segmentation, with a padding of 5 voxels. (default: None)

--laminar_coords_res_hipp, --laminar-coords-res-hipp

Set the resolution that the laminar (IO) coords will be computed with for hippocampus. This is implemented by resampling the segmentation to this resolution prior to generating the coords. (default: “0.3x0.3x0.3mm”)

Default: “0.3x0.3x0.3mm”

--laminar-coords-res-dentate, --laminar_coords_res_dentate

Set the resolution that the laminar (IO) coords will be computed with for the dentate gyrus. This is implemented by resampling the segmentation to this resolution prior to generating the coords. (default: “0.1x0.1x0.1mm”)

Default: “0.1x0.1x0.1mm”

--no-unfolded-reg, --no_unfolded_reg

Do not perform unfolded space (2D) registration based on surface metrics (e.g. thickness, curvature, and gyrification) for closer alignment to the reference atlas. (default: False)

Default: False

--generate-myelin-map, --generate_myelin_map

Generate myelin map using T1w divided by T2w, and map to surface with ribbon approach. Requires both T1w and T2w images to be present. (default: False)

Default: False

--use-gpu, --use_gpu

Enable gpu for inference by setting resource gpus=1 in run_inference rule (default: False)

Default: False

--nnunet-enable-tta, --nnunet_enable_tta

Enable test-time augmentation for nnU-net inference, slows down inference by 8x, but potentially increases accuracy (default: False)

Default: False

--output_spaces, --output-spaces

Possible choices: T1w, corobl

Sets output spaces for results (default: [])

Default: []

--hemi

Possible choices: L, R

Hemisphere(s) to process (default: [‘L’, ‘R’])

Default: [‘L’, ‘R’]

--laminar_coords_method, --laminar-coords-method

Possible choices: laplace, equivol, equidist

Method to use for laminar coordinates. Equivol and equidist are from the laynii LN2_LAYERS tool. (default: “equidist”)

Default: “equidist”

--autotop_labels, --autotop-labels

Possible choices: hipp, dentate

Run hipp (CA + subiculum) alone or include dentate (default: [‘hipp’, ‘dentate’])

Default: [‘hipp’, ‘dentate’]

--force-nnunet-model, --force_nnunet_model

Possible choices: T1w, T2w, T1T2w, b1000, trimodal, hippb500, neonateT1w, synthseg_v0.1, synthseg_v0.2, neonateT1w_v2, neonateT2w_v2, neonateT12w_v2, ADNI_T1w_v1, neonate_synthseg

Force nnunet model to use (expert option). (default: False)

Default: False

--enable_bids_validation, --enable-bids-validation

Enable validation of BIDS dataset. BIDS validation would be performed using the bids-validator plugin (if installed/enabled) or with the pybids validator implementation (if bids-validator is not installed/enabled).

Default: True

--version

Print the version of HippUnfold

--participant-label, --participant_label

The label(s) of the participant(s) that should be analyzed. The label corresponds to sub-<participant_label> from the BIDS sec (so it does not include “sub-“). If this parameter is not provided all subjects should be analyzed. Multiple participants can be specified with a space separated list.

--exclude-participant-label, --exclude_participant_label

The label(s) of the participant(s) that should be excluded. The label corresponds to sub-<participant_label> from the BIDS spec (so it does not include “sub-“). If this parameter is not provided all subjects should be analyzed. Multiple participants can be specified with a space separated list.

--derivatives

Path(s) to a derivatives dataset, for folder(s) that contains multiple derivatives datasets

Default: False

--pybidsdb-dir, --pybidsdb_dir

Optional path to directory of SQLite databasefile for PyBIDS. If directory is passed and folder exists, indexing is skipped. If pybidsdb_reset is called, indexing will persist

--pybidsdb-reset, --pybidsdb_reset

Reindex existing PyBIDS SQLite database

Default: False

--help-snakemake, --help_snakemake

Options to Snakemake can also be passed directly at the command-line, use this to print Snakemake usage

--force-output, --force_output

Force output in a new directory that already has contents

Default: False

ATLASES

--atlas

Select the atlas (unfolded space) to use for subfield labels. (default: “multihist7”)

Default: “multihist7”

--output-density, --output_density

Possible choices: native, 512, 2k, 8k, 18k

Sets the output vertex density for participant-level results. Note: the density refers to the number of vertices in the hipp surface; the dentate has 1/4 the number of vertices.: (default: [‘8k’])

Default: [‘8k’]

--new_atlas_name, --new-atlas-name

Name to use for the atlas created with group_create_atlas.

--new_atlas_subfields_from, --new-atlas-subfields-from

Possible choices: unfoldreg, native

Method for defining subfields for the new atlas, either ‘unfoldreg’ to use unfoldreg with existing –atlas, or ‘native’ to use native space subfield segmentations. Note: if ‘native’ subfields are selected, data from both hemispheres will be concatenated.

--new-atlas-metrics, --new_atlas_metrics

Possible choices: curvature, gyrification, thickness, myelin

Surface metrics to use when creating new atlas (default: [‘curvature’, ‘gyrification’, ‘thickness’])

Default: [‘curvature’, ‘gyrification’, ‘thickness’]

BIDS FILTERS

Update filters for input components. Each filter can be specified as a ENTITY=VALUE pair to select an value directly. To use regex filtering, ENTITY:match=REGEX or ENTITY:search=REGEX can be used for re.match() or re.search() respectively. Regex can also be used to select multiple values, e.g. ‘session:match=01|02’. ENTITY:required and ENTITY:none can be used to require or prohibit presence of an entity in selected paths, respectively. ENTITY:optional can be used to remove a filter.

--filter-T2w, --filter_T2w: (default: suffix=T2w extension=.nii.gz datatype=anat)
--filter-hippb500, --filter_hippb500: (default: suffix=b500 extension=.nii.gz datatype=dwi)
--filter-T1w, --filter_T1w: (default: suffix=T1w extension=.nii.gz datatype=anat)
--filter-dsegtissue, --filter_dsegtissue: (default: suffix=dseg extension=.nii.gz datatype=anat desc=tissue)
--filter-dsegsubfields, --filter_dsegsubfields: (default: suffix=dseg extension=.nii.gz datatype=anat desc=subfields)

INPUT WILDCARDS

Provide entities to be used as wildcards.

--wildcards-T2w, --wildcards_T2w: (default: subject session acquisition run)
--wildcards-hippb500, --wildcards_hippb500: (default: subject session)
--wildcards-T1w, --wildcards_T1w: (default: subject session acquisition run)
--wildcards-dsegtissue, --wildcards_dsegtissue: (default: subject session hemi acquisition run)
--wildcards-dsegsubfields, --wildcards_dsegsubfields: (default: subject session hemi acquisition run)

PATH OVERRIDE

Options for overriding BIDS by specifying absolute paths that include wildcards, e.g.: /path/to/my_data/{subject}/t1.nii.gz

--path-T2w, --path_T2w
--path-hippb500, --path_hippb500
--path-T1w, --path_T1w
--path-dsegtissue, --path_dsegtissue
--path-dsegsubfields, --path_dsegsubfields

Snakemake command-line interface

In addition to the above command-line arguments, Snakemake arguments are also be passed at the hippunfold command-line.

The most critical of these is the --cores or -c argument, which is a required argument for HippUnfold.

The complete list of Snakemake arguments are below, and mostly act to determine your environment and App behaviours. They will likely only need to be used for running in cloud environments or troubleshooting. These can be listed from the command-line with hippunfold --help-snakemake.