Learn R Programming

Publish (version 2017.10.24)

plotConfidence: Plot confidence intervals

Description

Function to plot confidence intervals with their values and additional labels. One anticipated use of this function involves first the generation of a regression object, then arrangement of a result table with "regressionTable", further arrangment of table with with e.g. "fixRegressionTable" and various user defined changes - and then finally table along with forest plot using the current function.

Usage

plotConfidence(x, lower, upper, pch = 16, cex = 1, lwd = 1, col = 4,
  xlim, xlab, labels, title.labels, values, title.values, order,
  leftmargin = 0.025, rightmargin = 0.025, stripes, factor.reference.pos,
  factor.reference.label = "Reference", factor.reference.pch = 8,
  refline = 1, xratio, y.offset = 0, y.title.offset = 1.3, digits = 2,
  format, extremearrows.length = 0.05, extremearrows.angle = 30,
  add = FALSE, layout = TRUE, xaxis = TRUE, ...)

Arguments

x

Either a vector containing the point estimates or A list whose first element contains the point estimates. Further list elements can contain the confidence intervals and labels. In this case the list needs to have names 'lower' and 'upper' to indicate the values of the lower and the upper limits of the confidence intervals, respectively, and 'labels' to indicate a vector or matrix or list with labels.

lower

Lower confidence limits. Used if object x is a vector and if x is a list lower overwrites element x$lower.

upper

Upper confidence limits. Used if object x is a vector and if x is a list upper overwrites element x$upper.

pch

Symbol for points.

cex

Defaults size of all figures and plotting symbol. Single elements are controlled separately. See ....

lwd

Default width of all lines Single elements are controlled separately. See ....

col

Default colour of confidence intervals.

xlim

Plotting limits for the confidence intervals. See also xratio on how to control the layout.

xlab

Label for the x-axis.

labels

Vector or matrix or list with labels. Used if object x is a vector and if x is a list it overwrites element x$labels. If labels=FALSE do not draw labels.

title.labels

Title of the labels. If labels is a matrix or list title.labels should be a vector with as many elements as labels has columns or elements.

values

Either logical or vector, matrix or list with values. If values=TRUE values are constructed according to format from lower and upper overwrites constructed values. If values=FALSE do not draw values.

title.values

Title of the values. If values is a matrix or list title.labels should be a vector with as many elements as values has columns or elements.

order

Order of the three blocks: labels, confidence limits, values. See examples.

leftmargin

Percentage of plotting region used for leftmargin. Default is 0.025. See also Details.

rightmargin

Percentage of plotting region used for rightmargin. Default is 0.025. See also Details.

stripes

Vector of up to three Logicals. If TRUE draw stripes into the background. The first applies to the labels, the second to the graphical presentation of the confidence intervals and the third to the values. Thus, stripes

factor.reference.pos

Position at which factors attain reference values.

factor.reference.label

Label to use at factor.reference.pos instead of values.

factor.reference.pch

Plotting symbol to use at factor.reference.pos

refline

Vertical line to indicate the null hypothesis. Default is 1 which would work for odds ratios and hazard ratios.

xratio

One or two values between 0 and 1 which determine how to split the plot window in horizontal x-direction. If there are two blocks (labels, CI) or (CI, values) only one value is used and the default is 0.618 (goldener schnitt) which gives the graphical presentation of the confidence intervals 38.2 graph. The remaining 61.8 If there are three blocks (labels, CI, values), xratio has two values which default to fractions of 0.7 according to the relative widths of labels and values, thus by default only 0.3 are used for the graphical presentation of the confidence intervals. The remaining 30 confidence intervals. See examles

y.offset

Either a single value or a vector determining the vertical offset of all rows. If it is a single value all rows are shifted up (or down if negative) by this value. This can be used to add a second group of confidence intervals to an existing graph or to achieve a visual differentiation of rows that belong together. See examples.

y.title.offset

Numeric value by which to vertically shift the titles of the labels and values.

digits

Number of digits, passed to pubformat and formatCI.

format

Format for constructing values of confidence intervals. Defaults to '(u;l)' if there are negative lower or upper values and to '(u-l)' otherwise.

extremearrows.length

Length of the arrows in case of confidence intervals that stretch beyond xlim.

extremearrows.angle

Angle of the arrows in case of confidence intervals that stretch beyond xlim.

add

Logical. If TRUE do not draw labels or values and add confidence intervals to existing plot.

layout

Logical. If FALSE do not call layout. This is useful when several plotConfidence results should be combined in one graph and hence layout is called externally.

xaxis

Logical. If FALSE do not draw x-axis.

...

