# plots a graph (network), based on a transition matrix visualises a transition matrix as a number of (labeled) boxes connected by (labeled) arrows. ```r 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`. ## Returns 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 ## Examples ```r 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") ``` ## 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 ## See Also `shadowbox`, `Arrowhead` from package shape try: demo(plotmat)

plotmat function