%\VignetteIndexEntry{PANTHER.db: An annotation package to access the PANTHER Classification System}
%\VignetteDepends{AnnotationDbi}
%\VignetteKeywords{annotation, database}
%\VignettePackage{PANTHER.db}
%\VignetteEngine{knitr::knitr}

\documentclass[11pt]{article}

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


\title{PANTHER.db: An annotation package to access the PANTHER Classification System}
\author{Julius M\"uller}

\begin{document}


\maketitle

\section{Introduction to \Rpackage{PANTHER.db}}

The \Rpackage{PANTHER.db} package provides a \Rfunction{select}
interface to the compiled PANTHER ontology residing within a SQLite database.

<<loadPkg>>=
library(PANTHER.db)
@

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

<<help,eval=FALSE>>=
help("PANTHER.db")
@


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

<<show,tidy=TRUE>>=
PANTHER.db
@

By default, you can see that the \Robject{PANTHER.db} object is set to
retrieve records from various organisms. The choice of the organism is the
intersection of organisms supported by PANTHER and the core annotation packages
in bioconductor. Methods are provided to restrict all queries to a
specific organism. In order to change it, you first need to look up the
appropriate organism identifier for the organism that you are interested in.
The PANTHER gene ontology is based on the Uniprot reference proteome set.
In order to display the choices, we have provided the helper function
\Rfunction{availablePthOrganisms} which will list all the supported
organisms along with their Uniprot organism name and taxonomy ids:

<<availSpecies>>=
availablePthOrganisms(PANTHER.db)
@

Once you have learned the PANTHER organism name for the organism of interest, you
can then change the organism for the \Robject{PANTHER.db} object:

<<setTaxID,tidy=TRUE>>=
pthOrganisms(PANTHER.db) <- "HUMAN"
PANTHER.db
resetPthOrganisms(PANTHER.db)
PANTHER.db
@

As you can see, organisms are now restricted to Homo sapiens.
To display all data which can be returned from a select query,
the columns method can be used:

<<columns>>=
columns(PANTHER.db)
@

Some of these fields can also be used as keytypes:

<<keytypes>>=
keytypes(PANTHER.db)
@

It is also possible to display all possible keys of a table for
any keytype. If keytype is unspecified, the FAMILY\_ID will be returned.

<<keys>>=
go_ids <- head(keys(PANTHER.db,keytype="GOSLIM_ID"))
go_ids
@

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

<<select>>=
cols <- c("FAMILY_ID","CLASS_ID")
res <- select(PANTHER.db, keys=go_ids, columns=cols,keytype="GOSLIM_ID")
head(res)
@

To access the PANTHER Protein Class ontology tree structure, the
method \Rfunction{traverseClassTree} can be used:

<<traverseClassTree>>=
term <- "PC00209"
select(PANTHER.db,term, "CLASS_TERM","CLASS_ID")

ancestors <- traverseClassTree(PANTHER.db,term,scope="ANCESTOR")
select(PANTHER.db,ancestors, "CLASS_TERM","CLASS_ID")

parents <- traverseClassTree(PANTHER.db,term,scope="PARENT")
select(PANTHER.db,parents, "CLASS_TERM","CLASS_ID")

children <- traverseClassTree(PANTHER.db,term,scope="CHILD")
select(PANTHER.db,children, "CLASS_TERM","CLASS_ID")

offspring <- traverseClassTree(PANTHER.db,term,scope="OFFSPRING")
select(PANTHER.db,offspring, "CLASS_TERM","CLASS_ID")
@

\end{document}