-
Notifications
You must be signed in to change notification settings - Fork 44
GetStarted
Before using the hMRI toolbox, please read the README.md and LICENSE files.
SOFTWARE REQUIREMENTS
INSTALL THE TOOLBOX
DOWNLOAD DATASET & PROTOCOL EXAMPLES
TUTORIALS
HELP & RESOURCES
NOTE ON RUNTIMES
COMPILATION OF THE TOOLBOX
You'll need Matlab to run the hMRI toolbox. Matlab versions from release R2018a (MATLAB 9.4) and up have been used to develop the software and in general, testing is performed with versions from R2019a (MATLAB 9.6, last 5 years). Some functionality may still work in earlier versions of Matlab, but this is not officially supported. Please note that a single Matlab version should be used to process all of a given dataset, as results can differ slightly between versions due to changes in Matlab's internal algorithms.
The hMRI toolbox relies on SPM functionalities and has been developed starting from SPM12 (version 12.3 - r6906). It is recommended to have the latest release of SPM12. You can get the latest version of SPM12 either from Download form or from the SPM12-Github. If you wish to git clone it, you can do so by getting the clone hash from clone SPM12 or you can directly run the command
git clone https://github.com/spm/spm12.git
After the download/unzip or clone, please make sure you have added the SPM root directory spm12 to your Matlab Path.
For users who wish to keep their version of the hMRI toolbox up-to-date with the repository, and developers who wish to contribute to the toolbox development, it is necessary to have Git installed. You can download Git here. See the Git documentation pages to get started if you are new to Git.
The installation procedure allows users to manage the hMRI toolbox repository independently from their SPM installation, thanks to a redirection script. This is especially convenient when a version control system is used for SPM as well. The following steps describe how to get your own copy of the toolbox in a directory of your choice and how to make it available as an SPM tool.
For users of the hMRI toolbox who do not plan to modify the code by themselves, it is recommended to download the latest release from the hMRI Releases page. After download, unzip the compressed file and proceed with the installation instructions below (skip the next section for developers). For information on the various releases and related changes, please refer to the Releases wiki page.
If you are an advanced user, you might want to clone the hMRI toolbox repository and keep your version regularly up-to-date. The following Git command line will create a hMRI-toolbox directory in the current directory and clone the toolbox repository within that directory:
git clone https://github.com/hMRI-group/hMRI-toolbox.gitIf you wish to further develop the toolbox, we recommend you fork the repository. For more details on forking and more development guidelines, please refer to the Develop & Contribute wiki page.
The redirection script is a short script to be copied to your SPM/toolbox directory. It will point to the full implementation of the hMRI toolbox, thus making it available as an SPM tool. The following steps describe how to proceed:
- Create the (empty) directory
hMRIin<path-to-your-spm>/toolbox - Copy
hMRI-Toolbox/install/tbx_cfg_hmri_redirect.minto<path-to-your-spm>/toolbox/hMRI - Add the hMRI-Toolbox root directory (containing the unzipped release or your local repository including the full implementation of the hMRI-Toolbox) to your Matlab Path. NOTE: in Matlab, choose the
Add Folder...option. Do not use theAdd with Subfolders...option. The appropriate subfolders will be automatically added when starting the toolbox.
- Start Matlab and the SPM (fMRI) user interface:
spm fmri, - Start the Batch GUI (Batch button in the SPM Menu).
- Check whether you can access the hMRI toolbox:
SPM > Tools > hMRI Tools
A number of unit tests are provided in hMRI/hmri_code_tests. To run these you must first ensure that the hMRI toolbox is on your Matlab path, then navigate to that folder and run runtests in Matlab.
A full dataset is available for download, as well as several protocols containing all acquisition parameters. The following section makes use of this dataset.
Examples and tutorials are based on the hMRI demo dataset available here.
The present Wiki is the main source of information to learn about how to use the toolbox and how it works, together with the toolbox paper.
In addition to this Wiki, help information can also be found in the Help section of each matlab script
(or by typing help <function> in Matlab) and in the SPM Batch GUI in the Help box at the bottom of the Batch window.
If you cannot find the expected information above, you may want to browse the mailing list archive (you must register to the mailing list, get a password and log in as registered user to access the archive) or the issue tracking system.
If you still cannot find an answer to your question or a solution to your issue, you can either send an email to the mailing list or open a new issue. Guidelines and practical information on using the mailing list and the issue tracking system can be found on the Develop & Contribute wiki page.
The runtime of the various processes depends of course on the available hardware. On a MacBookPro with i7 (2.9GHz) with 16GB RAM and Mac OS 10.13.6 (High Sierra) with Matlab 2017b the creation of qMRI maps with the toolbox using the example dataset takes approximately 11 minutes. This includes the transmit and receive bias correction. The spatial processing of multiple subjects relies on adjusted SPM functionalities. Thus, the runtime for this part of the toolbox is very similar to the runtime known for the corresponding processes in SPM.
Compilation of the toolbox is available as an asset at:
After downloading and unzipping the file standalone-hMRItoolboxv0.6.1.zip, it is possible to run the compiled version of hMRI-toolbox by typing in the linux commandline the following command:
/path/to/standalone > ./run_spm12.sh /data/software fmri
Of course, before doing all these, you need to check that your Matlab already has the runtime environment. In order to check for this, go to your matlab folder and check whether you have the runtime folder containing the directory glnxa64. In the above example the runtime folder needs to be located in /data/software
In addition if you already have a batch, e.g. testbatch.mat, that you would like to run in the compilation directly on the command line, after placing your testbatch.mat in the standalone folder /path/to/standalone, this time you need to use the command:
/path/to/standalone > ./run_spm12.sh /data/software batch testbatch.mat