Release note

1.3.0 (commit 3ad47fd)

Note

Upgrade notes

SpecifyToolboxesDirectory.m and SpecifyAtlasDirectory.m are no longer tracked in git (see “Housekeeping” below). No action needed - your existing local copies are untouched - but git status will now show them as untracked instead of unmodified.

New QSM methods & toolboxes

• Added support for the χ-separation (Chi-separation) toolbox as a new QSM add-on (paramagnetic/diamagnetic susceptibility separation via Chi-sepnet, chi_sep_MEDI and chi_sep_iLSQR; requires ONNX checkpoint files and the Deep Learning Toolbox Converter for ONNX Model Format support package)

• Added HEIDI as a dipole inversion method, available both as the two-stage “LSQR+HEIDI” pipeline and as a “Streaking reduction by HEIDI” post-processing option that can be applied on top of any other QSM dipole-inversion method’s output

• Updated the mu2 parameter handling for FANSI

• New download_FANSI_toolbox.m script to automatically download a pinned FANSI-toolbox commit and register it in SpecifyToolboxesDirectory.m

• HEIDI_HOME and ChiSepNet_HOME are now configured centrally in SpecifyToolboxesDirectory.m (editable via the Utility tab’s Manage Dependency panel - see Utility), instead of hand-editing setup_Chi_sepnet_environment.m or a hardcoded path

• New download_HEIDI_toolbox.m script to automatically download the HEIDI package and register it in SpecifyToolboxesDirectory.m; the package itself is hosted as a GitHub Release asset on the SEPIA repo (tag heidi-sepiaready-v1, kept separate from SEPIA’s own version tags)

• New download_toolboxes.m script to check/download FANSI, HEIDI and Tensor-MPPCA in one go, instead of running each toolbox’s own setup script separately

• New setup_sepia.m script that auto-creates a machine-local SpecifyToolboxesDirectory.m from SpecifyToolboxesDirectory.template.m the first time it’s missing

Preprocessing

• New Tensor-MPPCA denoising option (automatically downloads the required external toolbox on first use)

• New upsampling option for the phase/magnitude data prior to processing

• Added STI-Suite’s V-SHARP 2D as a background field removal method for multi-slice/2D EPI acquisitions

• New “no unwrapping” option when only field mapping is required (e.g. for functional QSM)

Masking

• New two-pass masking option (see Two-pass Masking), and a new, generalised mask refinement pipeline (shared between the I/O panel’s “Refine mask” option and the QSM panel’s two-pass masking)

• Brain extraction is no longer limited to FSL’s BET: a new method dropdown adds Otsu’s-method thresholding and (when FreeSurfer’s mri_synthstrip is available) SynthStrip and SynthStrip (no CSF)

• Built-in V-SHARP: fixed a bug where the k-space deconvolution step was missing, causing incomplete background field removal; kernel radius is now specified in mm instead of voxels (and supports anisotropic voxel sizes)

• Fixed several compatibility issues between two-pass masking and the mask refinement pipeline (BIDS directory input, QSM/mask-refinement wrapper argument handling)

R2* handling

• The R2* map is now computed once per pipeline run and reused across the mask refinement, unreliable-voxel exclusion, and QSM CSF-masking steps (previously recomputed redundantly); it is only recomputed automatically if the data is subsequently denoised or upsampled

Configuration & GUI

• SEPIA can now parse sepia_config*.m pipeline configuration files and extract the algorithm parameters directly, storing them in the GUI figure handle

• Updated config-file parsing to keep up with newer pipeline configuration files (e.g. the HEIDI-related fields added this release)

• Various GUI bug fixes for loading saved configuration files (e.g. NDI’s GPU option, VSHARP/FANSI parameters)

• GUI default method selection is now toolbox-availability-aware for the total field/phase unwrapping, background field removal, and QSM dipole inversion steps, following a consensus-informed priority chain per step (e.g. QSM defaults to FANSI → MEDI → LSQR+HEIDI → TKD, whichever is actually installed); the background field removal “remove residual B1 field” default (3D Polynomial / None) now automatically follows whichever BFR method is selected

• Added a dark theme for the GUI

BIDS / I/O

