carpetplot {fMRItools}

Carpetplot

Description

Plot a matrix with graphics::image. For fMRI data, this is the "carpetplot" or grayplot coined by (Power, 2017). The graphics and grDevices packages are required.

Usage

carpetplot(
  x,
  qcut = 0.1,
  fname = NULL,
  center = TRUE,
  scale = FALSE,
  colors = "gray255",
  sortSub = TRUE,
  ...
)

Arguments

x

The T \times V numeric data matrix, or a "xifti" object. In the plot, the T index will increase from left to right, and the V will increase from top to bottom.

qcut

Sets blackpoint at the qcut quantile, and the whitepoint at the 1-qcut quantile. Default: .1. This is equivalent to setting the color range between the 10% and 90% quantiles. The quantiles are computed across the entire data matrix after any centering or scaling.

Must be between 0 and .49. If 0 or NULL (default), do not clamp the data values.

fname

A .pdf (highly recommended) or .png file path to write the carpetplot to. If NULL (default), return the plot directly instead of writing a file.

center, scale

Center and scale the data? If x is fMRI data which has not otherwise been centered or scaled, it is recommended to center but not scale it (default).

colors

"gray255" (default) will use a grayscale color ramp from black to white. Otherwise, this should be a character vector of color names to use.

Colors will be assigned from the lowest to the highest data value, after any clamping of the data values by qcut.

sortSub

If x is a "xifti" object with subcortical data, should the voxels be sorted by structure alphabetically? Default: TRUE.

...

Additional arguments to pdf or png, such as width and height.

Value

The image or NULL, invisibly if a file was written.

References

• Power, J. D. A simple but useful way to assess fMRI scan qualities. NeuroImage 154, 150-158 (2017).