# pimage

From seriation v1.2-2
by Michael Hahsler

##### Permutation Image Plot

Provides methods for plotting image plots for
matrix and `dist`

objects given a permutation.
By default, no permutation is performed.
This plot can also
be used as a more versatile replacement of `image`

plot
in graphics based on grid.

- Keywords
- hplot

##### Usage

```
pimage(x, order = NULL, col = NULL, main ="", xlab = "", ylab = "",
axes = "auto", zlim=NULL, key=TRUE, key.lab="", symkey=TRUE,
upper.tri = TRUE, lower.tri = TRUE, prop = NULL,
..., newpage=TRUE, pop=TRUE, gp=NULL)
```

##### Arguments

- x
- a matrix or an object of class
`dist`

. - order
- an object of class
`ser_permutation`

. If`NULL`

the order in`x`

is plotted. - col
- a list of colors used. If
`NULL`

, a gray scale is used (for matrix larger values are displayed darker and for`dist`

smaller distances are darker). For matrices containing logical data, black and white is used. For matrices containing negative values a symmetric diverging color palette is used. - main
- plot title.
- xlab, ylab
- labels for the x and y axes.
- axes
- a character string indicating if axes labels (column and row
names of
`x`

) should be potted. Possible values are`"auto"`

(only plot if less then 25 labels),`"x"`

,`"y"`

,`"both"`

and`"none"`

. - zlim
- vector with two elements giving the range (min, max) for representing the values in the matrix.
- key
- logical; add a color key? No key is available for logical matrices.
- key.lab
- string plotted next to the color key.
- symkey
- logical; if
`x`

contains negative values, should the color palate be symmetric (zero is in the middle)> - upper.tri, lower.tri
- a logical indicating whether to show the upper or lower triangle of the distance matrix.
- prop
- logical; draw the cells in the image proportional (defaults to
`TRUE`

for`dist`

and`FALSE`

for matrix). - …
- further arguments passed on to
`image`

in graphics. - newpage, pop
- two logical. Start plot on a new page and pop the viewports after plotting (see grid).
- gp
- a
`gpar`

object (see grid).

##### Details

Plots a matrix in its original row and column orientation. This means, in a plot the columns become the x-coordinates and the reversed rows the y-coordinates.

If `x`

is of class `dist`

it is converted to full-storage
representation before plotting.

The viewports used for plotting are called: `"plot"`

, `"image"`

and `"colorkey"`

.

##### See Also

##### Examples

```
x <- matrix(sample(c(FALSE, TRUE), 300, rep=TRUE), ncol=10,
dimnames = list(1:30, LETTERS[1:10]))
## matrix (large values are dark/black)
pimage(x, main = "Random data", key = FALSE)
## plot seriated matrix (use red, proportional display and plot all axes)
pimage(x, seriate(x), col = c("white", "red"),
prop = TRUE, axes="both", main = "Reordered data", key = FALSE)
## show correlation (for neg. values a diverging color scheme is
## used automatically)
pimage(cor(x), prop=TRUE)
## distances (note that low distances are represented dark!)
d <- dist(x, method = "binary")
pimage(d, upper.tri = FALSE, main = "Distances")
pimage(d, seriate(d), upper.tri = FALSE, main = "Distances", axes = "both")
## add to the plot using grid (use pop = FALSE)
library(grid)
pimage(x, pop = FALSE)
downViewport(name = "image")
## highlight cell 7/5 with a red arrow
grid.lines(x = c(5, 7), y = c(3, 5), arrow = arrow(),
default.units = "native", gp = gpar(col="red", lwd = 3))
## add a red box around rows 15 and 16
grid.rect(x = 0.5, y = 15.5, width = ncol(x), height = 2,
just = "left",
default.units = "native", gp = gpar(col="red", lwd = 3, fill = NA))
## remove the viewports
popViewport(0)
## put several pimages on a page (uses viewports and newpage = FALSE)
library(grid)
grid.newpage()
pushViewport(viewport(layout=grid.layout(nrow = 1, ncol = 2)))
pushViewport(viewport(layout.pos.row = 1, layout.pos.col = 1))
## seriate matrix
o <- seriate(x)
pimage(x, o, main = "Random data", prop = TRUE, axes = "both", key = FALSE,
newpage = FALSE)
upViewport(1)
pushViewport(viewport(layout.pos.row = 1, layout.pos.col = 2))
## add the reordered disimilarity matrix for rowa
pimage(d, o[[1]], upper.tri = FALSE, main = "Distances", axes = "both",
key = FALSE, newpage = FALSE)
upViewport(1)
popViewport(0)
```

*Documentation reproduced from package seriation, version 1.2-2, License: GPL-3*

### Community examples

Looks like there are no examples yet.