\name{writeGenes}
\alias{writeGenes}
\title{Description of features using package \code{biomaRt}.}
\usage{
  writeGenes(data, filename = NULL,
    mart = useMart(biomart = "ensembl", dataset = "hsapiens_gene_ensembl"),
    typeId = "hgnc_symbol", typeRetrieved = NULL,
    sortBy = NULL, sortAbs = TRUE, colAnnot = NULL,
    decreasing = TRUE, highlight = NULL, caption = "")
}
\arguments{
  \item{data}{Either a data.frame whose rownames or one of
  its columns contain the IDs to be annotated, or a vector
  of IDs.}

  \item{filename}{The name of the HTML file where gene
  annotations are written.}

  \item{mart}{Output of function \code{useMart} from
  package \code{biomaRt}.}

  \item{typeId}{The type of IDs available in \code{data},
  in the biomaRt way (type \code{listFilters(mart)} to
  choose one).}

  \item{typeRetrieved}{The descriptors uses to annotate the
  features of \code{data} (type \code{listAttributes(mart)}
  to choose one or several).}

  \item{sortBy}{Name of a column of \code{data} used to
  order the output.}

  \item{sortAbs}{If TRUE absolute value of column
  \code{sortBy} is used to order the output.}

  \item{colAnnot}{The column containing the IDs to be
  annotated, if NULL or missing and argument \code{data} is
  a data.frame, then rownames of \code{data} must contain
  the IDs.}

  \item{decreasing}{If TRUE, the output is sorted by
  decreasing values of the \code{sortBy} column}

  \item{highlight}{IDs to be displayed in colour red in the
  returned table}

  \item{caption}{A title for the HTML table}
}
\value{
  This function returns a data.frame which contains
  annotations of the input data.
}
\description{
  This function annotates IDs (typically gene IDs) provided
  by the user and returns an html file with their
  description.
}
\details{
  \code{"hgnc_symbol", "ensembl_gene_id", "description",
  "chromosome_name", "start_position", "end_position",
  "band"}, and \code{"strand"}, are automatically added to
  the list of fields available in argument
  \code{typeRetrieved} queried on biomaRt. The web-links to
  www.genecards.org and www.proteinatlas.org are
  automatically added in the columns of the output
  respectively corresponding to \code{hgnc_symbol} and
  \code{ensembl_gene_id}.
}
\examples{
if (interactive()) {
## define the database to be used
mart <- useMart(biomart="ensembl", dataset="hsapiens_gene_ensembl")

### Describe:
## a set of hgnc symbols with default descriptions (typeRetrieved=NULL)
genes <- c("TOP2A","E2F3","E2F1","CDK1","CDC20","MKI67")
writeGenes(data=genes, filename="foo", mart=mart, typeId = "hgnc_symbol")

## a data.frame indexed by hngc symbols, sort output according to column "values", add a title to the HTML output
datagenes <- data.frame(values=rnorm(6),row.names = genes)
writeGenes(data=datagenes, filename="foo", sortBy = "values", caption = "Description of some proliferation genes.")

## a set of Entrez Gene IDs with default descriptions
genes <- c("7153","1871","1869","983","991","4288")
writeGenes(data=genes, filename="foo", mart=mart, typeId = "entrezgene")
}
\dontrun{
## add the GO category the genes belong to
## search in listAttributes(mart)[,1] which filter correspond to the Gene Ontology -> "go_id"
writeGenes(data=genes, filename="foo", mart=mart, typeId = "entrezgene", typeRetrieved = "go_id")
}
}
\author{
  Anne Biton
}
\seealso{
  \code{\link[biomaRt]{getBM}},
  \code{\link[biomaRt]{listFilters}},
  \code{\link[biomaRt]{listAttributes}},
  \code{\link[biomaRt]{useMart}}
}