dipy_fit_force

Synopsis

Workflow for FORCE microstructure reconstruction.

Performs FORCE (FORward modeling for Complex microstructure Estimation) reconstruction [1] on the files by ‘globing’ input_files and saves the FORCE metrics in a directory specified by out_dir.

Usage

dipy_fit_force [OPTIONS] input_files bvalues_files bvectors_files mask_files

Input Parameters

• input_files

  Path to the input volumes. This path may contain wildcards to process multiple inputs at once.

• bvalues_files

  Path to the bvalues files. This path may contain wildcards to use multiple bvalues files at once.

• bvectors_files

  Path to the bvectors files. This path may contain wildcards to use multiple bvectors files at once.

• mask_files

  Path to the input masks. This path may contain wildcards to use multiple masks at once.

General Options

• --b0_threshold

  Threshold used to find b0 volumes. (default: 50)

• --bvecs_tol

  Threshold used to check that norm(bvec) = 1 +/- bvecs_tol. (default: 0.01)

• --penalty

  Penalty weight for fiber complexity in the FORCE model. (default: 1e-05)

• --n_neighbors

  Number of neighbors for signal matching. (default: 50)

• --use_exact

  Use best match instead of posterior averaging. (default: False)

• --posterior_beta

  Softmax temperature for posterior averaging. (default: 2000.0)

• --compute_odf

  Compute posterior ODF maps. (default: False)

• --num_simulations

  Number of simulated voxels for the simulation library. (default: 500000)

• --wm_threshold

  Minimum white-matter signal fraction for a simulated voxel to be assigned fiber-orientation labels when building the library. (default: 0.5)

• --tortuosity

  Constrain the white-matter perpendicular diffusivity through the tortuosity model instead of sampling wm_d_perp_range independently. (default: False)

• --odi_range

  Two values min max giving the orientation-dispersion-index prior range sampled when building the simulation library. If not set, the FORCE default 0.01 0.3 is used. (default: None)

• --num_odi_values

  Number of points in the ODI sampling grid. If not set, the grid is autoscaled from odi_range so its sampling density matches the default grid (10 points across 0.01 0.3). (default: None)

• --wm_d_par_range

  Two values min max (in mm^2/s) for the white-matter parallel (axial) diffusivity prior. If not set, defaults to 0.002 0.003. (default: None)

• --wm_d_perp_range

  Two values min max (in mm^2/s) for the white-matter perpendicular (radial) diffusivity prior. Ignored when tortuosity is set. If not set, defaults to 0.0003 0.0015. (default: None)

• --gm_d_iso_range

  Two values min max (in mm^2/s) for the gray-matter isotropic diffusivity prior. If not set, defaults to 0.0007 0.0012. (default: None)

• --csf_d

  Fixed CSF isotropic diffusivity in mm^2/s. If not set, defaults to 0.003. (default: None)

• --num_cpus

  Number of CPU cores for simulation generation. Use -1 to use all available cores. (default: -1)

• --use_cache

  Load cached simulations if available. (default: True)

• --compute_kurtosis

  Compute kurtosis metrics (mk, ak, rk, kfa) during simulation. (default: False)

• --engine

  Parallel engine for fitting: “ray” or “serial”. If “ray” is requested but not installed, falls back to “serial” with a warning. (default: serial)

• --save_metrics

  List of metrics to save. Possible values: fa, md, rd, wm_fraction, gm_fraction, csf_fraction, num_fibers, dispersion, nd, ufa, uncertainty, ambiguity, mk, ak, rk, kfa, entropy, predicted_signal. If not set, all available metrics are saved. (default: None)

• --verbose

  Whether to print verbose messages during processing. (default: False)

Output Options

• --out_dir

  Output directory. (default: current directory)

• --out_fa

  Name of the fractional anisotropy volume to be saved. (default: fa.nii.gz)

• --out_md

  Name of the mean diffusivity volume to be saved. (default: md.nii.gz)

• --out_rd

  Name of the radial diffusivity volume to be saved. (default: rd.nii.gz)

• --out_wm_fraction

  Name of the white matter fraction volume to be saved. (default: wm_fraction.nii.gz)

• --out_gm_fraction

  Name of the gray matter fraction volume to be saved. (default: gm_fraction.nii.gz)

• --out_csf_fraction

  Name of the CSF fraction volume to be saved. (default: csf_fraction.nii.gz)

• --out_num_fibers

  Name of the number of fibers volume to be saved. (default: num_fibers.nii.gz)

• --out_dispersion

  Name of the orientation dispersion volume to be saved. (default: dispersion.nii.gz)

• --out_nd

  Name of the neurite density volume to be saved. (default: nd.nii.gz)

• --out_ufa

  Name of the micro-FA volume to be saved. (default: ufa.nii.gz)

• --out_uncertainty

  Name of the uncertainty volume to be saved. (default: uncertainty.nii.gz)

• --out_ambiguity

  Name of the ambiguity volume to be saved. (default: ambiguity.nii.gz)

• --out_mk

  Name of the mean kurtosis volume to be saved (requires compute_kurtosis). (default: mk.nii.gz)

• --out_ak

  Name of the axial kurtosis volume to be saved (requires compute_kurtosis). (default: ak.nii.gz)

• --out_rk

  Name of the radial kurtosis volume to be saved (requires compute_kurtosis). (default: rk.nii.gz)

• --out_kfa

  Name of the kurtosis FA volume to be saved (requires compute_kurtosis). (default: kfa.nii.gz)

• --out_entropy

  Name of the entropy volume to be saved (requires use_posterior). (default: entropy.nii.gz)

• --out_predicted_signal

  Name of the predicted signal volume to be saved. (default: predicted_signal.nii.gz)

• --out_peaks

  Name of the peaks file to be saved (in .pam5 format). (default: peaks.pam5)

• --out_micro_uncertainty_dir

  Name of the subdirectory for per-microstructure uncertainty maps (weighted IQR of posterior density, normalized by prior range). Maps saved: fa, md, rd, wm_fraction, gm_fraction, csf_fraction, num_fibers, dispersion, nd, ufa, mk, ak, rk, kfa. (default: microstructure_uncertainty)

• --out_micro_ambiguity_dir

  Name of the subdirectory for per-microstructure ambiguity maps (FWHM of posterior density, normalized by prior range). Maps saved: fa, md, rd, wm_fraction, gm_fraction, csf_fraction, num_fibers, dispersion, nd, ufa, mk, ak, rk, kfa. (default: microstructure_ambiguity)

References

[1]

Atharva Jaydeep Shah, Rafael Neto Henriques, Alonso Ramirez-Manzanares, Patryk Filipiak, Steven Baete, Kaustav Deka, Maharshi Gor, Serge Koudoro, and Eleftherios Garyfallidis. FORCE: FORward modeling for Complex microstructure Estimation. Research Square (Preprint), 2025. Under review at Nature Portfolio. URL: https://www.researchsquare.com/article/rs-8151109/v1, doi:10.21203/rs.3.rs-8151109/v1.

Garyfallidis, E., M. Brett, B. Amirbekian, A. Rokem, S. Van Der Walt, M. Descoteaux, and I. Nimmo-Smith. Dipy, a library for the analysis of diffusion MRI data. Frontiers in Neuroinformatics, 1-18, 2014.