Apply CLEARSWI in the command line without Julia programming experience. This repository contains the CLEARSWI algorithm and a command line interface.

Susceptibility Weighted Imaging (CLEAR-SWI)

Published as CLEAR-SWI. It provides magnetic resonance images with improved vein and iron contrast by weighting a combined magnitude image with a preprocessed phase image. This package has the additional capability of multi-echo SWI, intensity correction, contrast enhancement and improved phase processing. The reason for the development of this package was to solve artefacts at ultra-high field strength (7T), however, it also drastically improves the SWI quality at lower field strength.

Option 1: Download standalone executables

https://github.com/korbinian90/CompileMRI.jl/releases
This package contains binaries with dependencies.
For usage help, run the command line program in bin/clearswi without arguments or see below.

Option 2: Usage - command line via Julia

This option works on every system

1. Install the newest Julia version from the Official Julia Webpage
2. Download the file clearswi.jl from this repository and save in a convenient location
3. (optional) An alias for clearswi as julia <path-to-file>/clearswi.jl might be useful

    $ julia <path-to-file>/clearswi.jl -p phase.nii -m mag.nii -t [2.1,4.2,6.3] -o results

On the first run, the dependencies will be installed automatically. For an extended explanation of the command line interface see below.

Option 3: Usage - Julia

Prerequisites

A Julia installation ≥ 1.7 (Official Julia Webpage)

Single-echo or multi-echo Magnitude and Phase images in NIfTI fileformat (4D images with echoes in the 4th dimension)

Installing

Run the following commands in Julia (either interactively in the REPL or as a script)

import Pkg; Pkg.add("CLEARSWI")

Function Reference

https://korbinian90.github.io/CLEARSWI.jl/dev

Usage

This is a simple multi-echo case without changing default behavior

using CLEARSWI

TEs = [4,8,12] # change this to the Echo Time of your sequence. For multi-echoes, set a list of TE values, else set a list with a single TE value.
nifti_folder = CLEARSWI.dir("test","data","small") # replace with path to your folder e.g. nifti_folder="/data/clearswi"
magfile = joinpath(nifti_folder, "Mag.nii") # Path to the magnitude image in nifti format, must be .nii or .hdr
phasefile = joinpath(nifti_folder, "Phase.nii") # Path to the phase image

mag = readmag(magfile);
phase = readphase(phasefile; fix_ge=true); # use `fix_ge=true` only for GE data with corrupted phase
data = Data(mag, phase, mag.header, TEs);

swi = calculateSWI(data);
# mip = createIntensityProjection(swi, minimum); # minimum intensity projection, other Julia functions can be used instead of minimum
mip = createMIP(swi); # shorthand for createIntensityProjection(swi, minimum)

savenii(swi, "<outputpath>/swi.nii"; header=mag.header) # change <outputpath> with the path where you want to save the reconstructed SWI
savenii(mip, "<outputpath>/mip.nii"; header=mag.header)

Available Options

To apply custom options use the following keyword syntax (example to apply 3D high-pass filtering for the phase with the given kernel size and deactivate softplus magnitude scaling):

options = Options(phase_hp_sigma=[10,10,5], mag_softplus=false)
swi = calculateSWI(data, options);

All the possible options with the default values are

mag_combine=:SNR
mag_sens=nothing
mag_softplus=true
phase_unwrap=:laplacian
phase_hp_sigma=[4,4,0]
phase_scaling_type=:tanh
phase_scaling_strength=4
writesteps=nothing
qsm=false

• mag_combine selects the echo combination for the magnitude. Options are

  • :SNR
  • :average
  • :last to select the last echo
  • (:CNR => (:gm, :wm)) to optimize the contrast between two selected tissues with the possible tissues classes to select in src\tissue.jl, currently only working for 7T
  • (:echo => 3) to select the 3rd echo
  • (:closest => 15.3) to select the echo that is closest to 15.3 ms
  • (:SE => 15.3) to simulate the contrast that would be achieved using a corresponding single-echo scan with 15.3 ms echo time.

• If mag_sens is set to an array, it is used instead of CLEAR-SWI sensitivity estimation. This can also be set to mag_sens=[1] to use the constant sensitivity of 1 and effectively avoid sensitivity correction. To change the sigma_mm value of the expected bias field size, set it to i.e. mag_sens=(:sigma_mm => 7). The default is 7mm.

