%\VignetteIndexEntry{cimpl example session}
%\VignetteDepends{}
%\VignetteKeywords{retro-viral transpon insertional mutagenesis mulv mmtv sleeping beauty piggyBac common insertion site cis gaussian kernel convolution}
%\VignettePackage{cimpl}

\documentclass[a4paper]{article}

\title{CIMPL Vignette}
\author{Jelle ten Hoeve and Jeroen de Ridder}


\begin{document}

\maketitle

\section{Introduction}

In this Vignette we demonstrate the usage of the \texttt{cimpl} R package. CIMPL is the abbreviation for Common Insertion site Mapping PLatfrom. This package identifies common insertion sites (CISs) given insertional mutagenesis data collected across a cohort of tumors. The implementation is based on the Gaussian Kernel Convolution (GKC) framework developed by de Ridder {\it et al}. Originally, this method was developed for analysis of retroviral insertional mutagenesis data. However, we have extended the method to enable the analysis of transposon insertional mutagenesis as well. In cancer research, well known used retro-viruses are Mouse Mammary Tumor Virus (MMTV) and Murine Leukemia Virus (MuLV). Sleeping Beauty (SB) and piggyBac (PB) are examples of transposon-based systems. In this Vignette we walk through the steps for calculation and visualization of the results.

\section{Data}

First, we load an insertional mutagenesis dataset. The dataset has to be a \texttt{data.frame} containing mapped insertion locations. Columns named 'chr' (chromosome) and 'location' are mandatory. Not required (but useful) columns are 'sampleID' if you want to plot tumor densities (Section \ref{sec:kse}) and 'contig\_depth' if local hopping correction is needed. All other columns are not used. However, they will be reported in the results (Section \ref{sec:export}) and thus, it might be useful to include other columns for one's own further analysis.

In this package, we have included data of a transposon based screen in mice developing colorectal cancer \cite{Starr}. This data was harvested from 135 tumors containing 16690 non-redundant mapped insertions. As can be seen, some additional columns are included.

<<>>=
library(cimpl)
data(colorectal)
str(colorectal)
@

Next, we load the \texttt{BSgenome} on which the insertions are mapped. Make sure you use exactly the same genome version as used for the mapping! Package \texttt{BSgenome.Mmusculus.UCSC.mm9} provides a \texttt{Mmusculus} object (which we use later) and is based on the NCBI m37 mouse assembly, which is compatible with the colorectal data.
<<>>=
library(BSgenome.Mmusculus.UCSC.mm9)
@

We are now ready to apply the GKC framework.

\section{Analysis}
In this example we ran only 100 iterations, selected only Chromosome 18 and varied the scale for only three values. This to minimize computation time. Normally, we recommend 10000 iterations to obtain appropriate p-values. Select all chromosomes, unless, for example, the experimental design forces you to leave out chromosomes that contain the donor site. Regarding scales, [1k, 2.5k, 5k, 10k, 30k, 50k, 100k, 150k] is recommended for retroviral data and [10k, 20k, 30k, 40k, 50k, 60k, 70k, 80k, 90k, 100k, 110k, 120k, 130k, 140k, 150k] for transposon data. If you are not interested in comparing results from different scales, a single scale of 30k for retroviral data is reasonable \cite{deRidder}. For transposon data, no clear guideline exists yet. The following command executes the CIMPL analysis.

<<>>=
ca <- doCimplAnalysis(colorectal, scales = c(30e3, 50e3, 70e3), chromosomes = c('chr18'), n_iterations = 100, BSgenome = Mmusculus, system = 'SB', lhc.method='none')
@

The steps performed in \texttt{doCimplAnalysis} are explained below.

\subsection{Null distribution}

First, random data are generated by permuting the positions of the insertions in the dataset. For each chromosome and each scale, the insertions are randomly distributed across the genome. Although retro-viruses can integrate anywhere on the genome (not taking insertion biases into account), transposons are usually restricted to certain genomic sequences, called specificity patterns. For example, the SB transposon can only insert at TA sites. Therefore, such a restriction can be set using the \texttt{specificity.pattern} argument. When a restriction pattern is supplied, random insertion perturbations are only allowed on the site define by the specificity pattern. For convenience, you can set the \texttt{system} argument to MMTV, MuLV, SB or PB. The specificity pattern is then automatically set.

Secondly, on these random data GKC is performed and the peaks are detected. For each peak we save the peak height and the specificity pattern (or background) density. If no specificity pattern is used, the background distribution is uniform (\texttt{1/chr\_length}), else, the background distribution is computed using GKC on the locations of the specificity pattern. This process of randomly permuting the data, performing GKC, and calculating the peak heights and local specificity pattern density (if applicable) is repeated many times. When a specificity pattern is provided, an empirical distribution of peak height conditioned on specificity pattern density can be constructed (Figure \ref{fig:ecdf}). When no specificity pattern is provided, a single empirical distribution function of peak height is constructed. The conditional distribution function is used for the significance calculation of peaks found in the observed data. More specifically, it allows the computation of the probability that a peak observed in the real data exceeds a peak height observed in the $\alpha$\% of the random cases.

