\name{gene.graph}
\alias{gene.graph}
\alias{gene.graph}

\title{ Use the X:Map database to find annotated gene structure and generate a plot }
\description{
  Draws a variety of line graphs mapping expression data to a given gene.
}
\usage{
gene.graph(gene,data,gps,group,gp.cols,gp.lty,gp.pch,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,main="gene",xlab,ylab,xlim,ylim,exon.y=0,exon.height=1,by.order=FALSE,show.introns,exon.bg.col="#eeeeee",exon.bg.border.col="#dddddd")
}

\arguments{
\item{gene}{The gene to plot}
\item{data}{ matrix or \code{ExpressionSet} object containg expression data}
\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{gp.cols}{Vector of colours to colour each group's line by. If generating a fold or splicing index plot, only the first element is used.}
\item{gp.lty}{Vector of line types for each group's line. If generating a fold change or splicing index plot, only the first element is used. }
\item{gp.pch}{For 'by.order' plots, a vector of plot character types for each group's line. If generating a fold change or splicing index plot, only the first element is used. }
\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}{ Show probesets with at least this many probes hitting the gene. }
\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}{ Range of values to plot on the y axis. }
\item{exon.y}{ y position to draw exons}
\item{exon.height}{ Height to draw exons. }
\item{by.order}{ If \code{TRUE} then the x axis position corresponds to the nucleotide position of the probeset match against the genome (see details), including introns. 
                 If \code{FALSE}, then sort probesets by chromosomal location, and plot them in numerical order. }
\item{show.introns}{ Only has an effect when \code{by.order} is \code{TRUE}. If \code{FALSE} then don't include intronic probesets in the plot. }
\item{exon.bg.col}{ Background colour used to draw exons in \code{by.order} plots. Setting the colour to NA suppresses them.}
\item{exon.bg.border.col}{ Border colour used to draw exons. Setting the colour to NA suppresses them.}
}

\details{
 At its simplest, takes an Ensembl gene id and plots the intron-exon
structure of the gene along with one or more line plots calculated
from the expression data. The method used to calculate the plotted data is specified by
\code{type}, and can be used to define plots based on average
intensities, fold changes, or the splicing index. 


  The function divides the expression data into one or more groups, defined by the parameter
  \code{gps}.


 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, while
 \code{...,gps=list(1,2,3,4,5,6),...} would define 6 groups, and would
 therefore result in a separate line for each of the individual arrays.

 When the type of the plot is 'mean-int' or 'median-int' then the
mean (or median) intensity for each group is plotted as a separate
line in the plot. If the type is 'mean-fc', 'median-fc' or
'splicing-index', then gps is expected to contain two elements and a
single line is plotted, representing the average fold change.

 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.

The x position of each probeset is taken to be half way between the
5'-most and 3'-most probe for that probeset. If \code{by.order} is
TRUE, then probesets are sorted by x position and plotted in numeric
order. For these (\code{by.order=TRUE} plots), if \code{show.introns} is \code{FALSE}, then only exon-targeting
probesets are plotted.
 
}
\value{
  none
}
\seealso{\code{\link{gene.strip}} \code{\link{plotGene}} \code{\link{mappings}}
\code{\link{filters}} \code{\link{details}}}

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

\keyword{ misc }
\examples{ 
\dontrun{
   xmapConnect()
   data(exonmap)
   par(mfrow=c(3,2))
   gene.graph("ENSG00000141510",x.rma,gps=list(1:3,4:6),type="mean-fc",gp.col="red")
   gene.graph("ENSG00000141510",x.rma,gps=list(1:3,4:6),type="mean-int",gp.col=c("red","orange"))
   gene.graph("ENSG00000141510",x.rma,gps=list(1,2,3,4,5,6),type="mean-int",gp.col=1:6)
   gene.graph("ENSG00000141510",x.rma,gps=list(1,2,3,4,5,6),type="mean-int",gp.col=1:6,by.order=TRUE)
   gene.graph("ENSG00000141510",x.rma,gps=list(1,2,3,4,5,6),type="mean-int",gp.col=1:6,by.order=TRUE,show.introns=TRUE)
   gene.graph("ENSG00000141510",x.rma,gps=list(1,2,3,4,5,6),type="mean-int",gp.col=c(rep("red",3),rep("orange",3)),gp.pch=c(1,1,1,2,2,2),by.order=TRUE,show.introns=TRUE,exon.bg.col=NA)
}
}