plotmat {diagram}

plots a graph (network), based on a transition matrix

Description

visualises a transition matrix as a number of (labeled) boxes connected by (labeled) arrows.

Usage

plotmat(A, pos = NULL, curve = NULL, name = NULL, absent = 0,  
        relsize = 1, lwd = 2, lcol = "black", box.size = 0.1, 
        box.type = "circle", box.prop = 1, box.col = "white", 
        box.lcol = lcol, box.lwd = lwd, 
        shadow.size = 0.01, shadow.col = "grey", dr = 0.01, 
        dtext = 0.3, self.lwd = 1, self.cex = 1, 
        self.shiftx = box.size, self.shifty = NULL, 
        self.arrpos = NULL, arr.lwd = lwd, arr.lcol = lcol, 
        arr.tcol = lcol, arr.col = "black", arr.type = "curved", 
        arr.pos = 0.5, arr.length = 0.4, arr.width = arr.length/2,
        endhead = FALSE, mx = 0.0, my = 0.0, box.cex = 1, 
        txt.col = "black", txt.xadj = 0.5, txt.yadj = 0.5,
        txt.font = 1, prefix = "", cex = 1, cex.txt = cex, 
        add = FALSE, main = "", cex.main = cex, 
        segment.from = 0, segment.to = 1, latex = FALSE, ...)

Arguments

A

square coefficient matrix, specifying the links (rows=to, cols=from).

pos

vector, specifying the number of elements in each graph row, or a 2-column matrix with element position, or NULL. If a 2-column matrix, the values should be withing 0 and 1.

curve

one value, or a matrix, same dimensions as A, specifying the arrow curvature; 0 for straight; NA for default curvature.

name

string vector, specifying the names of elements, dimension = number of rows (columns) of A.

absent

all elements in A different from this value are connected.

relsize

scaling factor for size of the graph.

lwd

default line width of arrow and box.

lcol

default color of arrow line and box line.

box.size

size of label box, one value or a vector with dimension = number of rows of A.

box.type

shape of label box (rect, ellipse, diamond, round, hexa, multi), one value or a vector with dimension=number of rows of A.

box.prop

length/width ratio of label box, one value or a vector with dimension=number of rows of A.

box.col

fill color of label box, one value or a vector with dimension=number of rows of A.

box.lcol

line color of label box, one value or a vector with dimension=number of rows of A.

box.lwd

line width of the box, one value or a vector with dimension = number of rows of A.

shadow.size

relative size of shadow of label box, one value or a vector with dimension=number of rows of A.

shadow.col

color of shadow of label box, one value or a vector with dimension=number of rows of A.

dr

size of segments, in radians, to draw ellipse (decrease for smoother ellipses).

dtext

controls the position of arrow text relative to arrowhead.

self.lwd

line width of self-arrow, (arrow from i to i), one value or a vector with dimension=number of rows of A.

self.cex

relative size of self-arrow, relative to box, one value or a vector with dimension=number of rows of A.

self.shiftx

relative shift of self-arrow, in x-direction, one value or a vector with dimension=number of rows of A.

self.shifty

relative shift of self-arrow, in y-direction, one value or a vector with dimension=number of rows of A.

self.arrpos

position of the self-arrow, angle in radians relative to x-direction, one value or a vector with dimension=number of rows of A.

arr.lwd

line width of arrow, connecting two different points, one value, or a matrix with same dimensions as A.

arr.lcol

color of arrow line, one value, or a matrix with same dimensions as A.

arr.tcol

color of arrow text, one value, or a matrix with same dimensions as A.

arr.col

color of arrowhead, one value, or a matrix with same dimensions as A.

arr.type

type of arrowhead, one of ("curved", "triangle", "circle", "ellipse", "T", "simple", "none"), one value, or a matrix with same dimensions as A.

arr.pos

relative position of arrowhead on arrow segment/curve, one value, or a matrix with same dimensions as A.

arr.length

arrow length, one value, or a matrix with same dimensions as A.

arr.width

arrow width, one value, or a matrix with same dimensions as A.

endhead

if TRUE: the arrow line stops at the arrowhead; default = FALSE and arrow line continues beyond the arrow head.

mx

horizontal shift of the boxes.

my

vertical shift of the boxes.

box.cex

relative size of text in boxes, one value or a vector with dimension=number of rows of A.

txt.col

color of text in boxes, one value or a vector with dimension=number of rows of A.

txt.xadj, txt.yadj

the x and y adjustment of the labels in the boxes, one value or a vector with dimension=number of rows of A values usually within [0,1], although on most devices values outside that interval will also work.

txt.font

the font to be used for the text in boxes, one value or a vector with dimension=number of rows of A.

prefix

to be added in front of non-zero arrow labels.

cex

relative size of text.

cex.txt

relative size of arrow text, one value, or a matrix with same dimensions as A.

add

start a new plot (FALSE), or add to current plot (TRUE).

main

main title. Only effective if add = FALSE.

cex.main

relative size of main title.

segment.from

