smriprep.interfaces.msm module

class smriprep.interfaces.msm.MSM(command=None, terminal_output=None, write_cmdline=False, **inputs)[source]

Bases: CommandLine

Wrapped executable: msm.

MSM (Multimodal Surface Matching) is a tool for registering cortical surfaces. The tool has been developed and tested using FreeSurfer extracted surfaces. However, in principle the tool with work with any cortical surface extraction method provided the surfaces can be mapped to the sphere. The key advantage of the method is that alignment may be driven using a wide variety of univariate (sulcal depth, curvature, myelin), multivariate (Task fMRI, or Resting State Networks) or multimodal (combinations of folding, myelin and fMRI) feature sets.

The main MSM tool is currently run from the command line using the program msm. This enables fast alignment of spherical cortical surfaces by utilising a fast discrete optimisation framework (FastPD Komodakis 2007), which significantly reduces the search space of possible deformations for each vertex, and allows flexibility with regards to the choice of similarity metric used to match the images.

>>> msm = MSM(
...   config_file=load('msm/MSMSulcStrainFinalconf'),
...   in_mesh='sub-01_hemi-L_sphere.surf.gii',
...   reference_mesh='tpl-fsaverage_hemi-L_den-164k_desc-std_sphere.surf.gii',
...   in_data='sub-01_hemi-L_sulc.shape.gii',
...   reference_data='tpl-fsaverage_hemi-L_den-164k_sulc.shape.gii',
...   out_base='L.',
... )
>>> msm.cmdline  
'msm --conf=.../MSMSulcStrainFinalconf     --indata=sub-01_hemi-L_sulc.shape.gii     --inmesh=sub-01_hemi-L_sphere.surf.gii     --out=L.     --refdata=tpl-fsaverage_hemi-L_den-164k_sulc.shape.gii     --refmesh=tpl-fsaverage_hemi-L_den-164k_desc-std_sphere.surf.gii'
Mandatory Inputs:

in_mesh (a pathlike object or string representing an existing file) – Input mesh (available formats: VTK, ASCII, GIFTI). Needs to be a sphere. Maps to a command-line argument: --inmesh=%s.

Optional Inputs:

  • args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

  • config_file (a pathlike object or string representing an existing file) – Configuration file. Maps to a command-line argument: --conf=%s.

  • environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})

  • in_data (a pathlike object or string representing an existing file) – Scalar or multivariate data for input - can be ASCII (.asc,.dpv,.txt) or GIFTI (.func.gii or .shape.gii). Maps to a command-line argument: --indata=%s.

  • in_register (a pathlike object or string representing an existing file) – Input mesh at data resolution. Used to resample data onto input mesh if data is supplied at a different resolution. Note this mesh HAS to be in alignment with either the input_mesh of (if supplied) the transformed source mesh. Use with supreme caution. Maps to a command-line argument: --in_register=%s.

  • in_weight (a pathlike object or string representing an existing file) – Cost function weighting for input - weights data in these vertices when calculating similarity (ASCII or GIFTI). Can be multivariate provided dimension equals that of data. Maps to a command-line argument: --inweight=%s.

  • levels (an integer) – Number of resolution levels (default = number of resolution levels specified by –opt in config file). Maps to a command-line argument: --levels=%d.

  • out_base (a pathlike object or string representing a file) – Output basename. Maps to a command-line argument: --out=%s.

  • output_format (‘GIFTI’ or ‘VTK’ or ‘ASCII’ or ‘ASCII_MAT’) – Format of output files. Maps to a command-line argument: --format=%s.

  • reference_data (a pathlike object or string representing an existing file) – Scalar or multivariate data for reference - can be ASCII (.asc,.dpv,.txt) or GIFTI (.func.gii or .shape.gii). Maps to a command-line argument: --refdata=%s.

  • reference_mesh (a pathlike object or string representing an existing file) – Reference mesh (available formats: VTK, ASCII, GIFTI). Needs to be a sphere.If not included algorithm assumes reference mesh is equivalent input. Maps to a command-line argument: --refmesh=%s.

  • reference_weight (a pathlike object or string representing an existing file) – Cost function weighting for reference - weights data in these vertices when calculating similarity (ASCII or GIFTI). Can be multivariate provided dimension equals that of data. Maps to a command-line argument: --refweight=%s.

  • smooth_output_sigma (an integer) – Smooth transformed output with this sigma (default=0). Maps to a command-line argument: --smoothout=%d.

  • transformed_mesh (a pathlike object or string representing an existing file) – Transformed source mesh (output of a previous registration). Use this to initialise the current registration. Maps to a command-line argument: --trans=%s.

  • verbose (a boolean) – Switch on diagnostic messages. Maps to a command-line argument: --verbose.

Outputs:

  • downsampled_warped_mesh (a pathlike object or string representing a file) – A downsampled version of the warped_mesh where the resolution of this mesh will be equivalent to the resolution of the final datamesh.

  • warped_data (a pathlike object or string representing a file) – The input data passed through the MSM warp and projected onto the target surface.

  • warped_mesh (a pathlike object or string representing a file) – The warped input mesh (i.e., new vertex locations - this capture the warp field, much like a _warp.nii.gz file would for volumetric warps created by FNIRT).