\name{chipAlongChrom}
\alias{chipAlongChrom}
\title{Visualize ChIP intensities along the chromosome}
\description{
  This function can visualize the array intensities from a ChIP chip
  experiment for a chromosomal region or the whole chromosome. It's
  loosely based on the \code{plotAlongChrom} function from the package
  \code{tilingArray}, but provides a different visualization.
}
\usage{
chipAlongChrom(eSet, chrom, probeAnno, xlim, ylim = NULL, 
 samples = NULL, paletteName = "Dark2", colPal = NULL,
 byStrand = FALSE, ylabel = "fold change [log]", rugCol = "#000010",
 itype = "r", ipch = 20, icex = 1, ilwd = 3, ilty = 1, useGFF = TRUE,
 gff = NULL, featCol = "darkblue", zero.line = TRUE, putLegend = TRUE,
 add = FALSE, maxInterDistance = 200, verbose = TRUE, ...)
}
\arguments{
  \item{eSet}{An expression set containing the (normalized) ChIP
    intensities. Can be generated by using the function
    \code{asExprSet}.}
  \item{chrom}{character; the chromosome to visualize}
  \item{probeAnno}{Environment holding genomic position, index and gene
    association of probes on array. See \code{scripts/makeProbeAnno.R}
    for how to generate such an environment.}
  \item{xlim}{start and end genomic coordinates on the chromosome to
    visualize}
  \item{ylim}{minimum and maximum probe intensities for the plot, if
    \code{NULL}(default) set as \code{range(exprs(eSet))}}
  \item{samples}{numeric; which samples from the \code{eSet} are to be
    shown. Default is to show all samples in the \code{eSet},}
  \item{paletteName}{character; Name of the RColorBrewer palette to use
    for sample colors. If the number of samples is greater than the palette
    size, random colors are taken.}
  \item{colPal}{vector of colors to use for the sample intensities.
    This is alternative to the argument \code{paletteName}
    for specifying which colors to use.}
  \item{byStrand}{logical; not implemented yet.}
  \item{ylabel}{character; label for the y-axis, passed on to the
    plotting function as \code{ylab}}
  \item{rugCol}{color to use for marking the probe positions on the
    x-axis (genomic coordinate) }
  \item{itype}{character; type of plot type to use for the sample
    intensities. Can be "r","u", or any of the \code{type}
    specifications used in \code{plot.default}.
    Defaults to "r". Please refer to the details section below.}
  \item{ipch}{plot character to use with \code{itype="p"}}
  \item{icex}{character expansion to use for plotting symbol}
  \item{ilwd}{line width of plotted lines if \code{itype="l"}}
  \item{ilty}{line type of plotted lines if \code{itype="l"}; passed on
    to \code{par(lty)}.}
  \item{useGFF}{use further annotation}
  \item{gff}{Data frame containing annotation for genomic feature to be
    used to further annotate the plot.}
  \item{featCol}{color to use for genomic features.}
  \item{zero.line}{logical; should a dashed horizontal line at y=0 be
    put into the plot?}
  \item{putLegend}{logical; should a legend be put into the plot?}
  \item{add}{logical; should expression set intensities be plotted onto
    current device instead of a new one?}
  \item{maxInterDistance}{numeric; only used when \code{itype} is either
    "r" or "u"; specifies the maximal distance up to which
    adjacent probe positions should be connected by a line.}
  \item{verbose}{logical; progress output to STDOUT.}
  \item{\dots}{further parameters passed on to \code{plot.default}, see
    details}
}
\value{
  \code{\link{invisible}} matrix of probe intensities in the selected
  genomic regions
}
\details{
  The following \code{plot.default} arguments are already defined by
  arguments of this function and thus may not be included in \code{...}:
  \code{xlim, ylim, col, pch, cex, lwd, lty, frame.plot}

  The \code{itype} argument specifies the desired type of plot. It can
  be any valid specification of the \code{type} argument in
  \code{plot.default} or one of two special types:
  \describe{
    \item{"r"}{\strong{r}estricted drawing of position-connecting
      lines. adjacent probe connections will be connected by a line
      only if less or equal to argument \code{maxInterDistance} apart
      from each other; each probe position will be marked by an
      individual point anyway (whose shape is determined by the argument
      \code{ipch}).}
    \item{"u"}{similar as "r" but the lines and the points will be
      \strong{u}nconnected; reminiscent of \code{plot.default}'s
      \code{type} "b".}
  }
}
\author{Joern Toedling \email{toedling@ebi.ac.uk}}
\note{Use the function \code{\link[geneplotter]{alongChrom}} for
  alternative ways to display probe intensities in genomic regions.}
\seealso{\code{\link[graphics]{plot.default}};
  \code{plotAlongChrom} in package \code{tilingArray}}
\examples{
  # load data
  ringoExampleDir <- system.file("exData",package="Ringo")
  load(file.path(ringoExampleDir,"exampleProbeAnno.rda"))
  load(file.path(ringoExampleDir,"exampleX.rda"))

  # show a gene that is well represented on this microarray
  chipAlongChrom(exampleX, chrom="9", xlim=c(34318000,34321000),
                 ylim=c(-2,4), probeAnno=exProbeAnno, gff=exGFF)
}
\keyword{hplot}% at least one, from doc/KEYWORDS