\name{ImageParCoord}
\alias{ImageParCoord}
\alias{JointImageParCoord}
%- Also NEED an `\alias' for EACH other topic documented here.
\title{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
\code{ImageParCoord} OR jointly across all
variables using \code{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,
legend.shrink = 0.9,
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]),
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,
legend.shrink = 0.9,
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]),
horizontal.legend = TRUE,
offset.legend=0.03,
nlevel.legend=length(color.image),
xlab.image="",
ylab.image="Bins",
MY.DEBUG=TRUE,...)
}
\arguments{
\item{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}
\item{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}
\item{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}
\item{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.}
\item{joint}{boolean; if TRUE then the plots will be joined;
default value is TRUE}
\item{title}{character string denoting the title of the image plot;
default value is an empty string}
\item{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}
\item{color.image}{the color scheme for the image plot; default is
gray((25:5/25)[-c(1,2,3, 4, 5, 6)])}
\item{xwidth.scale}{numeric value denoting the horizontal width of the variable
and the transitions blocks; default value is 5 units of width}
\item{ntrans}{numeric value denoting the number of transition columns
between each pair of variables; default is 1 transition column
between each pair of variables}
\item{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}
\item{legend.shrink}{numeric to reduce the size of the legend}
\item{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}
\item{image.plotted}{Boolean; if TRUE, then the image parallel
coordinates plot is displayed; otherwise if FALSE, the plot is
surpressed; default is TRUE}
\item{para.plotted}{Boolean; if TRUE, then the parallel
coordinates plot is displayed; otherwise if FALSE, the plot is
surpressed; default is TRUE}
\item{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}
\item{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}
\item{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}
\item{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).}
\item{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}
\item{horizontal.legend}{default value is TRUE}
\item{offset.legend}{default value is 0.03}
\item{nlevel.legend}{default value is the length of the color.image vector}
\item{xlab.image}{a character string denoting the label of the
horizontal x-axis on the image plot; default value is an empty string}
\item{ylab.image}{a character string denoting the label of the
vertical y-axis on the image plot; default value is "Bins"}
\item{MY.DEBUG}{a boolean; if TRUE then debugging statements for the
binning are output, otherwise if FALSE, the statements are
surpressed; default is TRUE}
\item{...}{graphical parameters for \code{\link{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:
\deqn{ bin.predicted = slope*(xpos.trans - xpos.V1) + bin.V1}
\describe{
\item{$bin.predicted$}{a row observation's predicted bin value for the specific transition
column}
\item{$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: \eqn{ slope = (bin.V2-bin.V1)/(xpos.V2 - xpos.V1)} }
\item{$xpos.trans$}{the x-axis, horizontal position of the transition
column for the particular row observation}
\item{$xpos.V1$}{the x-axis, horizontal position of V1 for the
particular row observation}
\item{$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
\code{JointImageParCoord} should be used.
The line widths in the image parallel coordinates plot were scaled by
the following equation:
\deqn{ x = (m-1)*((n-i)(a-i)) + 1}
\item{$x$}{is the scaled size for a particular line}
\item{$m$}{is the maximum line width size denoted by max.lwd from the function
signature}
\item{$n$}{is the number of observations denoted by the line}
\item{$i$}{is the minimum number of observations denoted by a line}
\item{$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:
\item{image.block}{a matrix denoting the number of observations in
each cell of the image plot}
\item{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.}
\item{breaks}{vector of breaks for binning on the vertical axis for the
values of the variables}
}
\author{A.J. Rossini and J.Y. Wan}
\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.
}
\section{WARNING}{On some workstations, some colors may not be able to
be allocated using \code{rainbow} or \code{heat.colors} as the
image.color.}
\seealso{
\code{\link{parallelCoordinates}},
\code{\link[grDevices:palettes]{rainbow}},
\code{\link[grDevices:palettes]{heat.colors}},
\code{\link{ContourScatterPlot}},
\code{\link{ProbBin.FCS}},
\code{\link{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)
}
}
}
\keyword{hplot}