if not 0 then the arrow line will not start at the position as given in A, but with an offset. one value, or a matrix with same dimensions as A

segment.to

if not 1 then the arrow line will not end at the position as given in A, but with an offset. one value, or a matrix with same dimensions as A

latex

if FALSE then expressions will be interpreted before print, if TRUE they will be printed literally to the plot. Set to TRUE if LaTeX code is to be printed.

...

other arguments passed to function shadowbox.

Details

The square transition matrix A determines the number of elements of A (rows of A) and which elements are connected (all values in A different from absent).

A also provides the values of arrowlabels.

The position of the elements are specified with pos, which is either NULL, or a vector specifying the number of elements on a row, or a 2-columned matrix specifying the (x,y) position of each element.

The ordering of elements is according to the row number of A

• when pos is NULL, the elements will be arranged on a circle

• when pos is a vector, it specifies the number of elements in each row. For instance, with pos = c(3,2,1) the elements will be arranged in 3 rows (length of vector); on top row, 3 elements; on second row 2, and on third row 1 element will be positioned. All elements within a row are equally distributed horizontally, all rows are equally distributed vertically.

• when pos is a matrix, it specifies the x (1st column) and y (2nd column) position of each element.

The offset from x-axis and from y-axis can be changed with mx and my.

The name of each element is given by vector name; this name is written in its respective box.

The relative size of this text can be changed by box.cex.

By default, a shadow is drawn, in the right-lower corner of the box.

The shadow color and relative size is specified with shadow.col and shadow.size respectively.

both can be one value (equal shadows) or a vector, specifying one value for each box shadow.

shadow.size = 0 toggles off the drawing of the shadow.

The type of the box is set with "box.type" which can take on the values:

• "rect": a rectangle,

• "ellipse": an ellipse,

• "diamond": a diamond,

• "round": a rectangle with rounded left and right edges,

• "hexa": a hexagonal shape,

• "multi": a multigonal shape.

• "none" if no box is to be drawn.

The length of the box is set with box.size, the proportionality (length/width) ratio with box.prop.

The fill-color of the box is specified with box.col; the line width of the box with box.lwd and the line color with box.lcol;

All box properties can be either one value (equal boxes) or a vector, specifying one value for each box.

For all values A[i,j] of A which are not equal to absent, one arrow is drawn *from* column-element j *to* the row-element i of A.

The curvature of this arrow is specified with matrix element curve[i,j],

where 'curve' is either NULL, one value, or has the same dimension as A.

A straight arrow has curvature 0, NA (the default) chooses a default curvature,

Positive or negative values of curve draws curved arrows.

If the arrow is curved, then dr is the increment used to draw the ellipse; set to a lower value for smoother lines.

The type of the arrowhead is set with arr.type which can take the values:

• "simple" : uses comparable R function arrows

• "triangle": uses filled triangle

• "curved" : draws arrowhead with curved edges

• "circle" : draws circular head

• "ellipse" : draws ellepsoid head

• "T" : draws T-shaped (blunt) head

• "none" : no arrow head is drawn

The line color and width of the arrow line is set with arr.lcol and arr.lwd

The size of the arrow head is specified with arr.length and arr.width,

the position of the arrow head is specified with arr.pos (value between [0,1]).

see Arrowhead for details on arrow head

Value

a list containing:

arr

a data.frame with arrow information:

• nonzero: the elements between which an arrow is drawn.

• Angle: the angle of the arrow.

• Value: the value written next to the arrow head.

• rad: the radius of the arrow (if 0: straight line).

• ArrowX: the x-position of arrowhead.

• ArrowY: the y-position of arrowhead.

• TextX: the x-position of arrowtext.

• TextY: the y-position of arrowtext.

.

comp

a matrix with the element position (centre of the boxes).

radii

the radiusses in x- and y-direction of the boxes.

rect

the "xleft","ybot","xright",and "ytop" of the boxes - redundant.

Author(s)

Karline Soetaert <[e-mail]>

See Also

shadowbox,

Arrowhead from package shape

try: demo(plotmat)

Examples

M <- matrix(nrow = 4, ncol = 4, byrow = TRUE, data = 0)
pp <- plotmat(M, pos = c(1, 2, 1), name = c("A", "B", "C", "D"),
              lwd = 1, box.lwd = 2, cex.txt = 0.8, 
              box.size = 0.1, box.type = "square", box.prop = 0.5,
              main = "plotmat")
pp

# when explicitly given, pos should should be inbetween 0, 1
pos <- cbind (c(0.2, 0.4, 0.6, 0.8), c(0.8, 0.6, 0.4, 0.2))

pp <- plotmat(M, pos = pos, name = c("A", "B", "C", "D"),
              lwd = 1, box.lwd = 2, cex.txt = 0.8, 
              box.size = 0.1, box.type = "square", box.prop = 0.5,
              main = "plotmat")

              
# includes arrows between boxes
pm <- par(mfrow = c(2, 2))
M  <- matrix(nrow = 4, ncol = 4, byrow = TRUE, data = 0)
M[2, 1] <- M[3, 1] <- M[4, 2] <- M[4, 3] <- "f1"

