ImageParCoord {rflowcyt} | R Documentation

## Image Parallel Coordinates Plot: Joint and marginal

### Description

This function constructs an image plot in which a rectangular grid structure displays the change of observations from the value of one variable to the value of the next variable. The vertical axis of the image plot denotes the value of the variables that are labeled on the horizontal axis. Traditionally, the lines in a parallel coordinates plot represent the movement of each observation from one variable to the next, but in this case a colored image transition column will represent the movement of observations from cell to cell in the image grid produced by horizontal bins on the vertical axis and vertical divisions between variables and transitions between variables labeled on the horizontal axis. Lines with scaled widths overlaying the image plot indicate the movement of observations from binned values of one variable to the binned values of another (either marginally and only between pairs of variables using `ImageParCoord` OR jointly across all variables using `JointImageParCoord`). Histograms for each variable and the transitions between the variables can be plotted as well.

### Usage

    ImageParCoord(x,
                  num.bins=10,
                  range.var=range(x),
                  break10 = NULL,
                  joint=FALSE,
                  title="",
                  use.shortnames=FALSE,
                  color.image=gray((25:5/25)[-c(1,2,3, 4, 5, 6)]),
                  xwidth.scale=5,
                  ntrans=1,
                  legend.plotted=TRUE,
                  hist.plotted=FALSE,
                  image.plotted=TRUE,
                  para.plotted=FALSE,
                  lines.plotted=TRUE,
                  lwd.vec=1:7,
                  lty.vec=rep(1,7),
                  col.vec=7:1,
                  range.image=c(0,dim(x)[1]),
                  shrink.legend=TRUE,
                  horizontal.legend = TRUE,
                  offset.legend=0.03,
                  nlevel.legend=length(color.image),
                  xlab.image="",
                  ylab.image="Bins",
                  MY.DEBUG=TRUE,...)

    JointImageParCoord(x,
        num.bins=10,
        range.var=range(x),
        break10=NULL,
        title="",
        use.shortnames=FALSE,
        color.image=gray((25:5/25)[-c(1,2,3, 4, 5,6)]),
        xwidth.scale=5,
        ntrans=1,
        legend.plotted=TRUE,
        hist.plotted=FALSE,
        image.plotted=TRUE,
        para.plotted=FALSE,
        lines.plotted=TRUE,
        lwd.vec=1:7,
        lty.vec=rep(1,7),
        col.vec=7:1,
        range.image=c(0, dim(x)[1]),
        shrink.legend=TRUE,
        horizontal.legend = TRUE,
        offset.legend=0.03,
        nlevel.legend=length(color.image),
        xlab.image="",
        ylab.image="Bins",
        MY.DEBUG=TRUE,...)

### Arguments

