Tractography Tractography Tractography!

This update introduces tractography via DTI, DKI, and FBI ODFs to parse into MRtrix3's tckgen. Additionally, .fib files are also created for tractography through DSI Studio.

PyDesigner is now also published on PyPI for easy installation. Simple type pip install PyDesigner-DWI for easy installation. It is no longer a requirement to download this repository and manually installing PyDesigner.

Added

• Tractography modules tractography.dsistudio, tractography.odf,
  tractography.sphericalsampling
• ODF computations and spherical harmonic expansion for DTI and DKI
• Option to add user-defined map for tractography stopping criteria
• Added option to import multiple custom maps into DSI studio file
• PyDesigner can now be pulled from PyPI with pip install PyDesigner-DWI

Changed

• Fixed a logic in multi-TE detection algorithm that prevented certain
  datasets from processing
• Overhauled how inputs paths are entered. Paths to input DWIs can now
  be provided to PyDesigner without comma separation
• Udpate des2dke.m for compatibility with nii_preprocess
• Replaced FBI SH with tesseral SH

Removed

• None

New Year, New Fixes

This version removes the requirement to separate multiple inputs with a comma. Instead of parsing arguments as

pydesigner -s --rpe_pairs 1 --verbose -o [PATH TO OUTPUT] /media/sid/Secondary/Datasets/Sid_Brain/nifti/18_DKI_BIPOLAR_2mm_64dir_62slices.nii,media/sid/Secondary/Datasets/Sid_Brain/nifti/19_DKI_BIPOLAR_2mm_topup_PA.nii

users can now replace the comma delimiter with space

pydesigner -s --rpe_pairs 1 --verbose -o [PATH TO OUTPUT] /media/sid/Secondary/Datasets/Sid_Brain/nifti/18_DKI_BIPOLAR_2mm_64dir_62slices.nii media/sid/Secondary/Datasets/Sid_Brain/nifti/19_DKI_BIPOLAR_2mm_topup_PA.nii

The new processing syntax is:

pydesigner [OPTIONS] $DWI1 $DWI2 $DWI3

Logic to handle datasets with multiple echo times (multi-TE) has also been overhauled to enable processing of certain problematic datasets. Documentation has also been updated to reflect new files and flags.

• None

Changed

• Fixed a logic in multi-TE detection algorithm that prevented certain
  datasets from processing
• Overhauled how inputs paths are entered. Paths to input DWIs can now
  be provided to PyDesigner without comma separation

Removed

• None

Not a turkey but minimizes CSF contamination

This release adds overhauls Gaussian smoothing to smooth CSF and non-CSF tissue separately without propagation to minimize CSF contamination. In doing so, we aim to minimize partial volume effect bleeding into dMRI metrics.

Added:

• CSF excluded smoothing to minimize partial volume effect (PVE).
  Two methods to do this have been implemented - (1) -cf or --csf_fsl
  using FSL FAST segmentation, and (2) -cd or --csf_adc n using
  pseudo-ADC threshold of more than 2 (ADC > 2).
• Various other support functions such as mrpreproc.csfmask() and
  mrinfoutil.shells() to support CSF masking. These functions can
  also be used for other applications
• User provided brain mask is now rotated to the same orientation as
  input DWI to prevent fitting errors from incorrect masking.

Changed

• Overhaul of preprocessing.smoothing to enable NaN-smoothing
• B0 volumes are now excluded from IRLLS outlier detection to ensure
  there are some minimum volumes present in tensor fitting. This
  prevents various fitting errors.

Removed

• None

Scenic Train through Echo Mountains

This release adds multi TE support for datasets composed of multiple TEs. Concatenated DWI is now preprocessed together, but the tensor fitting regime extracts metric maps for each TE separately. Multi TE support primes PyDesigner for triple diffusion encoding (TDE) datasets.

FBI and FBWM has also been overhauled to make calculations more stable. In some rare instances, rectification of FBI fODFs can degrade them instead. This is particularly true for excellent FBI acquisitions and requires that rectification be disabled with --no_rectify flag.

Thresholds have also been updated to more accurately classify datasets into DTI, DKI or FBI.

Added:

• Support for multi echo time (TE) datasets. PyDesigner will now
  preprocess DWIs with multiple TEs together, but extract diffusion
  metrics for each TE separately. Users need to parse -te
  flag to enable this feature.
