Type:	Package
Title:	Plotting Module of the 'ribios' Software Suite
Version:	1.3.0
Date:	2026-02-20
Description:	Provides data structures and functions for data transformation and visualization in computational biology in drug discovery as part of the 'ribios' software suite. Zhang (2025) https://github.com/bedapub/ribiosPlot.
Depends:	R (≥ 3.4.0)
Imports:	lattice, grDevices, RColorBrewer, grid, gridExtra, graphics, ribiosUtils, stats, ggplot2
Suggests:	latticeExtra, ribiosArg, plotrix, MASS, testthat, knitr, rmarkdown
Enhances:	Vennerable
Collate:	AllClasses.R AllMethods.R utils.R ribiosPlot-package.R robustdist.R p2asterisk.R ellipse.R colors.R fcol.R hist.R jitter.xyplot.R compactTrellis.R cascadePlot.R biosHeatmap.R PCAScoreMatrix.R expVar.R pcaPlots.R plotVenn.R pairs.R figurePanel.R ggSmoothScatter.R openFileDevice.R vennMembers.R
License:	GPL-3
URL:	https://github.com/bedapub/ribiosPlot
BugReports:	https://github.com/bedapub/ribiosPlot/issues
LazyLoad:	yes
Encoding:	UTF-8
RoxygenNote:	7.3.3
Additional_repositories:	https://bedapub.r-universe.dev
NeedsCompilation:	no
Packaged:	2026-02-20 20:57:10 UTC; david
Author:	Jitao David Zhang [aut, cre, ctb]
Maintainer:	Jitao David Zhang <jitao_david.zhang@roche.com>
Repository:	CRAN
Date/Publication:	2026-02-25 10:50:02 UTC

ribiosPlot: Plotting Module of the 'ribios' Software Suite

Description

Provides data structures and functions for data transformation and visualization in computational biology in drug discovery as part of the 'ribios' software suite. Zhang (2025) https://github.com/bedapub/ribiosPlot.

Author(s)

Maintainer: Jitao David Zhang jitao_david.zhang@roche.com (ORCID) [contributor]

See Also

Useful links:

• https://github.com/bedapub/ribiosPlot

• Report bugs at https://github.com/bedapub/ribiosPlot/issues

Construct a S3-class PCAScoreMatrix object

Description

Construct a S3-class PCAScoreMatrix object

Usage

PCAScoreMatrix(scoreMatrix, expVar)

Arguments

Value

A S3-class PCAScoreMatrix object, which is a score matrix with explained variances (expVar) as attribute.

See Also

as.matrix.PCAScoreMatrix, expVar.PCAScoreMatrix, print.PCAScoreMatrix. This function is usually not called by the end user; instead, it is used by the function pcaScores

Examples

myPCmat <- PCAScoreMatrix(matrix(rnorm(15),ncol=3), c(0.25, 0.15, 0.1))
myPCmat

Subsetting PCAScoreMatrix while keeping the expVar attribute

Description

Subsetting PCAScoreMatrix while keeping the expVar attribute

Usage

## S3 method for class 'PCAScoreMatrix'
x[i, j, ..., drop = TRUE]

Arguments

Value

A PCAScoreMatrix object

Coerece a PCAScoreMatrix into data.frame

Description

Coerece a PCAScoreMatrix into data.frame

Usage

## S3 method for class 'PCAScoreMatrix'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data.frame consisting of the score matrix

See Also

as.data.frame

Examples

myPCmat <- PCAScoreMatrix(matrix(rnorm(15),ncol=3), c(0.25, 0.15, 0.1))
as.matrix(myPCmat)

Coerece a PCAScoreMatrix into score matrix

Description

Coerece a PCAScoreMatrix into score matrix

Usage

## S3 method for class 'PCAScoreMatrix'
as.matrix(x, ...)

Arguments

Value

A numeric matrix, the score matrix

Examples

myPCmat <- PCAScoreMatrix(matrix(rnorm(15),ncol=3), c(0.25, 0.15, 0.1))
as.matrix(myPCmat)

CUSTOMED HEATMAP.2 FOR BIOS USERS

Description

A tailored version of the heatmap.2 function in the gplots package, by giving the default values in the paramter list.

Usage

biosHeatmap(
  x,
  Rowv = TRUE,
  Colv = if (symm) "Rowv" else TRUE,
  distfun = dist,
  hclustfun = function(x) hclust(x, method = "ward.D2"),
  dendrogram = c("both", "row", "column", "none"),
  symm = FALSE,
  scale = c("none", "row", "column"),
  na.rm = TRUE,
  revC = identical(Colv, "Rowv"),
  add.expr,
  breaks,
  symbreaks = min(x < 0, na.rm = TRUE) || scale != "none",
  col = "greenred",
  na.color = "darkgray",
  colsep,
  rowsep,
  sepcolor = "white",
  sepwidth = c(0.05, 0.05),
  cellnote,
  notecex = 1,
  notecol = "cyan",
  trace = c("none", "column", "row", "both"),
  tracecol = "cyan",
  hline = median(breaks),
  vline = median(breaks),
  linecol = tracecol,
  margins = NULL,
  main = NULL,
  xlab = NULL,
  ylab = NULL,
  labRow = NULL,
  labCol = NULL,
  cexMain = NULL,
  cexRow = pmin(1, 0.2 + 1/log10(nr)),
  cexCol = pmin(1, 0.2 + 1/log10(nc)),
  ColSideColors,
  RowSideColors,
  color.key.title = "Color Key",
  key = TRUE,
  keysize = 1.5,
  density.info = c("none", "histogram", "density"),
  denscol = tracecol,
  symkey = min(x < 0, na.rm = TRUE) || symbreaks,
  densadj = 0.25,
  zlim,
  lhei = c(1, 7),
  lwid = c(1, 7),
  lmat = NULL,
  ...
)

