%\VignetteDepends{Biobase,limma,IRanges,Biostrings,GenomicRanges,genomeIntervals}
%\VignetteIndexEntry{S4 Case Studies}
%\VignettePackage{HTSandGeneCentricLabs}

\documentclass{beamer}

\usepackage{Bioconductor}
\SweaveOpts{keep.source=TRUE}

\title{S4 Case Studies}
\subtitle{with an eye towards the GRanges and GRangesList classes}
\author{Patrick Aboyoun}
\institute[FHCRC]{Fred Hutchinson Cancer Research Center}
\date{28 July, 2010}

\begin{document}

<<setup, echo=FALSE>>=
options(width = 62)
@ 

\frame{\titlepage}

\section[Outline]{}
\frame{\tableofcontents}


\section{Use of S4 in Bioconductor}

\begin{frame}[t]
  \frametitle{Use of S4 in Bioconductor}
\begin{block}{Statistics on packages in BioC 2.6}
  \begin{itemize}
    \item 197 of 389 (51\%) BioC packages define S4 classes
    \item 97 use inheritance
    \begin{itemize}
      \item traditional parents: \Rclass{ExpressionSet}
        and \Rclass{eSet} from \Rpackage{Biobase}
      \item newer prolific parent: \Rclass{Sequence} from
        \Rpackage{IRanges}
      \item common off-beat parent: \Rclass{list}, an S3 type
    \end{itemize}
    \item 30 define virtual classes
    \item 14 use multiple inheritance
  \end{itemize}
\end{block}
\end{frame}


\section{S4 Case Studies}

\subsection{Data Representations (Annotated Genomic Intervals)}

\begin{frame}[t,fragile]
  \frametitle{General Feature Format}
{\small
\begin{enumerate}
\item \textbf{seqname} - The name of the sequence. Must be a chromosome or scaffold.
\item \textbf{source} - The program that generated this feature.
\item \textbf{feature} - The name of this type of feature. Some examples of standard feature types are "CDS", "start\_codon", "stop\_codon", and "exon".
\item \textbf{start} - The starting position of the feature in the sequence. The first base is numbered 1.
\item \textbf{end} - The ending position of the feature (inclusive).
\item \textbf{score} - A score between 0 and 1000.
\item \textbf{strand} - Valid entries include '+', '-', or '.' (for don't know/don't care).
\item \textbf{frame} - If the feature is a coding exon, frame should be a number between 0-2 that represents the reading frame of the first base. If the feature is not a coding exon, the value should be '.'.
\item \textbf{group} - All lines with the same group are linked together into a single item.
\end{enumerate}

\begin{verbatim}
track name=regulatory description="TeleGene(tm) Regulatory Regions"
chr22  TeleGene enhancer  1000000  1001000  500 +  .  touch1
chr22  TeleGene promoter  1010000  1010100  900 +  .  touch1
chr22  TeleGene promoter  1020000  1020000  800 -  .  touch2
\end{verbatim}
}
\end{frame}

\begin{frame}[t,fragile]
  \frametitle{Data Representations (Annotated Genomic Intervals)}
  \begin{columns}[t]
    \column{0.45\textwidth}
    \Rpackage{GenomicRanges}'s \Rclass{GRanges}
{\scriptsize
<<GenomicRanges, results=hide>>=
library(GenomicRanges)
@
<<options-set, echo=FALSE>>=
options(width=35)
@
<<GRanges>>=
getSlots("GRanges")
@
}
\begin{block}{Important considerations}
  \begin{enumerate}
    \item Interval overlap timings
    \item Coverage timings
    \item Subset timings
    \item Object size
    \item Grouping (exons in tx)
  \end{enumerate}
\end{block}

    \column{0.55\textwidth}
\Rpackage{genomeIntervals}'s \Rclass{Genome\_intervals\_stranded}
{\scriptsize
<<genomeIntervals, results=hide>>=
library(genomeIntervals)
@
<<options-set, echo=FALSE>>=
options(width=42)
@
<<Genome_intervals_stranded>>=
getSlots("Genome_intervals_stranded")
@
}
\Rpackage{IRanges}'s \Rclass{RangedData}
{\scriptsize
<<IRanges, results=hide>>=
library(IRanges)
@
<<RangedData>>=
getSlots("RangedData")
@
<<options-reset, echo=FALSE>>=
options(width=62)
@
}
  \end{columns}
