\name{annotFeaturesComp}
 \alias{annotFeaturesComp}
 \title{Features annotation}
 \usage{
   annotFeaturesComp(icaSet, params,
     type = toupper(typeID(icaSet)["geneID_annotation"]),
     featureId = typeID(icaSet)["featureID_biomart"],
     geneId = typeID(icaSet)["geneID_biomart"])
 }
 \arguments{
   \item{icaSet}{An object of class \code{\link{IcaSet}}
   whose features have to be annotated. The attribute
   \code{annotation} of this object contains the annotation
   package to be used.}
 
   \item{params}{An object of class
   \code{\link{MineICAParams}} containing the parameters of
   the analysis.}
 
   \item{type}{The ID of the object of the annotation
   package to be used for the annotation, must be available
   in \code{ls("package:package_name")}}
 
   \item{featureId}{The type of the feature IDs, in the
   \code{biomaRt} way (type \code{listFilters(mart)} to
   choose one). Used when \code{annotation(icaSet)} is of
   length 0.}
 
   \item{geneId}{The type of the gene IDs, in the
   \code{biomaRt} way (type \code{listAttributes(mart)} to
   choose one). Used when \code{annotation(icaSet)} is of
   length 0.}
 }
 \value{
   This function returns the argument \code{icaSet} with
   attributes \code{SByGene} and \code{datByGene} filled.
 }
 \description{
   ##' This function annotates the features of an object of
   class \code{\link{IcaSet}}, and fills its attributes
   \code{SByGene} and \code{datByGene}.
 }
 \details{
   This function is called by function
   \code{\link{annotInGene}} which will check the validity
   of the attributes \code{annotation, typeID, chipManu} and
   eventually \code{chipVersion} of \code{icaSet}. If
   available, the attribute \code{annotation} of argument
   \code{icaSet} must be an annotation package and will be
   used to annotate the \code{featureNames} of
   \code{icaSet}. If attribute \code{annotation} of argument
   \code{icaSet} is not available (of length 0),
   \code{biomaRt} is used to annotate the features.
 
   This function fills the attributes \code{SByGene} and
   \code{datByGene} of the argument \code{icaSet}. When
   several feature IDs are available for a same gene ID, the
   median value of the corresponding features IDs is
   attributed to the gene (the median of projection values
   is used for attribute \code{SByGene}, and the median of
   expression values is used for attribute
   \code{datByGene}).
 
   When attribute \code{chipManu} of the argument
   \code{icaSet} is "illumina", the features are first
   converted into nuID using the package 'lumi*Mapping' and
   then annotated into genes. In that case, features can
   only be annotated in ENTREZID or SYMBOL. It means that
   \code{typeID(icaSet)['geneID_annotation']} must be either
   'ENTREZID' or 'SYMBOL'. You will need to annotate
   yourself the \code{\link{IcaSet}} object if you want to
   use different IDs.
 }
 \examples{
 ## load an example of IcaSet
 data(icaSetCarbayo)
 params <- buildMineICAParams()
 require(hgu133a.db)
 ####===================================================
 ## Use of annotation package contained in annotation(icaSet)
 ####====================================================
 ## annotation in SYMBOL
 icaSetCarbayo_annot <- annotFeaturesComp(icaSet=icaSetCarbayo, params=params, type="SYMBOL")
 # arg 'type' is optional since the function uses contents of typeID(icaSet) as the defaults,
 # it is specified in these examples for pedagogy views
 
 ## annotation in Entrez Gene
 icaSetCarbayo_annot <- annotFeaturesComp(icaSet=icaSetCarbayo, params=params, type="ENTREZID")
 
 \dontrun{
 ####===================================================
 ## Use of biomaRt, when annotation(icaSet) is of length 0
 ####====================================================
 ## empty attribute 'annotation' of the IcaSet object
 # when this attribute is not specified, biomaRt is used for annotation
 annotation(icaSetCarbayo) <- character()
 
 # make sure the mart attribute is correctly defined
 mart(icaSetCarbayo) <- useMart(biomart="ensembl", dataset="hsapiens_gene_ensembl")
 
 ## make sure elements "featureID_biomaRt" and "geneID_biomaRt" of typeID(icaSet) are correctly filled
 # they will be used by function 'annotFeaturesComp' through biomaRt to query the database
 typeID(icaSetCarbayo)
 
 ## run annotation of HG-U133A probe set IDs into Gene Symbols using biomaRt
 icaSetCarbayo_annot <- annotFeaturesComp(icaSet=icaSetCarbayo, params=params)
 
 }
 }
 \author{
   Anne Biton
 }
 \seealso{
   \code{\link{annotFeatures}},
   \code{\link{annotFeaturesWithBiomaRt}},
   \code{\link{annotInGene}}
 }