\name{gene.strip}
\alias{gene.strip}
\alias{value.to.colour}
\alias{ps.value}
\title{ Use the X:MAP database to find annotated gene structure and generate a plot for multiple genes}
\description{
Takes a list of genes and an \code{ExpressionSet} object or matrix and generates
a plot summarising the expression data for the supplied genes.
}
\usage{
gene.strip(genes,data,gps,group,col=col.rd.bl,col.range,type=c("mean-int","median-int","mean-fc","median-fc","splicing-index"),
           show.introns=FALSE,f,f.extra.params, col.f =value.to.colour, scale.to.gene = FALSE, use.symbols = TRUE,
           use.mt=FALSE,no.data.col="white",probes.min=4,main,xlab,ylab,xlim,show.legend=TRUE)

value.to.colour(vals,col=col.rd.bl,col.range=c(-5,5))
ps.value(x,gps,type=c("mean-int","median-int","mean-fc","median-fc","splicing-index"),f.extra.params)

}

\arguments{
  \item{genes}{A character vector of Ensembl gene ids containing the genes to plot. Duplicates are removed,
	        and genes plotted in order with the first gene being placed at the bottom of the plot}
  \item{data}{Expression data (should be a matrix or \code{ExpressionSet}). If a  matrix is suppplied \code{row.names} should 
              correspond to probeset ids for the genes to be plotted. Note that if a probeset id is missing, the probeset will be silently ignored. }
  \item{gps}{List of groups by which to collect the expression data when calculating, for example, fold change or mean intensities. 
    Each group is a vector of column indices into \code{data}}
  \item{group}{If specified, then the column in \code{pData(x)} to use}
  \item{col}{A vector containing the colours to use when colouring the plot by expression data. \code{\link{col.rd.bl}} is used by default.}
  \item{col.range}{ A range specifying the extents of the colour palette. Expression data are turned into a value for each probeset
(how this is done is defined by \code{type}) and then mapped into the colour vector \code{col}. \code{col.range} specifies the value 
 corresponding to the first and last entry in the colour palette; values outside this range are mapped to the extreme. By default the ranges are \code{c(-5,5)}
 for fold change plots and \code{c(0,16)} for intensity. }
  \item{type}{The way to map the expression data onto colours. For example, \code{mean-fc} expects two groups and calculates the mean fold-changes between them.}
  \item{show.introns}{If \code{FALSE}, then draw exons in number order, all the same size. If \code{TRUE}, then x-position corresponds to residue position 
                      from the start of the gene, and intronic probes are also shown.}
  \item{f}{The function used to map between the expression data and a colour in \code{col}. By default, this is \code{ps.value}.}
  \item{f.extra.params}{Any extra parameters that need to be passed through to \code{f}. This is only necessary if supplying an alternative function for computing the colourings.}
  \item{col.f}{Function used to map the expression summary data generated by f to a colour in \code{col}. Not normally required; might be used for a non-linear scale, for example.}
  \item{scale.to.gene}{If \code{TRUE},then mean-center the values for each gene around zero.}
  \item{use.symbols}{If \code{TRUE} then label the plot using gene symbols. otherwise, use the Ensembl gene id.}
  \item{use.mt}{If \code{TRUE} then use data from multiply targeted probesets when generating the plots. See \code{\link{select.probewise}} and \code{\link{exclude.probewise}} for more details.}
  \item{no.data.col}{The colour to draw exons when there is no matching probeset}
  \item{probes.min}{Ignore probesets unless they have at least this many probes hitting an exon or gene}
  \item{main}{plot title}
  \item{xlab}{x axis label}
  \item{ylab}{y axis label}
  \item{vals}{A numeric vector containing values that should be mapped into the specified palette}
  \item{x}{A vector of expression data for a probeset}
  \item{xlim}{range specifying x-axis limits within which to plot}
  \item{show.legend}{If \code{TRUE}, then plot a colour bar in the margin of the plot, showing col and the col.range}
}
\details{

  At its simplest, takes a list of genes and an ExpressionSet object
and plots their data coloured by expression.  Each row of the plot
corresponds to a gene, and the X axis corresponds to position within
that gene. By default the plot shows only exons. Each exon is
represented by a rectangle, coloured using the expression data (see
below), and introns are ignored. Overlapping exons are plotted next to
each other, and if multiple probesets hit an exon they are stacked
vertically within the exon. Data are filtered (by default) to remove
multiply targeted probesets. If there are no 'well-behaved' probesets
hitting an exon, it is drawn as a rectangle in the 'no.data.col',
which is, by default, white.

If \code{plot.introns} is \code{TRUE} then introns are included in the
plot, and position on the x-axis corresponds to nucleotide position
relative to the start of the gene. Exons are drawn as rectangles in
the border colour - the default is black.  Note that they will show up
as vertical lines if the gene is long and the the graph is not very
wide. Each probe is represented by a line, is coloured by expression.


 Groups of arrays can be specified in two ways, depending on whether \code{groups} is supplied. If it is,
 then it should represent the name of a column in the
 \code{ExpressionSet}'s \code{pData} object, and \code{gps} should be a
 list of levels in this factor defining the groups of arrays. So for
 example, \code{...,group="group",gps=c("a","b"),...} will define
 two groups of arrays, one for each cell line, as defined by the "group"
 column in the expression set's \code{pData} object.

 Alternatively, if \code{groups} is not supplied, \code{gps} should be a
 list of numeric vectors, each defining the indices of a set of
 arrays. For example, \code{...,gps=list(a=1:3,b=4:6),...} would define
 two groups, called "a" and "b", each with three arrays in it.

 Note that for fold change calculations the number returned is gps[1] -gps[2] i.e. if gp[1] is more highly expressed than group 2, the result is
 positive. With default colouring, positive values are blue, negative,
 red.

 Colouring can be changed by supplying an alternate palette to the
 default (\code{col.rd.bl}), and alternate mappings between values and
 colours can be generated by supplying a different function via
 \code{col.f}. See \code{value.to.colour} for more details.
}
\value{
  none
}
\seealso{\code{\link{gene.legend}} \code{\link{plotGene}}  \code{\link{gene.graph}}}

\references{\url{ http://bioinformatics.picr.man.ac.uk/}}
\author{ Crispin Miller }

\keyword{ misc }
\examples{ 
   if(interactive()) {
     data(exonmap)
     xmapConnect()
     genes <- probeset.to.gene(featureNames(x.rma))
     gene.strip(genes,x.rma,list(1:3,4:6),type="mean-fc",col.range=c(-2,2))
     par(mfrow=c(2,2))
     gene.strip(genes,x.rma,list(1:3),type="mean-int",col.range=c(0,16),col=heat.colors(16),main="MCF7",show.legend=FALSE)
     gene.strip(genes,x.rma,list(4:6),type="mean-int",col.range=c(0,16),col=heat.colors(16),main="MCF10A",show.legend=FALSE)
     gene.strip(genes,x.rma,list(1:3),type="mean-int",col.range=c(0,16),col=heat.colors(16),main="MCF7",show.introns=TRUE,show.legend=FALSE)
     gene.strip(genes,x.rma,list(4:6),type="mean-int",col.range=c(0,16),col=heat.colors(16),main="MCF10A",show.introns=TRUE,show.legend=FALSE)

     fold.changes <- apply(exprs(x.rma)[1:10,],1,ps.value,gps=list(1:3,4:6),type="mean-fc")
     value.to.colour(fold.changes)
  }
}