%\VignetteIndexEntry{How-to guide to Rgb}

\documentclass[a4paper]{article}

\renewcommand{\familydefault}{\sfdefault}

\usepackage[margin=2.5cm]{geometry}
\usepackage{Sweave}
\usepackage{graphicx}
\usepackage[colorlinks=true, pdftitle={How-to guide to Rgb}, pdfsubject={How to use the "R Genome Browser" package}, pdfauthor={Sylvain Mareschal}, ]{hyperref}

\newcommand{\code}[1]{\texttt{#1}}
\newcommand{\strong}[1]{\textbf{#1}}

\let\stdsection\section
\renewcommand\section{\newpage\stdsection}

\begin{document}

% Set figure width
\setkeys{Gin}{width=1\textwidth}

% Load package for code chunks
\begin{Scode}{echo=false, results=hide}
  library(Rgb)
\end{Scode}

\title{\textbf{How-to guide to Rgb}}
\author{Sylvain Mareschal}

\begin{titlepage}
	\centering
	\vfill
	{\bfseries\huge
		How-to guide to Rgb\\
	}
	\vskip1cm
	{\bfseries
		Last edition February 23rd 2017\\
		\smallskip
		Sylvain Mareschal\\
		\vskip1cm
		\url{http://bioinformatics.ovsa.fr/Rgb}
	}
	\vskip2cm
	\includegraphics[width=4cm]{cghRA.png}
	\vfill
	\vfill
\end{titlepage}

\bigskip



\subsection*{About}

This document describes how to use the R Genome Browser, from general concepts to practical user cases. Questions and feedback may be sent to \href{mailto:maressyl@gmail.com}{maressyl@gmail.com}, news and updates will be made available on the \href{http://bioinformatics.ovsa.fr/Rgb}{package web page}.



\subsection*{Reference}

Mareschal S, Dubois S, Lecroq T, Jardin F. \\
\textbf{Rgb: a scriptable genome browser for R.} \\
\textit{Bioinformatics}. 2014 Aug 1;30(15):2204-5. \\
doi: 10.1093/bioinformatics/btu185



\subsection*{Acknowledgements}

Many thanks to Sydney Dubois for her consciencious copy-editing, to Christian Bastard for his implication in Rgb development, and to Bioinformatics' peer reviewers for their useful suggestions on the current manual.



\tableofcontents






\section{Quick start}



\subsection{Purpose}

Rgb, the "R genome browser", aims to provide native \strong{genome browsing} solutions for the R language. Genomes are usually organized in independent chromosomes, each of them consisting in a long sequence of nucleotides in which strips of biological interest (genes, introns, exons ...) can be localized using integer coordinates. Working with this specific paradigm requires dedicated tools, usually called "Genome browsers".

As a member of this family, Rgb provides classes to store such genomically located data, and methods to perform common tasks on them (subset, edit, draw ...). These classes transparently integrate a generic drawing system able to produce publication-grade representations of a locus of interest, which can be controlled either by direct R commands or by a Graphical User Interface that requires no specific R knowledge to be operated.

In most genome browsers (including Rgb), data is handled as \strong{tracks}, which consist of collections of genomic features of the same kind (genes, transcripts ...) and from the same organism. Rgb provides R classes to handle them, and a specific file format (.rdt) to store them from one session to another. Numerous parameters can be customised in such tracks to control the way the data will be represented, and great care has been taken to allow R developers to implement entirely new representation systems in Rgb.



\subsection{Track building}

Full documentation on track object building can be found in the R manuals: 

\begin{Scode}{eval=false}
  help("Annotation")
\end{Scode}

\subsubsection{Usual annotation tracks}

A few functions are provided to build annotation tracks from data available in remote repositories (NCBI, UCSC ...). First download the appropriate file, call the parsing function to produce the object and export it as a .rdt file:

\begin{Scode}{eval=false}
  download.file(
    "http://hgdownload.cse.ucsc.edu/goldenPath/hg19/database/cytoBand.txt.gz",
    destfile = "cytoBand.txt.gz"
  )
  track <- track.bands.UCSC(
    file = "cytoBand.txt.gz",
    .organism = "Human",
    .assembly = "hg19"
  )
  saveRDT(track, file="cytoBands.rdt")
\end{Scode}

The full list of handled datasets and links to download the corresponding files are described in the Annotation help page:

\begin{Scode}{eval=false}
  help("Annotation")
\end{Scode}

\subsubsection{Custom annotation tracks}

Annotation data can be downloaded from the \href{http://www.genome.ucsc.edu/cgi-bin/hgTables}{UCSC Table Browser} in the "Gene Transfert Format" (GTF), parsed, and saved as a RDT track. The following example is derived from the user case \ref{sec:TableBrowser}, in which we were interested in the COSMIC mutations in the ATM gene region:

\begin{center}
  \includegraphics{TableBrowser.png}
\end{center}

The downloaded GTF file can be parsed using the \code{track.table.GTF} function. Notice this function handles gzipped GTF files, so it is preferable to download them in such a format in order to minimize download time and disk usage. To make the example run, the following commands rely on the same file which is included in the Rgb package for testing purposes.

\begin{Scode}
  file <- system.file("extdata/Cosmic_ATM.gtf.gz", package="Rgb")
  tt <- track.table.GTF(file)
  saveRDT(tt, file="custom.rdt")
\end{Scode}

As the tables supplied by the Table Browser may need some reshaping, such files can also by parsed into data.frames by the \code{read.gtf} function, updated manually according to your needs, and exported as RDT tracks (see \ref{sec:customTrack} for the generic method, and \ref{sec:TableBrowser} for the more specific user case).

\subsubsection{Custom R data tracks}
\label{sec:customTrack}

Custom datasets can easily be converted from \code{data.frame} to \code{track.table} objects, then exported as .rdt files for Rgb. The table can hold as many columns as you want, as long as the few required columns are provided: chrom (factor), strand ("+" or "-"), start (integer), end (integer) and name (character). For more information on the \code{track.table} class and constructor, see \ref{sec:trackTable}.

\begin{Scode}
  data(hsFeatures)
  class(hsGenes)
  head(hsGenes)
  tt <- track.table(hsGenes)
  saveRDT(tt, file="custom.rdt")
\end{Scode}

\subsubsection{Next Generation Sequencing tracks}

BAM files are currently supported as an experimental feature, by the \code{track.bam} function which relies on a de novo R implementation of BAM querying based on \href{http://samtools.github.io/hts-specs/SAMv1.pdf}{SAM 1.4 specification sheet}. Due to the size of the datasets handled in such formats, the track produced does not contain the dataset but rather links it to R.

\begin{Scode}
  track <- track.bam(
    bamPath = system.file("extdata/ATM.bam", package="Rgb"),
    .organism = "Human",
    .assembly = "hg19"
  )
  saveRDS(track, file="sequencing.rds")
\end{Scode}

Notice the file format for such a track is slightly different: we use the RDS file format provided by R here, which is also plainly supported by Rgb.





\subsection{Genome browsing}

\subsubsection{Interactive genome browsing}

The genome browser can be summoned in an interactive session by a single call to \code{tk.browse}. It requires the \code{tcltk} and \code{tkrplot} packages (both available at the CRAN for most operating systems).

\begin{Scode}{eval=false}
  tk.browse()
\end{Scode}

\begin{center}
  \includegraphics{Main.png}
\end{center}

Track files can be selected by clicking the "Tracks" button in the top left hand corner, via the track management interface presented below. Tracks can be hidden by ticking the corresponding "Hidden" box, edited or reordered. Drawing parameters of all loaded tracks can be edited, replacing their values by valid R code (most parameters are single values). For more information on the drawing parameters, please refer to the appropriate drawing function manual (summoned by the "drawFun" parameter).

\begin{center}
  \includegraphics{Secondary.png}
\end{center}

The plotted window can be moved by entering genomic coordinates, or via keyboard shortcuts: use the \strong{left and right arrows} to move along the chromosome and the \strong{up and down arrows} to zoom in and out (or the mouse wheel if available). Zooming in can also be achieved with the mouse, \strong{holding a left click} from the desired left border to the desired right border. Finally the \strong{"R" key} can prove useful to force a plot refresh.

\medskip

Centering the view on track features searched by "name" can also be achieved by using the top right hand fields, selecting the track to be searched and entering the searched pattern aside. The default behavior is to return only exact matches, but regular expressions can be used by checking the "using regexp" box. If multiple hits are found, a message window pops up and reminds the user which match is currently viewed, switching each time the "Find" button is hit.

\subsubsection{Scripted genome browsing}

Genome browser representations can also be produced by scripts, calling the \strong{browsePlot} on which \strong{tk.browse} relies for its renderings. This function needs the track list to be passed as a \strong{drawable.list} object:

\begin{Scode}
  data(hsFeatures)
  dl <- drawable.list()
  dl$add(file=NA, track=hsBands)
  dl$add(file=NA, track=track.table(hsGenes))
  browsePlot(dl, chrom="1", start=0, end=10e6)
\end{Scode}

Drawable lists provide a common interface for scripts and GUI, allowing users to edit their content interactively even while scripting. Notice tracks should be passed with their paths to allow updates to be stored, in the examples presented here updates can only be stored in memory:

\begin{Scode}{eval=false}
  dl$fix.files()
  dl$fix.param()
\end{Scode}

As it relies on R plot, it can be redirected to a file (PNG, PDF ...):

\begin{Scode}
  pdf("Rgb_tests.pdf")
  browsePlot(dl, chrom="1", start=0, end=10e6)
  browsePlot(dl, chrom="8", start=50e6, end=60e6)
  dev.off()
\end{Scode}




\subsection{Working with genomic data}

The \strong{track.table} class developed for Rgb can prove very useful when computationally intensive operations are to be performed on genomic data.

\subsubsection{slice: subset by coordinates}

Aside from the \strong{draw} method extensively used by the genome browser, a fast and memory efficient \strong{slice} method is proposed for the most common task in genomic data manipulation: extracting rows in a given genomic window.

\begin{Scode}
  data(hsFeatures)
  genes <- track.table(hsGenes)
  genes$slice(chrom="12", start=45e6, end=48e6)
  system.time(
    for(i in 1:10000) genes$slice("12", 25e6, 118e6)
  )
\end{Scode}

\subsubsection{cross: intersect two tables}

The \strong{cross} method, which makes direct use of the \strong{slice} one presented above, can also prove particularly useful to annotate genomic tables or count overlaps between tables:

\begin{Scode}
  data(hsFeatures)
  print(hsBands)
  genes <- track.table(hsGenes)
  hsBands$cross(genes, type="count")[1:5]
  hsBands$cross(genes, colname="genes", type="name", maxElements=5)
  print(hsBands)
\end{Scode}

For further details on the \strong{track.table} class, please refer to the next chapter.

\subsubsection{draw: plot a single table}

The multi-track genome browsing system described above may be quite heavy to visualize a single track. In this case, one should consider using the \code{drawable} features directly:

\begin{Scode}{fig=true, width=8, height=1}
  # Drawable data format
  data(hsFeatures)
  genes <- track.table(hsGenes)
  
  # Draw
  genes$draw(chrom="8", start=15e6, end=20e6)
\end{Scode}

Drawing parameters may be changed for a single call:

\begin{Scode}{fig=true, width=8, height=1}
  print(genes$defaultParams()[1:5])
  genes$draw(chrom="8", start=15e6, end=20e6, colorVal="blue")
\end{Scode}

Or in a more persistent way:

\begin{Scode}{fig=true, width=8, height=1} 
  # Session persistent
  print(genes$defaultParams()[["mar"]])
  genes$setParam("mar", c(1.5, 5.0, 0.2, 1.0))
  genes$draw(chrom="8", start=15e6, end=20e6)
  
  # Save to file with custom parameters
  saveRDT(genes, file="genes.rdt")
\end{Scode}





\section{Manipulating the objects}



\subsection{Reference classes reminder}

All the classes used by Rgb are defined as "reference classes" (not to be confused with "S3" and "S4" systems). Complete documentation on this system can be found in the R manuals, however here is a quick reminder on this system, more similar to Java's Object-Oriented paradigm than R's "Function-Oriented" one.

\begin{Scode}{eval=false}
  help("setRefClass")
\end{Scode}

\subsubsection{Methods are called from objects, using the \$ sign}
\begin{Scode}
  data(hsFeatures)
  hsBands$fill(1:5, "stain", LETTERS[1:5])
  hsBands$getColNames()
\end{Scode}

\subsubsection{Objects are only copied on explicit demand}
\begin{Scode}
  data(hsFeatures)
  a <- hsBands
  a$getColNames()
  a$delColumns("stain")
  hsBands$getColNames()
  hsCopy <- hsBands$copy()
\end{Scode}

\subsubsection{Classes are self-documented objects}
\begin{Scode}
  classDefinition <- getRefClass("sliceable")
  classDefinition$methods()
  classDefinition$help("draw")
\end{Scode}

\subsubsection{Classes inherit methods and parameters}
\begin{Scode}
  # All "track.table" objects are "drawable" objects
  class(hsBands)
  is(hsBands, "drawable")
  
  # Many "track.table" methods are defined by "drawable" class
  dw <- getRefClass("drawable")
  tl <- getRefClass("track.table")
  intersect(dw$methods(), tl$methods())
\end{Scode}



\subsection{Rgb class hierarchy}

\begin{center}
  \includegraphics{UML.pdf}
\end{center}

Rgb heavily relies on class inheritance to avoid code duplication. As can be seen on the UML diagram above, objects from the \code{track.table} class (most of the objects manipulated in Rgb) are a convergence between the \code{refTable} class (that stores tabular data in an efficient way) and \code{drawable}-inheriting classes (managing all the drawing process, independently from the data type).

\medskip

The \code{sliceable} class in the \code{drawable} inheritance tree only implements the straight-forward way to plot genomic data: in most cases, the dataset must first be "sliced" (only data located in the queried genomic window are extracted), then the slice must be provided to the suitable drawing function. As a result, all classes inheriting from \code{sliceable} only need to implement an appropriate \code{slice} method to make use of the existing drawing engine (\code{track.table} and \code{track.bam} are two examples of very dissimilar data types that benefit from the same drawing system).

\medskip

The \code{crossable} class in the \code{drawable} inheritance tree offers a \code{cross} method to classes implementing a \code{slice} method, allowing one track to be annotated according to its overlaps with a second one.



\subsection{refTable: tabular data storage}

Rgb defines a new class to store tabular data: the \code{refTable} class. Such objects are very similar to R classical \code{data.frames}, and differ mainly in the way data is stored and extracted. The purpose of this class is to handle such data in a more efficient way, avoiding frequent copies due to R copy-on-write paradigm, within the strict context of object oriented programming. Please refer to the "Reference classes" chapter above for a quick reminder on reference class pitfalls in R.

\medskip

Data can be imported in such objects using the \code{refTable} constructor, with a single \code{data.frame} or a collection of vectors:

\begin{Scode}
  library(Rgb)
  df <- data.frame(colA=letters[1:5], colB=5:1)
  rt <- refTable(df)
  rt <- refTable(colA=letters[1:5], colB=5:1)
  print(rt)
\end{Scode}

Extraction from \code{refTable} objects is handled by the \code{extract} method, which returns data.frames or vectors. As with the R classical "[", lines can be extracted using several vector types: integers for row indexes, (recycled) logicals, or characters if row names were provided to refTable. Additionaly, an expression using column names and returning such a vector can be used, similarly to \code{with} behavior in data.frames:

\begin{Scode}
  library(Rgb)
  data(hsFeatures)
  rf <- refTable(hsGenes)
  rf$extract(1:5)
  rf$extract(c(TRUE, rep(FALSE, 799)))
  rf$extract(expression(name == "RDX"))
  rf$extract(expression(chrom == "X" & grepl("^AR", name)))
\end{Scode}

To mutate \code{refTable} objects, several methods are provided: \code{addList}, \code{addVectors} and \code{addDataFrame} to add new rows, \code{addColumn} and \code{delColumns} to update whole columns, and \code{fill} to modify single cells. Finally the \code{rowOrder} method can prove useful to play with row ordering or subsetting (keep in mind that \code{track.table} objects require rows to be genomically ordered, but \code{refTable} does not). See the \code{refTable-class} manual page for examples.

\begin{Scode}{eval=false}
  example(topic="refTable-class", package="Rgb")
\end{Scode}



\subsection{track.table: genomically located tabular data}
\label{sec:trackTable}

The \code{track.table} inherits most of its methods from \code{refTable}, please have a look at the previous section to know how to handle such data. Objects from this class can be produced using the \code{track.table} constructor, in the same way as the \code{refTable} constructor presented above. Notice though the few required columns: chrom (factor), strand ("+" or "-"), start (integer), end (integer) and name (character). Notice the following example raises warnings about meta-data missingness (organism, assembly ...), they can be provided or silenced by \code{warn = FALSE} in the \code{track.table} constructor.

\begin{Scode}
  library(Rgb)
  tl <- track.table(name=letters[1:5], chrom=1:5, strand="+", start=1:5, end=2:6)
  df <- data.frame(chrom=1:5, strand="+", start=1:5, end=2:6)
  tl <- track.table(df, .makeNames=TRUE, .organism="Human", warn=FALSE)
  print(tl)
\end{Scode}

The most valuable features of \code{track.table} are the \code{slice} and \code{cross} methods, which are presented in the "Quick start" section of the current manual. Notice chromosomes can be armed (e.g. "1p" and "1q" in humans) or not, and two methods are provided to switch from one representation to the other (\code{eraseArms} and \code{addArms}, the former needing centromere positions as provided by the \code{track.bands.UCSC} function).



\subsection{drawable: drawing management}
\label{sec:drawable}

The \code{drawable} class implements some features to be added to inheriting classes, such as \code{track.table}. It provides a common mechanism to manage drawing parameters, mainly through the \code{getParam} and \code{setParam} methods, and requires inheriting classes to define a \code{draw} method to plot its content in a given genomic window. \code{track.table} and \code{track.bam} both rely on the \code{sliceable} virtual class to implement such a method, itself requiring only a slice method to extract data in the given genomic window, and a drawing function to plot this slice of data.

\begin{Scode}{fig=true, width=8, height=1}
  library(Rgb)
  data(hsFeatures)
  hsBands$draw("1", 0, 150e6)
\end{Scode}

\begin{Scode}{fig=true, width=8, height=1}
  hsBands$getParam("drawFun")
  hsBands$setParam("label", FALSE)
  hsBands$draw("1", 0, 150e6)
\end{Scode}

\bigskip

Drawing parameters can be set at many levels, and are collated following a strict hierarchy: drawing parameters passed as additional arguments to \code{draw} have the top-most priority, preceding parameters set in objects (using the \code{setParam} method), which precede class-specific defaults (defined at class definition, see \ref{sec:extendingRgb}) following the inheritance order (\code{track.table} defaults are prioritary over \code{drawable} and so on). At the lowest priority are the default values of the R drawing functions (named in the "drawFun" parameter).

\begin{Scode}{fig=true, width=8, height=1}
  library(Rgb)
  data(hsFeatures)
  hsBands$setParam("label", FALSE)
  hsBands$draw("1", 0, 150e6, label=TRUE)
\end{Scode}

\bigskip

If a parameter was not defined specifically in an object, a call to \code{getParam} will rely on \code{defaultParams} to return a value. To erase an object-level setting (and thus turn back to class-specific default), just call \code{setParam} without value. Notice default parameters returned by \code{defaultParams} depend on the drawing function currently defined by the "drawFun" drawing parameter itself:

\begin{Scode}
  library(Rgb)
  data(hsFeatures)
  hsBands$getParam("drawFun")
  names(hsBands$defaultParams())
  hsBands$setParam("drawFun", "draw.points")
  names(hsBands$defaultParams())
\end{Scode}





\section{User case : ATM mutations in human}

This user case introduces the handling of BAM files in a well annotated organism, for which custom annotation tracks can be found at the UCSC. It makes extensive use of the interactive genome browser, but also describes an automation scheme.



\subsection{Objectives}

The ATM gene was sequenced by the Ion Torrent technology in a tumoral sample, and we would like to visualize the mutations found. The resulting BAM file and its BAI index, as processed and aligned by the Torrent Suite, are provided with the Rgb package:

\begin{Scode}
  library(Rgb)
  system.file("extdata/ATM.bam", package="Rgb")
  system.file("extdata/ATM.bam.bai", package="Rgb")
\end{Scode}

To minimize their impact on the Rgb package size, they were downsampled to 2000 reads from chromosome 11. However Rgb can handle standard-sized BAMs as well, and users are encouraged to use one of them if available.



\subsection{Interactive browsing}

\subsubsection{Launch the interactive browser}

As a first approach to the dataset, we will begin to browse it interactively. First a track file must be produced from the data, and saved as a file that can be imported in the interactive genome browser:

\begin{Scode}
  track <- track.bam(
    bamPath = system.file("extdata/ATM.bam", package="Rgb"),
    .organism = "Human",
    .assembly = "hg19"
  )
  saveRDS(track, file="ATM.rds")
\end{Scode}

Then the genome browser can be launched:

\begin{Scode}{eval=false}
  tk.browse()
\end{Scode}

Hit the "Tracks" button, "Add file" and select the "ATM.rds" file produced above (you may need to change the extensions shown as by default only ".rdt" files are displayed). Wait for the track to appear in the list, and hit "Done" to go back to the main window.

As no region was defined, there is currently nothing drawn. However to get a first idea of our data, let's have a look at the "chr11:108225450-108225660" region: write "11", "108.22545" and "108.22566" in the coordinate boxes (notice the coordinates are expected in megabases, Mb). Hit the "Enter" key or the "Jump" button.

Data is represented as a \strong{pileup}, an histogram of all nucleotide frequences at each position of the genome. The arrow keys can be used to zoom in and out, and to move left and right. Zooming in will allow the nucleotide letters to appear, while zooming out may disable the representation ("maxRange reached").

\subsubsection{Add standard annotation}

To make the interpretation simpler, let's gather some basic annotation, beginning with datasets already handled by Rgb. This can be achieved in the R terminal while the genome browser is running. Firstly the cytogenetic banding, to be downloaded from \href{http://hgdownload.cse.ucsc.edu/goldenPath/hg19/database/cytoBand.txt.gz}{UCSC}:

\begin{Scode}
  track <- track.bands.UCSC(
    file = "cytoBand.txt.gz",
    .organism = "Human",
    .assembly = "hg19"
  )
  saveRDT(track, file="cytoBands.rdt")
\end{Scode}

Then the coding sequences (exons), to be downloaded from the \href{http://ftp.ncbi.nlm.nih.gov/pub/CCDS/current_human/CCDS.current.txt}{CCDS} database:

\begin{Scode}
  track <- track.exons.CCDS(
    file = "CCDS.current.txt",
    .organism = "Human",
    .assembly = "hg19"
  )
  saveRDT(track, file="exons.rdt")
\end{Scode}

Both can be added from the "Tracks" interface of the genome browser seen previously. After closing the "Tracks" window with the "Done" button, hit the "R" key or an arrow key to refresh the plot.

\subsubsection{Customize the representation}

The order of the tracks may not be optimal. Try to move the cytoband track to the top: open the "Tracks" window, check the radio button in the "Action" column for the "cytoBands.rdt" file, and hit "Move up". When finished, hit "Done", and refresh the plot as previously.

The exon track may be too large for the small content it has to offer in this genomic location. Hit the "Tracks" window, check the "exons.rdt" line as previously and hit "Edit". The first menu on the left allows switching the track currently edited, while the menu on the right lists the parameters that can be edited. Search "height", and replace "1" by "0.5". Hit "Save in memory" or "Save in file", according to your preference (in the first case, changes will be lost at the closure of the genome browser). Hit "Close and discard" to close this window, "Done", and refresh the plot. This parameter is particularly important, as it controls the relative sizes of tracks: by default most are set to 1, which means that every track with such a value must have the same height, equally sharing the window size. A value of 0.5 will result in a track twice as short as the others, and so on. Fixed heights can also be obtained, defining the height in centimeters ("3 cm").

As you may have noticed, zooming out quickly results in "maxRange reached" messages. The maximum range at which the plot is no longer displayed is a parameter that can be changed. As for the "height" updated previously, try to replace the "5000L" by a larger value (the "L" is optional and only enforces the value as an integer). Beware however as the drawing time will increase exponentially when large pileups are to be plotted ...

By default, the Y axis is dynamic, which can make the comparison of depth of coverage tricky. As previously, try to replace the "NA" value of the "ylim" parameter by "c(0, 50)" (a vector of two values defining the minimum and maximum to use). If you are familiar with R, this syntax should be evident: each parameter actually supports any valid R expression as a value.

\subsubsection{Add annotation from UCSC}
\label{sec:TableBrowser}

As we are looking for mutations in a cancer sample, the location of all known \href{http://cancer.sanger.ac.uk/cancergenome/projects/cosmic/}{COSMIC} mutations may prove particularly valuable to interpret our data. The \href{http://www.genome.ucsc.edu/cgi-bin/hgTables}{UCSC Table Browser} allows such data to be downloaded from its Table Browser, let's have a look at it:

\begin{center}
  \includegraphics{TableBrowser.png}
\end{center}

The region was restrained to the ATM gene location to minimize download time and disk usage, however feel free to download the whole COSMIC dataset. The resulting file is available in Rgb for testing purposes:

\begin{Scode}
  file <- system.file("extdata/Cosmic_ATM.gtf.gz", package="Rgb")
  track <- track.table.GTF(file, .organism="Human", .assembly="hg19")
\end{Scode}

As GTF is a very generic file format, it usually requires a few modifications to produce statisfying visualizations. Let's have a look at it, using the \code{draw} method in a random region directly:

\begin{Scode}{fig=true, width=8, height=2}
  print(track)
  track$draw("11", 108.5e6, 108.6e6)
\end{Scode}

It seems that the track contains many records, so the "maxElements" limit that prevents overcrowded tracks to be plotted is suboptimal. Before making more permanent changes in the file or manual changes in the interactive browser, let's find a more optimal value by temporarly setting it in the \code{draw} call:

\begin{Scode}{fig=true, width=8, height=2}
  track$draw("11", 108.5e6, 108.6e6, maxElements=100)
\end{Scode}

Once the appropriate value is found, we can edit it more permanently using the \code{setParam} method:

\begin{Scode}{fig=true, width=8, height=2}
  track$setParam("maxElements", 100)
  track$draw("11", 108.5e6, 108.6e6)
\end{Scode}

Now let's focus on record names. As Rgb is unable to predict which column of the table contains the data you wish to display as feature names, it generates names concatenating the chromosome location and an order number. As you can see using \code{print}, the "gene\_id" and "transcript\_id" columns seem to offer more interesting information (the COSMIC ID). As Rgb always use the "name" column to label features, all we have to do is replace its content by the content of the column of our choice:

\begin{Scode}{fig=true, width=8, height=2}
  newNames <- track$extract(,"gene_id")
  track$fill(, "name", newNames)
  track$draw("11", 108.5e6, 108.6e6)
\end{Scode}

To finish with a more cosmetic change, let's give a neater name to the track that the one extracted from the file:

\begin{Scode}{fig=true, width=8, height=2}
  track$name <- "COSMIC ATM"
  track$draw("11", 108.5e6, 108.6e6)
\end{Scode}

Keep in mind that all the modifications we made here only apply to the object stored in R memory, it must be saved in an ".rdt" file to avoid the hassle of rerunning all these commands in each new R session. Once saved, we can import it in our current interactive browser window, using the "Tracks" button as previously.

\begin{Scode}
  saveRDT(track, file="COSMIC_ATM.rdt")
\end{Scode}

\subsubsection{Manual check of the exons}

Zooming out with the down arrow key, we are able to zoom into each exon to visualize the data, even if the "maxRange reached" message masks them at the gene level zooming. To zoom into a particular exon, just click the left mouse button at its start, move it to the ending position and release the button ("drag and drop").



\subsection{Automation}

\subsubsection{Produce a single plot}

All the operations manually performed above can be achieved using the \code{browsePlot} equivalent of the \code{tk.browse} function, in order to automatically generate representations of the 62 exons rather than manually jump to each of them. First the tracks must be collected in a \code{drawable.list} object:

\begin{Scode}
  dl <- drawable.list(
    files = c(
      "cytoBands.rdt",
      "ATM.rds",
      "exons.rdt",
      "COSMIC_ATM.rdt"
    )
  )
\end{Scode}

Here they can be edited interactively by the \code{fix.param} method, and expanded using \code{fix.files} in the same way as in the interactive genome browser.

\begin{Scode}{eval=false}
  dl$fix.param()
  dl$fix.files()
\end{Scode}

However to make the whole process automatic, we will edit them using commands only. Tracks in drawable lists may be selected using one of the following methods: \code{getByNames}, \code{getByClasses} and \code{getByPositions}, each of them returning tracks as an R list (which means further subsetting is required).

\begin{Scode}
  print(dl)
  dl$getByNames("UCSC bands")
\end{Scode}

To obtain a list of handled parameters as the interactive browser offers, the \code{defaultParams} method may prove useful:

\begin{Scode}
  target <- dl$getByNames("UCSC bands")[[1]]
  names(target$defaultParams())
\end{Scode}

Then the \code{setParam} method can be called to update the parameters. As reference classes are used here, feel free to store \code{getByNames} output in an intermediary variable, any modification applied to the intermediate will also apply to the drawable list:

\begin{Scode}
  dl$getByNames("CCDS exons")[[1]]$setParam("height", 0.5)
  target <- dl$getByNames("ATM.bam")[[1]]
  target$setParam("maxRange", 8000)
  target$setParam("ylim", c(0, 50))
\end{Scode}

Finally the drawable list can be handed to \code{browsePlot} for plotting:

\begin{Scode}{fig=true, width=8, height=6}
  browsePlot(dl, chrom="11", start=108225450, end=108225660)
\end{Scode}

Keep in mind that \code{tk.browse} also handles drawable lists as input, a feature that can prove useful for script debugging or to launch the browser with a predefined set of tracks.

\begin{Scode}{eval=false}
  tk.browse(dl)
\end{Scode} 

\subsubsection{Loop on exons}

While automating a single representation may make its future modification easier, its strength resides in its ability to save a lot of manual manipulations. Let's try to generate representations using the previous settings on the 62 exons of ATM.

First we need to collect the coordinates of the exons to loop on. More than an input for \code{tk.browse} and \code{browse.plot}, the track files we produced are also easy to query datasets. Let's have a look at the exon track:

\begin{Scode}
  exons <- readRDT("exons.rdt")
  print(exons)
\end{Scode}

As you can see, the track is basically a table with more than 300 000 rows and a few columns. The gene symbol in which to look for ATM is held in the "transcript" column, which can be queried in-situ using the \code{extract} method:

\begin{Scode}
  loci <- exons$extract(expression(grep("^ATM ", transcript)))
  print(head(loci))
\end{Scode}

However R users not familiar with reference classes may find it easier (but slower) to convert the whole track to a \code{data.frame} and use base R mechanisms:

\begin{Scode}
  exonTable <- exons$extract()
  print(head(exonTable))
  loci <- subset(exonTable, grepl("^ATM ", transcript))
\end{Scode}

Looping throught the loci is now straight-forward, and resulting representations can be derived to a plotting device such as a PDF file:

\begin{Scode}{eval=false}
  pdf("ATM.pdf", width=12)
  for(i in 1:nrow(loci)) {
    browsePlot(dl,
      chrom = loci[i,"chrom"],
      start = loci[i,"start"] - 150,
      end = loci[i,"end"] + 150
    )
  }
  dev.off()
\end{Scode}





\section{User case : Gene expression mapping in A. thaliana}

This user case shows how Rgb can be used on more confidential organisms, for which annotation data must be processed manually from heterogeneous data sources.



\subsection{Objectives}

In this user case, we are interested in visualizing gene expression mapping data in Arabidopsis thaliana. The dataset we are going to use is freely available in the \href{http://www.ncbi.nlm.nih.gov/geo/}{Gene Expression Omnibus} database of the NCBI, under the accession number \href{http://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSM589609}{GSM589609}. As most micro-array datasets published nowadays are stored in GEO, it may prove valuable to know how to process data from this repository.

While some R packages from Bioconductor (\href{http://www.bioconductor.org/packages/release/bioc/html/GEOquery.html}{GEOquery}) propose downloading and pre-formatting data from the GEO database, we will process it manually to avoid Bioconductor's cumbersomeness and understand the whole process.

As the data files handled here can be very large (hundreds of Mo) and could not be distributed with the package, the current vignette was designed with files manually subset to a predefined window (chr1:16123000-16158000). However feel free to download the full data sets and run the commands on them, rather than using the distributed ones.

\subsection{Micro-array data from GEO}

\subsubsection{Aggregate the dataset}

On GEO, records are from two main types: \strong{platforms}, documenting probesets, their annotations and locations in the genome, and  \strong{sample} data. The first step will be to download the two datasets, and merge them into a single track that can be handled by Rgb.

Many file formats are provided, however the "Full table" proposed by GEO has the advantage of being platform-independent. The \href{http://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSM589609}{sample} (70 Mo) and \href{http://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GPL10855}{platform} (215 Mo) tables can be found on the dedicated webpages, and parsed using R basic mecanisms:

\begin{Scode}
  gpl <- read.table(
    file = "GPL10855-34953.txt",
    sep = "\t",
    header = TRUE,
    stringsAsFactors = FALSE
  )
  gsm <- read.table(
    file = "GSM589609-38201.txt",
    sep = "\t",
    header = TRUE,
    stringsAsFactors = FALSE
  )
\end{Scode}

Printing the first lines, notice that both rely on a single "ID" column to identify probes:

\begin{Scode}
  head(gpl)
  head(gsm)
\end{Scode}

A quick check can confirm that the two tables are ordered in the same way, and thus can be merged side-by-side without further processing. Consider the \code{merge} function for cases where these conditions fail (it may take a few minutes of computation on datasets of this size):

\begin{Scode}
  nrow(gpl) == nrow(gsm)
  all(gpl$ID == gsm$ID_REF)
\end{Scode}

The track can now be constructed using the generic \code{track.table} function, providing columns as vectors as for \code{data.frame}. Arguments beginning by dots are reserved for annotation meta-data to store along the dataset, which can be retrieved from the GEO webpage. Optional columns can also be picked from \code{gpl}, as long as the 5 mandatory columns (name, chrom, start, end, strand) are provided. Notice "start" and "end" requires columns to be of class "integer", and it may have to be enforced using \code{as.integer} if \code{read.table} didn't guess it while parsing:

\begin{Scode}
  cgh <- track.table(
    name = gpl$ID,
    chrom = gpl$RANGE_GB,
    start = as.integer(gpl$RANGE_START),
    end = as.integer(gpl$RANGE_END),
    strand = gpl$RANGE_STRAND,
    value = gsm$VALUE,
    .name = "GSM589609",
    .organism = "Arabidopsis thaliana",
    .assembly = "TAIR9"
  )
\end{Scode}

Printing the object, noticed that chromosome names are not very informative, which may cause conflicts with the future annotation sets:

\begin{Scode}
  cgh
\end{Scode}

The code{refTable} class proposes the \code{getLevels} and \code{setLevels} to its offspring, which can prove useful in this situation (correspondance between sequence accessions used here and general chromosome numbering can be found by querying \href{http://www.ncbi.nlm.nih.gov/nuccore}{Nucleotide} at NCBI). To enforce compatibility with tracks produced in \ref{sec:tairExons}, we will also define levels for the chloroplastic (C) and mitochrondrial (M) genomes:

\begin{Scode}
  cgh$getLevels("chrom")
  cgh$chromosomes()
  cgh$setLevels("chrom", newLevels=c(1:5, "C", "M"))
  cgh$chromosomes()
  cgh
\end{Scode}

\subsubsection{Customize the representation}

Now that the dataset is ready, let's have a look at how Rgb plots it:

\begin{Scode}{fig=true, width=8, height=2}
  cgh$draw(chrom="1", start=16125e3, end=16127e3)
\end{Scode}

Pretty disappointing isn't it ? As a default, Rgb considers features in tracks as boxes, which is nice for most datasets (genes, exons, CNV ...) but suboptimal in this case. However it offers solutions to switch the representation mode, which relies on the \strong{drawing function}. Three of them are provided for generic plotting: \code{draw.boxes} (default), \code{draw.hist} (for histograms) and \code{draw.points} (for scatter plots), but custom functions are also handled (see \ref{sec:drawCustom}). The selected drawing function sets the other parameters that can be changed, so have a look at the corresponding manual page for an exhaustive list of them and their signification. Notice the three of them rely on \code{draw.bg} to plot the background, so parameters proposed by this function are always handled:

\begin{Scode}{eval=false}
  help(draw.boxes)
  help(draw.points)
  help(draw.hist)
  help(draw.bg)
\end{Scode}

The scatter plot seems the most fitting for our dataset, let's give it a try. Parameters can be changed using the \code{setParam} method:

\begin{Scode}{fig=true, width=8, height=2}
  cgh$setParam("drawFun", "draw.points")
  cgh$draw(chrom="1", start=16125e3, end=16127e3)
\end{Scode}

The queried region seems empty, but a quick look at the track content can confirm it is not. Actually there are features in the region, but parameters that were set for \code{draw.boxes} don't really fit the new drawing function. Comparing the handled parameters (as described in \code{draw.points}) and the current values can help pinpoint the problem:

\begin{Scode}
  cgh$defaultParams()$ylim
\end{Scode}

"ylim", which controls the Y axis boundaries, does not fit the data we used here (the "value" column ranges from units to thousands). Let's redefine it to a more suitable value. While \code{setParam} was used previously to make the change permanent, we are here tuning without really knowing the optimal value, so temporary changes may be more practical. Parameters can be passed directly to the \code{draw} method to be forgotten after the call:

\begin{Scode}{fig=true, width=8, height=2}
  cgh$draw(chrom="1", start=16125e3, end=16127e3, ylim=c(0, 500))
\end{Scode}

When satisfied by the value, the change can be made permanent:

\begin{Scode}{fig=true, width=8, height=2}
  cgh$setParam("ylim", c(0, 500))
  cgh$draw(chrom="1", start=16125e3, end=16127e3)
\end{Scode}

While the Y axis is of better use like this, it still lacks an explicit legend. This parameter is handled by \code{draw.bg}, and to comply with R standards it is named "yaxt" (see the documentation of \code{par}, which describes many standard parameters that are also handled by drawing functions):

\begin{Scode}{fig=true, width=8, height=2}
  cgh$setParam("yaxt", "s")
  cgh$draw(chrom="1", start=16125e3, end=16127e3)
\end{Scode}

Once finalized, the track can be saved to a file for further use:

\begin{Scode}
  saveRDT(cgh, file="GSM589609.rdt")
\end{Scode}



\subsection{Annotation from TAIR}

To interpret this data, we now need some annotation. As for many species, biologists working on Arabidopsis thaliana have gathered into a community with a dedicated website, \href{http://www.arabidopsis.org/}{The Arabidopsis Information Resource} (TAIR). On such species-specific websites, you can generally browse the data directly and download it in various file formats.

\subsubsection{Note on assembly versions}

When browsing the web for annotation data, a critical point must be kept in mind: genome assemblies vary, so take care to always compare data from the same assembly. For Arabidopsis thaliana, releases are numbered as TAIR7, TAIR8, TAIR9 and so on by the TAIR cited above. As the platform annotation we have downloaded refers to TAIR9, we need to download TAIR9 compliant annotation. Notice the sequences of the probes are available, so remapping them using Next-Generation Sequencing aligners like \href{http://bowtie-bio.sourceforge.net/index.shtml}{bowtie}, \href{http://bio-bwa.sourceforge.net/}{bwa} or simply \href{http://genome.ucsc.edu/FAQ/FAQblat.html#blat3}{blat} can be considered, but it falls outside of this user case scope (consider the cghRA package to apply such methodology).

\subsubsection{Tab-separated genetic markers}

Let's begin with the genomic markers, which can be downloaded from the \href{ftp://ftp.arabidopsis.org/home/tair/Maps/mapviewer_data/TAIR9_AGI_marker.data}{TAIR FTP}. The ".data" extension seems very unfamiliar, so a first approach would be to open the file with a notepad, just as a first approach (or read the associated \href{ftp://ftp.arabidopsis.org/home/tair/Maps/mapviewer_data/README}{README} file if it exists, it usually does on FTP servers). It seems to be a tabulation-separated file, a good point as R can easily parse them, with the minimal information required: chromosome number, starting and ending positions.

\begin{Scode}
  tab <- read.table(
    file = "TAIR9_AGI_marker.data",
    sep = "\t",
    header = FALSE,
    stringsAsFactors = FALSE
  )
\end{Scode}

As previously, the data.frame can be turned into \code{track.table} without major difficulty. As no strand information is present but \code{track.table} requires it, we can use the \code{NA} value provided by R:

\begin{Scode}
  mrk <- track.table(
    name = tab$V2,
    chrom = tab$V5,
    start = tab$V3,
    end = tab$V4,
    strand = NA,
    .name = "Genetic markers",
    .organism = "Arabidopsis thaliana",
    .assembly = "TAIR9"
  )
\end{Scode}

As previously, the track can be customised, but its content fits well with the default \code{draw.boxes} behavior, so it is ready to be saved to a track file. We will only enforce chromosome levels as for CGH data for future compatibility:

\begin{Scode}{fig=true, width=8, height=1}
  mrk$setLevels("chrom", newLevels=c(1:5, "C", "M"))
  mrk$draw(chrom="1", start=16124e3, end=16130e3)
  saveRDT(mrk, file="GeneticMarkers.rdt")
\end{Scode}

\subsubsection{GFF3 exons}
\label{sec:tairExons}

In the TAIR FTP, another file seems to fit our needs: the \href{ftp://ftp.arabidopsis.org/home/tair/Maps/gbrowse_data/TAIR9/TAIR9_GFF3_genes.gff}{gene track}. It is particularly interesting for this user case as it introduces two specificities: the widely spread GFF format, and the drawing of exonic tracks.

While Rgb does not provide an explicit GFF3 parser, users familiar with such file formats should have noticed that GTF is an extension of GFF3, and thus the \code{read.gtf} and \code{track.table.GTF} functions from Rgb are able to parse such files.

GFF3 files can store highly hierarchized content, describing relationships between genes, transcripts, exons, CDS, UTR ... The data is stored in a tabulation-separated file, which is nice to handle with R, but its "attributes" column which allows row-specific data makes them hard to parse with \code{read.table}. Let's use Rgb's \code{read.gtf} function without subsetting to get an idea of the file complexity:

\begin{Scode}
  gtf <- read.gtf("TAIR9_GFF3_genes.gff")
  head(gtf)
  dim(gtf)
\end{Scode}

Records in such files are typed, according to the content of the "feature" column:

\begin{Scode}
  table(gtf$feature)
\end{Scode}

In this user case, we will focus on exons. While parsing the whole table is interesting to get an idea of the file, keep in mind that \code{read.gtf} and \code{track.table.GTF} can subset on features earlier to make parsing faster:

\begin{Scode}
  gtf <- read.gtf("TAIR9_GFF3_genes.gff", features="exon")
  trk <- track.table.GTF(
    file = "TAIR9_GFF3_genes.gff",
    name = "Exons",
    attr = "split",
    features = "exon",
    .organism = "Arabidopsis thaliana",
    .assembly = "TAIR9"
  )
  trk
\end{Scode}

As GTF enforces a few columns that are not used in this dataset, let's begin with freeing some wasted memory:

\begin{Scode}
  trk$delColumns(c("source","feature","score","frame"))
  trk
\end{Scode}

As previously, chromosomes have to be recoded to be consistent with other tracks:

\begin{Scode}
  trk$setLevels("chrom", c(1:5, "C", "M"))
\end{Scode}

While the track is now functional, it is pretty unsatisfying:

\begin{Scode}{fig=true, width=8, height=3}
  trk$draw(chrom="1", start=16150e3, end=16158e3)
\end{Scode}

Exons are usually drawn side-by-side and grouped by transcript to make the reading easier. The \code{draw.boxes} function can handle such representations, as long as a littke more information is precomputed and passed to the function as drawing parameters:

\begin{description}
  \item[groupBy] The name of the column that stores transcript names
  \item[groupPosition] The name of the column that stores exon number
  \item[groupSize] The name of the column that stores exon count
\end{description}

While "groupBy" can be directly set to "Parent", the two others need to be computed first. The \code{track.exons} class was designed to handle such datasets and provide convenient methods to build them, so let's begin with converting the generic \code{track.table} to the inheriting class \code{track.exons}. The second advantage to converting to \code{track.exons} is that it enforces several other drawing parameters that we no longer need to be concerned about, such as "maxElements" or "maxDepth".

\begin{Scode}
  exn <- new("track.exons")
  exn$import(trk)
  exn
\end{Scode}

Now the methods can be called, passing the grouping column:

\begin{Scode}
  exn$buildGroupSize("Parent", "exonCount")
  exn$buildGroupPosition("Parent", "exonNumber")
  exn
\end{Scode}

These new columns may be useful to define more informative row names:

\begin{Scode}
  newNames <- paste(exn$extract(,"Parent"), exn$extract(,"exonNumber"), sep="#")
  exn$fill(, "name", newNames)
\end{Scode}

Finally the three drawing parameters cited above have to be updated to reflect our naming convention:

\begin{Scode}{fig=true, width=8, height=2}
  exn$setParam("groupBy", "Parent")
  exn$setParam("groupPosition", "exonNumber")
  exn$setParam("groupSize", "exonCount")

  exn$draw(chrom="1", start=16150e3, end=16158e3)
  saveRDT(exn, file="TAIR9 exons.rdt")
\end{Scode}

\subsection{Integrated analysis}

\subsubsection{Visualization}

As for the previous user case, browsing the datasets conjointly is now straight-forward, and can be achieved interactively by using commands. While \code{tk.browse} offers interfaced solutions to select tracks, both methods can be initiated from the same drawable list:

\begin{Scode}{fig=true, width=8, height=8}
  dl <- drawable.list()
  dl$add(file="GeneticMarkers.rdt")
  dl$add(file="TAIR9 exons.rdt")
  dl$add(file="GSM589609.rdt")
  browsePlot(dl, chrom="1", start=16123e3, end=16158e3)
\end{Scode}

\begin{Scode}{eval=false}
  tk.browse(dl)
\end{Scode}

\subsubsection{Computation}

The gene expression data used here is mapped to the genome rather than individual genes, but Rgb can help solving this issue. As RNA was hybridized during this experiment, it is judicious to limit our analysis to probes located in exons of genes of interest. Given the size of the exon track (roughly 200 000 rows), using \code{refTable}-inherited methods rather than converting to \code{data.frame} is recommended to minimize computing time and memory consumption. Let's focus on the gene homing the most expressed probe as an example:

\begin{Scode}
  gsm <- readRDT("GSM589609.rdt")
  exn <- readRDT("TAIR9 exons.rdt")
  gen <- gsm$extract(expression(which.max(value)), asObject=TRUE)
  gen$cross(exn, type="Parent", colname="gene")
  gen
  exn$extract(expression(Parent == gen$extract(,"gene")))
\end{Scode}

While \code{extract}'s default behavior is to return \code{data.frame}, it may be more interesting in our case to profit from \code{track.table}-inherited methods. As an example, the \code{cross} method may prove valuable to count probes overlapping with the exons of interest:

\begin{Scode}
  atg <- exn$extract(expression(Parent == gen$extract(,"gene")), asObject=TRUE)
  atg$cross(gsm, type="count")
  atg$cross(gsm, type="count", colname="probeCount")
  atg
\end{Scode}

As can be seen in the previous example, \code{cross} can be used to perform temporary computation or to output its computation in a new column. All exons seem to be covered, and it would be interesting to compute the mean expression for each of them. While \code{cross} proposes diverse computations, more custom schemes need to be scripted, using the \code{slice} method \code{cross} relies on:

\begin{Scode}
  atg$addColumn(
    content = rep(as.double(NA), atg$getRowCount()),
    name = "expr"
  )
  for(i in 1:atg$getRowCount()) {
    probes <- gsm$slice(
      chrom = atg$extract(i, "chrom"),
      start = atg$extract(i, "start"),
      end = atg$extract(i, "end")
    )
    atg$fill(i, "expr", mean(probes$value))
  }
  atg
\end{Scode}

In the same spirit, expression by exon can easily be plotted using R functions:

\begin{Scode}{fig=true, width=8, height=6}
  expr <- list()
  for(i in 1:atg$getRowCount()) {
    probes <- gsm$slice(
      chrom = atg$extract(i, "chrom"),
      start = atg$extract(i, "start"),
      end = atg$extract(i, "end")
    )
    expr[[i]] <- probes$value
  }
  boxplot(expr, varwidth=TRUE, log="y")
\end{Scode}

It suggests an interesting splicing pattern: exons 1, 2, 3, 6 and 9 seem to be expressed roughly at the same levels, exons 4, 5 and 8 at a higher level and exon 7 to not be expressed (value nearing the background level).





\section{Extending Rgb capabilities}
\label{sec:extendingRgb}



\subsection{New representations of tabular content}
\label{sec:drawCustom}

Most genomic data is currently stored as a table of features, a format already handled by the \code{track.table} class. New data representations can thus be added to Rgb by expanding this class, and notably by developing new \strong{drawing functions}. In the current implementation, a \code{track.table} that needs to be drawn in a given genomic window is first "sliced", then the slice is passed as a data.frame to the drawing function named in the "drawFun" parameter. Defining a new drawing function that takes such a slice and the genomic coordinates as arguments is enough to allow Rgb to draw it, whether with the interactive genome browser or with the scripted interface.

\medskip

It is heavily recommended that drawing function developers take a look at existing ones' code before starting (\strong{draw.points}, \strong{draw.hist} and \strong{draw.boxes}). For \code{track.table} drawing functions, at least the "slice", "start", "end" and "..." arguments are mandatory, and the background of the plot should be drawn by a call to \code{draw.bg}.

\begin{Scode}{fig=true, width=8, height=1}
  # Really simple drawing function, just drawing lines
  draw.custom <- function(slice, start, end, ...) {
     draw.bg(start=start, end=end, ...)
  	segments(x0=slice$start, x1=slice$end, y0=0:1, y1=1:0)
  }
    
  # Edit a track to use it
  data(hsFeatures)
  hsBands$setParam("drawFun", "draw.custom")
  
  # Let's draw
  hsBands$draw("1", 0, 100e6)
\end{Scode}



\subsection{New drawing parameter defaults}

As the available drawing functions are quite generic, it can prove useful to define standard behaviors for certain data types, and avoid a long series of \code{setParam} calls at each track construction. To achieve this, it is strongly recommended to define classes inheriting from \code{track.table}, enforcing new drawing parameters defaults by overloading the \code{defaultParams} method. As default parameters are collated along the inheritance tree from the children to the mothers (see \ref{sec:drawable}), only new defaults are to be defined, superseding defaults defined in mother classes.

\medskip

Notice class definitions are not stored in .rdt files, so class defaults can be updated without updating all the objects created from it: just redefine a class with the same name before the call to \code{readRDT}. Unfortunately, this behavior is not retrieved with drawable objects exported with \code{saveRDS} and this format may be abandoned in the future.

\begin{Scode}{fig=true, width=8, height=1}
  # Define a new class, just drawing red boxes
  setRefClass(
    Class = "track.custom",
    contains = "track.bands",
    methods = list(
      defaultParams = function(...) {
        params <- callSuper(...)
        params$colorVal <- "red"
        params$colorFun <- function(slice) NULL
        return(params)
      }
    )
  )
  
  # Class switch
  data(hsFeatures)
  obj <- new("track.custom")
  obj$import(hsBands)
  
  # Let's draw
  obj$draw("1", 0, 100e6)
\end{Scode}





\subsection{New data storage}

The \code{track.table} class should fit most of your needs, but you may be confronted with data that cannot be stored efficiently as a single table of features. This is typically the case with external data sources like huge files or web services.

\medskip

A first example of such a need is illustrated in Rgb by the \strong{track.bam} class, designed lately to provide pileup representations of BAM files. As bioinformaticians may know, such files may be huge, and it is faster to query them directly via SAMtools in-situ than to preprocess their content to produce a tabular track. Such is designed \code{track.bam}, implementing a \code{slice} method relying on R binary file processing capabilities to generate pileups in the queried window on-the-fly. The pileup slice is then passed to a custom drawing function, \code{draw.pileup}, making use of the whole system described earlier. In most of the cases extending the \code{sliceable} or \code{crossable} classes is the simplest solution, only requiring you to define an inheriting class with a \code{slice} method and possibly some custom drawing functions (see Rgb source code for examples).

\medskip

One can also be interested in defining more atypical tracks, for which "slicing" is not pertinent. This can englobe tracks without embedded data such as scales, designed only to facilitate the reading. In such a case, the \code{drawable} class may be directly extended, providing a custom \code{draw} method. Such method should rely on the \code{callParams} method to handle drawing arguments in a consistent way, as \code{sliceable}'s \code{draw} method does. Consider also using the \code{draw.bg} function to plot a background consistent with other tracks:

\begin{Scode}{fig=true, width=8, height=1}
  setRefClass(
    Class = "track.scale",
    contains = "drawable",
    methods = list(
      defaultParams = function(...) {
        # Define new class defaults
        params <- callSuper(...)
        params$col <- "lightblue"
        params$points <- 500L
        return(params)
      },
      draw = function(chrom, start=NA, end=NA, ...) {
        # Aggregate and prioritize drawing parameters
        argList <- callParams(chrom, start, end, ...)
        
        # Plot background, using drawing parameters
        do.call(what=draw.bg, args=argList)
        
        # Data points
        x <- seq(from=start, to=end, length.out=argList$points)
        y <- cos(x)
        
        # Plot, using drawing parameters
        lines(x=x, y=y, col=argList$col)
      }
    )
  )
  object <- new("track.scale")
  object$draw("11", 0, 10e6)
  object$defaultParams()
\end{Scode}

In the simple example above, notice that \code{draw.bg} arguments seem not to be handled as drawing parameters. Actually they do, but it is up to you to make them returned by \code{defaultParams}, as this behavior is implemented in \code{sliceable}. This is quite optional, but keep in mind that only parameters detected by \code{defaultParams} are editable via the GUI interface.

\begin{Scode}{eval=false}
defaultParams = function(...) {
  # Get inherited defaults
  params <- callSuper(...)
  
  # Get draw.bg defaults
  form <- formals("draw.bg")
  form <- form[ setdiff(names(form), c("start", "end", "...")) ]
  for(fname in names(form)) params[[ fname ]] <- eval(form[[ fname ]])
  
  # Define new class defaults
  params$col <- "lightblue"
  params$points <- 500L
  
  return(params)
}
\end{Scode}

As a good habit and to ensure consistent behavior, consider overloading the following virtual methods of the \code{drawable} class: \code{draw}, \code{defaultParams}, \code{show}, \code{check}, \code{chromosomes} and \code{getChromEnd}. However as can be seen in the example above, only the \code{draw} one is mandatory as most of them are provided as stubs by \code{drawable}.

\medskip

To conclude with such custom classes, notice the \code{saveRDT} export function works only with \code{track.table} inheriting objects, so instanciated tracks need to be exported with \code{saveRDS}. This function is defined in R base and is supported by the Rgb interface.

\begin{Scode}{fig=true, width=8, height=1}
  saveRDS(object, "custom.rds")
  dl <- drawable.list(files="custom.rds")
  browsePlot(dl, chrom="1", start=10e6, end=100e6)
\end{Scode}





\end{document}