<<label=fig1plot, include=FALSE>>=
plot(ca, type='null.cdf', chr='chr18', scale=50e3)
@
\begin{figure}
\begin{center}
<<label=fig1, fig=TRUE, echo=FALSE>>=
<<fig1plot>>
@
\end{center}
\caption{The null-distribution of peaks in terms of peak height and specificity pattern density.}
\label{fig:ecdf}
\end{figure}

\subsection{Kernel smoothed estimate}
\label{sec:kse}

Finally, GKC is performed on the observed data, resulting in a kernel smoothed estimate (kse) of the insertion density. The result can be visualized with the plot command:

<<label=fig2plot, include=FALSE>>=
plot(ca, type='kse', chr='chr18', scale=50e3, bpLim=c(34e6, 35e6), interactive=FALSE)
@
\begin{figure}
\begin{center}
<<label=fig2, fig=TRUE, echo=FALSE>>=
<<fig2plot>>
@
\end{center}
\caption{The kse plot.}
\label{fig:kse}
\end{figure}

Figure \ref{fig:kse} gives details about Chromosome 18: 34Mb-35Mb for scale 50k, which contains a CIS. The CIS is the region where the kse (blue line) is above the significance threshold (red solid line) or above the significance threshold corrected for multiple testing (dotted red line).  Peaks are indicated with red circles. The vertical lines at the bottom indicate the insertions color-coded by the sample identifiers (`sampleID' column in the data).  

By default, the significance threshold is set to 5\% and Bonferroni multiple testing correction is applied. This can be modified using the \texttt{alpha} and \texttt{mul.test} arguments. If you set \texttt{interactive=TRUE}, one can interactively browse over the genome using the mouse.

Additionally, a `lava' plot can be constructed (Figure \ref{fig:lava}), where the colored bands (layers of lava) represent the contribution of each sample to the kse.

<<label=fig3plot, include=FALSE>>=
plot(ca, type='kse', chr='chr18', scale=70e3, bpLim=c(34e6, 35e6), plot.tumor.densities=TRUE, interactive=FALSE)
@
\begin{figure}
\begin{center}
<<label=fig3, fig=TRUE, echo=FALSE>>=
<<fig3plot>>
@
\end{center}
\caption{The `lava' plot.}
\label{fig:lava}
\end{figure}

\subsection{Scale space}

To inspect the scale space one can make a scale space plot with the following command:

<<label=fig4plot, include=FALSE>>=
plot(ca, type='scale.space', chr='chr18', bpLim=c(34e6, 35e6), interactive=FALSE)
@
\begin{figure}
\begin{center}
<<label=fig4, fig=TRUE, echo=FALSE>>=
<<fig4plot>>
@
\end{center}
\caption{The scale space plot.}
\label{fig:scale_space}
\end{figure}

The result is depicted is Figure \ref{fig:scale_space}. The green blocks represent significant regions, obtained by computing the region corresponding to a peak exceeding the significance threshold. In this case, the CIS becomes smaller as the scale decreases.

\section{Export}
\label{sec:export}


Several functions are included to export the results of a cimpl analysis. First, one can retrieve the CISs in a \texttt{data.frame} using the \texttt{getCISs} function. This function also associates genes to CISs by associating the closest gene to the CIS.

<<>>=
genes <- getEnsemblGenes(ca)
ciss <- getCISs(ca, scales=50e3, genes=genes)
ciss[1:3, ]
@

To inspect the full results of a genome-wide, multi-scale analysis, we have included the \texttt{export.html} function.
<<>>=
export.html(ca, genes=genes, dir='colorectal_chr18', verbose=FALSE)
@

Open \texttt{[CIMPL package dir]/doc/colorectal\_chr18/index.html} with your browser.

Additionally, export functions for BED and WIG files (\texttt{export.bed} and \texttt{export.wig}) are also available.

\begin{thebibliography}{}

\bibitem{deRidder}
De Ridder {\it et al}. Detecting statistically significant common insertion sites in retroviral insertional mutagenesis screens. {\it PLoS Comput Biol}, 2:e166, 2006.

\bibitem{Starr}   
Starr {\it et al}. A transposon-based genetic screen in mice identifies genes altered in colorectal cancer. {\it Science}. 2009 Mar 27;323(5922):1747-50. Epub 2009 Feb 26.
   
\end{thebibliography}

\section*{Session info}
<<>>=
sessionInfo()
@

\end{document}

\bibliography{cimpl}
\bibliographystyle{plainnat} 
\nocite{*}
