tbox {Epi}R Documentation

Draw boxes and arrows for illustration of multistate models.

Description

Boxes can be drawn with text (tbox) or a cross (dbox), and arrows pointing between the boxes can be drawn automatically not overlapping the boxarr boxes.

Usage

   tbox( txt, x, y, w, h,
         font = 2, txt.col = "black", lwd = 2,
         border = "black", col = "transparent", ...)
   dbox( x, y, w, h=w,
         font=2, cross.col="black", cwd=5,
         lwd=2, border="black", col="transparent" )
   boxarr( b1, b2, ... )
   ## S3 method for class 'Lexis':
   boxes( obj, file, mult = 1.5, cex = 1.5,
               show   = inherits( obj, "Lexis" ),
               show.Y = show,
               show.D = show,
              scale.Y = 1,
             digits.Y = 1,
                eq.wd = FALSE,
                eq.ht = FALSE, ... )
   fillarr( x1, y1, x2, y2, fr=0.8,
            angle=17, lwd=2, length=par("pin")[1]/30, ... )
   

Arguments

txt Text to be placed inside the box.
x x-coordinate of center of box.
y y-coordinate of center of box.
w width of box.
h height of box.
font Font for the text.
txt.col Color for the text.
lwd Line width of the box / arrow.
border Color of the box border.
col Background color for the interior of the box.
... Arguments to be passed on to the call of other functions.
cross.col Color of the cross.
cwd Width of the lines in the cross.
b1 Coordinates of the "from" box. A vector with 4 components, x, y, w, h.
b2 Coordinates of the "to" box.
obj A Lexis object, or a transition matrix; that is a matrix
file Name of the file with the code reproducing the plot.
mult Multiplier for the withdt of the box relative to the width of the text in the box.
cex Character expansion for text in the box.
show Should person-years and transitions be put in the plot. Ignored if obj is not a Lexis object.
show.Y Should person-years be put in the boxes. Ignored if obj is not a Lexis object.
show.D Should transitions be put alonside the arrows. Ignored if obj is not a Lexis object.
scale.Y What scale should be used for annotation of person-years.
digits.Y How many digtis after the decimal point should be used for the person-years.
eq.wd Should boxes all have the same width?
eq.ht Should boxes all have the same height?
x1 x-coordinate of the starting point.
y1 y-coordinate of the starting point.
x2 x-coordinate of the ending point.
y2 y-coordinate of the ending point.
fr Length of the arrow as the fraction of the distance between the boxes.
angle What angle should the arrow-head have?
length Length of the arrow head in inches.

Details

These functions are designed to facilitate the drawing of multistate models, mainly by automatic calculation of the arrows between boxes. tbox draws a box with centered text, and returns a vector of location, height and width of the box. This is used when drawing arrows between boxes. dbox draws a box with a cross, symbolizing a death state. boxarr draws an arrow between two boxes, making sure it does not intersect the boxes. Only straight lines are drawn.

boxes.Lexis takes as input a Lexis object sets up an empty plot area and prompts you to click on the locations for the state boxes, and the draws the model. A transition matrix can also be supplied, in which case the row/column names are used as state names. Optionally returns a file with R-code reproducing the plot.

fill.arr is just a utility drawing nicer arrows than the default arrows command, basically by using filled arrow-heads.

Value

The functions tbox and dbox return the location and dimension of the boxes, c(x,y,w,h), which are designed to be used as input to the boxarr function.
The boxarr function returns the coordinates (as a named list with names x and y) of the midpoint of the arrow, designated to be used for annotation of the arrow.

Author(s)

Bendix Carstensen

Examples

par( mar=c(0,0,0,0), cex=1.5 )
plot( NA,
      bty="n",
      xlim=0:1*100, ylim=0:1*100, xaxt="n", yaxt="n", xlab="", ylab="" )
bw  <- tbox( "Well"    , 10, 60, 22, 10, txt.col="blue" )
bo  <- tbox( "other Ca", 45, 80, 22, 10, txt.col="gray" )
bc  <- tbox( "Ca"      , 45, 60, 22, 10, txt.col="red" )
bd  <- tbox( "DM"      , 45, 40, 22, 10, txt.col="blue" )
bcd <- tbox( "Ca + DM" , 80, 60, 22, 10, txt.col="gray" )
bdc <- tbox( "DM + Ca" , 80, 40, 22, 10, txt.col="red" )
      boxarr( bw, bo , col=gray(0.7), lwd=3 )
# Note the argument adj= can takes values outside (0,1) 
text( boxarr( bw, bc , col="blue", lwd=3 ),
      expression( lambda[Well] ), col="blue", adj=c(1,-0.2), cex=0.8 )
      boxarr( bw, bd , col=gray(0.7) , lwd=3 )
      boxarr( bc, bcd, col=gray(0.7) , lwd=3 )
text( boxarr( bd, bdc, col="blue", lwd=3 ),
      expression( lambda[DM] ), col="blue", adj=c(1.1,-0.2), cex=0.8 )
# Set up a transition matrix
tm <- rbind( c(NA,1,1), c(NA,NA,1), c(NA,NA,NA) )
rownames(tm) <- colnames(tm) <- c("Cancer","Recurrence","Dead")
## Not run: boxes.Lexis( tm, file="" )
    

[Package Epi version 1.1.4 Index]