# 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)

- `--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.