\name{parallelCoordinates}
\alias{parallelCoordinates}


\title{Parallel coordinates: Plotting each observation across all variables}
\description{
  To view multi-dimensional data, a parallel coordinates plot is made
  such that each row is treated as
  an observation which is plotted across all column variables.  The two
  dimensional plot which results has the column variables on the horizontal
  axis and the values of the column variables on the vertical axis.  Care
  should be taken to note that each line drawn corresponds to a row
  observation.  Also the units of measurements should be the same among
  all column variables. Note that the row observations can be grouped
  visually by specifying group line options such as line type, color, or
  width.  The data can also be scaled to have a range of (0,1).
}
\usage{
  parallelCoordinates(x, varlabpos=1:dim(x)[2],
                       variable.names=colnames(x),my.ylab ="",
                       my.ylim =c(min(x),max(x)),
                       at.y=seq(min(x), max(x),
                            by=(max(x)-min(x))/20),
                       each.ylab=at.y, scaled = FALSE,
                       group = rep(1, dim(x)[1]),
                       group.lty=group, group.col=group,
                       group.lwd=group, superimpose=FALSE,...)


}
%- maybe also `usage' for other objects documented here.
\arguments{
  \item{x}{matrix of the data (rows are the observations & columns are
    the variables) }
  \item{varlabpos}{numerical vector denoting the position of the
    variables/variable labels on the horizontal axis; default is a vector of 1 to the
    number of variables}
  \item{variable.names}{a vector of strings denoting the names of each
    variable; default value is the column names of the input matrix, x}
  \item{my.ylab}{character string denoting the name/label of the
    vertical y-axis; default value is "Values"}
  \item{my.ylim}{two-dimensional vector denoting the range of the
    vertical y-axis, ie, the range of the variables; default is the
    vector of the min and the max of the input matrix, x}
  \item{at.y}{vector of the vertical y-axis values at which labels will be
    shown on the plot; default is a vector of the minimum to the maximum
    by increments of one-twentieth of the difference between the mininum
    and the maximum}
  \item{each.ylab}{vector of the vertical y-axis labels; default is the
    numerical values of at.y}
  \item{scaled}{boolean; if TRUE, then the data is scaled to a range of [0,1]}
  \item{group}{a vector of indicating which group the row observations
    are in; default is all the row observations are in one group }
  \item{group.lty}{vector corresponding to each data row's line type
    corresponding to the group that each row observation is in; default
    is the vector value of group}
 \item{group.col}{vector corresponding to each data row's line type
    corresponding to the group that each row observation is in; default
    is the vector value of group}
  \item{group.lwd}{vector corresponding to each data row's line type
    corresponding to the group that each row observation is in; default
    is the vector value of group}
  \item{superimpose}{Boolean, if TRUE then parallel coordinate lines
    will be added to the existing plot; otherwise a new parallel
    coordinate plot will be made; default is FALSE}
  \item{...}{\code{plot} options}
}

\value{
 A parallel coordinates plot in which row observations are plotted
 across all column variables in a plot with x-axis= names of the column
 variables and y-axis=values of the column variables.
}

\author{A.J. Rossini, J.Y. Wan}

\section{WARNING}{
  The dataset may have to be subsetted before
  implementing this function because the plot may take a long time to
  finish and may not be readable.

  If the at.y option is not within the range of the column variables,
  then the range will be changed appropriately, but the interval or the
  difference between two elements of at.y will remain the same in order
  to keep the specified spacings of the y labels/tick marks.

  If the each.ylab vector is different in length with the number of tick
  marks specified by at.y for the vertical axis, then by default the
  each.ylab will be the values of at.y.  In other words, the labels will
  be the number values specified by at.y.
}

\seealso{
  \code{\link{pairs}},
  \code{\link{plot}},
  \code{\link{ImageParCoord}}
}

\examples{
if (require(rfcdmin)){
  data.there<-is.element("MC.053",objects())
    if ((sum(data.there) != length(data.there))) {
      ## obtaining the FCS objects from FHCRC data
      data(MC.053min)
    }
 
  dataMC<-MC.053@data

 
  if (interactive()) {
   par(mfrow=c(2,2))

    ### subset the data to the first 5 observations because it is too huge
    parallelCoordinates(dataMC[c(1:5),-6])
    ### the first 2 rows are a group and the last 3 rows are a different group
    parallelCoordinates(dataMC[c(1:5),-6], group=c(1,1,2,2,2))
    
    ### the same plot is scaled to 0,1 range
    parallelCoordinates(dataMC[c(1:5),-6], scaled=TRUE)
    parallelCoordinates(dataMC[c(1:5),-6], scaled=TRUE, group=c(1,1,2,2,2))
    
    parallelCoordinates(dataMC[c(1:5),1:4])
    ## changing the positions of the variables to the 1st, 5th, 8th, 16th
    ## positions on the horizontal x-axis
    parallelCoordinates(dataMC[c(1:5),1:4], varlabpos=c(1, 5, 8, 16))
    
    parallelCoordinates(dataMC[c(1:5),1:3])
    ## having the variable positions out of order of how they are plotted
    parallelCoordinates(dataMC[c(1:5),1:3], varlabpos=c(1, 15, 8))
    
    ## changing the labels of the vertical y-axis
    parallelCoordinates(dataMC[c(1:5),1:3], at.y=c(0, 500,
    1000),my.ylim=c(0, 1000),
    each.ylab=c("zero", "five hundred", "one thou"))
  }
}
}
\keyword{hplot}