\name{GSload.genelist}
\alias{GSload.genelist}
\alias{GSsave.genelist}
\title{Load and save GeneSpring gene lists}
\description{
These functions load and save list of genes from and to GeneSpring.
Gene lists can consists of a simple list of genes or can contain one column
of associated values containing either the classifications or some numeric value
representing the result of an analysis (Like P values after a ANOVA for instance).
}
\usage{
GSload.genelist(filename = "GS_R_in.txt", EOF="///", chunk=1)
GSsave.genelist(genelist, filename = "GS_R_out.txt", EOF="///", append=TRUE)
}
\arguments{
  \item{filename}{Name of the file of the genelist. Can be connection object like \code{stdin()}.}
  \item{EOF}{String containing the delimiter used to separate the chunks in the file to be read.}
  \item{chunk}{Number indicating the chunk the gene list should be read from.}
  \item{genelist}{Gene list to be saved to the file. Can either be a list or a data frame/matrix.}
  \item{append}{Boolean indicating if the gene list should be appended to the output, allowing for multiple objects to be send back to GeneSpring.}
}
\details{
Gene lists are either simple lists or vectors of gene names or data.frames.
When the gene list contains associated values, the gene list is stored as a data.frame,
with the gene names as the first column of the data.frame and the values in the second
column of the data.frame.

GeneSpring will be able to send multiple objects and it sends all of the objects in one file,
one object per "chunk", separated by a delimiter on its own line. The order in which the
objects are defined (in the "Input" section of the External Program Interface definition),
determines in which chunk the gene list can be found. Conversely, by using the "append"
parameter in the \code{GSsave.genelist} function, multiple gene lists (or other objects)
can be send to GeneSpring and each of them will be loaded as a separate object.

There are two types of gene lists within GeneSpring, although only one is actually called
a gene lists while the other one is called a classification.

Gene lists proper are list of genes in GeneSpring with an optional NUMERICAL associated value.
This numerical values usually represents the result of one or more analyses, like the P value
of an ANOVA, or the number of samples that passed the filter that was applied.

The other type of gene lists are those lists that are produced when a Classification
is saved to a file. The classification objects are the result of the clustering
methods in GeneSpring, like K-means clustering or the QT-clustering. When classifications
are stored in file from GeneSpring, the classifications are simply gene lists with STRING
associated values, where the values designate the cluster name that gene belongs to.

The two functions \code{GSload.genelist} and \code{GSsave.genelist} will not make a distinction
between the two types of gene lists and it is left to the user to determine from the contents
of the genelists which of the two types has been loaded.

When a classification is attempted to be loaded into GeneSpring as a proper gene list, the
associated values will simply be missing if they are non-numerical.
}
\value{
The GSload.genelist() function will return either a vector of genenames, if the input was a 
simple list of genes or a data.frame where the gene names are the first column,
and the second column is the associated data.
}
\references{
For more information on using GeneSpring with R see
\url{http://www.chem.agilent.com/scripts/generic.asp?lpage=34733}
}
\author{ 
   Thon de Boer, Agilent Technologies, Santa Clara, CA, USA \email{thon\_deboer@agilent.com}
}
\note{This and any other functions in the GeneSpring package are only useful
when using Agilent Technologies Gene Expression software GeneSpring.
}
\seealso{
}
\examples{
#Create a simple GeneList
glist <- c("160640_at","101906_at", "104099_at")
#Save the genelist to a file
GSsave.genelist(glist, filename = "GS_R_out.txt")
#Load the genelist again
g2 <- GSload.genelist(filename = "GS_R_out.txt")
#Add some values to the genelist as associated values by making a data.frame out of it
g3 <- data.frame(genes = g2, value=rnorm(3))
#Save the genelist again to the default file ("GS_R_out.txt") and append it to the file
GSsave.genelist(g3, append=TRUE)
#Load the gene list and display
GSload.genelist(filename = "GS_R_out.txt", chunk=2)

#Create classification style gene list
g4 <- data.frame(genes = g2, classification=c("Cluster 1","Cluster 2", "Cluster 1"))
GSsave.genelist(g4, append=FALSE)
#Load the gene list and display
GSload.genelist(filename = "GS_R_out.txt")
}
\keyword{IO}