Running NiFreeze

Command line interface

A model-based algorithm for the realignment of 4D brain images.

usage: nifreeze [-h] [--brainmask BRAINMASK] [--align-config ALIGN_CONFIG]
                [--models MODELS [MODELS ...]] [--gp-hyperparameters FILE]
                [--nvox-prefit NVOX_PREFIT] [--nthreads NTHREADS] [-J N_JOBS]
                [--seed SEED] [--output-dir OUTPUT_DIR] [--write-hdf5]
                [--debug-dir DEBUG_DIR] [--no-instant-update]
                [--gradient-file FILE [FILE ...]] [--b0-file FILE]
                [--ignore-b0] [--timing-file FILE]
                input_file

Positional Arguments

input_file

Path to the HDF5 file containing the original 4D data.

Named Arguments

--brainmask

Path to a brain mask in NIfTI format.

--align-config

Path to the yaml file containing the parameters to configure the image registration process, at every level of the cascade: ‘ants_config’ names a configuration of nifreeze/registration/config, and the other keys override its settings.

--models

Select the data model(s) used to generate registration targets; multiple models run as a cascade. By default each model runs in Leave-One-Volume-Out mode (refit per held-out volume). Prefix a model name with ‘single’ (e.g. ‘singledti’) to run it in single-fit mode: fit once on all volumes and reuse that locked fit (still predicting per volume from it). Single-fit is faster but leaks the queried volume into its own target (biasing motion toward zero); use it for development, testing, or coarse initialization only, not for accuracy-critical estimation. The closed-form LOVO models (‘gp-loo’, ‘gqi-krr’) predict every held-out volume exactly from one matrix, so the ‘single’ prefix makes no difference for them.

--gp-hyperparameters

JSON file with Gaussian process hyperparameters for the ‘gp-loo’ model (e.g., pooled across the subjects of an acquisition protocol). When given, no hyperparameter is fitted at run time.

--nvox-prefit

Number of random voxels used to fit the hyperparameters of the Gaussian process models (‘gp’, ‘gp-loo’).

--nthreads, --omp-nthreads, --ncpus

Maximum number of threads an individual process may use.

-J, --n-jobs, --njobs

Number of parallel jobs.

--seed

Seed the random number generator for deterministic estimation.

--output-dir

Path to the output directory. Defaults to the current directory.The output file will have the same name as the input file.

--write-hdf5

Generate an HDF5 file also.

--debug-dir

Keep the registration working files of each model in a folder of this directory, with an ‘aligned_<index>.nii’ image per volume: the registered volume with its affine corrected by the estimated motion (no resampling), which a viewer shows on top of its target ‘predicted_<index>.nii’.

--no-instant-update

Train the models on the original volumes only. By default, as soon as a volume is registered, the models see it realigned (resampled once from the original, with its rotated b-vector) when predicting the remaining volumes.

Options for dMRI inputs

--gradient-file

A gradient file containing b-vectors and b-values

--b0-file

A NIfTI file containing the b-zero reference

--ignore-b0

Ignore the low-b reference and use the robust signal maximum

Options for PET inputs

--timing-file

A NIfTI file containing the timing information (onsets and durations) corresponding to the input file