\HeaderA{resplot}{Simple Graphical Summaries for Gene Set Enrichment Analysis
(GSEA)}{resplot}
\aliasA{mnDiffPlot}{resplot}{mnDiffPlot}
\aliasA{restrip}{resplot}{restrip}
\keyword{methods}{resplot}
\keyword{hplot}{resplot}
\begin{Description}\relax
Diagnostic plots for GSEA. 'resplot' and 'restrip' group residuals (or
expression levels) from a specific gene-set by sample. 'mnDiffPlot'
shows mean expression differences for a dichotomous phenotype, by
gene, for a specific gene set.
\end{Description}
\begin{Usage}
\begin{verbatim}
resplot(GSname = "All", resmat, incidence = dumminc(resmat), fac,
     atomic = "Gene", core.text = "Residuals by Sample",
     yname = "Standardized Residual", xname = "Sample ID",
     ID = colnames(resmat), lims = 0, gnames = levels(factor(fac)),
     prefix = "", horiz = FALSE, colour=5,pch='+',...)

restrip(GSname = "All", resmat, incidence = dumminc(resmat), fac,
   atomic = "Gene", core.text = "Residuals by Sample",
  yname = "Standardized Residual", xname = "Sample ID", ID = colnames(resmat),
  gnames = levels(factor(fac)), prefix = "", colour=c(2:4,6), resort=TRUE,
  horiz = FALSE, resort.fun=num.positive, pch='+', ...)

mnDiffPlot(GSname = "All", exprmat, incidence = dumminc(exprmat), fac,
  atomic = "Gene", core.text = paste("Mean Expression Difference by",atomic),
  yname="Log Expression Ratio", xname="Log Expression",
  gnames = levels(factor(fac)), prefix = "", fitline=FALSE, varsize=FALSE,
  reverse=FALSE, ...)\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{GSname}] Gene-set Name. See "Details".
\item[\code{resmat,exprmat}] Numerical matrix with the values to be
plotted. See "Details". 
\item[\code{incidence}] Gene-set 0/1 membership matrix 
\item[\code{fac}] The phenotypical variable to plot by. Must be discrete. For
'mnDiffPlot', must be dichotomous.
\item[\code{atomic}] string identifying the meaning of rows in the data
matrix. Defaults to "Gene". 
\item[\code{core.text,gnames,prefix,xname,yname}] strings controlling the
text of main and axis captions 
\item[\code{ID}] Group names associated with the data matrix columns 
\item[\code{lims}] plotting limits for the response axis
\item[\code{horiz}] logical: whether the boxplots or strips should be
horizontal (defaults to FALSE)
\item[\code{colour}] color of boxplot filling ('resplot') or symbols
('restrip')
\item[\code{pch}] the plotting symbol
\item[\code{resort}] 
\item[\code{resort.fun}] ('restrip' only) what function to sort groups
by. Ignored unless 'resort==TRUE'. See \code{\LinkA{stripchart}{stripchart}} documentation for
more details
\item[\code{fitline}] ('mnDiffPlot' only) logical: whether a loess fit should be
plotted
\item[\code{varsize}] ('mnDiffPlot' only) logical: whether symbol sizes should
be proportional to (t-test style) standard errors
\item[\code{reverse}] ('mnDiffPlot' only)logical: whether the factor's order
should be reversed so that the second level is on the x-axis rather
than the first one
\item[\code{...}] Additional graphical parameters passed on to the generic
plotting functions.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
These functions provide simple graphical summaries for processed
gene-expression data, or other similar datasets for which matrix form is
useful. They are tailored predominantly for GSEA, but are useful in
general as well.

'resplot' calls \code{\LinkA{boxplot}{boxplot}} and 'restrip' calls
\code{\LinkA{stripchart}{stripchart}}; both summarize *all* data points from those
rows in 'resmat' which are members in the gene-set specified by
'GSname'. The summary is by column. For each level of 'fac' there will
be a separate pane.

'mnDiffPlot' calls \code{\LinkA{plot}{plot}}; it plots the mean differences, by
row, between columns belonging to the two groups specified by 'fac', as
a function of the mean values for the first group alone. Each row
translates to a single point on the graph. Again, the summary is only
for rows indicated by 'GSname'.

For gene-set selective plots to properly work, the incidence matrix
needs to have non-empty row names, and 'GSname' must match one of them.

If both 'GSname' and 'incidence' are left blank, automatic
utilities are called which help generate a summary of the entire matrix,
by column.

All functions plot a reference line signalling zero. 'mnDiffPlot' also
optionally plots a loess fit for expression differences (if 'fitline=TRUE').
\end{Details}
\begin{Note}\relax
One can use 'resplot'/'restrip' to plot raw expression values rather
than residuals; it all depends on what's in the data matrix.
\end{Note}
\begin{Author}\relax
Assaf Oron
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{boxplot}{boxplot}},\code{\LinkA{plot}{plot}},\code{\LinkA{stripchart}{stripchart}},\code{\LinkA{par}{par}},\code{\LinkA{GOmnplot}{GOmnplot}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

data(sample.ExpressionSet)
lm1 = lmPerGene(sample.ExpressionSet,~sex)
r1 = getResidPerGene(lm1)
### now a boxplot of all residuals by sample
resplot(resmat=exprs(r1),fac=sample.ExpressionSet$sex)
### This plot is not very informative because of some gross outliers;
### try this instead
resplot(resmat=exprs(r1),fac=sample.ExpressionSet$sex,lims=c(-5,5))

### stripchart for first 10 genes
restrip(resmat=exprs(r1)[1:10,],fac=sample.ExpressionSet$type,prefix="Not")

### note the wild trajectory of the loess fit:
mnDiffPlot(exprmat=exprs(sample.ExpressionSet),fac=sample.ExpressionSet$type,xname="Raw Expression",yname="Expression Difference",fitline=TRUE)
\end{ExampleCode}
\end{Examples}