col   <- M
col[] <- "red"
col[2, 1] <- col[3, 1] <- "blue"
pp <- plotmat(M, pos = c(1, 2, 1), curve = 0, name = 1:4,
              lwd = 1, box.lwd = 2, box.cex = 1:4, cex.txt = 0.8, 
              arr.lcol = col, arr.tcol = col, 
              arr.col = col, box.type = "circle",
              box.prop = 1.0, main = "plotmat")

pp <- plotmat(M, pos = c(1, 2, 1), curve = 0, name = 1:4,
              lwd = 1, box.lwd = 2, box.cex = 1:4, cex.txt = 0.8, 
              arr.lcol = col, arr.tcol = col, arr.col = col, 
              box.type = "circle", box.prop = 1.0, arr.len = 0.3,
              segment.from = 0.35, segment.to = 0.65)

M[1, 2] <- M[1, 3] <- M[2, 4] <- M[3, 4] <- "f2"

pp <- plotmat(M, pos = c(1, 2, 1), curve = 0.1, name = 1:4,
              lwd = 1, box.lwd = 2, box.cex = 1:4, cex.txt = 0.8, 
              arr.lcol = col, arr.tcol = col, 
              arr.col = col, box.type = "none",
              box.prop = 1.0, main = "plotmat", arr.len = 0.2,
              segment.from = 0.3, segment.to = 0.7)

pp <- plotmat(M, pos = c(1, 2, 1), curve = 0.1, name = 1:4, 
              box.lwd = 2, box.cex = 1:4, cex.txt = 0.8, 
              arr.lcol = col, arr.tcol = "green", 
              arr.col = col, arr.pos = 0.7,
              arr.type = "simple", lwd = 2, box.type = "none",
              box.prop = 1.0, main = "plotmat", arr.len = 0.2,
              segment.from = 0.3, segment.to = 0.7)
par(mfrow=pm)
  
# self arrows
diag(M) <- "self"
pp <- plotmat(M, pos = c(2, 2), curve = 0, name = LETTERS[1:4],
              lwd = 1, box.lwd = 2, cex.txt = 0.8, self.cex = 0.5,
              self.shiftx = c(-0.1, 0.1, -0.1, 0.1),
              box.type = "diamond", box.prop = 0.5, main = "plotmat")


# different arrows  
M <- matrix(nrow = 4, ncol = 4, data = 0)
M[2, 1]<- 1 ; M[4, 2] <- 2 ; M[3, 4] <- 3; M[1, 3] <- 4
pp <- plotmat(M, pos = c(1, 2, 1), curve = 0.2, name = letters[1:4],
              lwd = 1, box.lwd = 2, cex.txt = 0.8, arr.type = "triangle",
              box.size = 0.1, box.type = "hexa", box.prop = 0.5,
              main = "plotmat")

arrlwd <- M*2
arr.length <- M*0.4
cextxt <- M*0.8
plotmat(M, pos = c(1, 2, 1), curve = 0.2, name = letters[1:4], lwd = 1,
        box.lwd = 2, arr.type = "triangle", box.size = 0.1,
        box.type = "hexa", box.prop = 0.5, main = "plotmat",
        arr.lwd = arrlwd, arr.length = arr.length, cex.txt = cextxt,
        txt.font = 1:4, txt.xadj = seq(-3, 3, length.out = 4),
        txt.yadj = 1)

M <- matrix(nrow = 4, ncol = 4, byrow = TRUE, data = 0)
M     <- as.data.frame(M)
M[[2,1]]<- "k[si]"
M[[3,1]]<- "k[N]"
M[[4,2]]<- "sqrt(frac(2,3))"

names <-
  c(expression(lambda[12]), "?", 
    expression(lambda[13]),expression(lambda[23]))

plotmat(M, pos = c(1, 2, 1), name = names, lwd = 1, box.lwd = 2, 
        curve = 0, cex.txt = 0.8, box.size = 0.1, box.type = "square",
        box.prop = 0.5, main = "plotmat")
              
plotmat(M, name = letters[1:4], curve = 0, box.cex = 1:4, box.lwd = 4:1,
        box.size = 0.075, arr.pos = 0.7, 
        box.col = c("lightblue", "green", "yellow", "orange"))


# No arrows, just lines with different colors
M <- matrix(nrow = 4, ncol = 4, data = 0)
M[2, 1]<- 1 ; M[4, 2] <- 2 ; M[3, 4] <- 3; M[1, 3] <- 4
pp <- plotmat(M, pos = c(1, 2, 1), curve = 0.2, name = letters[1:4],
              lwd = 1, box.lwd = 2, cex.txt = 0.8, arr.type = "none",
              arr.lcol = M, box.size = 0.1, box.type = "hexa", 
              box.prop = 0.5, main = "plotmat")

pp <- plotmat(M, pos = c(1, 2, 1), curve = 0.4, name = "",
              arr.type = "none", arr.lcol = M, 
              box.type = "none", cex.txt = 0, 
              main = "plotmat")