Plotting brain images with ggplot — ggBrain • ggBrain

ggBrain creates ggplot brain images with minimal user input. This function calls getBrainFrame, which generates a data frame for use in ggplot objects. Aesthetic changes to the resulting figures can be made with standard ggplot functions, such as scale_fill_gradient2. The getBrainFrame function can also be directly accessed by the user, for a deeper control of aesthetics.

ggBrain(brains, template = NULL, mar = 1, mar_ind, row_ind = rep(1,
  length(mar_ind)), col_ind = rep(1, length(mar_ind)),
  col_template = rev(brewer.pal(8, "Greys")), type = "signed",
  binary_color = "darkred", combine_legend = TRUE, breaks_legend = 8,
  digits_legend = 2, signed_colors = brewer.pal(9, "RdYlBu")[c(1, 9)],
  fix_ratio = TRUE, tri_planar = FALSE, lines_color = "white",
  center_coords = TRUE, lines_mat = NULL, ...)

getBrainFrame(brains, mask = NULL, mar = 1, mar_ind, row_ind = rep(1,
  length(mar_ind)), col_ind = rep(1, length(mar_ind)), brain_ind = rep(1,
  length(mar_ind)), all_brain_and_time_inds_one = FALSE, time = rep(1,
  length(mar_ind)), center_coords = FALSE)

Arguments

brains	A list of 4-D arrays of brain images, with time on the fourth dimension. Alternatively, a list of 3-D arrays, a single 3-D, or a single 4-D array can be entered.
template	A 3-D structural brain image over which to plot voxelwise statistics, such as p-values or seed correlations.
mar	a numeric vector. The length of this vector should be equal to the number of panels in the figure. The \(j^{th}\) element of `mar` tells which margin of the image to slice over, for the \(j^{th}\) panel (see examples).
mar_ind	a numeric vector of the same length as `mar`. The \(j^{th}\) element of `mar_ind` tells the slice number to be shown in the \(j^{th}\) panel.
row_ind	a numeric vector of the same length as `mar`, which partially determines the layout of the image plots. The \(j^{th}\) element of `row_ind` tells the row number where the \(j^{th}\) panel should be positioned.
col_ind	a numeric vector of the same length as `mar`, which partially determines the layout of the image plots. The \(j^{th}\) element of `row_ind` tells the column number where the \(j^{th}\) panel should be positioned.
col_template	a vector of colors to be used for displaying the template brain image.
type	the type of brain image to be shown, either 'signed', 'positive', 'binary' or 'structural'. These types should be used when the objects in `brains` are, respectively, images of voxelwise statistics that can be positive or negative (e.g. seed correlations); images of voxelwise statistics that are all positive (e.g. p-values); binary masks to be shown on top of tempaltes; or structural brain images that do not contain voxelwise statistics. When setting `type='structural'` there is no need to input a template brain image.
binary_color	the color to be used for plotting either binary masks or voxelwise, positive statistics (e.g. p-values). This argument will be used when `type` is set to either 'positive' or 'binary'. The color of 'signed' type figures can be changed using the standard ggplot functions for `fill` (see `scale_fill_gradient2`).
combine_legend	when `type` is set to `'signed'`, the default approach `ggBrain` takes is to map absolute value of the voxelwise statistic to alpha blending, and sign of the voxelwise statistic to fill. This results in two separate legends. When the `combine_legend` is set to TRUE, `ggBrain` creates a new custom scale that combines both binary coloring for sign, and gradual alpha blending for absolute value. Each voxel is binned according to it's value. The legend created shows the upper bounds for each bin. This argument is only used when `type` is set to `'signed'`.
breaks_legend	the number of bins to use in creating a combined legend. This is only used when `combine_legend` is set to `TRUE`.
digits_legend	the number of digits to be used in the combined legend for 'signed' plots. This is only used when `combine_legend` is set to `TRUE`.
signed_colors	a vector of length two, with entries corresponding to the colors for negative and positive values of the overlaying voxelwise statistic. This argument is only used when `type` is set to `'signed'`.
fix_ratio	whether the aspect ratio should be fixed, to avoid warping of images.
tri_planar	a special mode for simultaneously plotting saggital, transverse, and coronal brain slices. If set to TRUE, a cross-hair will be plotted to show correspondance between these images (see examples).
lines_color	color of the lines defined by `lines_mat`, or the lines defined by using `tri_planar=TRUE`.
center_coords	whether the brains should be centered. If TRUE, axis tick marks will not be shown. If FALSE, axis tick marks will correspond to slice number
lines_mat	a matrix with 3 columns, and one row for each line to be added to the figure. Each row of `lines_mat` contains a triplet of values, with the first element telling which panel the line should be placed in, the second element containing the margin to plot over, and the third element telling the slice index where the line should be placed. If `NULL`, no lines will be plotted.
...	Parameters passed from `ggBrain` to `getBrainFrame`, such as `time` and `brain_ind`.
mask	A 3-D binary array of which voxels in the image to plot. If no mask is provided, the mask is set to be all voxels not equal to `NA`.
brain_ind	a vector of the same length as `mar`. The \(j^{th}\) element of `brain_ind` tells the index number of the appropriate brain image to be plotted in the \(j^{th}\) panel, from the list `brains`.
all_brain_and_time_inds_one	a parameter specific to `getBrainFrame`, which can generally be ignored by the user. This arguments helps `getBrainFrame` be called from different contexts within `ggBrain`, particularly when contructing ggplot objects for the template brain. If set to `TRUE`, all elements of `brain_ind` and `time` will be forced to equal 1.
time	a vector of the same length as `mar`, used for plotting snapshots of 4-D fMRI data over time. The \(j^{th}\) element of `time` tells the time index to be used for the \(j^{th}\) panel.

