Specifying a Timepoint

cerebroViz allows visualization of brain data temporally, as well as spatially. Multiple time points (corresponding to the columns of a properly formatted matrix) can be specified for rendering by passing an integer vector to the timePoint = argument of cerebroViz(). This generates an outer and slice image for each time point, where the number of the corresponding time point is appended to the file name after outer or slice. For example: ex1_outer_1.svg is the lobe view for the first time point and ex1_slice_2.svg is the sagittal view for the second time point.

library('cerebroViz')

cerebroViz(cerebroEx, timePoint = c(1, 5, 9))

## Success! Your diagrams have been saved.

Changing the Ouput File

Users may specify a custom prefix for the rendered images with the filePrefix = argument of cerebroViz(). The saved filenames with also contain a suffix indicating outer or slice and the requested time point before the file extension. By default, cerebroViz() save files to the working directory, but a file path may be passed to filePrefix = so images may be saved elsewhere:

library('cerebroViz')

dir.create('custom_directory/')

cerebroViz(cerebroEx, filePrefix = 'custom_directory/a_custom_filename', timePoint = c(1, 5, 9))

## Success! Your diagrams have been saved.

list.files('custom_directory/')

## [1] "a_custom_filename_outer_1.svg" "a_custom_filename_outer_5.svg"
## [3] "a_custom_filename_outer_9.svg" "a_custom_filename_slice_1.svg"
## [5] "a_custom_filename_slice_5.svg" "a_custom_filename_slice_9.svg"

Back to top

Divergant Scales

By default, cerebroViz() maps input data to a linear color scale. When working with divergent data (e.g. gene expression), it is desirable to have a neutral “middle” color.

A divergent scale can be specified by passing the divData = TRUE argument. In this case, cerebroViz() maps the median value of all data points in the matrix to a neutral yellow and the extreme values to a pleasant red and blue.

library('cerebroViz')

summary(as.vector(cerebroEx))

##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.    NA's 
##   1.317   2.637   2.966   3.071   3.596   4.600      15

cerebroViz(cerebroEx, divData = TRUE, timePoint = 11, filePrefix = 'divergent')

## Success! Your diagrams have been saved.

Back to top

Clamping Outliers

The removal of outliers from data is crucial to producing interpretable visualizations. For example, if we set the data for the cerebellum in our example data cerebroEx to an extremely high value:

ex1_out <- cerebroEx

ex1_out["CB",11] <- 55

The cerebellum has an extremely high signal, and all other values are indistinguishable.

cerebroViz(ex1_out, timePoint = 11, filePrefix = 'outlier')

## Success! Your diagrams have been saved.

To compensate for outliers, a value can be passed to the clamp = argument of cerebroViz(). The clamp value is used as a coefficient with the Median Absolute Deviation (MAD) to calculate a range of ‘acceptable’ values.

\[median \pm clamp \times MAD \]

Values greater than this range are reduced (or “clamped”) to its maximum value, while values less than the range are increased to its minimum. The ideal clamp value depends on the shape of the data, but values near 3 are often used as a rule of thumb. Applying this process to the ex1_out matrix, which has been edited to contain an outlier:

cerebroViz(ex1_out, clamp = 3, timePoint = 11, filePrefix = 'outlier_clamped')

## Success! Your diagrams have been saved.

Back to top

Comparisons

It is often useful to compare observations across corresponding time points, such as with gene or isoform expression. So long as the data are collected in comparable units, like RPKM, they can be compared by subtracting the matricies from one another and visualized with cerebroViz().

ex_dif <- cerebroEx[,1:3] - cerebroEx2[,1:3]

cerebroViz(ex_dif, filePrefix = 'ex_dif')

## Success! Your diagrams have been saved.

In these diagrams, a positive value indicates higher expression in cerebroEx relative to cerebroEx2, while a negative value corresponds to higher expression of cerebroEx2. In this case, it appears cerebroEx is always higher.

Back to top

Labeling regions

To label the regions of the brain for which you have data, pass the regLabel = TRUE argument to cerebroViz(). The labels generated by regLabel always display the cerebroViz default, but are fully editable in any vector graphics manipulation program, or even a text editor.

cerebroEx -> ex1

cerebroViz(ex1, regLabel = TRUE, filePrefix = 'regLabel')

## Success! Your diagrams have been saved.

Back to top

Labeling time points

Viewers find it easier to follow a series when every image in the series is labled. Passing the figLable = TRUE argument to cerebroViz() prints the column name for each figure on the lower left corner of the vizualization.

cerebroEx -> ex1