\end{frame}

\begin{frame}[t,fragile]
  \frametitle{Data Representations (Grouped Genomic Intervals)}
  \begin{columns}[t]
    \column{0.5\textwidth}
    \Rpackage{GenomicRanges}'s \Rclass{GRangesList}
{\scriptsize
<<GenomicRanges, results=hide>>=
library(GenomicRanges)
@
<<options-set, echo=FALSE>>=
options(width=35)
@
<<GRangesList>>=
getSlots("GRangesList")
is(new("GRangesList"),
   "CompressedList")
@
}

    \column{0.5\textwidth}
\Rpackage{GenomicRanges}'s \Rclass{GappedAlignments}
{\scriptsize
<<GappedAlignments>>=
getSlots("GappedAlignments")
@
<<options-reset, echo=FALSE>>=
options(width=62)
@
}
  \end{columns}
\end{frame}

\subsection{Slot-Oriented Virtual Class (eSet)}

\begin{frame}[t,fragile]
  \frametitle{Slot-Oriented Virtual Class (eSet)}
  \begin{columns}[t]
    \column{0.5\textwidth}
    \Rpackage{Biobase}'s \Rclass{eSet}
{\scriptsize
<<Biobase, results=hide>>=
library(Biobase)
@
<<options-set, echo=FALSE>>=
options(width=35)
@
<<eSet>>=
isVirtualClass("eSet")
getSlots("eSet")
@
<<options-reset, echo=FALSE>>=
options(width=62)
@
}

    \column{0.5\textwidth}
\Rpackage{limma}'s \Rclass{MAList}
{\scriptsize
<<limma, results=hide>>=
library(limma)
@
<<MAList>>=
isVirtualClass("MAList")
getSlots("MAList")
@
}
  \end{columns}
\end{frame}

\subsection{Method-Oriented Virtual Class (Sequence)}

\begin{frame}[t,fragile]
  \frametitle{Finding Methods for an S4 Class}
\begin{block}{\Rfunction{showMethods} function wrapper}
{\small
<<s4Methods>>=
s4Methods <- function(class)
{
    methods <-
      showMethods(classes = class, printTo = FALSE)
    methods <- methods[grep("^Function:", methods)]
    sapply(strsplit(methods, " "), "[", 2)
}
@
}
\end{block}
\end{frame}

\begin{frame}[t,fragile]
  \frametitle{Method-Oriented Virtual Class (Sequence)}
    \Rpackage{IRanges}'s \Rclass{Sequence}
{\footnotesize
<<IRanges, results=hide>>=
library(IRanges)
@
<<Sequence>>=
isVirtualClass("Sequence")
getSlots("Sequence")
getSlots("Rle")
length(s4Methods("Sequence"))
head(s4Methods("Sequence"), 8)
@
}
\end{frame}

\begin{frame}[t,fragile]
  \frametitle{Method-Oriented Virtual Class (Sequence)}
\begin{block}{\Rclass{Sequence} subclass defines}
  \Rfunction{"["}, \Rfunction{c}, \Rfunction{length},
  \Rfunction{window}, \Rfunction{seqselect}, \Rfunction{"seqselect<-"}
\end{block}
\begin{block}{\Rclass{Sequence} subclass inherits}
    \Rfunction{head}, \Rfunction{tail}, \Rfunction{append},
    \Rfunction{subset}, \Rfunction{rep}, \Rfunction{rev} \footnotesize{(optimize?)},
    \Rfunction{"window<-"}, \Rfunction{"[<-"}
{\footnotesize
\begin{verbatim}
setMethod("head", "Sequence",
    function(x, n = 6L, ...)
    {
        stopifnot(length(n) == 1L)
        if (n < 0L)
            n <- max(length(x) + n, 0L)
        else
            n <- min(n, length(x))
        if (n == 0L)
            x[integer(0)]
        else
            window(x, 1L, n)
    })
\end{verbatim}
}
\end{block}
\end{frame}

\subsection{Multiple Inheritance \& Vectorization (CompressedIRangesList)}

\begin{frame}[t,fragile]
  \frametitle{Multiple Inheritance \& Vectorization (CompressedIRangesList)}