• Added support for reading multiple volumes per echo in BIDS-formatted data (e.g. functional QSM)

• Fixed echo-tag (_echo-##_) parsing to work regardless of zero-padding used in the echo number

• Fixed an undefined input-filename-cell error when auto-detecting a BIDS directory containing single-volume-per-echo data

• Pipeline outputs now include BIDS-Derivatives-style JSON sidecars (units, source files, algorithm parameters) alongside the NIfTI files, plus a dataset_description.json at the output root

• Output NIfTI extension (.nii vs .nii.gz) is now detected from the input data instead of always being forced to .nii.gz

• Fixed output filenames ending up with two desc- BIDS entities when the output prefix already contained one (e.g. from a previous processing stage); it is now merged with SEPIA’s own output-type label instead, chained in actual processing order (e.g. denoised → upsampled)

• Renamed the paramagnetic/diamagnetic susceptibility map outputs from the non-standard ChiParamap/ChiDiamap suffixes to the BIDS-valid desc-paramagnetic_Chimap/desc-diamagnetic_Chimap

• Fixed sepiaIO not resolving relative input/mask/output paths against the working directory before processing (could break since SEPIA changes its current directory internally mid-run)

• sepiaIO now always generates a fresh sepia_config file for a run, instead of reusing one already present in the output directory

Segmentation & analysis

• Automatic contrast matching, quick nonlinear registration using a dilated subcortical mask, label-based registration, and CSV statistics export added to the MuSus-100/CIT168/AHEAD atlas-based segmentation tools

• Chimap values can now be exported to a CSF file after segmentation

Bug fix

• Fixed get_set_qsm_ndi.m erroring when loading a saved configuration file

• Fixed a bug in R2* NLLS mapping

• Fixed direct file loads (e.g. user-supplied R2*/R2 maps in the Chi-separation wrapper) bypassing the odd-matrix-size zero-padding step - they now go through the same loading path as other auxiliary data

• Fixed get_set_qsm_Chi_separation.m leaving literal quotation marks in the R2*/R2 edit fields when reloading a saved configuration file, and not re-triggering the solver dropdown’s callback on load (so field enable/disable state and the Dr default could be left mismatched with the loaded solver)

• Fixed check_and_set_SEPIA_header_data.m dropping the r2s field (and its availableFileList entry) when passing header/extra data through

Housekeeping

• SpecifyToolboxesDirectory.m and SpecifyAtlasDirectory.m are no longer tracked in git (now machine-specific and gitignored; see their .template.m files and the new setup_sepia.m)

• Removed a large set of unused/deprecated legacy wrapper and parser files (e.g. the deprecated parse_varargin_* argument parsers, the GPU-prototype cuBackgroundRemovalMacro.m/cuQSMMacro.m wrappers, and a deprecated GUI callback)

• Renamed/reorganised a few internal analysis and R2* utility functions to avoid name clashes with other repositories

1.2.2.6 (commit 1790ac6)

Release date: 3 December 2023

• Support read Input/Output information from sepia_config.m

• Phase DICOM values are rescaled using the max/min values in the data instead of rescale slope/intercept of the NIFTI

1.2.2.5 (commit 8630efe)

Release date: 12 October 2023

• Fix the mismatch between SEPIA defined B0 direction and LPCNN when it is not along the z-direction

• Fix the shared library issue when using ROMEO with latest versions of Matlab on Linux (see here)

• Allow user to define atlases’ directory paths

1.2.2.4 (commit 9083249)

Release date: 3 April 2023

• Fix bug when importing SEPIA pipeline configuration files (sepia_config.m) to the GUI for using VSHARP and FANSI

1.2.2.3 (commit efde35b)

Release date: 7 March 2023

• Fix bug when using BIDS compatible directory input where magnitude images did not utilise the rescale slope and intercept to obtain the true values for R2* mapping

1.2.2.2 (commit e53fd99)

Release date: 9 February 2023

• Fix bug when using BIDS compatible directory input where magnitude images did not utilise the rescale slope and intercept to obtain the true values for QSM

1.2.2.1 (commit 1f04298)

Release date: 2 February 2023

• Fix bug when using optimum weight total field computation with odd matrix size data

1.2.2 (commit d6bb60e)

Release date: 27 January 2023

• Fix bug for non-double type input for MATLAB’s strel function

• Make sure all holes inside the ROI mask are filled after the background field removal step

• ROI (brain) mask is applied on the fieldmap regardless of what method is chosen

1.2.1.1 (commit 941cd5b) Patch update

Release date: 12 December 2022

• Enable option of GPU processing for FANSI and NDI

1.2.1 (commit 190dd44)

Release date: 7 December 2022

Bug fix

• Fix bug when one of the dimension of the input images is odd nunmber

• Fix bug for missing function for R2* nonlinear least square algorithm

1.2.0 (commit d2f54a3)

Release date: 11 October 2022

Toolbox related

• Support several deep learning based methods (BFRnet, xQSM, QSMnet+ and LP-CNN) on Linux

• Support atlas-based subcortical structure segmentation (CIT168 Reinforcement learning atlas, MuSus-100 and AHEAD) on Linux and Mac

• Integrate R2* mapping toolbox into SEPIA

• New function to further refine brain mask by thresholding high R2* voxels on brain edges

• When magnitude image is used for NDI, the image will be weighted by the intensity of the 99th percentile of the masked voxels instead of the maximum to improve robustness

1.1.1 (commit a7680bb) Patch update

Release date: 3 October 2022

Toolbox related

• New function to support refining brain mask before background field removal step

• Official support mritools v3.5.5 (https://github.com/korbinian90/CompileMRI.jl/releases/tag/v3.5.5), which included ROMEO and CLEAR-SWI

• ‘ROMEO_HOME’ is now renamed to ‘MRITOOLS_HOME’ in SpecifyToolboxesDirectory.m

• Add GPU compatibility for NDI

Bug fix

• Fixed bug for full pipeline application and phase unwrapping standalone application used different bipolar readout correction implementations

• Fixed bug for NDI when weight was used instead of weight^2

1.1.0 (commit 9ffe0e2)

Release date: 22 September 2022

GUI related

• Experimental support to export phase image from real|imaginary images (could be useful for GE data)

Toolbox related

• Better compatibility with ROMEO, including loading config file with ROMEO parameter back to GUI

• New implementation of bipolar readout phase offset correction (no phase unwrapping is required) and provide the estimated phase offset map as output

• New implementation of incorporating relative residual map into the weighting map when the “Exclude voxels using reisdual” box is checked with “weighting map” option

Bug fix

• Several minor bugs fixed

Backend related (advanced user)

• New backend architecture for SWI/SMWI. Now new SWI or SMWI methods can be added to SEPIA usinf the add-on feature similar to other methods

1.0.1 (commit 3a2b387)

Release date: 4 Aug 2022

Toolbox related

• Updated function performing phase conversion from arbitary DICOM values to radian (could result in minor numerical differences compared to previous versions if the input phase NIfTI not in radian)

Bug fix

• Fixed bug when phase NIfTI is in wrapped range with non-unity rescale slope (e.g. from Philips’ scanners)

• Several other minor bugs fixed

1.0 (commit 8e35aee)

Release date: 25 Feb 2022

GUI related

• New utility tool for managing external dependencies

Toolbox related

• Support ROMEO as total field computation and phase unwrapping method

• Support MRI susceptibility calculation methods for QSM dipole field inversion

• Support FANSI v3.0 (note that the algorithm parameters are adapted for this version)

• Improve BIDS compartibility with SEPIA

• Update output filenames in accordance with BIDS format

• Improve the comparability of weighting maps across different datasets and methods

• GUI supports on managing toolbox dependencies

Bug fix

• Improve the robustness of measuring a reference phase point for B0 computation

Backend related (advanced user)

• New architecture for easier integration of new echo combination methods

• New data loading method to reduce memory usage during processing

0.8.1.1 (commit 52dd20b)

Release date: 6 May 2021

Bug fix

• Fixed bug when using single-echo dataset

• Fixed bug when input phase data in unit of radian with single datatype

0.8.1 (commit c78247d)

Release date: 4 Feb 2021

Toolbox related

• Log file and error message file are now paired (last 15 digits in the extension) instead of sorting in simple numerical order

• Log file and error message file are now generated in both GUI and command-based operations (when using sepiaIO)

• When running SEPIA, the current directory will temporaily move to the output directory to avoid overwriting temporary files if multiple processings happen simultaneously

• A SEPIA pipeline configuration file will be automatically generated using sepiaIO is the output directory does not have any existing configuration file. This would be useful to look up the pipeline used to produce the results when using command-based operation

Bug fix

• Bug fix when running FANSI (see here)

• Bug fix when getting B0 direction from Sagittal or Coronal acquisition (see here)

• Bug fix when running QSM standalone with magnitude image for regularisation (see here)

• Bug fix when running MEDI with zeropadding option is not equal to zero

Backend related (advanced user)

• Improved readiility of how the data are loaded in SEPIA, which could make better BIDS compartibility in the future

0.8.0 (commmit b4255d8)

Release date: 18 July 2020

GUI related

• New layout for input/output panel for data selection

• New pipeline configuration file (sepia_config.m), log file (run_sepia.log) and error message file (run_sepia.error)

• New feature to load parameters in a pipeline configuration file (sepia_config.m) to the GUI

• New option to save unwrapped echo phase

• New option to exlcude unreliable voxels

• New option to select reference tissue for QSM normalisation/referencing

• New option to remove residual B1 field in local field using spherical harmonic function with adjustable order of the fitting

Toolbox related

• Support the lastest version of MEDI toolbox (Jan 15, 2020)

• Support extra brain extraction (FSL’s BET) parameters from MEDI toolbox

• New ‘percentage’ option for MEDI+0 algorithm

• Support the lastest version of FANSI toolbox (commit dc68c306)

• New option to use weak harmonic regularisation with FANSI

Backend related (advanced user)

• Support developers adding a third-party method as an addon

• Introduce tutorial scripts to guide developers on how to adding third-party method in SEPIA

• Introduce functions to simplify the workflow of creating new method panel

• The order of removal of residual B1 field and mask erosion is interchanged to produce better a fitting result

Bug fix

• Bug fix: running SEPIA without parrallel computing toolbox

• Bug fix: running MEDI toolbox nonlinear fit echo phase combination with 2 echoes

• Bug fix: running MEDI method in SEPIA

• Bug fix: running single echo data with exclusion of unreliable voxels option enabled

Please update the MEDI toolbox (Jan 15, 2020) and FANSI toolbox (commit dc68c306) to the lastest version for the best performance.

0.7.3 (commmit 68c53bc)

Release date: 9 Nov 2019

• Support nonlinear dipole inversion (NDI) as external library

• Support SEGUE as external library

0.7.2 (commmit bf020ce)

Release date: 4 Jun 2019

• Support single-echo dataset

• Bug fix with odd-number matrix dimension by zero-padding

• Offload unuse variables to reduce memory usage

• Bug fix for reading NIfTI when the rescale slope and intercept are not 1 and 0

0.7.1 (commmit dc51fbe)

Release date: 9 May 2019

• Support simple susceptibility weighted imaging (SWI) and susceptibility map weighted imaging (SMWI) as part of the GUI

• resolved loading/saving NIfTI issue related to 0.7.0 update

• DICOM input is deprecated: the only possible input is NIfTI data

• fixed bug when running MEDI with CSF regularisation

• fixed bug for single echo SWI

• now support automatic magnitude and phase images detection with name containing string “mag” for magnitude image and “ph” for phase image

• fixed global phase offset with graph-cut phase unwrapping

0.7.0 (commmit e66d8e4)

Release date: 12 Apr 2019

• redesigned log file format; the algorithms and parameters being used are much clearer and neat than before (previous log file cannot work in this version)

• resolved ‘.nii.nii’ issue when using STI suite algorithms

• resolved no. of iterations with FANSI does not change issue

• resolved problematic QSM results with FANSI when an input matrix is an odd number

• resolved excluded unreliable voxels issue when 3D best path algorithm doesn’t work

• improved build-in VSHARP results when there are masked voxels on the image edges

• added image erosion function for background field removal algorithms

• get header function is now compatible with the JSON files generated by dcm2niix and dicm2nii

0.6.0 (commmit 1c27dc4)

Release date: 1 Sep 2018

• updated diretcory structure

• added options to select individual files