\name{sdf.visualize}
\alias{sdf.visualize}
\title{Subset a SDF and visualize selected compounds in a webpage}
\description{
'sdf.visualize' will take a descriptor database generated by 'cmp.parse' and an
array of indecies, send an SDF consisting structure information of compounds
indexed by this array to ChemMine (\url{http://bioweb.ucr.edu/ChemMineV2}), and
open a webpage that shows the structures of these compounds. It returns the URL
of that page.
}
\usage{
sdf.visualize(db, cmps, extra=NULL, reference.sdf=NULL, reference.note=NULL, browse=TRUE, quiet=TRUE)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{db}{The database generated by 'cmp.parse'}
  \item{cmps}{A vector of indecies that correspond to a set of selected
	  compounds from the database}
  \item{extra}{A vector or list of character strings or matrices or data frames, each entry of which gives extra description on the compounds being visualized.}
  \item{reference.sdf}{A character string of SDF or a filename of an SDF file for the reference compound.}
  \item{reference.note}{Note to be displayed with the reference compound.}
  \item{browse}{Whether to open the webpage automatically after the upload
          is finished}
  \item{quiet}{Whether to display the progress information}
}
\details{

	'sdf.visualize' uses \code{\link{sdf.subset}} to extract the SDF for
	the selected compounds. Therefore, 'sdf.visualize' also depends on
	information embedded in the descriptor database returned by
	'cmp.parse'. It also relies on the availability of the original SDF
	file where the database has been generated from.  Basically, when
	'cmp.parse' parses the original SDF file, it will store the path of
	that SDF file as well as offset information for SDF segment in that
	file. Therefore, if the SDF file has been changed or deleted,
	'sdf.visualize' cannot function properly.

	After extracting the SDF segments for the selected compounds,
	'sdf.visualize' will send the SDF to ChemMine (\url{
	http://bioweb.ucr.edu/ChemMineV2}) using HTTP POST method. ChemMine
	will generate the 2D images for the selected compounds and a webpage
	containing these images as well as the SDFs. The URL is returned by
	'sdf.visualize'. If 'browse' is set to TRUE, the URL will be opened by
	your default browser.

	If the argument 'extra' is given, it must be a vector or list of character
	strings or data frames or matrices. The length of the vector or list must be
	the same as that of the indices. Each entry may be named
	or not. Each entry of this vector is a character string giving extra
	description on a compound. This vector will be sent to ChemMine, and
	the extra description for a compound will be listed at the right hand
	side of the compound. Data frames or matrices will be formatted and
	displayed as they would be formatted by the 'print' function.

	The 'reference.sdf' argument is given when you want to upload an
	extra compound as a reference compound. This compound will be displayed
	at the top of the visualization web page. This argument can be a
	character string of SDF(s), or it can be a filename or URL that points
	to an SDF file. If the string or the file contains multiple SDFs, this
	function will use the first one.

    If a reference compound is uploaded, note about this compound can be set
    via the 'reference.note' argument. This note will be displayed next to the
    structure of the compound on the resulting webpage.
}
\value{
	Returns the URL of the webpage containing all the SDFs and 2D images
	corresponding to the selected compounds.
}

\seealso{\code{\link{cmp.parse}}, \code{\link{sdf.subset}}}
\examples{
# load sample database from web
db <- cmp.parse("http://bioweb.ucr.edu/ChemMineV2/static/example_db.sdf")
# set default browser to firefox
options(browser="firefox")
# select SDF for 1st and 2nd compound in that SDF and visualize it
# url will contain the URL of the page. Your browser will automatically open
# the page, too.
\dontrun{url <- sdf.visualize(db, c(1, 2))}
# upload first 20 compounds, disable browsing the page automatically
url <- sdf.visualize(db, 1:20, browse=FALSE)
cat(paste("point your browser to ", url, "\n", sep=''))
# upload the first two compounds, with extra description
extra <- c("Mark's compound", "Alan's compound")
names(extra) <- rep("Note", 2)
\dontrun{url <- sdf.visualize(db, c(1, 2), extra=extra)}
# upload the first two compound, and use an reference compound
reference.cmp <- "http://bioweb.ucr.edu/ChemMineV2/compound/Aurora/b32:NNQS2MBRHAZTI===/sdf"
\dontrun{url <- sdf.visualize(db, c(1, 2), extra=extra, reference.sdf=reference.cmp, reference.note='Reference compound from Aurora library')}
}
\keyword{utilities}