Possible breaking changes with previous version: Uses latest SPM vers…

…ion of MB

OBS: Now contains some MEX files that requires compilation.

Makefile

@@ -0,0 +1,108 @@
+#!/usr/bin/env make -f
+# Makefile to compile SPM MB GMM lib C-MEX files (hacked together by MB)
+#
+# Copyright (C) 1991-2021 Wellcome Centre for Human Neuroimaging
+#
+# $Id: Makefile 8058 2021-02-10 10:38:31Z guillaume $
+#
+###############################################################################
+#
+# This Makefile has been tested under Linux, Windows and MacOS.
+#
+# If you have to tweak this Makefile or Makefile.var to compile the SPM
+# mex-files for your platform, please send the details to <[email protected]>
+# so they can be included here.
+#
+# To compile and install SPM, type the following in a Unix console:
+# >  make distclean && make && make install
+#
+# You can specify a particular platform with the following syntax:
+# >  make PLATFORM=Your_Platform
+# The standard targets are 'all', 'clean', 'distclean', 'doc' and 'install'.
+#
+# For a list of compatible compilers, see
+#    https://www.mathworks.com/support/compilers.html
+#
+###############################################################################
+
+include Makefile.var
+
+###############################################################################
+# Objects to go in the archive and mexfiles
+###############################################################################
+
+SPMMEX  =\
+	spm_gmmlib.$(MEXEXT)
+
+###############################################################################
+# Public make targets
+###############################################################################
+
+all: verb.$(MEXEXT) main-all verb.all.end
+
+clean: verb.distclean main-distclean verb.distclean.end
+
+###############################################################################
+# Private make targets
+###############################################################################
+
+main-all: $(SPMMEX)
+
+main-distclean:
+	$(DEL) $(SPMMEX)
+
+###############################################################################
+# Compile the mex files themselves
+###############################################################################
+
+spm_gmmlib.$(MEXEXT): spm_gmmlib.c gmmlib.c gmmlib.h 
+	$(MEX) spm_gmmlib.c gmmlib.c $(MEXEND)
+
+###############################################################################
+# Display Messages
+###############################################################################
+
+verb.clean:
+	$(call verb, "Deleting object (.o) files")
+
+verb.distclean:
+	$(call verb, "Deleting MEX (.$(MEXEXT)) and archive (.a) files")
+
+verb.install:
+	$(call verb, "Installing MEX files")
+
+verb.tarball:
+	$(call verb, "Creating archive spm_mex.tar.gz")
+
+verb.mexw32:
+	$(call verb, "Windows compilation (32 bit)")
+
+verb.mexw64:
+	$(call verb, "Windows compilation (64 bit)")
+
+verb.mexglx:
+	$(call verb, "Linux compilation (x86-32)")
+
+verb.mexa64:
+	$(call verb, "Linux compilation (x86-64)")
+
+verb.mexmaci:
+	$(call verb, "MacOS compilation (Intel 32 bit)")
+
+verb.mexmaci64:
+	$(call verb, "MacOS compilation (Intel 64 bit)")
+
+verb.mex:
+	$(call verb, "${PLATFORM} compilation (`${MEXBIN} -v | head -n 1`)")
+
+verb.all.end:
+	$(call verb, "Compilation: done")
+
+verb.distclean.end:
+	$(call verb, "Distclean: done")
+
+verb.install.end:
+	$(call verb, "Installation: done")
+
+verb.external:
+	$(call verb, "In external")

Makefile.var

