How to warp¶

Running BigBrainWarp¶

To run BigBrainWarp using docker, you should mount a working directory (using the -v argument). It is expected that your input data is housed in the mounted directory. The output will also be deposited in that directory.

# with docker (change the path to the local location of the mount accordingly)
docker run -it --rm -v /local/directory/with/data/:/BigBrainWarp/mount \
    caseypaquola/bigbrainwarp bigbrainwarp

# without docker
bigbrainwarp

The following arguments can be used with BigBrainWarp

Parameter	Description	Conditions	Options
in_space	Space of input data	Required	bigbrain, bigbrainsym, icbm, fsaverage, fs_LR
out_space	Space of output data	Required	bigbrain, bigbrainsym, icbm, fsaverage, fs_LR
wd	Path to working directory	Required
desc	Descriptor that determines the naming of the output. See more details in Naming Conventions	Required.
in_vol	Full path to input data, whole brain volume.	Requires either in_vol, or in_lh and in_rh	Permitted formats: mnc, nii or nii.gz
ih_lh	Full path to input data, left hemisphere surface.	Requires either in_vol, or in_lh and in_rh	Permitted formats: label.gii, annot, shape.gii, curv or txt
ih_rh	Full path to input data, left hemisphere surface.	Requires either in_vol, or in_lh and in_rh	Permitted formats: label.gii, annot, shape.gii, curv or txt
interp	Interpolation method	Required for in_vol.	Optional for txt input. Not permitted for other surface inputs. For in_vol, can be trilinear (default), tricubic, nearest or sinc. For txt, can be linear or nearest
out_type	Specifies whether output in surface or volume space	Optional function for bigbrain and bigbrainsym output. Otherwise, defaults to the same type as the input.	surface, volume
out_res	Resolution of output volume	Optional where out_type is volume. Default is 1.	Value provided in mm
out_dens	Density of output mesh	Optional where out_type is surface. Default is 164	For fs_LR, 164 or 32

What’s under the hood?¶

The BigBrainWarp function currently wraps the following range of transformations. In C), the output template is not specified as it is assumed that either the input or the output is BigBrain.

Each coloured path represents a distinct script called by bigbrainwarp. The method for each transformation is as follows:

Input type	Input template	Output type	Colour	Method
Volume	BigBrain	Volume	Dark pink	Nonlinear volume-based transformation (Xiao et al.,)
Volume	BigBrain	Surface	Light pink	Volume-to-surface (HCP workbench) then multi-modal surface matching (Lewis et al., 2020)
Volume	ICBM152	Volume	Dark orange	Nonlinear volume-based transformation (Xiao et al.,)
Volume	ICBM152	Surface	Light orange	Nonlinear volume-based transformation (Xiao et al.,) then volume-to-surface (HCP workbench)
Surface	BigBrain	Volume	Dark green	Surface-to-volume (HCP workbench) then nonlinear volume-based transformation (Xiao et al.,)
Surface	BigBrain	Surface	Light green	Multi-modal surface matching (Lewis et al., 2020)
Surface	fsaverage	Volume	Dark blue	Multi-modal surface matching (Lewis et al., 2020) then surface-to-volume (HCP workbench)
Surface	fsaverage	Surface	Light blue	Multi-modal surface matching (Lewis et al., 2020)

Example transformations in volume space¶

      # for example, transformation of a bigbrain to icbm can take the form with a local installation
      bigbrainwarp --in_vol data.nii --in_space bigbrain  --interp trilinear --out_space icbm --out_res 0.5 --desc data --wd /project/
# or with the docker version - note how the working input volume is preprended with the "mount/" and the working directory is set to "mount"
docker run -it --rm -v /project/:/BigBrainWarp/mount caseypaquola/bigbrainwarp \
bigbrainwarp --in_vol mount/data.nii --in_space bigbrain  --interp trilinear --out_space icbm --out_res 0.5 --desc data --wd mount

      # in contrast, transformation from icbm to bigbrainsym could be
      bigbrainwarp --in_vol data.mnc --in_space icbm  --interp sinc --out_space bigbrainsym --desc data --wd /project/

BigBrainWarp utilises a recently published nonlinear transformation Xiao et al., (2019) If you use volume-based transformations in BigBrainWarp, please cite: Xiao, Y., et al. ‘An accurate registration of the BigBrain dataset with the MNI PD25 and ICBM152 atlases’. Sci Data 6, 210 (2019). https://doi.org/10.1038/s41597-019-0217-0

Example transformations for surface-based data¶

Surface-based transformation can be enacted using multi-modal surface matching; a spherical registration approach. Ongoing work by Lewis et al., involves optimisation of registration surafces between BigBrain and standard surface templates. These are available at ftp://bigbrain.loris.ca/BigBrainRelease.2015/BigBrainWarp_Support. More details on procedure can be also found on the following poster and slides. The functions currently support fsaverage and fs_LR as standard imaging templates for input or output.

      # for example, transformation of a bigbrain to fsaverage can take the form
      bigbrainwarp --in_lh lh.data.label.gii --in_rh rh.data.label.gii --in_space bigbrain --out_space fsaverage --desc data --wd /project/
# or with the docker version - note how the working inputs are preprended with the "mount/" and the working directory is set to "mount"
docker run -it --rm -v /project/:/BigBrainWarp/mount caseypaquola/bigbrainwarp \
bigbrainwarp --in_lh mount/lh.data.label.gii --in_rh mount/rh.data.label.gii --in_space bigbrain --out_space fsaverage --desc data --wd mount

      # in contrast, transformation from icbm to bigbrainsym could be
      bigbrainwarp --in_lh lh.data.label.txt --in_rh rh.data.label.txt --in_space fs_LR --interp linear --out_space bigbrain --out_dens 32 --desc data --wd /project/

If you use surface-based transformations in BigBrainWarp, please cite: Lewis, L.B., et al. ‘A multimodal surface matching (MSM) surface registration pipeline to bridge atlases across the MNI and the Freesurfer/Human Connectome Project Worlds’ OHBM, Virtual (2020)