Arguments

Details

Customed version of the heatmap.2, with the common settings used by JItao David Zhang

Value

See heatmap.2 in the gplots package.

Author(s)

Jitao David Zhang <jitao_david.zhang@roche.com>

Examples

set.seed(123)
test <- matrix(rnorm(100), nrow=10)
biosHeatmap(test)

## do not draw row-wise dendrogram
biosHeatmap(test, Rowv=FALSE, dendrogram="column")
## do not draw column-wise dendrogram
biosHeatmap(test, Colv=FALSE, dendrogram="row")
## do not re-sort columns/rows (e.g. for visualization purposes)
biosHeatmap(test, Rowv=FALSE, Colv=FALSE, dendrogram="none")

## define the color range by zlim
biosHeatmap(test, zlim=c(-5, 5))

Build brewer.pal colors from factor (Deprecated)

Description

The functionality has been replaced by fcbrewer. The functions will be removed in the future release.

Usage

brewer.pal.factor(factor, name = "Greys")

Arguments

Details

The function is useful to build named RGB color values from factors. brewer.pal.factor return a color-HTML-string vector as the same length of the input factor vector, which is named by the input factor as well. brewer.pal.factorLevels returns a color vector of the length of the factor level, and the colors are named by the levels. See examples below.

From version 1.1-16, the color palette is automatically reduced/expanded when the levels of input factors underlies or exceeds the minimum and maximum colors. See example below.

Value

Named HTML RGB colors.

Author(s)

Jitao David Zhang <jitao_david.zhang@roche.com>

Examples

myFac <- factor(c("HSV", "BVB", "FCB", "HSV", "BVB", "HSV"))
brewer.pal.factor(myFac, name="Set1")

myLongFac <- factor(paste("Sample", 1:20))
brewer.pal.factor(myLongFac, name="Set1")

myShortFac <- factor(paste("Sample", 1:2))
brewer.pal.factor(myShortFac, name="Set1")

Order rows of a matrix in the cascade order

Description

The 'cascade order' is defined by three criteria (1) Rows are divided into two groups by the condition given by 'dichotomy'. (2) The positive and negative rows are ordered respectively so that rows reaching its absolute maximal values in column n are ordered prior to rows reaching reaching its absolute maximal values in columns n+1, where n can be from 1 to column number minus one. (3) If two rows reach the maximum value at the same column, they are ordered by the (decreasing) order of the absolute value in that column.

Usage

cascadeOrder(matrix, dichotomy = c("maxabs", "mean", "median"))

Arguments

Details

See example for illustration of the idea.

Value

An integer vector of row indices in cascade order.

Examples

checkBoard <- function(seed=1887) {
  set.seed(seed)
  mat <- matrix(rnorm(76, sd=1), ncol=4)
  delta <- 3
  for(i in seq(1, 16, 2)) {
    rowInd <- i:(i+1)
    colInd <- (i %/% 2) %% 4 +1
    delta <- ifelse(i>8, -6, 6) * c(0.6, 1)
    mat[rowInd, colInd] <- mat[rowInd, colInd] + delta
  }
  mat[17,1:4] <- rep(-1, 4)
  mat[18,1] <- NA
  mat[18,2] <- mat[18, 2] -6
  mat[19,1:4] <- rep(NA,4)
  rord <- sample(1:nrow(mat), replace=FALSE)
  mat <- mat[rord,]
  rownames(mat) <- sprintf("Row%d", 1:nrow(mat))
  return(mat)
}
myMat <- checkBoard(1887)
biosHeatmap(myMat, Rowv=FALSE, Colv=FALSE, dendrogram="none",
            zlim=c(-4,4), col="royalbluered",
            main="Original matrix")
## since dist by default does not accept rows full of NAs, we remove them in the example below
biosHeatmap(myMat[apply(myMat, 1, function(x) !all(is.na(x))),],
            Rowv=TRUE, Colv=TRUE, dendrogram="both",
            zlim=c(-4,4), col="royalbluered",
            main="hclust/dist clustering")
## note that cascadeOrder handles invariant rows and rows full of NA values
biosHeatmap(myMat[cascadeOrder(myMat),], Rowv=FALSE, Colv=FALSE, dendrogram="none",
            zlim=c(-4,4), col="royalbluered",
            main="Cascade order")

Generates a set of colors that varies smoothly.

Description

(copied from the colorpanel man page from the gplots package. See NOTES below)

Usage

colorpanel(n, low, mid, high)

Arguments

Details

