Learning center

DWI tensors: acquisition, gradients and bounded fit evidence

Keep diffusion images, gradient coordinates, sampled OLS/WLS agreement and geometry-aware exports within their documented evidence scope.

Written workflow with a bounded numerical reference. Medical Image Processing diffusion_tensor keeps a diffusion-weighted image, its gradient table and its spatial geometry together. The example below uses an existing OpenNeuro receipt: the complete acquisition was loaded, while tensor accuracy was compared at 256 sampled locations. This guide reviews current controls and export contracts without repeating that analysis or claiming a new GUI recording.

1. Keep the acquisition and its companions together

The saved example is OpenNeuro ds000221, version 1.0.0, sub-010002, ses-01. Its sub-010002_ses-01_dwi.nii.gz has source dimensions 128 × 128 × 88 × 67: 1,441,792 spatial locations and 67 acquired volumes, totaling 96,600,064 values. The fourth dimension indexes acquisitions; it is not another spatial direction.

Keep the matching .bval, .bvec and .json companions with the image. B-values use s/mm². In the BIDS/FSL gradient file, three rows describe the vector components and each column corresponds to one image volume. Reordering image volumes requires the same reordering of gradient entries. Image-axis conventions and handedness matter; a gradient table from another acquisition cannot be substituted just because it has 67 columns. See the BIDS gradient orientation specification.

The current loader accepts a four-dimensional NIfTI with one volume per b-value and gradient tables in 3 × N or N × 3 form. This is an app input contract, not evidence that a complete BIDS dataset has been validated. Keep image and companion hashes, acquisition metadata and the loader receipt. The receipt’s source identity binds all four files.

2. Distinguish the preserved source from the working input

The reviewed working copy has two explicit changes. The JSON PartialFourier value changes from the string "7/8" to the number 0.875. Seven measurements have b = 5 s/mm²; with a declared low-b threshold of 50 s/mm², their working gradient vectors are zeroed. The 60 diffusion-weighted vectors are unchanged. Image and b-value files remain byte-identical to the originals.

These are documented changes for this specific input, not instructions to silently rewrite an arbitrary dataset. Preserve originals and record any working-copy changes. The guide rechecks the six small original/working companion identities and these exact differences. It relies on the existing receipt for the large image’s identity and complete decode comparison.

For this source, conversion to canonical image axes reverses the first image axis and applies the corresponding gradient transformation, diag(−1, 1, 1). The receipt separately records that an FSL handedness x-flip was not applied. Those statements describe different stages of the conversion. Do not apply this example’s matrix to every NIfTI; retain each input’s own affine, axis transformation and gradient convention.

3. Choose a limited, explicit fit

  1. Open Diffusion Tensor in MRI Analysis. Use DWI NIfTI for the image or Use launcher input for the loaded acquisition. The separate DICOM controls are outside this NIfTI example.
  2. Use CLEAR, then select the results needed for the question. For the tensor comparison discussed here, the relevant outputs are Tensor fit, FA, MD, AD, RD and Eigenvalues. b-value shells and Gradient QC expose acquisition checks. These control instructions come from current source; they are not a claim that this exact GUI selection was recorded.
  3. Set Fit explicitly. Current defaults are WLS and b0 ≤ 50 s/mm². The saved comparison covers OLS and WLS separately, not NLLS or RESTORE. Retain the method and threshold with every result.
  4. Declare any Brain mask or ROI/atlas labels separately and confirm spatial alignment. The receipt’s 256 positive-signal sample locations are not a brain mask or anatomical segmentation.
  5. Read preflight and result status before interpreting a number. Current input checks require a low-b reference and at least six weighted volumes; those counts alone do not establish adequate gradient geometry or a scientifically suitable acquisition. Missing prerequisites and unavailable routes are not zero measurements.

PREPARE / REVIEW has opt-in MP-PCA denoising, Gibbs suppression and rigid motion with b-vector rotation. They are initially off. The current interface explicitly excludes eddy-current, susceptibility, slice-to-volume and gradient-nonlinearity correction from this preparer. Changing preparation creates a different analysis input and needs its own evidence; none of those operations is certified by the saved OLS/WLS comparison.

4. Read units and sampled agreement correctly

OutputMeaning in the checked tensor calculationUnits
Tensor / eigenvaluesDiffusion tensor components / its ordered eigenvaluesmm²/s
FAFractional anisotropy derived from the eigenvaluesDimensionless
MDMean of the three eigenvaluesmm²/s
ADLargest eigenvaluemm²/s
RDMean of the other two eigenvaluesmm²/s

The independent reference sampled 256 evenly spaced indices from the ordered locations with positive signal in every acquired volume. It assembled OLS and two-pass WLS equations separately from the product’s fitting helper. Its positive-eigenvalue floor was about 1.002824 × 10−9 mm²/s; 86 eigenvalues were clipped for each method. Agreement therefore includes that declared numerical convention and does not establish that every raw fitted eigenvalue was positive.

The saved comparison uses relative tolerance 0.0002, plus absolute tolerance 0.000002 for FA or 0.00000001 for the other quantities. Across the sampled results, the largest FA absolute differences are approximately 2.55 × 10−7 for OLS and 2.57 × 10−7 for WLS. These are numerical agreement measures, not clinical error rates or uncertainty intervals.

This guide reopened 8,192 saved actual/reference value pairs across the two methods and six output groups. All retain the recorded tolerances and maximum errors. No image was decoded again and no tensor was refitted. Complete acquisition loading does not extend the 256-location numerical comparison to every voxel. No whole-volume tensor, preprocessing, segmentation, tractography, clinical or whole-app validation follows from it.

5. Preserve geometry, precision and export scope

The following is the current source-defined export contract. This guide does not add a saved native DTI export acceptance. After a tensor-dependent route finishes, the viewer can export a result bundle to an explicit existing parent directory. The analysis route Export result bundle also requires an Export folder. A unique dti_results_… directory keeps earlier bundles separate.

  • Array and geometry: bundle arrays are saved as float32 NPY with IJK spatial axes and any declared component axes. Scalar NIfTI companions are conditional on verified spatial geometry and the NIfTI writer. A selected viewer volume instead saves NPY plus a geometry/provenance JSON sidecar; read its declared axis order and the ZYX-to-IJK permutation. Do not assign anatomical axes from the array shape alone.
  • Gradients: retain exported gradients.bval and gradients.bvec with the bundle geometry. Their text formats use 10 and 12 significant digits respectively. Exported arrays use float32, so neither the arrays nor gradient text promise bit-for-bit preservation of every intermediate floating-point value.
  • Tables and figures: the bundle writes ordered tables as .table.json and result figures as PNG. Individual selected-table export is CSV. Check the manifest’s row/column counts, file hashes, shape, units and result kind against the results actually computed. A complete selected table is not a promise that every app route ran.
  • Provenance: keep manifest.json, its run receipt, input identity, loader/gradient metadata, preprocessing declaration and any mask information. Current exports retain computed_not_independently_validated and publishable_as_validated: false. Preserve those labels even when selected saved numbers agree with an independent reference.

Keep the input files and exact settings separately. A PNG cannot replace the numerical arrays or establish alignment, and this bundle description is not a claim of a reloadable scientific session. Tractograms, atlas results and advanced fits require their own inputs, routes and validation.

Worked examples describe particular inputs, methods and recorded results. Check current availability and input requirements before planning an evaluation.

← Back to the learning center