`x` | data matrix from a FCS object; data has columns as the variables and rows as the cells and assume that all column variables are of the same unit and range
`num.bins` | numeric value denoting the number of horizontal bins on the vertical axis to determine how well-defined/sharp the columns of the image plot are; default value is 10 bins
`range.var` | a 2-dimensional vector denoting the minimum value and the maximum value of the variables to be plotted; default is the range of the FCS object data
`break10` | vector denoting the breaks for the binning on the vertical axis; default is equal interval binning denoted by num.bins unless otherwise specified; the breaks must include the range of the variable; each bin is denoted by an open lower value and a closed upper value, ie, (a,b] where a and b are breakpoints and a<b.
`joint` | boolean; if TRUE then the plots will be joined; default value is TRUE
`title` | character string denoting the title of the image plot; default value is an empty string
`use.shortnames` | Boolean; if TRUE, then the shortnames of the variables will be used in labeling in the plots; otherwise if FALSE, the longnames of the variables will be used; default is FALSE
`color.image` | the color scheme for the image plot; default is gray((25:5/25)[-c(1,2,3, 4, 5, 6)])
`xwidth.scale` | numeric value denoting the horizontal width of the variable and the transitions blocks; default value is 5 units of width
`ntrans` | numeric value denoting the number of transition columns between each pair of variables; default is 1 transition column between each pair of variables
`legend.plotted` | Boolean; if TRUE then the legend is produced in a separate graph/plot; otherwise if FALSE, then no legend plot is made; default is TRUE
`hist.plotted` | Boolean; if TRUE then the histogram plots of the variables and the transitions are made; otherwise if FALSE, there is no histogram plots; default value is FALSE
`image.plotted` | Boolean; if TRUE, then the image parallel coordinates plot is displayed; otherwise if FALSE, the plot is surpressed; default is TRUE
`para.plotted` | Boolean; if TRUE, then the parallel coordinates plot is displayed; otherwise if FALSE, the plot is surpressed; default is TRUE
`lines.plotted` | Boolean; if TRUE, then superimposed binned parallel coordinate lines displayed on top of the existing plot; otherwise if FALSE, the plot is surpressed; default is TRUE; Note that image.plotted has to be TRUE to see the superimposed image and parallelCoordinates lines
`lwd.vec` | vector denoting the line width sizes to be used in the lines overlaying the image parallel coordinates plot; default value is an integer vector from 1 to 7
`lty.vec` | vector denoting the line type (solid or dotted, etc) for the corresponding line width in lwd.vec; the default is to have a solid line for each line width
`col.vec` | vector denoting the color for each line with the corresponding line width in lwd.vec and line type in lty.vec; the default is to have colors ranging from yellow to black (in that order).
`range.image` | 2-dimensional numerical vector denoting the range of the number of counts in the image block to be plotted. The default value is to have a vector with a mininum value of zero and to have a maximum dependent on the number of cells/rows and bins
`shrink.legend` | boolean; if TRUE then the legend will be ; default value is TRUE
`horizontal.legend` | default value is TRUE
`offset.legend` | default value is 0.03
`nlevel.legend` | default value is the length of the color.image vector
`xlab.image` | a character string denoting the label of the horizontal x-axis on the image plot; default value is an empty string
`ylab.image` | a character string denoting the label of the vertical y-axis on the image plot; default value is "Bins"
`MY.DEBUG` | a boolean; if TRUE then debugging statements for the binning are output, otherwise if FALSE, the statements are surpressed; default is TRUE
`...` | graphical parameters for `plot` may also be passed as arguments to this function

### Details

The result is to have an image block or matrix. Each variable was binned according to the number of bins specified by the option num.bins.

A point-slope line formula was used to determine the counts in the transition block (a matrix of the same transition column across a certain number of rows defined by ntrans and x.width options) between two variables. For each pair of column variables, the horizontal positions of the two variables were regressed on the bin position of the particular observation in order to obtain a point-slope line formula. Thus, for each row observation, one could predict the particular bin that it passed through for the transition block between two known bin values of the two variables.

The following is the point-slope formula for each pair of column variables:

$ bin.predicted = slope*(xpos.trans - xpos.V1) + bin.V1$

$bin.predicted$
  a row observation's predicted bin value for the specific transition column
$slope$
  the slope of the line determined by dividing the difference between the bin values of variable 1 (V1) and variable 2 (V2) by the difference between the horizontal, x-axis positions of V1 and V2: $ slope = (bin.V2-bin.V1)/(xpos.V2 - xpos.V1)$
$xpos.trans$
  the x-axis, horizontal position of the transition column for the particular row observation
$xpos.V1$
  the x-axis, horizontal position of V1 for the particular row observation
$bin.V1$
  a row observation's bin value for V1

Please note that the lines are only marginal. They denote the number of cells moving only between adjacent pairs of variables. To view the cells jointly across all variables, the function `JointImageParCoord` should be used.

The line widths in the image parallel coordinates plot were scaled by the following equation:

$ x = (m-1)*((n-i)(a-i)) + 1$

$x$
  is the scaled size for a particular line
$m$
  is the maximum line width size denoted by max.lwd from the function signature
$n$
  is the number of observations denoted by the line
$i$
  is the minimum number of observations denoted by a line
$a$
  is the maximum number of observations denoted by a line

### Value

The image parallel coordinates plot with overlayed lines and a legend for the lines, the traditional parallel coordinates plot without the image, and histograms of the variables and the transitions are displayed upon user request as well as a list of the following:

`image.block` | a matrix denoting the number of observations in each cell of the image plot
`line.info` | list of matrices in which each matrix corresponds to the the line information between a pair of variables. Each matrix has three columns. The first two columns are the values of unique bin patterns between the pair of column variables, and the third column is the number of observations with that particular pattern.
`breaks` | vector of breaks for binning on the vertical axis for the values of the variables

