ImageParCoord            package:rflowcyt            R Documentation

_I_m_a_g_e _P_a_r_a_l_l_e_l _C_o_o_r_d_i_n_a_t_e_s _P_l_o_t: _J_o_i_n_t _a_n_d _m_a_r_g_i_n_a_l

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

       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

_D_e_t_a_i_l_s:

     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$

$_b_i_n._p_r_e_d_i_c_t_e_d$ a row observation's predicted bin value for the
     specific transition column

$_s_l_o_p_e$ 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)$ 

$_x_p_o_s._t_r_a_n_s$ the x-axis, horizontal position of the transition column
     for the particular row observation

$_x_p_o_s._V_1$ the x-axis, horizontal position of V1 for the particular row
     observation

$_b_i_n._V_1$ 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

_V_a_l_u_e:

     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

_W_A_R_N_I_N_G:

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

_N_o_t_e:

     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.

_A_u_t_h_o_r(_s):

     A.J. Rossini and J.Y. Wan

_S_e_e _A_l_s_o:

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

_E_x_a_m_p_l_e_s:

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

