Package: regfusion
reg-fusionProjection of a central sulcus probability map using the RF-ANTs approach (right hemisphere shown).This is a Python implementation ofWu et al (2018)'s registration fusion methodsto project MRI data from standard volumetric coordinates, either MNI152 or Colin27, to Freesurfer's fsaverage. This tool alreadyavailable in the original MATLAB-based versionprovided byWu et al, which works well out of the box. However, given Python's increasing stake in neuroimaging analysis, a pure Python version may be useful.A huge thank you toWu et alfor making their excellent tool openly available! If you use this package,please cite the original:Wu J, Ngo GH, Greve DN, Li J, He T, Fischl B, Eickhoff SB, Yeo BTT.Accurate nonlinear mapping between MNI volumetric and FreeSurfer surface coordinate systems,Human Brain Mapping39:3793–3808, 2018.InstallationThis package requires Python 3. Installingregfusionis simple withpip:pip install regfusionIf you want to buildregfusiondirectly from source code, use the following code:git clone https://github.com/danjgale/reg-fusion
cd reg-fusion
python setup.py installCommand-line interfaceRegistration fusion can be ran on the command-line usingregfusion. The flags correspond to the original implemenation, with the exception of-t, which is specific toregfusion(see Notes).usage: regfusion [-h] [-s input_vol] [-o output_dir] [-p template_type] [-r RF_type] [-i interp] [-t out_type]

