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. 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 (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

• ~/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)

A Note on Post Processing HCP data

A very important point to remember if using data processed through the HCP pipeline is that the native and FS_LR surfaces are rotated relative to one another. Therefore, if you are using surfaces extracted using these surfaces it is necessary to run the preprocessing script PreSulc.sh. This will output a file ending sphere.native.rot.surf.gii which is the native mesh rotated into alignment with the FS_LR surface using an affine transformed linearly approximated from the FreeSurfer transformed mesh.

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.

Configuration Files

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

• msm -p

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 () is:

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

Transforming Unseen Data

sub point 2