%\VignetteIndexEntry{UniProt.ws: A package for retrieving data from the UniProt web service}
%\VignetteDepends{UniProt.ws}
%\VignetteEngine{knitr::knitr}

\documentclass{article}

<<style-knitr, eval=TRUE, echo=FALSE, results="asis">>=
BiocStyle::latex()
@ 

\title{UniProt.ws: A package for retrieving data from the UniProt web service}
\author{Marc Carlson}

\begin{document}

\maketitle

\section{Configuring \Robject{uniport.ws}}

The \Rpackage{UniProt.ws} package provides a \Rfunction{select}
interface to the UniProt web service.  

<<loadPkg>>=
suppressPackageStartupMessages({
    library(UniProt.ws)
})
up <- UniProt.ws(taxId=9606)
@ 

If you already know about the select interface, you can immediately
learn about the various methods for this object by just looking it's
the help page.

<<help,eval=FALSE>>=
help("UniProt.ws")
@ 

When you load the \Rpackage{UniProt.ws} package, it creates a
\Robject{UniProt.ws} object.  If you look at the object you will see
some helpful information about it.

<<show>>=
up
@ 

By default, you can see that the \Robject{UniProt.ws} object is set to
retrieve records from Homo sapiens.  But you can change that of
course.  In order to change it, you first need to look up the
appropriate taxonomy ID for the species that you are interested in.
Uniprot provides support for over 20 thousand species, so there are a
few to choose from!  In order to make this easier, we have provided
the helper function \Rfunction{availableUniprotSpecies} which will
list all the supported species along with their taxonomy ids. When you
call the \Rfunction{availableUniprotSpecies} function, it's
recommended that you make use of the pattern argument to limit your
queries like this:

<<availSpecies>>=
availableUniprotSpecies(pattern="musculus")
@ 

Once you have learned the taxonomy ID for the species of interest, you
can then change the taxonomy id for the \Robject{UniProt.ws} object
using \Rfunction{taxId} setter or by calling the constructor for
\Rfunction{UniProt.ws}

<<setTaxID>>=
mouseUp <- UniProt.ws(10090)
mouseUp
@ 

As you can see the species is different for the
\Robject{mouseUp} new object.


\section{Using \Robject{UniProt.ws}}

Once you are safisfied that you have an \Robject{uniport.ws} that is
using the appropriate organsims, you can make use of the standard set
of methods in a \Rfunction{select} interface.  Specifically:
\Rfunction{columns}, \Rfunction{keytypes}, \Rfunction{keys} and
\Rfunction{select}.

You will probably notice that there are a large number of columns that can be
retrieved.

<<columns>>=
head(keytypes(up))
@ 

And most (but not all) of these fields can also be used as keytypes.

<<keytypes>>=
head(columns(up))
@ 

If necessary you can also look up the keys of a given type.  But
please be warned that the web service is slow at this particular kind
of lookup.  So if you really want to do this kind of operation you are
probably going to want to save the result to your R session.

<<keys,eval=FALSE>>=
egs = keys(up, "ENTREZ_GENE")
@ 

Finally, you can loop up whatever combinations of columns, keytypes and keys
that you need when using \Rfunction{select}.

<<select>>=
keys <- c("1","2")
columns <- c("PDB","HGNC","SEQUENCE")
kt <- "ENTREZ_GENE"
res <- select(up, keys, columns, kt)
res
@ 

\section*{\Rfunction{sessionInfo()}}

<<<sessionInfo>>=
sessionInfo()
@ 

\end{document}