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

plotmat {diagram} | R Documentation

## 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.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.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"), 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

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 <karline.soetaert@nioz.nl>

### 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.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.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.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.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")

    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"))

[Package diagram version 1.6.4 Index]