@@ -0,0 +1,113 @@
+# Makefile default variables
+#
+# Copyright (C) 1991-2020 Wellcome Centre for Human Neuroimaging
+#
+# $Id: Makefile.var 8020 2020-11-26 15:00:31Z guillaume $
+#
+###############################################################################
+#
+# This file defines variables used in Makefile and has been tested under
+# Linux, Windows and macOS.
+#
+# If you have to tweak this file to compile the SPM MEX-files for your
+# platform, please send the details to <[email protected]> so they can be
+# included here.
+#
+# You can find some more help online on the SPM wikibook:
+#  * Linux:
+#      https://en.wikibooks.org/wiki/SPM/Installation_on_64bit_Linux
+#  * Windows:
+#      https://en.wikibooks.org/wiki/SPM/Installation_on_64bit_Windows
+#      MinGW: http://www.mingw.org/
+#  * macOS:
+#      https://en.wikibooks.org/wiki/SPM/Installation_on_64bit_Mac_OS_(Intel)
+#
+###############################################################################
+
+SHELL        = /bin/sh
+MAKE         = make
+MEXOPTS      = -O -largeArrayDims
+MEXEND       =
+MOSUF        = o # mex output object suffix
+UNAME        = uname
+AR           = ar rcs
+COPY         = cp -f
+DEL          = rm -f
+MOVE         = mv -f
+TAR          = tar
+ZIP          = gzip -f
+OMPFLAG      = -fopenmp
+WARNFLAG     = -Wall -Wextra -Wpedantic
+USE_OPENMP  ?= 0
+
+ifndef PLATFORM
+  PLATFORM   = $(shell $(UNAME))
+endif
+
+##### Linux #####
+ifeq (Linux,$(PLATFORM))
+  MEXEXT     = mexa64
+  MEXBIN    ?= /usr/local/MATLAB/R2018a/bin/mex
+  #MEXOPTS   += CFLAGS='$$CFLAGS $(WARNFLAG)'
+endif
+
+##### MacOS #####
+ifeq (Darwin,$(PLATFORM))
+  MEXEXT     = mexmaci64
+  MEXBIN    ?= mex
+  # https://stackoverflow.com/questions/37362414/
+  OMPFLAG    = -fopenmp=libiomp5
+endif
+
+##### Windows #####
+ifeq (MINGW32,$(word 1,$(subst _, ,$(PLATFORM)))) # MSVC
+  override PLATFORM = windows
+  MEXEXT   = mexw64
+  MEXBIN    ?= cmd /c "mex.bat
+  MEXOPTS   += -DSPM_WIN32
+  MEXEND     = "
+  MOSUF      = obj
+  AR         = lib.exe /out:
+  OMPFLAG    = /openmp
+endif
+ifeq (MSYS,$(word 1,$(subst _, ,$(PLATFORM)))) # GCC
+  MEXEXT     = mexw64
+  MEXBIN    ?= mex
+  MEXOPTS   += -DSPM_WIN32
+  MOSUF      = obj
+endif
+
+#### Octave ####
+ifeq (octave,$(PLATFORM))
+  MEXEXT     = mex
+  MEXBIN    ?= mkoctfile
+  MEXOPTS    = --mex -DOCTAVE_MEX_FILE
+  #MEXOPTS   += $(WARNFLAG)
+  override PLATFORM = $(shell $(UNAME))
+  ifeq (MINGW64,$(word 1,$(subst _, ,$(PLATFORM))))
+    MEXOPTS += -DSPM_WIN32
+  endif
+  OMPFLAG    =
+endif
+
+#### Otherwise ####
+ifndef MEXEXT
+  $(error Unknowm platform $(PLATFORM))
+endif
+
+MATLABROOT   = $(realpath $(shell which $(firstword $(MEXBIN))))
+ifeq (1,$(USE_OPENMP))
+  ifneq ($(OMPFLAG),)
+    MEXOPTS += CFLAGS='$$CFLAGS $(OMPFLAG)' LDFLAGS='$$LDFLAGS $(OMPFLAG)'
+  endif
+endif
+MEX          = $(MEXBIN) $(MEXOPTS)
+SUF          = $(MEXEXT)
+
+define verb
+	@ echo "_____________________________________________________________"
+	@ echo ""
+	@ echo "        " $(1)
+	@ echo "_____________________________________________________________"
+	@ echo ""
+endef

README.md

@@ -1,35 +1,36 @@
-# Multi-Brain: Unified segmentation of population neuroimaging data
+# Multi-Brain: Group-wise diffeomorphic registration and segmentation of medical images
 
 ## Overview
 This repository contains the Multi-Brain (MB) model, which has the general aim of integrating a number of disparate image analysis components within a single unified generative modelling framework (segmentation, nonlinear registration, image translation, etc.). The model is described in Brudfors et al [2020], and it builds on a number of previous works. Its objective is to achieve diffeomorphic alignment of a wide variaty of medical image modalities into a common anatomical space. This involves the ability to construct a "tissue probability template" from a population of scans through group-wise alignment [Ashburner & Friston, 2009; Blaiotta et al, 2018]. Diffeomorphic deformations are computed within a *geodesic shooting* framework [Ashburner & Friston, 2011], which is optimised with a Gauss-Newton strategy that uses a multi-grid approach to solve the system of linear equations [Ashburner, 2007]. Variability among image contrasts is modelled using a much more sophisticated version of the Gaussian mixture model with bias correction framework originally proposed by Ashburner & Friston [2005], and which has been extended to account for known variability of the intensity distributions of different tissues [Blaiotta et al, 2018]. This model has been shown to provide a good model of the intensity distributions of different imaging modalities [Brudfors et al, 2019]. Time permitting, additional registration accuracy through the use of shape variability priors [Balbastre et al, 2018] will also be incorporated.
 
