Getting started

Prior to running MSM you will need to have passed your data through a surface extraction and inflation pipeline such as FreeSurfer, or the HCP minimal processing pipeline. This is because, if MSM is to work for your data you must have cortical surface meshes that have been mapped to the sphere. If you use the HCP pipeline you must additionally run the preprocessing script PreSulc. In addition, you will require a data file for each mesh, where the data may be scalar (such as sulcal depth, curvature or myelin features) or multivariate (RSNs or fMRI task maps).

Data can be supplied as GIFTI (.func.gii or .shape.gii), ASCII (.asc) files, or as a simple text file (with '.txt' extension) provided the text file has as many columns as there are mesh vertices. Surface files may be supplied as GIFTI (surf.gii) or ASCII (.asc). In general the key files required to run MSM are the:

• input mesh - otherwise known as the "source" or "moving" mesh. This will be the mesh that is deformed during the registration.

• reference mesh - otherwise the "target" or "fixed" mesh. This represents the surface you would like the source mesh to be deformed to most resemble. In some cases (for example if source and target data have both been resampled onto a population average surface (such as the HCP FS_LR164k or FS_LR32k average surface) it will be sufficient to supply just supply an input mesh.

• input data - the data file associated with the input mesh. This must therefore have as many data points as there are surface mesh vertices.

• reference mesh - the data file associated with the referenced mesh.

Example of the most basic call to msm (using these inputs) or:

• A. msm --inmesh=input_mesh.surf.gii --refmesh=ref_mesh.surf.gii --indata=in_data.func.gii --refdata=ref_data.func.gii -o ~/mydirname/L.

  B. msm --inmesh=average.sphere.FSLR32K.surf.gii --indata=in_data.func.gii --refdata=ref_data.func.gii -o ~/mydirname/L.

Where this assumes you are calling msm from the directory where the data exists. The final option (-o) is the stem of the path where you wish to output your data; we suggest ~/mydirname/L. or ~/mydirname/R as an example of how you can input left and right hemisphere results into the same directory. Case B shows an example of how, when both datasets have been resampled to a population average surface (such as the HCP's 32k FS_LR surface), it is possible to enter just the average sphere as the input mesh.

MSM Output

The most relevant outputs of MSM are:

• ~/mydirname/L.sphere.reg.surf.gii - the warped input mesh. Note that the true output basename is highlighted in bold, with the example output path prefixed to it.

• ~/mydirname/L.resampledandprojected.func.gii - the input data passed through the MSM warp and reprojected down onto the target surface for comparison.

The program also spits out a downsampled copy of the initial native mesh ~/mydirname/L.LOWRES.surf.gii and final warp ~/mydirname/L.LOWRES_transformed.surf.gii, which can be used for warping new meshes through the transformation (see section on transformation). GIFTI outputs are used here only as examples. The program also supports output as ASCII and VTK using the command line token -f.

Advanced Command Line Features

In addition to the required inputs to msm, there are several useful options. The most important of these is the --conf call which allows users to supply a configuration file which modifies key parameters of the registration. For optimal running of the registration a configuration file should be supplied, the parameters of which are described in more detail below.

Another very useful feature is the --trans option. This allows users to specify the output mesh from a previous registration stage. For example, if you wished to initialise registration of some resting state network maps (RSNs) by first aligning course folding structure using sulcal maps (as performed in our NeuroImage paper), you could run registration in two stages as:

• Step 1: msm --inmesh=input_mesh.surf.gii --refmesh=ref_mesh.surf.gii --indata=in_SULC_data.func.gii --refdata=ref_SULC_data.func.gii --conf=myconfigSULC -o ~/mySULCdirname/L. 
  Step 2: msm --inmesh=input_mesh.surf.gii --trans ~/mySULCdirname/L.sphere.reg.surf.gii --refmesh=ref_mesh.surf.gii --indata=in_RSN_data.func.gii --refdata=ref_RSN_data.func.gii --conf=myconfRSN -o ~/myRSNdirname/L.

Running registration in this way, rather than simply taking the output from the sulc registration and using it as an input mesh for the RSN registration, allows distortions for the full sulc + RSN registration to be penalised during alignment.

Output file formatting is controlled by the -f/--format option. The options are: GIFTI (surfaces are saved as .surf.gii and data as .func.gii); ASCII (surfaces are saved as .asc and data is saved as .dpv); ASCII_MAT (surfaces are saved as .asc and data is saved as a simple matrix in a textfile .txt); VTK (surfaces as .vtk and data as .txt). For more details on the .dpv format (which is FreeSurfer compatible, but differentiates surface from data files) please see the following blog post: http://brainder.org/2011/09/25/braindering-with-ascii-files/

Costfunction weighting (CFw) can be controlled using --inweight and --refweight options. This allows you to supply a weighting mask for each of your source and reference meshes, although it is possible to run msm with only one. The CFw masks can be multivariate which allows you to vary the contribution different features. For example in the "Multimodal alignment" section of our paper we use a single, multivariate CFw mask created on our template image (and therefore passed as a --refweight option) to vary the contribution of our different modalities to the registration.

Two final useful parameters are --levels which allows you to control the number of resolution levels run during the course of the registration e.g. --levels=2. This supersedes the influence of the configuration file. Finally --smoothout will allow the user to smooth the data after projection to the template image. By default the registration uses adaptive barycentric resampling (reference). However, this option will allow the user to smooth using a gaussian kernel with an input parameter equal to the standard deviation.

Therefore, with all command line parameters used an msm call might look like this:

• msm --inmesh=input_mesh.surf.gii --trans ~/mySULCdirname/L.sphere.reg.surf.gii --refmesh=ref_mesh.surf.gii --indata=in_RSN_data.func.gii --refdata=ref_RSN_data.func.gii --inweight=in_weight_RSN.func.gii --refweight=ref_weight_RSN.gii --levels=2 --smoothout=2 --conf=myconfRSN -o ~/myRSNdirname/L.

This will repeat Step 2 above, but this time each of the meshes will have a corresponding weighting function supplied in the form of a GIFTI func.gii (but this could also be shape.gii, .asc or as matrix in a text file); the output of the registration will also be smoothed using a kernel of standard deviation 2. The registration will also be stopped after two cycles or registration levels irrespective of the number of levels specified in the configuration file.

Configuration Files

Configuration files modify all tunable parameters of the registration. For a full list of all registration parameters you can enter:

• msm -p

Some parameters require inputs for every stage of the registration, and are input as comma separated lists e.g. --lambda=0,0.1,0.2,0.3 (for four levels). These are:

• --lambda Lambda weights the contribution of regulariser relative to the similarity force. We have found that we typically have to increase regularisation slightly when control point grid resolution increases. This is due to the sensitivity of the regularisation method to the spacing of the end points of discrete transformations which is not fully corrected for.

• --opt optimisation approach. Choice of: AFFINE or DISCRETE (default)

• --simval choice of similarity measure for each stage of the registration. There is a choice of 1) SSD; 2) correlation (default); 3) NMI; 5) alpha entropy (only for multivariate data). SSD is enforced for affine alignment. For discrete optimisation we strongly recommend correlation for all datasets. The current implementations of SSD and NMI do not in general work well in the discrete case, and we do not advise using them.