Used to control arguments of the following subroutines: plot: Applies to plotting frame of the graphical presentation of confidence intervals. Use arguments of plot, e.g., plot.main="Odds ratio". points, arrows: Use arguments of points and arrows, respectively. E.g., points.pch=8 and arrows.lwd=2. refline: Use arguments of segments, e.g., refline.lwd=2. See segments. labels, values, title.labels, title.values: Use arguments of text, e.g., labels.col="red" or title.values.cex=1.8. xaxis: Use arguments of axis, e.g., xaxis.at=c(-0.3,0,0.3) xlab: Use arguments of mtext, e.g., xlab.line=2. stripes: Use arguments of stripes. See examples. See examples for usage.

Value

List of dimensions and coordinates

Details

Function to plot means and other point estimates with confidence intervals, their values and additional labels . Horizonal margins as determined by par()$mar are ignored. Instead layout is used to divide the plotting region horizontally into two or three parts plus leftmargin and rightmargin.

When values is FALSE there are only two parts. The default order is labels on the left confidence intervals on the right. When no labels are given or labels is FALSE there are only two parts. The default order is confidence intervals on the left values on the right.

The default order of three parts from left to right is labels, confidence intervals, values. The order can be changed as shown by the examples below. The relative widths of the two or three parts need to be adapted to the actual size of the text of the labels. This depends on the plotting device and the size of the font and figures and thus has to be adjusted manually.

Oma can be used to further control horizontal margins, e.g., par(oma=c(0,4,0,4)).

If confidence limits extend beyond the range determined by xlim, then arrows are drawn at the x-lim borders to indicate that the confidence limits continue.

Examples

Run this code
# NOT RUN {
library(Publish)
data(CiTable)

## columns 6, 7, 8, 9 contain the hazard ratio, the lower
## and the upper confidence limits and the p-values, respectively
head(CiTable[,6:9])

## columns 1,2,3,4,5 contain the labels
head(CiTable[,1:5])

## A first draft version of the plot is obtained as follows
plotConfidence(x=CiTable[,6:8], labels=CiTable[,1:5])

## The graph consist of at most three blocks:
##
## block 1: labels
## block 2: printed values of the confidence intervals
## block 3: graphical presentation of the confidence intervals
##
## NOTE: block 3 appears always, the user decides if also
##       blocks 1, 2 should appear
##
## The blocks are arranged with the function layout
## and the default order is 1,3,2 such that the graphical
## display of the confidence intervals appears in the middle
##
## the order of appearance of the three blocks can be changed as follows
plotConfidence(x=CiTable[,6:8],
               labels=CiTable[,1:5],
               order=c(1,3,2))
plotConfidence(x=CiTable[,6:8],
               labels=CiTable[,1:5],
               order=c(2,3,1))
## if there are only two blocks the order is 1, 2
plotConfidence(x=CiTable[,6:8],
               labels=CiTable[,1:5],
               values=FALSE,
               order=c(2,1))
plotConfidence(x=CiTable[,6:8],
               labels=CiTable[,1:5],
               values=FALSE,
               order=c(1,2))



## The relative size of the blocks needs to be controlled manually
## by using the argument xratio. If there are only two blocks
plotConfidence(x=CiTable[,6:8],
               labels=CiTable[,1:5],xratio=c(0.4,0.15))

## The amount of space on the left and right margin can be controlled
## as follows:
plotConfidence(x=CiTable[,6:8],labels=CiTable[,1:5],xratio=c(0.4,0.15),
               leftmargin=0.1,rightmargin=0.00)

## The actual size of the current graphics device determines
## the size of the figures and the space between them.
## The sizes and line widths are increased as follows:
plotConfidence(x=CiTable[,6:8],
               xlab="Hazard ratio",
               labels=CiTable[,1:5],
               cex=1.3,
               lwd=3,
               xaxis.lwd=1.3,
               xaxis.cex=1.3)
## Note that 'cex' of axis ticks is controlled via 'par' but
## cex of the label via argument 'cex' of 'mtext'.
## The sizes and line widths are decreased as follows:
plotConfidence(x=CiTable[,6:8],
               labels=CiTable[,1:5],
               cex=0.8,
               lwd=0.8,
               xaxis.lwd=0.8,
               xaxis.cex=0.8)


## Another good news is that all figures can be controlled separately

## The size of the graphic device can be controlled in the usual way, e.g.:
# }
# NOT RUN {
    pdf("~/tmp/testCI.pdf",width=8,height=8)
    plotConfidence(x=CiTable[,6:8],
                   labels=CiTable[,1:5])
    dev.off()