-## OBS 
-Please ensure that: (1) the folder containing this repository (`diffeo-segment`) is placed in the `toolbox` folder of your SPM version; and (2), the folder is renamed to `mb`. 
-
 ## Dependencies
-The algorithm is developed using MATLAB and relies on external functionality from the SPM12 software. The following folders are therefore required downloads and need to be placed on the MATLAB search path (using `addpath`):
+The algorithm is developed using MATLAB and relies on external functionality from the SPM12 software. The following are therefore required downloads and need to be placed on the MATLAB search path (using `addpath`):
 * **SPM12:** Download from https://www.fil.ion.ucl.ac.uk/spm/software/download/.
 * **Shoot toolbox:** The Shoot folder from the toolbox directory of SPM12.
 * **Longitudinal toolbox:** The Longitudinal folder from the toolbox directory of SPM12.
 
+## Installation instructions
+1. Download/clone this repository to the `toolbox` folder of SPM12.
+2. Next, in a terminal, `cd` to this folder and execute the `make` command (this compiles required MEX-files).
+
 ## Example use cases
-This section contains example code demonstrating how the MB toolbox can be used for nonlinear image registration, spatial normalisation, tissue segmentation and bias-field correction. **Example 1** learns (or fits) the MB model from a population of MRI scans. Learning the MB model results in a bunch of tissue segmentations, bias-field corrected scans and forward deformations, aligning a template to each subject's scan (a combined nonlinear and rigid registration). The deformations can be used to warp a subject image to template space, or aligning two subjects' images together by composing their deformations. These two operations are demonstrated in **Example 2**. Finally, **Example 3** fits an already learned MB model to two subject MRIs. This is equivalent to registering to a pre-existing common space. Warping can then be done as shown in Example 2. For a full description of the model settings, see `demo_mb.m`.
+This section contains example code demonstrating how the MB toolbox can be used for nonlinear image registration, spatial normalisation, tissue segmentation and bias-field correction. **Example 1** fits the MB model to a population of images. Fitting the MB model results in: learned spatial (the template) and intensity priors, and a bunch of segmentations and forward deformations. The deformations can be used to warp subject images to template space, or aligning two subjects' images together by composing their deformations. These two operations are demonstrated in **Example 2**. Finally, **Example 3** fits an already learned MB model to two subject images. This is equivalent to registering to a pre-existing template space. Warping can then be done as shown in Example 2. For a full description of the model settings, see `demo_mb.m`.
 
 ### 1. Learning the MB model
 ``` matlab
-% This script fits the MB model to a population of MRIs. It is a
+% This script fits the MB model to a population of images. It is a
 % group-wise image registration where an optimal K class tissue template is 
 % built, as well as optimal intensity parameters learnt. The resulting
 % deformations (written to dir_out prefixed y_) can then be used to warp
 % between subject scans. Also native and template space tissue
 % segmentaitons are written to disk, as well as a bias-field corrected 
 % versions of the input scans.
 
-% Data directory, assumed to contain MRI nifti images of the same contrast.
-dir_data = '/directory/with/some/MRIs';
+% Data directory, assumed to contain a bunch of images.
+dir_data = '/directory/with/some/images';  % OBS: should be .nii (NIfTIs)
 
 % Get paths to data
-pth_im  = spm_select('FPList',dir_data,'^.*\.nii$'); % Selects all nifti files in dir_data
+pth_im  = spm_select('FPList',dir_data,'^.*\.nii$'); % Selects all NIfTIs files in dir_data
 
 % RUN module (fits  the model)
 run              = struct;
@@ -58,18 +59,18 @@ spm_jobman('run', jobs);
 ### 2. Warping with MB deformations
 ``` matlab
 % This script demonstrates warping with the deformation generated from
-% fitting the MB model. The template file generated by MB, plus two subject 
-% scans with their corresponding forward deformations (prefixed 'y_') are
+% fitting the MB model. The template file generated by MB, plus two images 
+% with their corresponding forward deformations (prefixed 'y_') are
 % needed. The following three warps are demonstrated:
 % 1. Warp an image to template space.
 % 2. Warp the template to image space.
 % 3. Warp one image to another image.
 
 % Path to a MB tissue template (this is dir_out in Example 1)
 pth_mu = fullfile(dir_out,'mu_mb_test.nii');