• Added dwiextract function to mrpreproc.py to allow
  splitting of .mif files.
• Added function fit_regime to dwipy.py to automatically run
  all tensor fitting steps in an appropriate manner.
• Added highprecisionpower to dwipy.py to mitigate integer
  overflow error when performing FBI fODF calculation.
• Flag --no_rectify to disable rectification of FBI fODFs. In
  some cases where FBI acquistion is excellent, rectification can
  degrade fODFs instead. This flag is intended to disable
  rectification of such datasets.

Changed

• Maximum DKI b-value threshold has been raised to 3,000 mm/s^2,
  thereby enabling DKI support for researchers using b-values higher
  than 2,000 mm/s^2 but less than 3,000 mm/s^2.
• IRLLS now also includes B0 volumes when evaluating goodness-of-fit
  to make outlier detection more robust and accurate.
• Various stability patches for FBI and FBWM to ensure error-free
  extraction of FBI/FBWM metrics.

Removed

• None

Stability Patch for Eddy Current Correction

Fixes a bug when unditortion would halt when non-integer b-values are present in datasets.

Mar 16, 2021

Added:

• None

Changed

• B-values are first rounded to a float insted of integer directly to
  prevent errors in preprocessing

Removed

• None

Rician Please

Rician correction was missing from -s, --standard preprocessing for some reason, this update fixes that.

Added:

• Added missing Rician preprocessing to -s, --standard
  preprocessing

Changed

• Potential sources of errors in FBWM have been mitigated
  with error-handling

Removed

• None

DKI and WMTI Fixes

This release fixes issues where radial kurtosis maps is identical to axial kurtosis due to a missing AKC calculation. WMTI metrics have also been updated to match those from DKE.

Added:

• Missing AKC calculation for radial kurtosis to fix RK being a duplicate of AK. This fixes the issue of dki_ak.nii and dki_rk.nii being the same, for real this time.
• Missing Docker figures in RTD documentation

Changed

• Added error mitigation when FBI cost function fails to converge to
  a minimum cost
• Updated WMTI calculation to follow DKE outputs

Removed

• WMTI flags, since they are now standard outputs
• Unnecessary WMTI calculations

Eddy correction fixes for high b-value shelled datasets

Added:

• None

Changed

• Replaced preprocessing.util.bvec_is_fullsphere() and
  preprocessing.util.vecs_are_fullsphere() with
  preprocessing.mrinfoutil.is_fullsphere(). Even though datasets
  may be half-shelled, it is inaccurate to label them as such because
  distortion relative to b-value is not linear. As such, the
  slm=linear makes no sense. This new method performs the proper
  checks required before labelling a DWI as fully-shelled. A DWI is
  half-shelled iff max B-value is less than 3000 AND the norm of the
  mean direction vector is more than 0.3.

Removed

• See above

FBI Fiber Tracking

This release adds FBI fiber tracking via DSI Studio. After computing FBI parameters, an fbi_tractography_dsi.fib file is also created. This new file can be loaded into DSI Studio to perform fiber tracking.

Added:

• Check for b-value scaling in .bval file so values
  specified as either 2.0 or 2000 can be processed.
• fitting.dwipy() can now be pointed to user-defined
  bvec and bval paths. It previously required bvec and
  bval files to have the same name and path as DWI.
• DSI Studio tractography for FBI. Processing FBI dataset now
  produces an fbi_tractography_dsi.fib file that can be loaded
  into DSI Studio to perform tractography.

Changed:

• Fixed issue where eddy correction would attempt
  to QC and fail despite parsing the --noqc flag.
• SNR plotting works in very specific scenarious when
  input DWIs are of the same same dimensions. A try/except
  loop now ensure that the entire pipeline doesn't halt
  due to errors in plotting.
• Fixed issue with dki_ak.nii not being saved

Removed:

• None

PyDesigner v1.0-RC4

Bugfix for DTI protocols

Added:

• Reslicing compatibility udpated for new MRTrix3 version
  where mrrelice has been changed to mrgrid.
  PyDesigner will work with either versions.

Changed:

• Fixed a bad indent in tensor reordering function
  that produced an error in DTI protocols.

Removed:

• None