optional arguments:
  -h, --help        show this help message and exit
  -s input_vol      Absolute path to input volume. Input should be in nifti format
  -o output_dir     Absolute path to output directory
  -p template_type  Type of volumetric template used in index files. Use MNI152_orig or Colin27_orig when -r is RF_ANTs. Use MNI152_norm or Colin27_norm when
                    -r is RF_M3Z. Otherwise, an exception is raised. Ensure that the template matches the standard space of -i (i.e., use MNI152_* if -i is
                    in MNI152-space). Default: MNI152_orig
  -r RF_type        Type of Registration Fusion approaches used to generate the mappings (RF_M3Z or RF_ANTs). RF_M3Z is recommended if data was registered
                    from subject's space to the volumetric atlas space using FreeSurfer. RF_ANTs is recommended if such registrations were carried out using
                    other tools, especially ANTs. Default: RF_ANTs
  -i interp         Interpolation (linear or nearest). If -g is label.gii, then interpolation is always set to nearest and a warning is raised. Default:
                    linear
  -t out_type       File type of surface files. nii.gz is true to the original Wu et al (2018) implementation. Note that gifti formats, either func.gii or
                    label.gii, are often preferred. Default: nii.gzPython APIThe CLI simply calls the main underlying function,vol_to_fsaverage. This function can imported directly in Python. In addition to saving the files toout_dir, the absolute file paths of the left and right surface files are returned.vol_to_fsaverage(input_img, out_dir, template_type='MNI152_orig', 
                 rf_type='RF_ANTs', interp='linear', out_type='nii.gz'):

    Project volumetric data in standard space (MNI152 or Colin27) to 
    fsaverage 

    Parameters
    ----------
    input_img : niimg-like
        Input image in standard space (i.e. MNI152 or Colin27)
    out_dir : str
        Path to output directory (does not need to already exist)
    template_type : {'MNI152_orig', 'Colin27_orig', 'MNI152_norm', 'Colin27_norm'}
        Type of volumetric template used in index files. Use 'MNI152_orig' or 
        'Colin27_orig' when `rf_type` is 'RF_ANTs'. Use 'MNI152_norm' or 
        'Colin27_norm' when `rf_type` is 'RF_M3Z'. Otherwise, an exception is 
        raised. Ensure that the template matches the standard space of 
        `input_img` (i.e., use MNI152_* if `input_img` is in MNI152-space). By 
        default 'MNI152_orig'.
    rf_type : {'RF_ANTs', 'RF_M3Z'}
        Type of Registration Fusion approaches used to generate the mappings.
        RF-M3Z is recommended if data was registered from subject's space to 
        the volumetric atlas space using FreeSurfer. RF-ANTs is recommended if 
        such registrations were carried out using other tools, especially 
        ANTs. By default 'RF_ANTs'
    interp : {'linear', 'nearest'}, optional
        Interpolation approach. If `out_type` is 'label.gii', then interpolation 
        is always set to 'nearest'. By default 'linear'
    out_type : {'nii.gz, 'func.gii', 'label.gii'}, optional
        File type of surface files. Default is 'nii.gz', which is true to the 
        original Wu et al (2018) implementation. Note that gifti 
        formats, either 'func.gii' or 'label.gii', are often preferred.

    Returns
    ----------
    str, str
        Absolute paths to left and right hemisphere output files, respectivelyExamples1. MNI to fsaverage (default)For example, the default RF-ANTs implementation (preferred) with MNI data would be:CLI:regfusion-smni_input.nii.gz-ooutputPython:fromregfusionimportvol_to_fsaveragelh,rh=vol_to_fsaverage('mni_input.nii.gz','output')True to the original implementation, two surface files (one each hemisphere) are saved to the output directory with the RF method and template embedded in the file names:output/
  lh.mni_input.allSub_RF_ANTs_MNI152_orig_to_fsaverage.nii.gz
  rh.mni_input.allSub_RF_ANTs_MNI152_orig_to_fsaverage.nii.gz2. MNI to fsaverage (GIfTI)It may be preferred to generate GIfTI files instead of the default NIfTI:CLI:regfusion-smni_input.nii.gz-ooutput-tfunc.giiPython:fromregfusionimportvol_to_fsaveragelh,rh=vol_to_fsaverage('mni_input.nii.gz','output',out_type='func.gii')The output, which will have the appropriate GIfTI file extensions:output/
  lh.mni_input.allSub_RF_ANTs_MNI152_orig_to_fsaverage.func.gii
  rh.mni_input.allSub_RF_ANTs_MNI152_orig_to_fsaverage.func.gii3. Projecting to label.giiShould you wish to project a binary mask (e.g., to display a region of interest), you may consider setting the output type,-t, tolabel.gii. In this case, interpolation,-i, will always be set tonearestto retain the original voxel values/labels. If not explicitly set with-i, interpolation will be overwritten tonearestand warning is raised.For example:CLI:regfusion-smni_input.nii.gz-ooutput-inearest-tlabel.giiPython:fromregfusionimportvol_to_fsaveragelh,rh=vol_to_fsaverage('mni_input.nii.gz','output',interp='nearest',out_type='label.gii')The output, which will have the appropriate GIfTI file extensions:output/
  lh.mni_input.allSub_RF_ANTs_MNI152_orig_to_fsaverage.label.gii
  rh.mni_input.allSub_RF_ANTs_MNI152_orig_to_fsaverage.label.gii4. MNI to fsaverage with RF-M3ZAnd finally, the RF-M3Z method can be used if that is preferred:CLI:regfusion-imni_input.nii.gz-ooutput-pMNI152_norm-rRF_M3ZPython:fromregfusionimportvol_to_fsaveragelh,rh=vol_to_fsaverage('mni_input.nii.gz','output',template_type='MNI152_norm',rf_type='RF_M3Z')The output, with different file names reflecting the method/template used:output/
  lh.mni_input.allSub_RF_M3Z_MNI152_norm_to_fsaverage.nii.gz
  rh.mni_input.allSub_RF_M3Z_MNI152_norm_to_fsaverage.nii.gzNotesregfusionimplements the same two registration fusion approaches byWu et al, and is validated against the original MATLAB version (seetests/). However, there are some differences in the API:regfusiondoes not have the-nflag that determines the number of subjects used to create the average mapping. That is because the standalone scripts of the MATLAB versions only uses all 1490 subjects, and thusregfusiondoes tooregfusiondoes not have the-mflag because no MATLAB is requiredregfusiondoes not have the-fflag because, technically, Freesurfer is not required. However, it is strongly recommended that you have a freely available Freesurfer license because we are ultimately projecting to Freesurfer's fsaverageUnlike the original MATLAB version,regfusionhas a-tflag (out_typeinvol_to_fsaverage; see above for description). The original MATLAB version outputs NIfTI images (regfusiondefault), but this option letsregfusionoutput to GIfTIs, which are generally preferred for surface files. Users are encouraged to set-t/out_typeto one of the GIfTI output types if they find that GIfTIs are more suitable for their needsSome useful things to know:Wu et alshow that RF-ANTs is generally the better approaches of the two, which is why it's the default inregfusion. RF-M3Z seems best-suited if the normalization was performed via Freesurfer.AsWu et alemphasize, theactualbest practice here avoid projecting standard volumetric coordinates (e.g., MNI) to fsaverage altogether. Alternatives include performing all you analyses in subject/native volumetric coordinates and projecting that data to fsaverage, based on Freesurfer'srecon-all. Or, perform analyses directly in fsaverage after runningrecon-all. Projecting data from one standard coordinates space to another is loses precision at each step (seeWu et alfor details). Neverthless, people do this all the time and these registration fusion approaches ensure that these projections are as accurate as possible.Relating to the previous point: If you do project from MNI/Colin coordinates to fsaverage, it's probably a wise idea to find a way to still show your data in volume-space too (e.g., as supplementary figures/material).ReferencesWu J, Ngo GH, Greve DN, Li J, He T, Fischl B, Eickhoff SB, Yeo BTT.Accurate nonlinear mapping between MNI volumetric and FreeSurfer surface coordinate systems,Human Brain Mapping39:3793–3808, 2018.