• --it controls the number of iterations at each resolution. In general affine registration will require in excess of 30 iterations. Discrete optimisation will work well with only 3-5 iterations.

• --sigma_in input smoothing: this changes the smoothing kernel's standard deviation (default --sigma_in=2,2,2 for very noisy data we suggest you smooth more)

• --sigma_ref reference smoothing: this is set equal to sigma_in by default, but you could smooth the reference less than the input if you are using an average template.

• --datagrid In MSM data is typically downsampled from the high resolution surfaces input_mesh and reference_mesh onto a regular (equally spaced vertex) grid. This speeds up the running of MSM without appreciably downgrading the quality of the alignment. These grids are formed from subdivision of a icosahedron and are coded in terms of the number of resamplings performed. For datagrids we typically we use 10K grids, which have code 5. If parameter = 0 then the native mesh is used.

• --CPgrid The Control Point (CP) Grid is a low resolution mesh which controls the warp of the input mesh to the reference. At each iteration of the registration, the CP Grid can undergo one of a discrete set of deformations, where end points are defined by points on the sampling grid. By default the first level of the discrete optimisation is started for a 162 vertex (code 2) and this is increased by one for each level.

• --SGgrid The Sampling Grid resolution determines the maximum number of discrete deformations available to each CP and thus the maximum possible accuracy of the registration at that stage of the registration. It is set 2 levels higher than the CP resolution by default.

• --aKNN Number of k-nearest neighbours used for estimation of similarity graph used during calculation of the alpha entropy measure (default 5)

Other parameters need only be specified once:

• --excl Ignore a predefined exclusion region when resampling the data

• --cutthr The exclusion region is defined for all intensities between a certain intensity range. It needs two values as upper and lower thresholds for defining cut vertices. As it is usually used to mask the cut on the medial wall (which is zero valued) these values are typically --cutthr=0,0.0001

• --mInt Method used for interpolation of the warp from the control point grid to the input mesh, options: Thin Plate Spline (TPS) or barycentric (BARY). Although TPS was used int he paper, it has since been found that barycentric interpolation is more stable to large distortions.

• --log log transform and normalise the data

• --IN Normalize intensity ranges using histogram matching

• --VN Variance normalize data when using alpha entropy

We supply a series of configuration files, each tuned to work with different (sulcal depth, myelin, and RSN) data. An example of the sulcal depth config file (which also forms the default parameterisation in the absence of any supplied configuration file) is:

• --simval=1,2,2,2
  --sigma_in=4,4,2,1
  --sigma_ref=2,2,1,1
  --lambda=0,0.1,0.2,0.3
  --it=50,3,3,3
  --opt=AFFINE,DISCRETE,DISCRETE,DISCRETE
  --CPgrid=0,2,3,4
  --SGgrid=0,4,5,6
  --datagrid=4,4,5,6
  --IN
  

The comma separated lists above represent parameters per level, and the number of resolution levels run by msm can be controlled by the length of the lists specified here. Registration may also be initialised using an affine alignment step, run as an additional level at the beginning. Therefore, the above case is stating that the registration should run one affine step using: SSD as a similarity measure, 50 iterations, input mesh smoothing 4mm, reference mesh smoothing 2mm, on a data grid of resolution 2562 vertices; Following this discrete optimisation is run over 3 levels with 3 iterations at each level, using control point grid resolutions 162, 642, and 2562, where the sampling grid resolution is 2 subdivisions above this, and the data grids have resolution: 2562, 10242 and 40962 vertices. Smoothing is applied to the source image as 4, 2, then 1mm sigma smoothing kernels, and to the reference image as 2, 1 and 1mmm smoothing. --IN indicates that the source intensity distribution is matched to the target intensity distribution, once at the beginning of the registration. NOTE as affine registration only implements the following parameters: --opt, --simval, --it, --sigma_in, --sigma_ref, --IN, --VN, --scale, --excl, for other multi level parameters a zero value should be supplied for the AFFINE stage.

Transforming Unseen Data

References