\begin{block}{\Rclass{CompressedIRangesList}}
{\small
\begin{verbatim}
setClass("CompressedIRangesList",
         prototype = prototype(elementType = "IRanges",
                               unlistData = new("IRanges")),
         contains = c("IRangesList", "CompressedList"))
\end{verbatim}
}
\end{block}
\begin{block}{\Rpackage{IRanges}'s \Rclass{List} paradigm}
  \begin{itemize}
    \item \Rclass{IRangesList} -- a method-oriented virtual class
    \item \Rclass{CompressedList} -- a slot-oriented virtual class
    \item \Rclass{SimpleIRangesList} -- a sibling class to 
      \Rclass{CompressedIRangesList}
  \end{itemize}
\end{block}
\end{frame}

\subsection{Build or Reuse? (CompresssedIRangesList)}

\begin{frame}[t,fragile]
  \frametitle{Build or Reuse? (CompresssedIRangesList)}
  \begin{columns}[t]
    \column{0.5\textwidth}
    \Rpackage{IRanges}'s \Rclass{CompressedIRangesList}
{\scriptsize
<<options-set, echo=FALSE>>=
options(width=35)
@
<<IRanges, results=hide>>=
library(IRanges)
@
<<CompressedIRangesList>>=
is(new("CompressedIRangesList"))
length(s4Methods("RangesList"))
head(s4Methods("RangesList"), 8)
@
}

    \column{0.5\textwidth}
\Rpackage{Biostrings}'s \Rclass{MIndex}
{\scriptsize
<<Biostrings, results=hide>>=
library(Biostrings)
@
<<MIndex>>=
isVirtualClass("MIndex")
s4Methods("MIndex")
s4Methods("ByPos_MIndex")
@
<<options-reset, echo=FALSE>>=
options(width=62)
@
}
  \end{columns}
\end{frame}

\subsection{Class Union \& Group Generic (Rle)}

\begin{frame}[t,fragile]
  \frametitle{Class Union \& Group Generic (Rle)}
  \Rpackage{IRanges}'s \Rclass{Rle}
{\footnotesize
\begin{verbatim}
setClassUnion("vectorORfactor", c("vector", "factor"))

setClass("Rle", contains = "Sequence")
         representation(values = "vectorORfactor",
                        lengths = "integer"),
         <<REMAINING DEFINITION>>)

setMethod("Summary", "Rle",
    function(x, ..., na.rm = FALSE)
        switch(.Generic,
               all =, any =, min =, max =, range =
               callGeneric(runValue(x), ..., na.rm = na.rm),
               sum = sum(runValue(x) * runLength(x), ...,
                         na.rm = na.rm),
               prod = prod(runValue(x) ^ runLength(x), ...,
                           na.rm = na.rm)))
\end{verbatim}
}
\end{frame}


\section{Resources}

\begin{frame}{Resources}
  \begin{block}{Books}
{\footnotesize
    \begin{itemize}
      \item John M. Chambers.
        \textit{Software for Data Analysis: Programming with R}.
        Springer, New York, 2008. ISBN-13 978-0387759357.
      \item Robert Gentleman. \textit{R Programming for Bioinformatics}.
        Chapman \& Hall/CRC, New York, 2008. ISBN-13 978-1420063677.
    \end{itemize}
}
  \end{block}
  \begin{block}{Documents on the Web}
{\footnotesize
    \begin{itemize}
      \item Patrick Aboyoun, ``S4 System Development in Bioconductor", \\
        \url{http://www.bioconductor.org/help/course-materials/2010/AdvancedR/S4InBioconductor.pdf}
      \item John M. Chambers, ``How S4 Methods Work", \\
        \url{http://developer.r-project.org/howMethodsWork.pdf}
      \item Friedrich Leisch, ``S4 Classes and Methods", \\
        \url{http://www.ci.tuwien.ac.at/Conferences/useR-2004/Keynotes/Leisch.pdf}
      \item ``S4 Classes in 15 pages, more or less", \\
        \url{http://www.stat.auckland.ac.nz/S-Workshop/Gentleman/S4Objects.pdf}
    \end{itemize}
}
  \end{block}
\end{frame}

\end{document}