• To deactivate scaling of the combined magnitude with the softplus function, use mag_softplus=false.

• phase_unwrap is either :laplacian, :romeo, or :laplacianslice (slicewise laplacian unwrapping)

• The phase_hp_sigma is used for high-pass filtering and is given in voxel for the [x,y,z]-dimension.

• phase_scaling_type is the scaling function to create the phase mask and can be :tanh or :negativetanh for sigmoidal filtering, or :positive, :negative, and :triangular for traditional SWI application.

• phase_scaling_strength adjusts the strength of the created phase mask. A higher phase_scaling_strength is a stronger phase appearance. With a traditional SWI phase_scaling_type it corresponds to the power or number of phase mask multiplications.

• Set writesteps to the path, where intermediate steps should be saved, e.g. writesteps="/tmp/clearswi_steps". If set to nothing, intermediate steps won't be saved.

• [Experimental] Set qsm to true to use QSM processing for the phase contrast. This requires the additional use of a QSM package. Supported are either QSM or QuantitativeSusceptibilityMappingTGV. Before setting this option, you need load one of these packages with using.

• [Experimental] Set qsm to :input and use a pre-calculated QSM instead of a phase input. This needs additional fine-tuning. Since most large fluctuations are removed in QSM, the filtering should be set to a larger kernel (e.g. phase_hp_sigma=[20,20,0]) and the strength might need to be adjusted to something in the range of phase_scaling_strength=0.04.

Calculating T2* and B0 maps on multi-echo datasets

T2* and B0 maps can be calculated using the package MriResearchTools:

Installing

B0 and R2*/T2* calculation requires the package MriResearchTools

using Pkg
Pkg.add("MriResearchTools")

Usage

With the previously defined variables phase, mag and TEs

using MriResearchTools

unwrapped = romeo(phase; mag=mag, TEs=TEs) # type ?romeo in REPL for options
B0 = calculateB0_unwrapped(unwrapped, mag, TEs) # inverse variance weighted

t2s = NumART2star(mag, TEs)
r2s = r2s_from_t2s(t2s)

Command Line Help

$ .\bin\clearswi
usage: clearswi.jl [-m MAGNITUDE] [-p PHASE] [-o OUTPUT]
                   [-t ECHO-TIMES [ECHO-TIMES...]] [-s MIP-SLICES]
                   [--qsm] [--qsm-input QSM-INPUT] [--qsm-mask QSM-MASK]
                   [--mag-combine MAG-COMBINE [MAG-COMBINE...]]
                   [--mag-sensitivity-correction MAG-SENSITIVITY-CORRECTION]
                   [--mag-softplus-scaling MAG-SOFTPLUS-SCALING]
                   [--unwrapping-algorithm UNWRAPPING-ALGORITHM]
                   [--filter-size FILTER-SIZE [FILTER-SIZE...]]
                   [--phase-scaling-type PHASE-SCALING-TYPE]
                   [--phase-scaling-strength PHASE-SCALING-STRENGTH]
                   [-e ECHOES [ECHOES...]] [-N] [--no-phase-rescale]
                   [--fix-ge-phase] [--writesteps WRITESTEPS] [-v]
                   [--version] [-h]

1.6.0

optional arguments:
  -m, --magnitude MAGNITUDE
                        The magnitude image (single or multi-echo)
  -p, --phase PHASE     The phase image (single or multi-echo)
  -o, --output OUTPUT   The output path or filename (default:
                        "clearswi.nii")
  -t, --echo-times ECHO-TIMES [ECHO-TIMES...]
                        The echo times are required for multi-echo
                        datasets specified in array or range syntax
                        (eg. "[1.5,3.0]" or "3.5:3.5:14").
  -s, --mip-slices MIP-SLICES
                        The number of slices in the MIP image
                        (default: "7")
  --qsm                 When activated uses TGV QSM for phase
                        weighting.
  --qsm-input QSM-INPUT
                        Give pre-calculated QSM instead of phase as
                        input. Not fine-tuned! Please adjust phase
                        filter to something like: "--filter-size
                        [20,20,0] --phase-phase_scaling_strength 0.04"
  --qsm-mask QSM-MASK   The mask used for QSM. Use a custom mask, if
                        the qsm_mask.nii is not good for your data.
  --mag-combine MAG-COMBINE [MAG-COMBINE...]
                        SNR | average | echo <n> | SE <te>. Magnitude
                        combination algorithm. echo <n> select