\name{dbGetGeneRegulationRanking}
\alias{dbGetGeneRegulationRanking}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Rank genes according to the number of comparisons they are regulated.}
\description{
This function can be used to generate a ranking list for genes that contains the number of comparisons (from a selected set of comparisons in the database) the gene was regulated (where regulation can be for example be defined as an M value bigger than 1 or smaller -1). The ranking can be restricted to a subset of genes and comparisons. Note that the comparisons have to be created in the database (from expresison values using the \code{\link{dbCalculateRegulations}} method).
By default the function maps first the submitted ids to UniGene IDs and calcultates therefore the ranking for genes (not for, in the case of Affymetrix, probe sets), bevertheless by setting \code{no.mapping.to.ug=TRUE} this mapping to UniGene IDs will be skipped and the ranking will be performed id per id.
}
\usage{
dbGetGeneRegulationRanking(con, ug = NULL, id = NULL, include.by.name = NULL, exclude.by.name = NULL, include.by.pk = NULL, exclude.by.pk = NULL, count.cols = NULL, write.info.file = TRUE, search.column = "exposure_time", no.mapping.to.ug = FALSE ,m.up= 1, m.down= -1, v = TRUE, chip=NULL)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{con}{The connection to the (maDB) database.}
  \item{ug}{A set of UniGene identifiers. The annotation table has to be created if this option is used!}
  \item{id}{A set of ids (eg Affymetrix probe set IDs or the IDs that were used as rownames in the \code{EexprSet@exprs} tables that were inserted into the database).}
  \item{include.by.name}{The comparisons are joined to the samples table. So comparisons can be selected or using the \code{include.by.pk} attribute, or using the sample names of the samples that were used as \code{red} signal channels in the calculation of the regulation value (\code{M = log2(R / G)}).}
  \item{exclude.by.name}{Samples that should be excluded.}
  \item{include.by.pk}{The primary keys of the comparisons that should be included to create the ranking.}
  \item{exclude.by.pk}{The primary keys of the comparisons that should be excluded (makes only sense when the \code{include.by.name} was used, and not all of the comparisons that share the same sample names should be included).}
  \item{count.cols}{The entries (of the samples table) that should be used to count the regulation. For example if you have in your database samples with 6 hours, 8 hours and 24 hours exposure time and you want to count for each gene the number of comparisons with 6 and 8 hours where they were regulated and additionally the number of comparisons with 24 hours exposure time samples, submit \code{count.cols=list(c("6h","8h"),c("24h"))} and for the attribute search.col \code{search.col="exposure_time"}.}
  \item{write.info.file}{If true a file called \dQuote{HL} with the current date and \dQuote{Info.txt} will be saved in the current working directory which contains the information which comaprisons were used to generate the ranking.}
  \item{search.column}{The column of the samples table that should be used to distinguish between different comparisons (see attribute count.cols).}
  \item{no.mapping.to.ug}{If TRUE the ranking will be computed for each submitted id, if FALSE each id will be mapped to UniGene IDs, and those will then be used to count the regulations. Because of this mapping it is important, that the annotation table in the database holds the correct information (see \code{\link{dbUpdateAnnotation}} for more information).}
  \item{m.up}{Genes that have an M value bigger than this value will be counted as regulated (up--regulated!), the default is 1.}
  \item{m.down}{Genes that have an M value smaller than this value will be counted as down--regulated.}
  \item{v}{If additional information (progress bar...) should be written to the console.}
  \item{chip}{The chip or array type (eg hgu133plus2).}
}
\details{
coming soon...
}
\value{
A table with the information about how many times a gene was regulated.
}
\author{Johannes Rainer}
\seealso{ \code{\link{dbUpdateAnnotation}}, \code{\link{publishToDB}}, \code{\link{dbCalculateRegulations}} }
\keyword{data}