The values for ‘low, mid, high’ can be given as color names (‘red’), plot color index (2=red), and HTML-style RGB, (“#FF0000”=red).

If ‘mid’ is supplied, then the returned color panel will consist of ‘n - floor(n/2)’ HTML-style RGB elements which vary smoothly between ‘low’ and ‘mid’, then between ‘mid’ and ‘high’. Note that if ‘n’ is even, the color ‘mid’ will occur twice at the center of the sequence.

If ‘mid’ is omitted, the color panel will vary smoothly beween ‘low’ and ‘high’.

Value

Vector of HTML-style RGB colors.

Note

The colorpanel function is copied from the gplots package (written by Warnes et al.) under the GPL-2 license. The gplots require heavy dependencies that prevent this function being used in speed-sensitive scenarios, e.g. in command-line tools.

Author(s)

Originally by Gregory R. Warnes <greg@warnes.net>. Adapted by Jitao David Zhang <jitao_david.zhang@roche.com>.

References

See gplots package.

See Also

blackyellow and royalbluered for two- and three-color panels.

Examples

showpanel <- function(col) {
  image(z=matrix(1:100, ncol=1), col=col, xaxt="n", yaxt="n")
}
 
oldpar <- par(mfrow=c(3,3))

# two colors only:
showpanel(colorpanel(8,low="red",high="green"))
 
# three colors
showpanel(colorpanel(8,"red","black","green"))
# note the duplicatation of black at the center, using an odd
# number of elements resolves this:
showpanel(colorpanel(9,"red","black","green"))
 
showpanel(greenred(64))
showpanel(redgreen(64))
showpanel(bluered(64))
showpanel(redblue(64))

showpanel(royalbluered(64))
showpanel(royalredblue(64))
par(oldpar)

Compact par setting

Description

For compact figures

Usage

compactPar(mar = c(3, 3, 1.5, 1.5), mgp = c(2, 1, 0), ...)

Arguments

Value

A named list of the previous par settings (invisibly), as returned by par.

Author(s)

Jitao David Zhang

See Also

par

Examples

  compactPar()
  plot(1:4)

Return a compact setting for lattice plots, useful for preparing publications

Description

The function returns a set of lattice options that are useful for compact figures, with less room for padding and therefore more room for the figure. It is often used to prepare for publications.

Usage

compactTrellis()

Value

A list that can be used in lattice.options

Examples

opts <- compactTrellis()

Plot confidence ellipse based on two-dimenstional data

Description

Plot confidence ellipse based on two-dimenstional data

Usage

confEllipse(x, y = NULL, conf = 0.95, ...)

Arguments

Value

Invisible coordinates of points on the ellipse

Examples

if(interactive()) {
  testX <- rnorm(100, mean=1, sd=2)
  testY <- rnorm(100, mean=2, sd=3)
  plot(testX, testY, pch=16, xlim=c(-5,7), ylim=c(-7,11))
  confEllipse(testX, testY, col="red", lwd=1)
  confEllipse(testX, testY, conf=0.99, col="red", lwd=2)
  confEllipse(testX, testY, conf=0.9, col="red", lwd=0.5)
}

if(interactive() & require("MASS")) {
  testMVR <- mvrnorm(n=100, mu=c(2,3), Sigma=matrix(c(1, 0.65, 0.65, 1), nrow=2))
  plot(testMVR, pch=16, xlim=c(-2,6), ylim=c(0,6))
  confEllipse(testMVR, col="orange")
  confEllipse(testMVR, conf=0.99, col="red")
  confEllipse(testMVR, conf=0.9, col="lightblue")
}

Convert degree to radian values

Description

Convert degree to radian values

Usage

degree2radian(x)

Arguments

Value

Radian value

Examples

degree2radian(90)
degree2radian(-225)

Display color panels

Description

Display color panels

Usage

display.colorpanels(panel.names, nc)

Arguments

Value

Side effect (visuzalization is used)

Author(s)

Jitao David Zhang

Examples

display.colorpanels(threecolor.panels(), 6)

Display three-color panels

Description

Display three-color panels

Usage

display.threecolor.panels(nc = 20)

Arguments

Value

Side effect is used

Examples

display.threecolor.panels()

Display two-color panels

Description

Display two-color panels

Usage

display.twocolor.panels(nc = 20)

Arguments

Value

Side effect is used

Examples

display.twocolor.panels()

Add an ellipse in an existing plot

Description

Add an ellipse in an existing plot

Usage

ellipse(
  x0 = 0,
  y0 = 0,
  a = 1,
  b = 2,
  alpha = 0,
  length = 1000,
  col = NULL,
  fill = NA,
  border,
  ...
)

Arguments

Value

Invisible coordinates of points on the ellipse

Examples

if(interactive()) {
  plot.new()
  plot.window(xlim=c(-1, 1), ylim=c(-1,1))
  ellipseCols <- heat.colors(11)
  ellipse(0, 0, a=1, b=0.5, alpha=0)
  for(i in 1:11) {
    ellipse(0, 0, a=1, b=0.5, alpha=degree2radian(i*15), col=ellipseCols[i])
  }
  ellipse(0, 0, a=1, b=1, col="black", lwd=2)
  ellipse(0, 0, a=0.5, b=0.5, fill="steelblue")
}

S3 function expVar to extract explained variance from prcomp and PCAScoreMatrix objects

Description

S3 function expVar to extract explained variance from prcomp and PCAScoreMatrix objects

Usage

expVar(x, choices)

## S3 method for class 'prcomp'
expVar(x, choices)

## S3 method for class 'PCAScoreMatrix'
expVar(x, choices)

Arguments

Value

A numeric vector of variance explained

Methods (by class)

• expVar(prcomp): Extract explained variance from a prcomp object

• expVar(PCAScoreMatrix): Extract explained variance from a PCAScoreMatrix object

Methods (by class)

• prcomp: Extract explained variance from a prcomp object

• PCAScoreMatrix: Extract explained variance from a PCAScoreMatrix object

Examples

myMat <- matrix(rnorm(100), ncol=10)
myPrcomp <- prcomp(myMat)
myPcaScoreMatrix <- pcaScores(myPrcomp, choices=NULL) 
expVar(myPrcomp)
expVar(myPcaScoreMatrix)

expVar(myPrcomp, 1:5)
expVar(myPcaScoreMatrix, 1:5)

Generic function expVarLabel to generate a label of explained variance from prcomp and PCAScoreMatrix objects

Description

Generic function expVarLabel to generate a label of explained variance from prcomp and PCAScoreMatrix objects

Usage

expVarLabel(x, choices, compact)

Arguments

Value

A character vector of labels describing the explained variance of each principal component.

Labels of principal components from PCAScoreMatrix

Description

Labels of principal components from PCAScoreMatrix

Usage

## S3 method for class 'PCAScoreMatrix'
expVarLabel(x, choices, compact = FALSE)

Arguments

Value

A character string vector of the same length as choices (or the same length as the column count of the PCAScoreMatrix), which are the labels of the PCs

Examples

pcaMat <- PCAScoreMatrix(matrix(rnorm(15),ncol=3), c(0.25, 0.15, 0.1))
expVarLabel(pcaMat)
expVarLabel(pcaMat, choices=1:2)
expVarLabel(pcaMat, choices=1:2, compact=TRUE)
expVarLabel(pcaMat, choices=c(1,3), compact=TRUE)

Labels of principal components from prcomp

Description

Labels of principal components from prcomp

Usage

## S3 method for class 'prcomp'
expVarLabel(x, choices, compact = FALSE)

Arguments

Value

A character string vector of the same length as choices (or the same length as the column count of the scores), which are the labels of the PCs

Examples

myPr <- prcomp(matrix(rnorm(100), ncol=5))
expVarLabel(myPr)
expVarLabel(myPr, choices=1:2)
expVarLabel(myPr, choices=1:2, compact=TRUE)

Return base colors of a fcol object

Description

Return base colors of a fcol object

Usage

fcbase(fcol)

Arguments

Value

A character vector, representing base colors

Examples

fc <- fcol(c("lightblue", "orange", "lightblue"), base=c("orange", "lightblue"))
fcbase(fc)

Replace base colors of a fcol object with a different value

Description

Replace base colors of a fcol object with a different value

Usage

fcbase(fcol) <- value

Arguments

Value

A new fcol object

Examples

fc <- fcol(c("lightblue", "orange", "lightblue"), base=c("orange", "lightblue"))
fcbase(fc)
fcbase(fc)[1] <- "red"
print(fc)
fcbase(fc) <- c("gray", "darkblue")
fc

Factor color brewer

Description

The function generates a vector of color names for a factor(-like) object.

Usage

fcbrewer(factor, panel = "Set1")

Arguments

Details

When using brewer.pal to generate palettes, the panel is automatically expanded using colorRampPalette when the number of levels of the input factor exceeds the limit of respective panel. This is done automatically.

Value

An fcol object encoding colors matching the factors as well as the base colors. The latter is often needed in figure legends.

Author(s)

Jitao David Zhang <jitao_david.zhang@roche.com>

See Also

brewer.pal.info for color panels.

Examples

testFactor <- gl(4,25)
testCol1 <- fcbrewer(testFactor, panel="Set2")
testCol2 <- fcbrewer(testFactor, panel=heat.colors)
testCol3 <- fcbrewer(testFactor, panel="heat.colors")
testCol4 <- fcbrewer(testFactor, panel=c("black", "green", "orange", "lightblue"))

testRan <- runif(100)
## use colors of each item and colors of each level
plot(testRan, pch=21, bg=testCol1)
legend("topright", legend=paste("Class", 1:4),
       pch=21, pt.bg=fcbase(testCol1))

## boxplot uses colors matching to each level only
boxplot(testRan ~ testFactor, col=fcbase(testCol1))

Construct a fcol object

Description

Construct a fcol object

Usage

fcol(colors, base)

Arguments

Value

A S3 class known as fcol, containing colors as vector and base colors in the attribute fcbase

Examples

fcol(c("lightblue", "orange", "lightblue"), base=c("orange", "lightblue"))

Make a figure panel with title

Description

Make a figure panel with title

Usage

figurePanel(gg, title)

Arguments

Value

A grob object

Examples

require("ggplot2")
df <- data.frame(
  gp = factor(rep(letters[1:3], each = 10)),
  y = rnorm(30)
)

ds <- do.call(rbind, lapply(split(df, df$gp), function(d) {
  data.frame(mean = mean(d$y), sd = sd(d$y), gp = d$gp)
  }))
  
g1 <- ggplot(df, aes(gp, y)) +
  geom_point() +
  geom_point(data = ds, aes(y = mean), colour = 'red', size = 3)
  
g2 <- ggplot() +
  geom_point(data = df, aes(gp, y)) +
  geom_point(data = ds, aes(gp, mean), colour = 'red', size = 3) +
  geom_errorbar(
    data = ds,
    aes(gp, mean, ymin = mean - sd, ymax = mean + sd),
    colour = 'red',
    width = 0.4
  )
  
panelA <- figurePanel(g1, "(A)")
panelB <- figurePanel(g2, "(B)")
layoutMat <- matrix(c(1,2), nrow=1)
gridExtra::grid.arrange(grobs=list(panelA, panelB),
 layout_matrix=layoutMat)

Get default font family

Description

Get default font family

Usage

getDefaultFontFamily()

Value

Character string, the default font family

Helper function to print PC and explained variances

Description

Helper function to print PC and explained variances

Usage

getExpVarLabel(ev, choices, compact = FALSE)

Arguments

Value

A character vector of labels in the form "Principal component N (X% variance explained)".

Get xlim/ylim ranges for plots from real values

Description

Get xlim/ylim ranges for plots from real values

Usage

getLims(..., perc = 0.99, symm = TRUE)

Arguments

Value

A numeric vector of length 2 giving the lower and upper axis limits.

Examples

myX <- rnorm(100, mean=1)
myY <- rnorm(100)
myLim <- getLims(myX, myY, perc=0.99)
plot(myX, myY, xlim=myLim, ylim=myLim)
mySymmLim <- getLims(myX, myY, perc=0.99, symm=TRUE)
plot(myX, myY, xlim=myLim, ylim=mySymmLim)

Mimicking the graphics::smoothScatter behaviour for GGally::ggpairs

Description

Mimicking the graphics::smoothScatter behaviour for GGally::ggpairs

Usage

ggSmoothScatter(
  data,
  mapping,
  colours = colorRampPalette(c("white", blues9[5:9], "black"))(256),
  xlim = NULL,
  ylim = NULL,
  ...
)

Arguments

Note

So far the outliers are not plotted, to be done later

Mimicking the graphics::smoothScatter behaviour for GGally::ggpairs, with aux lines

Description

Mimicking the graphics::smoothScatter behaviour for GGally::ggpairs, with aux lines

Usage

ggSmoothScatterWithAux(
  data,
  mapping,
  colours = colorRampPalette(c("white", blues9[5:9], "black"))(256),
  xlim = NULL,
  ylim = NULL,
  ...
)

Arguments

Guess width and height parameters for a heatmap

Description

guessWH helps biosHeatmap determines a proper canvas dimension as well as the proportion between legends and the main figure, especially in the command line mode.

Usage

guessWH(
  nrow,
  ncol,
  rownames,
  colnames,
  cexRow,
  cexCol,
  xlab,
  ylab,
  width,
  height
)

Arguments

Details

guessWH determines for visual purposes the best height/width and legend/figure proportion for heatmaps. Interested users are invited to read the codes to get insights how the task is done.

Value

A list of width proportions, height proportions, the total width and the total length.

Author(s)

Jitao David Zhang <jitao_david.zhang@roche.com>

See Also

biosHeatmap

Examples

myMat <- matrix(rnorm(256), nrow=16)
rownames(myMat) <- sample(paste(letters, LETTERS, sep="_"),16)
colnames(myMat) <- sample(paste(LETTERS, letters, sep="_"), 16)
guessWH(nrow=nrow(myMat), ncol=ncol(myMat), width=4, height=4)
guessWH(nrow=nrow(myMat), ncol=ncol(myMat), width=NA, height=NA)
myWH <- guessWH(nrow=nrow(myMat), ncol=ncol(myMat),
xlab="321", ylab="ABC",
rownames=rownames(myMat), colnames=colnames(myMat))

if(interactive()) {
X11(width=myWH$width, height=myWH$height)
biosHeatmap(myMat, lwid=myWH$lwid, lhei=myWH$lhei, xlab="321",
ylab="ABC", cexRow=2L, cexCol=2L)
dev.off()
}

Make histograms for matrix

Description

Make histograms for matrix

Usage

histMat(
  mat,
  linesOpt = list(lwd = NULL, col = NULL, lty = NULL, type = NULL, pch = NULL),
  main = NULL,
  xlab = NULL,
  xlim = NULL,
  ...
)

Arguments

Value

Invisibly, a list as returned by hist, with additional elements xlim and linesOpt.

Author(s)

Jitao David Zhang <jitao_david.zhang@roche.com>

See Also

hist

Examples

testMat <- matrix(rnorm(1000), nrow=100)
histMat(testMat)

Interative dev.print and pdf print

Description

Execute dev.print only if R session is interactive.

Usage

idev(...)

ipdf(file, ...)

Arguments

Details

ipdf is a shortcut in case PDF is used as the device, with the twist that useDingbats is set to FALSE by default. See NOTE.

dev.print will make a R-script fail if the session is not interactive (e.g. when the script is excuted with the -f option from R command line). Function idev checks first whether the session is interative, and executes dev.print only if the session is interactive.

A commonly used shortcut is ipdf, which prints the current device to a PDF file.

Value

Side effect used.

Note

useDingbats is set to FALSE in ipdf. Setting the option to TRUE causes problem in importing the PDF to Inkscape, a vector-based figure modifying software. Though the option may reduces smaller and (according to the R manual) better output, we have noticed no difference.

Author(s)

Jitao David Zhang <jitao_david.zhang@roche.com>

See Also

dev.print, pdf

Examples

tmfile <- tempfile()
plot(1:15, type="h")
idev(png, tmfile,width=600, height=800)
ipdf(tmfile)

Return a range defined by integers

Description

The function is similar to range but returns integer ranges that are just outside the real range: i.e. the floor of the left range and the ceiling of the right range.

Usage

intRange(x, na.rm = TRUE)

Arguments

Value

A vector of integers of length 2.

Author(s)

Jitao David Zhang <jitao_david.zhang@roche.com>

Examples

intRange(rnorm(100))

Make boxplots or dotplots with sample-size proportional jitters

Description

Make boxplots or dotplots with jitters of the size proportional to the sample size. See examples.

Usage

jitter.xyplot(x, y, N = 20, factor = 1, ...)

Arguments

Value

Side effects are used.

Author(s)

Jitao David Zhang <jitao_david.zhang@roche.com>

Examples

library(lattice)

testX <- gl(8,5)
testY <- rnorm(40)
xyplot(testY ~ testX)
xyplot(testY ~ testX, panel=jitter.xyplot)

(xyBw <- bwplot(testY ~ testX))
(xyBwJitter <- update(xyBw, panel=jitter.xyplot))

testXnum <- rep(1:8, 5)
xyplot(testY ~ testXnum, panel=jitter.xyplot)

Blender two colors to get the midpoint color of two colors

Description

Blender two colors to get the midpoint color of two colors

Usage

midCol(col1, col2)

Arguments

Value

The midpoint color of the two in the Lab space.

Examples

midCol("black", "red")
midCol(c("black", "red"))

set.seed(1778)
nCol <- 20
candCol <- grep("gr[a|e]y", colors(), value=TRUE, invert=TRUE)
firstCols <- sample(candCol, nCol)
secondCols <- rev(sample(candCol, nCol))
midCols <- sapply(seq(along=firstCols), function(i)
  midCol(firstCols[i], secondCols[i]))
plot.new()
plot.window(xaxt="n", yaxt="n", xlim=c(0, nCol),
     ylim=c(0.5, 4), bty="n")
title("Example of midCol")
segments(x0=1:nCol, y0=0, x1=1:nCol, y1=4, col="lightgray")
points(x=rep(1:nCol, each=3),
     y=rep(1:3, nCol),
     pch=21, cex=1.75,
     bg=as.vector(rbind(firstCols, midCols, secondCols)))
text(0, c(1.5, 2.5, 3.5), c("Second", "Midpoint", "First"),
     pos=4)

Order rows of a matrix with non-negative maximum values in the cascade order

Description

Order rows of a matrix with non-negative maximum values in the cascade order

Usage

nonNegCascadeOrder(matrix)

Arguments

Make sure that x is assigned a reasonable value

Description

Make sure that x is assigned a reasonable value

Usage

nonNull(x, default, length = NULL, defaultNULL.ok = FALSE)

Arguments

Value

non-null values

Open a device as a file preparing for plotting in the file

Description

The function openFileDevice opens a device of the type specified by the file extension name. It such prepares the file for visualizing data. User must call dev.off once the writing (plotting) to the device is finished.

Usage

openFileDevice(filename, width = 7, height = 7, dpi = 300L, family)

Arguments

Details

closeFileDevice quietly closes the current device: it does not print the information of the next device.

The function openFileDevice calls extname to determine the file type to be drawn in. Currently supported types include PDF, tiff (tif), bmp, jpeg (jpeg). When the file type is not recognized, the PDF format is used as a fallback.

As an example, myplot.pdf will triggers openning a PDF device, newplot.png a PNG device, and oldplot.tiff a TIFF device, whereas myfile.abc will be openned as a PDF device.

For bitmap files like BMP, JPEG,PNG and TIFF, we use inch as the size unit in order to be compatible with PDF. And the resolution is always set to 300dpi.Furthermore, JPEG quality is set to 90 instead of the default value 75, and TIFF do not use any compression. These settings follow our practices for scientific publication while allowing generic post-precessing of figures.

Value

Both functions are used for its side effect.

Note

After plotting, user should call dev.off to close the device in the file, otherwise the file can probably not be read.

Author(s)

Jitao David Zhang <jitao_david.zhang@roche.com>

See Also

extname for getting extension name of file. See pdf, png, jpeg, tiff and bmp for file formats.

Examples

if(interactive()) {
  tempfile1 <- paste(tempfile(), ".pdf", sep="")
  openFileDevice(tempfile1)
  plot(rnorm(100), rnorm(100))
  closeFileDevice()

  tempfile2 <- paste(tempfile(), ".png", sep="")
  openFileDevice(tempfile2, width=5, height=5)
  plot(rnorm(100), rnorm(100))
  closeFileDevice()
}

Convert p values into asterisks

Description

The function map p values into asterisks by common definitions

Usage

p2asterisk(p, use0.1 = TRUE)

Arguments

Value

A character vector of the same length as p of asterisk symbols. In case p is an array, both 'dim' and 'dimnames' properties are copied to the returning value.

Note

NA will be mapped to empty strings.

Examples

myPvals <- c(0.0005, 0.02, 0.4, 0.075, NA, 0.0044)
myPasterisks <- p2asterisk(myPvals, use0.1=FALSE)
stopifnot(identical(myPasterisks, c("***", "*", "", "", "", "**")))

myPasterisks2 <- p2asterisk(myPvals, use0.1=TRUE)
stopifnot(identical(myPasterisks2, c("***", "*", "", ".", "",  "**")))

Correlation panel for pairs

Description

Correlation panel for pairs

Usage

panel.cor(x, y, digits = 2, prefix = "", cex.cor, ...)

Arguments

Value

No return value, called for side effects as a panel function in pairs.

See Also

pairs.

Correlation panel

Description

Correlation panel

Usage

panel.lmSmooth(
  x,
  y,
  col = par("col"),
  bg = NA,
  pch = par("pch"),
  cex = 0.8,
  method = "spearman",
  use = "complete",
  ...
)

Arguments

Value

No return value, called for side effects as a panel function in pairs.

See Also

pairs.

Retrieve PCA rotations from prcomp objects

Description

Retrieve PCA rotations from prcomp objects

Usage

pcaRotation(x, choices, offset, reverse = c(FALSE, FALSE))

Arguments

Examples

testMatrix <- matrix(rnorm(1000), nrow=10)
testPCA <- prcomp(testMatrix)
testPCAscores <- pcaScores(testPCA)

testPCAscores.withOffset <- pcaScores(testPCA, offset=c(1,3,5))
## notice the average of offset-rows are near zero
colMeans(as.matrix(testPCAscores.withOffset)[c(1,3,5),])

testPCAscores.withReverse <- pcaScores(testPCA, reverse=c(TRUE, FALSE))
colMeans(as.matrix(testPCAscores.withReverse)[c(1,3,5),])

Retrieve PCA scores from prcomp objects

Description

Retrieve PCA scores from prcomp objects

Usage

pcaScores(x, choices, offset, reverse = c(FALSE, FALSE))

Arguments

Value

A PCAScoreMatrix object containing the PCA scores.

Examples

testMatrix <- matrix(rnorm(1000), nrow=10)
testPCA <- prcomp(testMatrix)
testPCAscores <- pcaScores(testPCA)

testPCAscores.withOffset <- pcaScores(testPCA, offset=c(1,3,5))
## notice the average of offset-rows are near zero
colMeans(as.matrix(testPCAscores.withOffset)[c(1,3,5),])

testPCAscores.withReverse <- pcaScores(testPCA, reverse=c(TRUE, FALSE))
colMeans(as.matrix(testPCAscores.withReverse)[c(1,3,5),])

Perform principal component analysis and derive PCA scores from a logFC matrix

Description

Perform principal component analysis and derive PCA scores from a logFC matrix

Usage

pcaScoresFromLogFC(lfcMat, reference = 0, choices, reverse = c(FALSE, FALSE))

Arguments

Value

A PCAScoreMatrix object containing the PCA scores derived from the log fold-change matrix.

Examples

lfcMat <- matrix(rnorm(9), nrow=3)
pcaScoresFromLogFC(lfcMat)

Use 'convert' (ImageMagick) to convert PDF to high-quality PNG

Description

The function makes a system call to convert PDF files to high-quality (300 dpi) PNG files.

Usage

pdf2png(
  ...,
  convert = "convert",
  density = 300,
  outdir = NULL,
  outfile = NULL,
  wait = FALSE
)

Arguments

Value

Output file names are returned invisibly.

Author(s)

Jitao David Zhang <jitao_david.zhang@roche.com>

Examples

  tmpdir <- tempdir()

  pdffile <- file.path(tmpdir, "test-plot.pdf")
  pdf(pdffile)
  plot(1:5)
  dev.off()

  pngfile <- file.path(tmpdir, "test.png")
  pdf2png(pdffile)
  pdf2png(pdffile, outfile=pngfile)

  testfile <- system.file("/doc/intro.pdf", package="limma")
  if(file.exists(testfile)) {
    pdf2png(testfile, outdir=tmpdir)
    Sys.sleep(1)
    dir(tmpdir)

   ## or waiting
    pdf2png(testfile, outdir=tmpdir, wait=TRUE)
  }

S3 method plotPCA

Description

S3 method plotPCA

Usage

plotPCA(x, choices, ...)

Arguments

Value

Depends on the method; see individual method documentation.

Visualise PCA results of expression data with the sample plot

Description

plotPCA is designed to visualize sample relationships revealed by PCA analysis of high-dimensional expression data. It is adapted from the biplot function in the stats package, with functionalities useful for sample visualization and labelling, and removing the visualization of features (usually genes) in the input matrix. The rationale is that in most cases there are too many features to provide an informative visualization.

Usage

## S3 method for class 'prcomp'
plotPCA(
  x,
  choices = c(1, 2),
  text = FALSE,
  points = list(pch = NULL, col = NULL, cex = NULL, bg = NULL, lwd = NULL, lty = NULL,
    order = NULL),
  arrows = FALSE,
  grid = FALSE,
  abline = FALSE,
  xlim = NULL,
  ylim = NULL,
  xlab = NULL,
  ylab = NULL,
  offset,
  main = NULL,
  reverse = c(FALSE, FALSE),
  ...
)

Arguments

Details

The values for text, points and arrows can be

1. Logical. If FALSE, no text or point is added.

2. List. A list containing options passed to text, points, and arrows respectively, such as col, cex, lwd, lty, code, length,angle, and pos (only for text). order decides in what order are the points drawn, which can be useful when there are points to be drawn 'above' other points.

3. A vector of character strigns (only for text)

See examples below.

Value

The value of the rotated data, namely the centered (and scaled if requested) data multiplied by the rotation matrix.

Note

prcomp should be called with retx=TRUE, which is the default behaviour.

See Also

prcomp and pcaScores

Examples

testVal <- matrix(rnorm(10000), nrow=500)
colnames(testVal) <- paste("Sample", 1:ncol(testVal), sep="")
rownames(testVal) <- paste("Gene",1:nrow(testVal), sep="")

testPCA <- prcomp(t(testVal), center=TRUE, scale=TRUE)


plotPCA(testPCA)

plotPCA(testPCA, points=FALSE, text=TRUE, grid=TRUE)

pointsList <- list(col=1:3, bg=21,pch=22, cex=4:1, lwd=1:2, lty=2:4)
textList <- list(col=c("orange", "royalblue"), cex=1.2, srt=15, pos=1)

plotPCA(testPCA, choices=c(1,2), grid=TRUE, points=pointsList,
        text=TRUE)

## visualize dimension 1:3
rop <- par(mfrow=c(1,2), pty="s")
plotPCA(testPCA, choices=c(1,2), grid=TRUE, points=pointsList, text=textList)
plotPCA(testPCA, choices=c(2,3), grid=TRUE, points=pointsList, text=textList)
par(rop)

Plot PCA loading

Description

Plot PCA loading

Usage

plotPCAloading(
  loadings,
  x = 1L,
  y = 2L,
  circle = FALSE,
  title = "",
  subtitle = "",
  ...
)

Arguments

Value

No return value, called for side effects (plotting).

Plot Venn object of the Vennerable package

Description

The function plots Venn objects from the Vennerable package with custom margins that better suit publication figures.

Usage

plotVenn(
  venn,
  main = "",
  show = list(FaceText = "weight", Universe = FALSE),
  ...
)

Arguments

Value

Side effect is used - a plot is generated.

Note

The function requires Vennerable package version 3.0 or later. Plotting logic adapted from Vennerable (GPL license).

Examples

if (requireNamespace("Vennerable", quietly = TRUE)) {
  myVenn <- list(A = LETTERS[1:24], B = LETTERS[3:8], C = LETTERS[5:9])
  plotVenn(Vennerable::Venn(myVenn), main = "Letters")
}

Print PCAScoreMatrix

Description

Print PCAScoreMatrix

Usage

## S3 method for class 'PCAScoreMatrix'
print(x, ...)

Arguments

Value

The input x, invisibly.

Examples

myPCmat <- PCAScoreMatrix(matrix(rnorm(15),ncol=3), c(0.25, 0.15, 0.1))
myPCmat

Print a fcol object

Description

Print a fcol object

Usage

## S3 method for class 'fcol'
print(x, ...)

Arguments

Value

The input x, invisibly.

Examples

fc <- fcol(c("lightblue", "orange", "lightblue"), base=c("orange", "lightblue"))
fc

Internal function to re-calculate breaks of histograms when x-axis is clipped

Description

The function calculates the new break numbers caused by the clipping of x axis. This is usally larger than the original number of breaks .

Usage

qBreaks(x, quantiles = c(0, 0.99), breaks = 100)

Arguments

Value

Integer: number of breaks

Author(s)

Jitao David Zhang <jitao_david.zhang@roche.com>

See Also

This function is directly used by qHist

Examples

testVal <- rnorm(1000)
qBreaks(testVal, quantiles=c(0.25, 0.75), breaks=100)

Histogram with quantile line(s) and text(s)

Description

A handy function to plot histogram with display elements of quantile.

Usage

qHist(x, quantiles = 0.25, breaks = 100, qlty = 2, qlwd = 2, qcol = "red", ...)

Arguments

Details

The appends vertical lines and texts to histograms produced by hist. This can be useful in unspecific filtering of expression data.

Value

The object returned by the hist function, with an extra item named quantiles.

Author(s)

Jitao David Zhang <jitao_david.zhang@roche.com>

See Also

hist

Examples

testVal <- rnorm(1000)
hist(testVal)
qHist(testVal, quantiles=c(0.25, 0.75), border="lightgray")

Convert radian to degree values

Description

Convert radian to degree values

Usage

radian2degree(x)

Arguments

Value

Degree value

Examples

radian2degree(2*pi)
radian2degree(-.5*pi)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

ribiosUtils

bound, boundNorm

Robust distance

Description

A wrapper function for the dist function in the stats package. It replaces NA values in the distance matrix by the maximum distance in the same matrix, therefore prevents cases where hclust fails because of NA distances.

Usage

robustDist(x, ...)

Arguments

Details

In the rare case of all-NA distance matrices, all values are assigned arbitrarily to one.

Value

The same as dist, however without NAs.

Author(s)

Jitao David Zhang <jitao_david.zhang@roche.com>

Examples

mymat <- matrix(c(3,2,1,NA,NA,NA,
                4,1,2,NA,NA,NA,
                NA,NA,NA,5,1,2), ncol=6, byrow=TRUE)
dist(mymat)
robustDist(mymat)

Variance of features in rows

Description

Variance of features in rows

Usage

rowVars(x, na.rm = TRUE)

Arguments

Value

A numeric vector of length nrow(x) with the row-wise variances.

Examples

myVal <- matrix(1:9, nrow=3, byrow=FALSE)
myVar <- rowVars(myVal)
stopifnot(identical(myVar, c(9,9,9)))

Two and three-color panels

Description

Two and three-color panels

Usage

royalbluered(n)

royalredblue(n)

royalbluegrayred(n)

royalredgrayblue(n)

blackyellow(n)

yellowblack(n)

whiteblue(n)

whitered(n)

blackred(n)

blackgreen(n)

whiteblack(n)

blackwhite(n)

turyeb(n)

redgreen(n)

greenred(n)

bluered(n)

redblue(n)

blueblackred(n)

cyanblackyellow(n)

yellowblackcyan(n)

redblackblue(n)

blackredyellow(n)

blackgoldred(n)

magentayellow(n)

yellowmagenta(n)

whiteblueblackheat(n)

heat(n)

Arguments

Value

Character vector of length n coding colors

See Also

blackyellow for two-color systems

Examples

display.threecolor.panels()

Set compact trellis as default

Description

The function sets compact trellis options as default. The previous lattice.options are saved and restored via on.exit when the calling function exits.

Usage

setCompactTrellis()

Value

Invisibly, the previous value of the default.theme lattice option, so it can be restored manually if needed.

Examples

old <- setCompactTrellis()

Plan a square/matrix layout of plots

Description

Plan a square/matrix layout of plots

Usage

squareLayout(n)

Arguments

Value

A vector of integers of length 2. Can be passed to layout or mfrow in par to make the layout.

Author(s)

Jitao David Zhang <jitao_david.zhang@roche.com>

Examples

  
    op <- par(mfrow=squareLayout(7))
    plot(1:5)
    plot(2:6)
    plot(3:7)
    plot(-9:-4)
    plot(8:5)
    plot(5:1)
    plot(1:9)
    par(op)
  

Return a symmetric range

Description

Return a symmetric range

Usage

symrange(x, mid = 0)

Arguments

Value

A vector of two numbers, a symmetric range with mid in the middle

Return available three-color panels

Description

Return available three-color panels

Usage

threecolor.panels()

Value

A vector of character strings

Return available three-color panels

Description

Return available three-color panels

Usage

twocolor.panels()

Value

A vector of character strings

Extract members of each region in Venn diagrams in to a data.frame

Description

Extract members of each region in Venn diagrams in to a data.frame

Usage

vennMembersDataframe(venn)

Arguments

Value

A data.frame containing logical values of sets and elements

Examples

if(requireNamespace("Vennerable")) {
  myList <- list(A=LETTERS[1:5], B=LETTERS[2:7], C=LETTERS[seq(2,9,2)])
  myVenn <- Vennerable::Venn(myList)
  myVennDf <- vennMembersDataframe(myVenn)
  print(myVennDf)
}

Extract members of each region in Venn diagrams in to a list

Description

Extract members of each region in Venn diagrams in to a list

Usage

vennMembersList(venn, removeNULL = TRUE)

Arguments

Value

A named list of members, each list item corresponding to a region in Venn diagrams

Examples

if(requireNamespace("Vennerable")) {
  myList <- list(A=LETTERS[1:5], B=LETTERS[2:7], C=LETTERS[seq(2,9,2)])
  myVenn <- Vennerable::Venn(myList)
  myVennList <- vennMembersList(myVenn)
}

Histogram with clipped x axis

Description

Draw histograms with clipped x axis; the clipping is determined by quantiles of x values.

Usage

xclipHist(
  x,
  xclip = c(0.01, 0.99),
  breaks = 100,
  quantiles = 0.25,
  qlty = 2,
  qlwd = 2,
  qcol = "red",
  ...
)

Arguments

Details

The function clips (subsets) x-axis and recalcualte the breaks so that the clipped image looks like a real subset of the original data.

Value

The object returned by the hist function, with an extra item named quantiles.

Author(s)

Jitao David Zhang <jitao_david.zhang@roche.com>

See Also

qHist, which draws quantile line and texts onto histograms.

Examples

testVal <- c(rnorm(1000),10)
hist(testVal, breaks=100)
xclipRes <- xclipHist(testVal, xclip=c(0.001, 0.999), quantiles=0.50)

xclipRes$quantiles