\HeaderA{plotExpressionGraph}{A function to plot a graph colored by expression data}{plotExpressionGraph}
\aliasA{defMapFun}{plotExpressionGraph}{defMapFun}
\aliasA{getPlotExpressionColors}{plotExpressionGraph}{getPlotExpressionColors}
\aliasA{IMCAEntrezLink}{plotExpressionGraph}{IMCAEntrezLink}
\keyword{utilities}{plotExpressionGraph}
\keyword{graphs}{plotExpressionGraph}
\keyword{hplot}{plotExpressionGraph}
\begin{Description}\relax
Given a graph and expression data for one entity, will plot the graph
with the nodes colored according to the expression levels provided.
\end{Description}
\begin{Usage}
\begin{verbatim}
plotExpressionGraph(graph, nodeEGmap, exprs, ENTREZIDenvir, mapFun, log = FALSE, nodeAttrs = list(), ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{graph}] The graph to plot
\item[\code{nodeEGmap}] A list with element names being node names and the
elements being EntrezLink IDs corresponding to those node names.
\item[\code{exprs}] A vector of expression data, with names being Affymetrix
IDs and values being the expression level.
\item[\code{ENTREZIDenvir}] An environment mapping Affymetrix IDs to EntrezLink
IDs, such as the ones provided in the xxx2ENTREZID environments from
the Bioconductor data packages (where xxx) is a data package)
\item[\code{mapFun}] A function to map expression levels to colors
\item[\code{log}] Whether or not the expression data 
\item[\code{nodeAttrs}] A list of node attributes, as per \code{plot.graph}
\item[\code{...}] Any extra arguments to be passed to \code{plot.graph} 
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
This function can be used to plot a graph and have the nodes colored
according to expression levels provided by the user.  The
\code{graph} parameter is a \code{graph} object from the \code{graph}
package.

The \code{nodeEGmap} parameter is a list that maps the nodes of the
graphs to EntrezLink IDs.  An example of this is the
\code{IMCAEntrezLink} object in the
\code{integrinMediatedCellAdhesion} data set in the
\code{graph} package.

The \code{exprs} argument is a vector mapping expression levels to
Affymetrix IDs.  One way to generate an appropriate vector is to
extract a single column from an \code{exprSet}.

The \code{ENTREZIDenvir} environment maps Affymetrix IDs to EntrezLink
IDs.  The simplest way to provide this argument is to load the
preferred Bioconductor data package (e.g. \code{hgu95av2}) and pass in
that package's \code{xxx2ENTREZID}, where \code{xxx} is the name of the
package.

The \code{mapFun} function defaults to the function \code{defMapFun},
which maps nodes to be either blue, green or red depending for
expression ranges of 0-100, 101-500, and 501+.  In the case where
\code{log} is \code{TRUE} these ranges are modified with
\code{\LinkA{log2}{log2}}.  Custom versions of this function can be supplied
by the user - it must take two parameters, first the expression vector
and a boolean value (\code{log}) specifying if the data has had a
\code{log2} applied to it.  The function must return a vector with the
same names as the expression vector, but the values of the vector will
be color strings.

The \code{nodeAttrs} list can be specified if any other node
attributes are desired to be set by the user.  Please see the
\code{\LinkA{plot.graph}{plot.graph}} man page for more information on this.  The
other attribute list (\code{attrs} and \code{edgeAttrs}) can be passed
in via the \code{...} parameter.

The IMCAEntrezLink data structure was created for the purpose of
illustrating this program.  On Sept 24 2007, the current versions
of  hgu95av2.db and hgu95av2 were used to map from the
nodes of IMCAGraph (in graph package) to Entrez identifiers.
\end{Details}
\begin{Author}\relax
Jeff Gentry
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{plot.graph}{plot.graph}}, \code{integrinMediatedCellAdhesion}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
   if ((require("Rgraphviz")) && (require("hgu95av2")) &&
        (require("fibroEset")) && (interactive())) {     
            data(integrinMediatedCellAdhesion)
            data(IMCAEntrezLink)
            data(fibroEset)
            attrs=getDefaultAttrs()
            attrs$graph$rankdir <- "LR"
            plotExpressionGraph(IMCAGraph, IMCAEntrezLink,
                                exprs(fibroEset)[,1],
                                hgu95av2ENTREZID, attrs=attrs)
   }
\end{ExampleCode}
\end{Examples}

