Download
The latest version of SEPIA can be downloaded from GitHub:
Installation/Setp up
Prerequisite
To support the fully functionality of SEPIA, the following external libraries, which are freely available for academic purposes, are required. You can download these toolboxes/libraries using the following links:
FANSI toolbox (v3.0, released on 2021.10.15, i.e., commit b6ac1c9e)
MRI susceptibility calculation methods (accessed 12 September 2019)
If you encounter any difficulty to download these toolboxes please let us know by opening a new issue in the GitHub page.
Installation of SEPIA
Once you have all the toolboxes in place, you have to add the directory containing sepia.m, i.e. the SEPIA HOME directory, to your MATLAB PATH
This can be done by: ‘Set Path’ -> ‘Add Folder’ -> /your/sepia/directory/ -> ‘Save’
Warning
To ensure only the selected algorithm is used for the QSM processing, please do not manually add the paths to the external toolboxes you want to run in SEPIA to the Matlab PATH, the sepia_addpath function will do the job for you:).)
or
with MATLAB’s command: addpath('/your/sepia/directory')
Managing external dependency
SEPIA is a pipeline processing tool focusing on integrating various tools in a single platform. Although SEPIA does provide QSM methods for some basic processing, the majority of the methods supported by SEPIA are from external tool. Users have to download these tools from the URLs provided aboved before they can be run in SEPIA. Once you have all the tools available in your computer, you can use the following options to manage these tools in the SEPIA environment.
Managing external dependency via GUI
You have to specify the directory of each toolbox. From SEPIA v1.0, this can be done on the SEPIA’s GUI: simply initialises the GUI using command sepia, this should start the GUI. For the first time, you will see some warning messages regarding missing dependencies. Ignore those messages for now.
Navigates to the ‘Utility’ tab, and select ‘Manage Dependency’:
Use the icon to select the top folder of the tool
Click ‘Open’ to select the folder
Click ‘Save’ once you finish adding all dependencies
Now, restart the SEPIA’s GUI by closing the window and re-open it using the sepia command in Matlab. You should recieve no more warning messages now if you provide all the required dependencies.
Managing external dependency directly on SpecifyToolboxesDirectory.m
Alternatively, the traditional way of manging dependency in SpecifyToolboxesDirectory.m is still feasible:
MEDI_HOME = '/path/to/MEDI/toolbox/';
STISuite_HOME = '/path/to/STISuite/toolbox/';
FANSI_HOME = '/path/to/FANSI/toolbox/';
SEGUE_HOME = '/path/to/SEGUE/library/;'
MRISC_HOME = '/path/to/MRI_susceptibility_calculation/library/;'
MRITOOLS_HOME = '/path/to/MRITOOLS/library/;'
Warning
The variable names of the toolboxes’ paths are changed from ‘_dir’ to ‘_HOME’ from v0.8. Please update your SpecifyToolboxesDirectory.m file accordingly to avoid error.
Warning
The variable ‘ROMEO_HOME’ is changed to ‘MRITOOLS_HOME’ in v1.1.1. Please update your SpecifyToolboxesDirectory.m file accordingly to avoid error. You can also specify the path to the previous ROMEO executable (but CLEAR-SWI might not work in this case).
For example, I have all my external toolboxes stored under the SEPIA home directory. Additionally, for each toolbox, I have different copies representing different versions when they were published
and here is an example of how is my SpecifyToolboxesDirectory.m defined:
% 1. sepcify the toolbox version you want to run
MEDI_version = 'MEDI_toolbox_20200115';
FANSI_version = 'FANSI-toolbox-77023b65';
STISuite_version = 'STISuite_V3.0';
SEGUE_version = 'SEGUE_28012021';
MRISC_version = 'MRI_susceptibility_calculation_20190912';
MRITOOLS_version = 'v3.5.5';
% 2. get the Sepia HOME directory from this script
fullName = mfilename('fullpath');
SEPIA_HOME = fileparts(fullName);
% 3. specify the top level of external dependency directory
external_dir = [SEPIA_HOME filesep 'external' filesep];
% 4. specify the parent directory of each toolbox
MEDI_dir = [external_dir 'MEDI_toolbox' filesep];
FANSI_dir = [external_dir 'FANSI_toolbox' filesep];
STISuite_dir = [external_dir 'STI_Suite' filesep];
SEGUE_dir = [external_dir 'SEGUE' filesep];
MRISC_dir = [external_dir 'MRI_susceptibility_calculation' filesep];
MRITOOLS_dir = [external_dir 'MRITOOLS' filesep];
% 5. sepcify the final destination of each toolbox you want to run in Sepia
MEDI_HOME = [MEDI_dir MEDI_version filesep];
FANSI_HOME = [FANSI_dir FANSI_version filesep];
STISuite_HOME = [STISuite_dir STISuite_version filesep];
SEGUE_HOME = [SEGUE_dir SEGUE_version filesep];
MRISC_HOME = [MRISC_dir MRISC_version filesep];
MRITOOLS_HOME = [MRITOOLS_dir MRITOOLS_version filesep];
IMPORTANT: Please do not modify the original structure of these toolboxes, SEPIA searches the path of the related functions based on the original folder structure.
Now you can start the GUI by entering sepia in the MATLAB’s command window.
Setup deep learning tools for SEPIA
Starting from v1.1.2, several deep learning methods for QSM processing are (experimentally) supported in SEPIA. Please refer to the individual algorithm pages on QSM Algorithms and Background Magnetic Field Removal Algorithms for more infomation on setting up these methods in SEPIA.
Compatibility
SEPIA is developed mainly in MATLAB R2016b on Linux and macOS. In general, all methods should compatible with earlier MATLAB versions up to R2014b. Most of the methods should also compatible with MATLAB R2017a or later, and other OS, except you might encounter issue with the following functions/algorithms
- Laplacian Boundary Value (LBV) for background field removal
Note
If the LBV algorithm doesn’t work on your operating system, you can go to the ‘_LBV’ directory of the MEDI toolbox and try the following command in the Matlab command window to re-compile the library:
mex mexMGv6.cpp
Graphcut for phase unwrapping
SEPIA v1.0 supports both FANSI v1.0 and v3.0. However, compartibility to FANSI v2.0 (commit 77023b65, released on 2020.07.27) is not yet tested!