\name{plotGene}
\alias{plotGene}
\alias{col.rd.bl}

\title{ Use the X:MAP database to find annotated gene structure and generate a plot }
\description{
  Draws a plot of a gene's structure, possibly coloured by expression
  data, similar to those shown in the X:Map genome browser.
}
\usage{
plotGene(x, data, gps, group, scale.to.gene = FALSE, 
    type = c("mean-int", "median-int", "mean-fc", "median-fc", "splicing-index"), 
    use.symbol = TRUE, use.mt = FALSE, 
    probes.min = 4, f = ps.value, f.extra.params, 
    col = col.rd.bl, col.range, col.f = value.to.colour,
    main, xlab, ylab, xlim, ylim,
    border.col = "#aaaaaa",no.data.col = "white", text.col="black",text.bg="white",
    exon.borders,
    pad=0.1,transcript.height=0.9,show.legend=TRUE)

col.rd.bl
}

\arguments{
\item{x}{the Ensembl gene id of the gene to plot}
\item{data}{Expression data (should be a matrix or \code{ExpressionSet}). If present, used to colour the plot}
\item{gps}{ Either a \code{list} of groups by which to collect the
  expression data when calculating, for example, fold change or mean
  intensities, or, if \code{group} is specified, the names of items in
  one of the columns in \code{pData(x)}. See details.}
\item{group}{If specified, then the column in \code{pData(x)} to use
  when defining the groups of arrays to compare. See details.}
\item{scale.to.gene}{If \code{TRUE}, then mean-center each plot around zero.}
\item{type}{The type of calculatin used to create the data for the plot. See details.}
\item{use.symbol}{If \code{TRUE} then label by the gene symbol, if \code{FALSE}, the gene name.}
\item{use.mt}{ If \code{TRUE} then include multitarget probesets. See \code{\link{select.probewise}} and \code{\link{exclude.probewise}} for details on how the filtering is done.}
\item{probes.min}{The minimum number of probes within a probeset that must match to an exon before it is incorporated in the plot. }
\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}{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 extremes. By default the ranges are \code{c(-5,5)} for fold change plots and \code{c(0,16)} for intensity. }
\item{col.f}{Function used to map the expression summary data generated by \code{f} to a colour in \code{col}. Not normally required; might be used for a non-linear scale, for example.}
\item{main}{ Plot title.}
\item{xlab}{ X axis label. Overrides \code{use.symbol}. }
\item{ylab}{ Y axis label.}
\item{xlim}{ Range of values to plot on the x axis. }
\item{ylim}{ Height of y-axis. By default this is just big enough to fit the gene. }
\item{border.col}{ Colour to use for gene, transcript and exon edges.}
\item{no.data.col}{Colour to plot exons with no matching probeset after filtering using \code{probes.min} and \code{use.mt}.}
\item{text.col}{ Colour to label genes and transcripts.}
\item{text.bg}{ Label background colour for the gene label.}
\item{exon.borders}{If \code{TRUE} then draw a border around exons.}
\item{pad}{Vertical space to leave between each element of the plot. Character height is adjusted to be the same as \code{pad}}
\item{transcript.height}{ Height of each transcript. With defaults, each gene is \code{(transcript.height + pad) * N + 3 * pad} high}
\item{show.legend}{If \code{TRUE}, show a colour bar as a legend in the margin of the plot.}
}

\details{
 At its simplest, takes an Ensembl gene name and plots the location and
 structure of the gene.  If data, gp1, and gp2 are specified, then
 colours the gene according to the expression data.  By default, this
 is done by calculating the mean fold change for all the well behaved
 exon probes (i.e. those that only hit the genome, once, in an exon in
 the gene of interest), mapping this value to a colour and using this to
paint each exon in the gene. The same is done for
 transcripts and genes.  Other methods of colouring are specified by
 \code{type}, and should be self-explanatory. See the vignette for
 more details.  If scale.to.gene is \code{TRUE}, then fold-changes (or
 intensities, depending on the value of \code{type}) are calculated
 relative to the mean fold change for the gene. Exons for which no matching
 probesets are found are drawn with a black border and annotated with an 'x'.

 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{gene.strip}}
  \code{\link{gene.graph}} \code{\link{mappings}} \code{\link{filters}} \code{\link{details}}}

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

\keyword{ misc }

\examples{ 
  if(interactive()) {   
   xmapConnect()
   data(exonmap)
   par(mfrow=c(3,1))
   plotGene("ENSG00000141510",x.rma,gps=list(1:3,4:6),type="mean-fc")
   plotGene("ENSG00000141510",x.rma,gps=c("a","b"),group="group",type="mean-fc")
   plotGene("ENSG00000141510",x.rma,gps=list(1:3),type="mean-int",col=heat.colors(16))
   plotGene("ENSG00000141510",x.rma,gps=list(4:6),type="mean-int",col=heat.colors(16))
  }
}