Value

ggBrain returns a ggplot object showing the desired brain images. Further aesthetic changes to the plotting can be added to this ggplot object using the usual ggplot notation (see examples). getBrainFrame outputs a "long" dataframe which can be used in ggplot objects. Accessing this dataframe directly allows the users to have more control over the plotting procedure hard-coded by ggBrain.

Examples

if (FALSE) {


#####################
# Load data
#####################

library(oro.nifti)

s_map1<-readNIfTI(system.file('seed_corr_1.nii.gz', package='ggBrain'))
s_map2<-readNIfTI(system.file('seed_corr_2.nii.gz', package='ggBrain'))
template <- readNIfTI(system.file('template.nii.gz', package='ggBrain'))
mask <- readNIfTI(system.file('brain_mask.nii.gz', package='ggBrain'))
seed_mask <- readNIfTI(system.file('seed_mask.nii.gz', package='ggBrain'))
nii1_trunc <- readNIfTI(system.file('subj_trunc_1.nii.gz', package='ggBrain'))


library(brainR)

hd_template <- readNIfTI(system.file("MNI152_T1_1mm_brain.nii.gz", package="brainR"))





#####################
# Generate plots
#####################

library(ggplot2)

###############
# Simple examples, just one plot

# structural image (type = 'structural')
dd<-ggBrain(brains=hd_template,mask=hd_template>0,mar=3,
mar_ind=93,type='structural')
dd
#now add aethetic changes with conventional ggplot code.
dd + scale_fill_continuous(low="black", high="white")+ theme_black_bg()

# seed correlation (type = 'signed')
dd<-ggBrain(template=template,brains=s_map1,mask=mask,mar=3,
mar_ind=30,type='signed')
dd

# positive voxelwise statistics (type='positive').
# Here we use absolute value of seed correlation,
# but a p-value map might also be applied.
dd<-ggBrain(template=template,brains=abs(s_map1),mask=mask,
mar=3,mar_ind=30,type='positive')
dd + theme_black_bg() + scale_alpha(range=c(0,1))
#note, for type='signed', a scale is already included

# Further customization can be done by using
# getBrainFrame directly
bf<-getBrainFrame(brains=hd_template,mar=3,mar_ind=93,
mask=hd_template>0,center_coords=FALSE)
ggplot() +
geom_tile(data=bf, aes(x=row,y=col,fill=value)) +
facet_grid(row_ind~col_ind)+
                theme_black_bg()+labs(x='',y='')+coord_fixed(ratio = 1)


# tri_planar basic example, cross-hairs show correspondence across plots
dd<-ggBrain(brains=s_map1,template=template,
        mar =           c(1,2,3),
        mar_ind =       c(37,18,30),
        row_ind=        c(1,1,2),
        col_ind=        c(2,1,1),
        tri_planar=TRUE, lines_color='black',mask=mask)
dd + theme_bw() +theme_no_ticks()


###################
# use grid.arrange to show the seed mask and the
# seed correlation.
# Since these are on different scales, we use
# grid.arrange to show them separately.
mar   =   c(1,2,3)
col_ind = factor(c(1,2,3),labels=c('Saggital','Coronal','Transverse'))
row_ind = c(1,1,1)
mar_ind=  c(37,18,30)

dd_mask<-ggBrain(brains=seed_mask,template=template,mar=mar,mar_ind=mar_ind,row_ind=row_ind,
                col_ind=col_ind,type='binary',binary_color='black',tri_planar=TRUE,mask=mask)+
        labs(alpha='Seed mask')+theme_black_bg()


dd_1<-ggBrain(brains=s_map1,template=template,mar=mar,mar_ind=mar_ind,row_ind=row_ind,
                col_ind=col_ind,tri_planar=TRUE,mask=mask) + theme_black_bg()

library(gridExtra)
grid.arrange(dd_mask,dd_1)


# We can also show two seed correlation maps
# from two different subjects. Note, these maps
# are on the same scale, as correlations are
# standardized
dd<-ggBrain(brains=list(s_map1,s_map2),
        brain_ind=c(1,1,1,2,2,2),
        template=template,
        mar=c(1,2,3,1,2,3),
        mar_ind=c(37,18,30,37,18,30),
        row_ind=c('Subject 1','Subject 1','Subject 1','Subject 2','Subject 2','Subject 2'),
        col_ind=factor(c(1,2,3,1,2,3),labels=c('Saggital','Coronal','Transverse')),
        mask=mask)
dd + ggtitle('Seed correlations for two subjects')+ theme_black_bg()



###################
# row_ind and col_ind can be used to look at
# several slices

# instead of inputting the mask directly, we
# can set the masked out voxels to NA
hd_template_masked<-hd_template
hd_template_masked[hd_template_masked==0]<-NA

dd<-ggBrain(brains=hd_template_masked,
        mar=rep(3,8),
        mar_ind=floor(seq(140,50,length=8)),
        col_ind=c(1,1,1,1,2,2,2,2),
        row_ind=c(1,2,3,4,1,2,3,4),
        type='structural')
dd+ theme_black_bg()



# We can also add a key to the above type of plot,
# using the lines_mat argument
mar=c(3,3,3,3,3,3,3,1)
mar_ind=c(floor(seq(140,50,length=7)),88)
col_ind=c(1,1,1,1,2,2,2,2)
row_ind=c(1,2,3,4,1,2,3,4)
lines_mat<-cbind(8,mar,mar_ind)[1:7,]

dd<-ggBrain(brains=hd_template,mar=mar,mar_ind=mar_ind,row_ind=row_ind,col_ind=col_ind,
                mask=hd_template>0,type='structural',lines_mat=lines_mat)


dd+ theme_black_bg()



# The same type of plots can be made for
# seed correlations
mar_ind=c(floor(seq(50,20,length=7)),30) #reduce dimensions
# to match fMRI data

lines_mat<-cbind(8,mar,mar_ind)[1:7,]

dd<-ggBrain(brains=s_map1,template=template,mar=mar,mar_ind=mar_ind,row_ind=row_ind,
                col_ind=col_ind,mask=mask,lines_mat=lines_mat)

dd + theme_black_bg()



# We can also plot fMRI activation over time
dd<-ggBrain(brains=nii1_trunc,template=template,
        mask=mask,
        mar=rep(3,4),
        mar_ind=rep(30,4),
        row_ind=rep(1,4),
        col_ind=paste('time',1:4),
        time=1:4)
dd + theme_black_bg()

# Note, to change legend labels for figures of type='signed',
# we must change both the label for fill and for alpha,
# as ggBrain combines these two aesthetics into a custom,
# hardcoded legend (when combine_legend=TRUE). If separate 
# labels are given for fill and alpha, the two aesthetic dimensions 
# will appear in separate legends.
# For example:
dd <- ggBrain(template=template,brains=s_map1,
mask=mask,mar=3,mar_ind=30,type='signed')
# ex1:
dd + labs(fill='new_label',alpha='new_label')
# ex2:
dd + labs(fill='sign',alpha='abs_value')
}