cerebroViz(ex1, figLabel = TRUE, timePoint = c(5, 9), filePrefix = 'figLabel')

## Success! Your diagrams have been saved.

Crosshatching Missing Regions

Depending on specified color schemes, it may be difficult to distinguish a color (likely a neutral color in divergent data) from the background color of the brain. When some data points are missing (NA), corresponding regions may appear to be near the median, when they are actually missing. The argument naHatch = TRUE may be passed to cerebroViz() to apply a cross-hatch to these regions to help distinguish them from the background or the neutral color.

cerebroEx -> ex1

cerebroViz(ex1, naHatch = TRUE, filePrefix = 'naHatch')

## Success! Your diagrams have been saved.

Back to top

Removing the legend

The color scale bar can be toggled off with the legend = FALSE argument of cerebroViz(), as may be desired when generating images to be used in multi-panel figures.

cerebroEx -> ex1

cerebroViz(ex1, legend = FALSE, filePrefix = 'legend')

## Success! Your diagrams have been saved.

Back to top

Custom color palettes

The palette = argument of cerebroViz() allows a custom color palette to be set for the vizulaization. To define a new palette, we recommend passing the RColorBrewer::brewer.pal() function to palette =. In fact, the default palettes for cerebroViz() use brewer.pal()!

RColorBrewer::brewer.pal() takes 2 arguments: n, the number of colors in the palette; and a name corresponding to the palette to use. An odd number of colors are reccomended whever divData = TRUE, ensuring the median is assigned to a known color.

library(cerebroViz)
library(RColorBrewer)

cerebroViz(cerebroEx, palette = rev(brewer.pal(11, "PiYG")), divData = TRUE, timePoint = 11, filePrefix = "palette")

## Success! Your diagrams have been saved.

To see a list of palettes available from RColorBrewer, use RColorBrewer::display.brewer.all(). More information about brewer.pal() can be read in the documentation for RColorBrewer.

Advanced custom colors

cerebroViz() allows users to fine-tune the color schemes used for both the visualization and the brain background.The color scale to which the data are mapped can be specified by passing a vector of color names, RGB values or hex values with a length of two or greater to the palette = argument:

library(cerebroViz)

cerebroViz(cerebroEx, palette = c("cornflowerblue", "antiquewhite", "coral"), timePoint = 11, filePrefix = "custom_palette")

## Success! Your diagrams have been saved.

Users are advised to specify an odd number of colors whenever using divData = TRUE, ensuring the median is assigned to a known color.

The color of the brain background (“empty” regions of the brain), brain outline, and image background can be specified, in that order, to the secPalette = argument. Like palette, this argument accepts a vector of color names, RGB values or hex values. Unlike palette, secPalette = only accepts a vector of length three.

library(cerebroViz)

cerebroViz(cerebroEx, secPalette = c("darkgrey", "white", "lightgrey"), timePoint = 11, filePrefix = "secPalette")

## Success! Your diagrams have been saved.

Back to top

Custom Regions Example

For example, Brainspan (from which cerebroEx was taken), uses the abbreviation CBC instead of CB, and MD instead of THA. Recreating this original nomenclature throws an error:

rownames(cerebroEx)[c(3, 14)]

## [1] "CB"  "THA"

rownames(cerebroEx)[c(3, 14)] <- c('CBC', 'MD')
cerebroViz(cerebroEx, filePrefix = "missing_name", timePoint = 9)

## Warning in cerebroViz(cerebroEx, filePrefix = "missing_name", timePoint
## = 9): Unknown row names in input data: CBC, MD. Unknown regions will
## be excluded from visualization. See the help manual for 'customNames'
## argument.

## Warning in cerebroViz(cerebroEx, filePrefix = "missing_name", timePoint
## = 9): The following regions encompass other regions of the brain: STR.
## Subregions are masked in output.

## Success! Your diagrams have been saved.

To map these regions to the custom names: create a 2 column matrix where [,1] contains cerebroViz convention names and [,2] contains the corresponding custom name, then pass it to the customNames = argument of cerebroViz().

matrix(c("CB", "THA", "CBC", "MD"), ncol=2 ) -> cnm
cnm

##      [,1]  [,2] 
## [1,] "CB"  "CBC"
## [2,] "THA" "MD"

cerebroViz(cerebroEx, customNames = cnm, filePrefix = "custom_name", timePoint = 9)

## Success! Your diagrams have been saved.

The data are now properly mapped to the corresponding regions. Note that both the “missing_name” and “custom_name” images have the same scale. cerebroViz uses all data in the supplied matrix to calculate its color scale, even those which cannot be mapped to regions in the output images.

Back to top