# }
# NOT RUN {
## More control of the x-axis and confidence intervals that
## stretch outside the x-range.
plotConfidence(x=CiTable[,6:8],
               xlab="Hazard ratio",
               xlab.line=1.8,
               xaxis.at=c(0.8,1,1.3),
               labels=CiTable[,1:5],xlim=c(0.8,1.3))

## log-scale
plotConfidence(x=CiTable[,6:8],
               xlab="Hazard ratio",
               xlab.line=1.8,
               xaxis.at=c(0.8,1,1.3),
               labels=CiTable[,1:5],xlim=c(0.8,1.3),plot.log="x")
## More pronounced arrows
## Coloured xlab expression
plotConfidence(x=CiTable[,6:8],
               xlab=expression(HR[1](s)),
               xlab.line=1.8,
               xlab.col="darkred",
               extremearrows.angle=50,
               extremearrows.length=0.1,
               labels=CiTable[,1:5],xlim=c(0.8,1.3))

## Controlling the labels and their titles
## and the values and their titles
plotConfidence(x=CiTable[,6:8],
               labels=CiTable[,1:5],
               xlab="Hazard ratio",
               title.values=expression(bold(HR (CI[95]))),
               title.labels=c("Drug/Time","Dose","Mean","St.dev.","N"),
               factor.reference.pos=c(1,10,19),
               cex=1.3,
               xaxis.at=c(0.75,1,1.25,1.5,2))

## For factor reference groups, one may want to replace the
## confidence intervals by the word Reference, as in the previous example.
## To change the word 'Reference' we use the argument factor.reference.label:
## To change the plot symbol for the reference lines factor.reference.pch
## To remove the plot symbol use 'NA' as follows:
plotConfidence(x=CiTable[,6:8],
               labels=CiTable[,1:5],
               xlab="Hazard ratio",
               factor.reference.label="Ref",
               title.values=expression(bold(HR (CI[95]))),
               title.labels=c("Drug/Time","Dose","Mean","St.dev.","N"),
               factor.reference.pos=c(1,10,19),
               factor.reference.pch=NA,
               cex=1.3,
               xaxis.at=c(0.75,1,1.25,1.5,2))


## changing the style of the graphical confidence intervals
plotConfidence(x=CiTable[,6:8],
               labels=CiTable[,1:5],
               xlab="Hazard ratio",
               factor.reference.pos=c(1,10,19),
               points.pch=15,
               points.col=rainbow(27),
               points.cex=2,
               arrows.col="darkblue",
               cex=1.3,
               order=c(1,3,2),
               xaxis.at=c(0.75,1,1.25,1.5))


## the values block of the graph can have multiple columns as well
## to illustrate this we create the confidence intervals
## before calling the function and then cbind them
## to the pvalues
HR <- pubformat(CiTable[,6])
CI95 <- formatCI(lower=CiTable[,7],upper=CiTable[,8],format="(l-u)")
pval <- format.pval(CiTable[,9],digits=3,eps=10^{-3})
pval[pval=="NA"] <- ""
plotConfidence(x=CiTable[,6:8],
               labels=CiTable[,1:5],
               values=list("HR"=HR,"CI-95"=CI95,"P-value"=pval),
               cex=1.2,
               xratio=c(0.5,0.3))

## Finally, vertical blocks can be delimited with background color
## NOTE: this may slow things down and potentially create
##       large figures (many bytes)
col1 <- rep(c(prodlim::dimColor("green",density=22),
              prodlim::dimColor("green")),length.out=9)
col2 <- rep(c(prodlim::dimColor("orange",density=22),
              prodlim::dimColor("orange")),length.out=9)
col3 <- rep(c(prodlim::dimColor("blue",density=22),
              prodlim::dimColor("blue")),length.out=9)
plotConfidence(x=CiTable[,6:8],
               labels=CiTable[,1:5],
               stripes=c(1,0,1),
               stripes.col=c(col1,col2,col3))
plotConfidence(x=CiTable[,6:8],
               labels=CiTable[,1:5],
               stripes=c(1,1,1),
               stripes.col=c(col1,col2,col3))

threegreens <- c(prodlim::dimColor("green",density=55),
                 prodlim::dimColor("green",density=33),
                 prodlim::dimColor("green",density=22))
plotConfidence(x=CiTable[,6:8],
               labels=CiTable[,1:5],
               values=FALSE,
               xlim=c(0.75,1.5),
               stripes=c(1,1,1),
               xratio=c(0.5,0.15),
               stripes.horizontal=c(0,9,18,27)+0.5,
               stripes.col=threegreens)

# }

Run the code above in your browser using DataLab