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 (boxarr) can be drawn automatically not overlapping the boxes. Lexis objects can be used to generate displays with person-years and events.

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, offset=FALSE, ... )
   boxes( obj, ... )
   ## S3 method for class 'Lexis':
   boxes( obj, file,
                wmult = 1.5,
                hmult = 1.5*wmult,
                  cex = 1.5,
               show   = inherits( obj, "Lexis" ),
               show.Y = show,
               show.D = show,
              scale.Y = 1,
             digits.Y = 1,
                eq.wd = TRUE,
                eq.ht = TRUE, ... )
   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.
offset Logical. Should the arrow be offset a bit to the left.
obj A Lexis object, or a transition matrix; that is a matrix
file Name of the file with the code reproducing the plot.
wmult Multiplier for the width of the box relative to the width of the text in the box.
hmult Multiplier for the height of the box relative to the height 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 alongside 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 (with axes 0 to 100 in both directions) and prompts you to click on the locations for the state boxes, and then draws arrows implied by the actual transitions in the Lexis object.

A transition matrix can also be supplied, in which case the row/column names are used as state names.

Optionally returns the R-code reproducing the plot in a file, which can be useful if you want to produce exactly the same plot with differing arrow colors etc.

boxarr draws an arrow between two boxes, on the line conneting the two box centers. The offset argument is used to offset the arrow a bit to the left (in the direction) on order to accomodate arrows both waus between boxes. boxarr returns a named list wit´h elements x, y and d, wher the two formewr is the location of the midpoint and the latter is a unit vector in the direction of the arrow, which is used by boxes.Lexis to position the annotation of arrows with the number of transitions.

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

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 allowing recovery
tm <- rbind( c(NA,1,1), c(1,NA,1), c(NA,NA,NA) )
rownames(tm) <- colnames(tm) <- c("Cancer","Recurrence","Dead")
## Not run: boxes.Lexis( tm, file="" )

# Set up a Lexis object
data(DMlate)
str(DMlate)
dml <- Lexis( entry=list(Per=dodm, Age=dodm-dobth, DMdur=0 ),
               exit=list(Per=dox),
        exit.status=factor(!is.na(dodth),labels=c("DM","Dead")),
               data=DMlate )
# Split follow-up at Insulin
dmi <- cutLexis( dml, cut=dml$doins, new.state="Ins", pre="DM" )
summary( dmi )
## Not run: boxes( dmi, file="" )
# Set up a bogus recovery date
dmi$dorec <- dmi$doins + runif(nrow(dmi),0.5,10)
dmi$dorec[dmi$dorec>dmi$dox] <- NA
dmR <- cutLexis( dmi, cut=dmi$dorec, new.state="DM", pre="Ins" )
summary( dmR )
## Not run: boxes( dmR )
    

[Package Epi version 1.1.5 Index]