Epi (version 1.1.20)

tbox: 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, wd, ht,
         font=2, lwd=2,
         col.txt="black",
         col.border="black",
         col.bg="transparent" )
   dbox( x, y, wd, ht=wd,
         font=2, lwd=2, cwd=5,
         col.cross="black",
         col.border="black",
         col.bg="transparent"  )
   boxarr( b1, b2, offset=FALSE, pos=0.45, ... )
   boxes( obj, ... )
      ## S3 method for class 'Lexis':
boxes( obj, file,
             detailed = FALSE,
               boxpos = FALSE,
                wmult = 1.5,
                hmult = 1.5*wmult,
                  cex = 1.5,
               show   = inherits( obj, "Lexis" ),
               show.Y = show,
              scale.Y = 1,
             digits.Y = 1,
               show.D = show,
              scale.D = FALSE,
             digits.D = as.numeric(as.logical(scale.D)),
                eq.wd = TRUE,
                eq.ht = TRUE,
                   wd,
                   ht,
               subset = NULL,
              exclude = NULL,
                 font = 2,
                  lwd = 2,
              col.txt = "black",
           col.border = col.txt,
               col.bg = "transparent",
              col.arr = "black",
              lwd.arr = 2,
             font.arr = 2,
              txt.arr = NULL,
          col.txt.arr = col.arr,
           offset.arr = 2, ... )
   fillarr( x1, y1, x2, y2, gap=2, 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.

wd

width of box.

ht

height of box.

font

Font for the text. Defaults to 2 (=bold).

lwd

Line width of the boxborders.

col.txt

Color for the text in boxes.

col.border

Color of the box border.

col.bg

Background color for the interior of the box.

...

Arguments to be passed on to the call of other functions.

cwd

Width of the lines in the cross.

col.cross

Color of the cross.

b1

Coordinates of the "from" box. A vector with 4 components, x, y, w, h.

b2

Coordinates of the "to" box; like b1.

offset

Logical. Should the arrow be offset a bit to the left.

pos

Numerical between 0 and 1, determines the position of the point on the arrow which is returned.

obj

A Lexis object, or a transition matrix; that is a matrix

file

Name of the file with the code reproducing the plot.

detailed

Should the output of R-code be detailed, showing all parameters?

boxpos

If TRUE the boxes are positioned equidistantly on a circle, if FALSE (the default) you are queried to click on the screen for the positions. This argument can also be a named li

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.

scale.Y

What scale should be used for annotation of person-years.

digits.Y

How many digits after the decimal point should be used for the person-years.

show.D

Should transitions be put alongside the arrows. Ignored if obj is not a Lexis object.

scale.D

If this a scalar, rates instead of no. transitions are printed at the arrows, scaled by scale.D.

digits.D

How many digits after the decimal point should be used for the rates.

eq.wd

Should boxes all have the same width?

eq.ht

Should boxes all have the same height?

subset

Draw only boxes and arrows for a subset of the states. Can be given either as a numerical vector or character vector state names.

exclude

Exclude states from the plot. The complementary of subset. Ignored if subset is given.

col.arr

Color of the arrows between boxes. A vector of character strings, the arrows are referred to as the row-wise sequence of non-NA elements of the transition matrix. Thus the first ones refer to the transitions out of state 1, in order of

lwd.arr

Line withs of the arrows.

font.arr

Font of the text annotation the arrows.

txt.arr

Text put on the arrows.

col.txt.arr

Colors for text on the arrows.

offset.arr

The amount offset between arrows that go between the same pair of boxes (two-way transitions).

x1

x-coordinate of the starting point.

y1

y-coordinate of the starting point.

x2

x-coordinate of the end point.

y2

y-coordinate of the end point.

gap

Length of the gap between the box and the ends of the arrows.

fr

Length of the arrow as the fraction of the distance between the boxes. Ignored unless given explicitly, in which case any value given for gap is ignored.

angle

What angle should the arrow-head have?

length

Length of the arrow head in inches. Defaults to 1/30 of the physical width of the plot.

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 a point on the arrow, designated to be used for annotation of the arrow.

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 if boxpos=FALSE (the default) 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 connecting the two box centers. The offset argument is used to offset the arrow a bit to the left (as seen in the direction of the arrow) on order to accommodate arrows both ways between boxes. boxarr returns a named list with elements x, y and d, where the two former give the location of a point on the arrow used for printing (see argument pos) 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.

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, col.txt="blue" )
bo  <- tbox( "other Ca", 45, 80, 22, 10, col.txt="gray" )
bc  <- tbox( "Ca"      , 45, 60, 22, 10, col.txt="red" )
bd  <- tbox( "DM"      , 45, 40, 22, 10, col.txt="blue" )
bcd <- tbox( "Ca + DM" , 80, 60, 22, 10, col.txt="gray" )
bdc <- tbox( "DM + Ca" , 80, 40, 22, 10, col.txt="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")
boxes.Lexis( tm, file="", boxpos=TRUE )
boxes.Lexis( tm, file="", detailed=TRUE, boxpos=TRUE )
# Illustrate texting of arrows
boxes.Lexis( tm, boxpos=TRUE, txt.arr=c("en","to","tre","fire") )
boxes.Lexis( tm, boxpos=TRUE, txt.arr=c(expression(lambda[C]),
                                        expression(mu[C]),
                                        "recovery",
                                        expression(mu[R]) ) )

# 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 )
boxes( dmi, boxpos=TRUE, 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 )
boxes( dmR, boxpos=TRUE, file="" )