Python implementation of Wu et al (2018)'s registration fusion

Overview

reg-fusion

logo
Projection of a central sulcus probability map using the RF-ANTs approach (right hemisphere shown).

This is a Python implementation of Wu et al (2018)'s registration fusion methods to project MRI data from standard volumetric coordinates, either MNI152 or Colin27, to Freesurfer's fsaverage. This tool already available in the original MATLAB-based version provided by Wu 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 to Wu et al for 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 Mapping 39:3793–3808, 2018.

Installation

This package requires Python 3. Installing regfusion is simple with pip:

pip install regfusion

If you want to build regfusion directly from source code, use the following code:

git clone https://github.com/danjgale/reg-fusion
cd reg-fusion
python setup.py install

Command-line interface

Registration fusion can be ran on the command-line using regfusion. The flags correspond to the original implemenation, with the exception of -t, which is specific to regfusion (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.gz

Python API

The CLI simply calls the main underlying function, vol_to_fsaverage. This function can imported directly in Python. In addition to saving the files to out_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, respectively

Examples

1. MNI to fsaverage (default)

For example, the default RF-ANTs implementation (preferred) with MNI data would be:

CLI:
regfusion -s mni_input.nii.gz -o output

Python:
from regfusion import vol_to_fsaverage
lh, 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.gz

2. MNI to fsaverage (GIfTI)

It may be preferred to generate GIfTI files instead of the default NIfTI:

CLI:
regfusion -s mni_input.nii.gz -o output -t func.gii

Python:
from regfusion import vol_to_fsaverage
lh, 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.gii

3. Projecting to label.gii

Should you wish to project a binary mask (e.g., to display a region of interest), you may consider setting the output type, -t, to label.gii. In this case, interpolation, -i, will always be set to nearest to retain the original voxel values/labels. If not explicitly set with -i, interpolation will be overwritten to nearest and warning is raised.

For example:

CLI:
regfusion -s mni_input.nii.gz -o output -i nearest -t label.gii

Python:
from regfusion import vol_to_fsaverage
lh, 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.gii

4. MNI to fsaverage with RF-M3Z

And finally, the RF-M3Z method can be used if that is preferred:

CLI:
regfusion -i mni_input.nii.gz -o output -p MNI152_norm -r RF_M3Z

Python:
from regfusion import vol_to_fsaverage
lh, 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.gz

Notes

regfusion implements the same two registration fusion approaches by Wu et al, and is validated against the original MATLAB version (see tests/). However, there are some differences in the API:

  • regfusion does not have the -n flag 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 thus regfusion does too
  • regfusion does not have the -m flag because no MATLAB is required
  • regfusion does not have the -f flag 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 fsaverage
  • Unlike the original MATLAB version, regfusion has a -t flag (out_type in vol_to_fsaverage; see above for description). The original MATLAB version outputs NIfTI images (regfusion default), but this option lets regfusion output to GIfTIs, which are generally preferred for surface files. Users are encouraged to set -t/out_type to one of the GIfTI output types if they find that GIfTIs are more suitable for their needs

Some useful things to know:

  • Wu et al show that RF-ANTs is generally the better approaches of the two, which is why it's the default in regfusion. RF-M3Z seems best-suited if the normalization was performed via Freesurfer.
  • As Wu et al emphasize, the actual best 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's recon-all. Or, perform analyses directly in fsaverage after running recon-all. Projecting data from one standard coordinates space to another is loses precision at each step (see Wu et al for 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).

References

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 Mapping 39:3793–3808, 2018.

Owner
Dan Gale
Neuroscience PhD candidate with an interest in data science and software development.
Dan Gale
Statistical-Rethinking-with-Python-and-PyMC3 - Python/PyMC3 port of the examples in " Statistical Rethinking A Bayesian Course with Examples in R and Stan" by Richard McElreath

Statistical Rethinking with Python and PyMC3 This repository has been deprecated in favour of this one, please check that repository for updates, for

Osvaldo Martin 786 Dec 29, 2022
This is a JAX implementation of Neural Radiance Fields for learning purposes.

learn-nerf This is a JAX implementation of Neural Radiance Fields for learning purposes. I've been curious about NeRF and its follow-up work for a whi

Alex Nichol 62 Dec 20, 2022
SparseInst: Sparse Instance Activation for Real-Time Instance Segmentation, CVPR 2022

SparseInst 🚀 A simple framework for real-time instance segmentation, CVPR 2022 by Tianheng Cheng, Xinggang Wang†, Shaoyu Chen, Wenqiang Zhang, Qian Z

Hust Visual Learning Team 458 Jan 05, 2023
Real-time analysis of intracranial neurophysiology recordings.

py_neuromodulation Click this button to run the "Tutorial ML with py_neuro" notebooks: The py_neuromodulation toolbox allows for real time capable pro

Interventional Cognitive Neuromodulation - Neumann Lab Berlin 15 Nov 03, 2022
Diffgram - Supervised Learning Data Platform

Data Annotation, Data Labeling, Annotation Tooling, Training Data for Machine Learning

Diffgram 1.6k Jan 07, 2023
A Lightweight Experiment & Resource Monitoring Tool 📺

Lightweight Experiment & Resource Monitoring 📺 "Did I already run this experiment before? How many resources are currently available on my cluster?"

170 Dec 28, 2022
Demo code for paper "Learning optical flow from still images", CVPR 2021.

Depthstillation Demo code for "Learning optical flow from still images", CVPR 2021. [Project page] - [Paper] - [Supplementary] This code is provided t

130 Dec 25, 2022
Text to image synthesis using thought vectors

Text To Image Synthesis Using Thought Vectors This is an experimental tensorflow implementation of synthesizing images from captions using Skip Though

Paarth Neekhara 2.1k Jan 05, 2023
Lowest memory consumption and second shortest runtime in NTIRE 2022 challenge on Efficient Super-Resolution

FMEN Lowest memory consumption and second shortest runtime in NTIRE 2022 on Efficient Super-Resolution. Our paper: Fast and Memory-Efficient Network T

33 Dec 01, 2022
Decision Transformer: A brand new Offline RL Pattern

DecisionTransformer_StepbyStep Intro Decision Transformer: A brand new Offline RL Pattern. 这是关于NeurIPS 2021 热门论文Decision Transformer的复现。 👍 原文地址: Deci

Irving 14 Nov 22, 2022
Visual Memorability for Robotic Interestingness via Unsupervised Online Learning (ECCV 2020 Oral and TRO)

Visual Interestingness Refer to the project description for more details. This code based on the following paper. Chen Wang, Yuheng Qiu, Wenshan Wang,

Chen Wang 36 Sep 08, 2022
Tightness-aware Evaluation Protocol for Scene Text Detection

TIoU-metric Release on 27/03/2019. This repository is built on the ICDAR 2015 evaluation code. If you propose a better metric and require further eval

Yuliang Liu 206 Nov 18, 2022
Code for the paper "Improving Vision-and-Language Navigation with Image-Text Pairs from the Web" (ECCV 2020)

Improving Vision-and-Language Navigation with Image-Text Pairs from the Web Arjun Majumdar, Ayush Shrivastava, Stefan Lee, Peter Anderson, Devi Parikh

Arjun Majumdar 44 Dec 14, 2022
Indoor Panorama Planar 3D Reconstruction via Divide and Conquer

HV-plane reconstruction from a single 360 image Code for our paper in CVPR 2021: Indoor Panorama Planar 3D Reconstruction via Divide and Conquer (pape

sunset 36 Jan 03, 2023
FactSeg: Foreground Activation Driven Small Object Semantic Segmentation in Large-Scale Remote Sensing Imagery (TGRS)

FactSeg: Foreground Activation Driven Small Object Semantic Segmentation in Large-Scale Remote Sensing Imagery by Ailong Ma, Junjue Wang*, Yanfei Zhon

Kingdrone 43 Jan 05, 2023
GANfolk: Using AI to create portraits of fictional people to sell as NFTs

GANfolk are AI-generated renderings of fictional people. Each image in the collection was created by a pair of Generative Adversarial Networks (GANs) with names and backstories also created with AI.

Robert A. Gonsalves 32 Dec 02, 2022
HeartRate detector with ArduinoandPython - Use Arduino and Python create a heartrate detector.

Syllabus of Contents Syllabus of Contents Introduction Of Project Features Develop With Python code introduction Installation License Developer Contac

1 Jan 05, 2022
Telegram chatbot created with deep learning model (LSTM) and telebot library.

Telegram chatbot Telegram chatbot created with deep learning model (LSTM) and telebot library. Description This program will allow you to create very

1 Jan 04, 2022
A Deep Learning based project for creating line art portraits.

ArtLine The main aim of the project is to create amazing line art portraits. Sounds Intresting,let's get to the pictures!! Model-(Smooth) Model-(Quali

Vijish Madhavan 3.3k Jan 07, 2023
Fbone (Flask bone) is a Flask (Python microframework) starter/template/bootstrap/boilerplate application.

Fbone (Flask bone) is a Flask (Python microframework) starter/template/bootstrap/boilerplate application.

Wilson 1.7k Dec 30, 2022