-% Paths to two subject MRIs to which MB has been fitted
-pth_img1 = '/directory/with/some/MRIs/img1.nii';
-pth_img2 = '/directory/with/some/MRIs/img2.nii';
+% Paths to twoimages, to which MB has been fitted
+pth_img1 = '/directory/with/some/img1.nii';
+pth_img2 = '/directory/with/some/img2.nii';
 % Paths to corresponding forward deformations of the above subjects
 pth_y1 = fullfile(dir_out,'/y_img1.nii');
 pth_y2 = fullfile(dir_out,'y_img2.nii');
@@ -123,7 +124,7 @@ spm_jobman('run',matlabbatch);
 ### 3. Fitting a learned MB model
 ``` matlab
 % This script demonstrates how to fit a learned MB model (template and 
-% intensity prior) to new data. In practice, it only involves modifying
+% intensity prior) to new (unseen/test) images. In practice, it only involves modifying
 % some settings in Example 1.
 
 % Path to results MAT-file generated by fitting MB
@@ -143,15 +144,15 @@ run.gmm.pr.hyperpriors = [];  % Avoids re-learning the intensity prior
 ```
 
 ## References
-* Ashburner J, Friston KJ. Unified segmentation. Neuroimage. 2005 Jul 1;26(3):839-51.
-* Ashburner J. A fast diffeomorphic image registration algorithm. Neuroimage. 2007 Oct 15;38(1):95-113.
-* Ashburner J, Friston KJ. Computing average shaped tissue probability templates. Neuroimage. 2009 Apr 1;45(2):333-41.
-* Ashburner J, Friston KJ. Diffeomorphic registration using geodesic shooting and Gauss–Newton optimisation. NeuroImage. 2011 Apr 1;55(3):954-67.
-* Blaiotta C, Cardoso MJ, Ashburner J. Variational inference for medical image segmentation. Computer Vision and Image Understanding. 2016 Oct 1;151:14-28.
+* Brudfors M, Balbastre Y, Flandin G, Nachev P, Ashburner J. Flexible Bayesian Modelling for Nonlinear Image Registration. In: International Conference on Medical Image Computing and Computer-Assisted Intervention 2020
+* Brudfors M, Ashburner J, Nachev P, Balbastre Y. Empirical Bayesian Mixture Models for Medical Image Translation. In: International Workshop on Simulation and Synthesis in Medical Imaging 2019 Oct 13 (pp. 1-12). Springer, Cham.
+* Balbastre Y, Brudfors M, Bronik K, Ashburner J. Diffeomorphic brain shape modelling using Gauss-Newton optimisation. In: International Conference on Medical Image Computing and Computer-Assisted Intervention 2018 Sep 16 (pp. 862-870). Springer, Cham.
 * Blaiotta C, Freund P, Cardoso MJ, Ashburner J. Generative diffeomorphic modelling of large MRI data sets for probabilistic template construction. NeuroImage. 2018 Feb 1;166:117-34.
-* Balbastre Y, Brudfors M, Bronik K, Ashburner J. Diffeomorphic brain shape modelling using Gauss-Newton optimisation. In International Conference on Medical Image Computing and Computer-Assisted Intervention 2018 Sep 16 (pp. 862-870). Springer, Cham.
-* Brudfors M, Ashburner J, Nachev P, Balbastre Y. Empirical Bayesian Mixture Models for Medical Image Translation. In International Workshop on Simulation and Synthesis in Medical Imaging 2019 Oct 13 (pp. 1-12). Springer, Cham.
-* Brudfors M, Balbastre Y, Flandin G, Nachev P, Ashburner J. Flexible Bayesian Modelling for Nonlinear Image Registration. To appear in: International Conference on Medical Image Computing and Computer-Assisted Intervention 2020
+* Blaiotta C, Cardoso MJ, Ashburner J. Variational inference for medical image segmentation. Computer Vision and Image Understanding. 2016 Oct 1;151:14-28.
+* Ashburner J, Friston KJ. Diffeomorphic registration using geodesic shooting and Gauss–Newton optimisation. NeuroImage. 2011 Apr 1;55(3):954-67.
+* Ashburner J, Friston KJ. Computing average shaped tissue probability templates. Neuroimage. 2009 Apr 1;45(2):333-41.
+* Ashburner J. A fast diffeomorphic image registration algorithm. Neuroimage. 2007 Oct 15;38(1):95-113.
+* Ashburner J, Friston KJ. Unified segmentation. Neuroimage. 2005 Jul 1;26(3):839-51.
 
 ## Acknowledgements
 This work was funded by the EU Human Brain Project’s Grant Agreement No 785907 (SGA2).