### WARNING

On some workstations, some colors may not be able to be allocated using `rainbow` or `heat.colors` as the image.color.

### Note

Other color images can be used (see the example), but please be advised of the color scheme.

Probability binning can be incorporated by using the signature option break10 to denote the breaks from probability binning.

### Author(s)

A.J. Rossini and J.Y. Wan

### See Also

`parallelCoordinates`, `rainbow`, `heat.colors`, `ContourScatterPlot`, `ProbBin.FCS`, `gate.IPC`

### Examples

      if (require(rfcdmin)){

        data.there<-is.element(c("st.1829", "unst.1829", "unst.DRT", "st.DRT"),objects())
        if ( ( sum(data.there) != length(data.there) )){
          ## obtaining the FCS objects from VRC data
          data(VRCmin)
        }

        if (interactive()==TRUE){
        par(mfrow=c(3,3))

        ImageParCoord(unst.1829@data[1:1000, 1:3], num.bins=16,
                  title="1000 obs 16 bins 5 trans", ntrans=5)
        ## joint line plot
        ImageParCoord(unst.1829@data[1:1000,c(1,2,3)], num.bins=16,joint=TRUE,
                  title="1000 obs 16 bins 5 trans", ntrans=5,legend.plotted=FALSE)

        ## color image is changed
        ImageParCoord(unst.1829@data[1:1000,c(1,2,3)], num.bins=20,
                  title="1000 obs 20 bins 5 trans", color.image=rainbow(16,
                  start=.4, end=.1), ntrans=5)

        par(mfrow=c(3,3))
        ImageParCoord(unst.1829@data[1:1000,c(1,2,3)], num.bins=20,
                  title="1000 obs 20 bins 10 trans", ntrans=10)
        ## joint line plot

        ImageParCoord(unst.1829@data[1:1000,c(1,2,3)], num.bins=20,joint=TRUE,
                  title="1000 obs 20 bins 10 trans", ntrans=10)

        ## plot the parallel coordinates plot also
        par(mfrow=c(2,2))
        ImageParCoord(unst.1829@data[1:1000,c(1,2,3)], 1:1000, num.bins=16,
                  color.image=gray((25:5/25)[-c(1, 2, 3, 4, 5, 6,7)]),
                  title="1000 obs 16 bins 5 trans", ntrans=5,
                  para.plotted=TRUE)

        ## plot the parallel coordinates plot also
        par(mfrow=c(2,2))
        ImageParCoord(unst.1829@data[1:1000,c(1,2,3)],joint=TRUE,
                  1:1000, num.bins=16,
                  color.image=gray((25:5/25)[-c(1, 2, 3, 4, 5, 6,7)]),
                  title="1000 obs 16 bins 5 trans", ntrans=5,
                  para.plotted=TRUE)

        ##histograms only
        par(mfrow=c(3,3))
        ImageParCoord(unst.1829@data[1:1000,c(1,2,3)], num.bins=10,
                 title="1000 obs 10 bins 1 trans",
                 ntrans=1, hist.plotted=TRUE,
                 image.plotted=FALSE, legend.plotted=FALSE,
                 lines.plotted=FALSE)

        ## histograms and images
        par(mfrow=c(3,3))
        ImageParCoord(unst.1829@data[1:1000,c(1,2,3)],
               num.bins=10,
               title="1000 obs 10 bins 5 trans",
               ntrans=5, hist.plotted=TRUE)

        ## legend only
        ImageParCoord(unst.1829@data[1:1000,c(1,2,3)], num.bins=10,
                 title="1000 obs 10 bins 5 trans", ntrans=5, legend.plotted=TRUE,
                 image.plotted=FALSE, lines.plotted=FALSE)

       ImageParCoord(unst.1829@data[1:1000,c(1,2,3)],joint=TRUE,
                 num.bins=10,
                 title="1000 obs 10 bins 5 trans",
                 ntrans=5, legend.plotted=TRUE,
                 image.plotted=FALSE, lines.plotted=FALSE)
        }
      }

[Package rflowcyt version 1.8.0 Index]