#LyX 2.0 created this file. For more info see http://www.lyx.org/
\lyxformat 413
\begin_document
\begin_header
\textclass article
\begin_preamble
%\VignetteIndexEntry{SomaticCancerAlterations package}
%\VignettePackage{SomaticCancerAlterations}

% To compile this document
% library('cacheSweave'); rm(list=ls()); Sweave('DESeq2.Rnw', driver=cacheSweaveDriver())

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

%\usepackage{Sweave}
\setkeys{Gin}{width=0.5\textwidth}

% use a vertical rule for R output instead of prompts for R input
%\usepackage{fancyvrb}
%\definecolor{darkgray}{gray}{0.2}
%\DefineVerbatimEnvironment{Sinput}{Verbatim}{xleftmargin=1em,formatcom={\color{darkgray}}}
%\DefineVerbatimEnvironment{Soutput}{Verbatim}{xleftmargin=1em,frame=leftline,framerule=.6pt,rulecolor=\color{darkgray},framesep=1em,formatcom={\color{darkgray}}}
%\fvset{listparameters={\setlength{\topsep}{0pt}}}
%\renewenvironment{Schunk}{\vspace{\topsep}}{\vspace{\topsep}}
\end_preamble
\use_default_options false
\begin_modules
sweave
\end_modules
\maintain_unincluded_children false
\language english
\language_package default
\inputencoding utf8
\fontencoding global
\font_roman default
\font_sans default
\font_typewriter default
\font_default_family default
\use_non_tex_fonts false
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100

\graphics default
\default_output_format default
\output_sync 0
\bibtex_command default
\index_command default
\paperfontsize default
\spacing single
\use_hyperref false
\pdf_bookmarks false
\pdf_bookmarksnumbered false
\pdf_bookmarksopen false
\pdf_bookmarksopenlevel 1
\pdf_breaklinks false
\pdf_pdfborder false
\pdf_colorlinks false
\pdf_backref false
\pdf_pdfusetitle false
\papersize a4paper
\use_geometry false
\use_amsmath 1
\use_esint 1
\use_mhchem 1
\use_mathdots 1
\cite_engine basic
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date false
\use_refstyle 0
\index Index
\shortcut idx
\color #008000
\end_index
\secnumdepth 3
\tocdepth 3
\paragraph_separation skip
\defskip smallskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\html_math_output 0
\html_css_as_file 0
\html_be_strict false
\end_header

\begin_body

\begin_layout Title
The 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
Biocpkg{SomaticCancerAlterations}
\end_layout

\end_inset

 package
\end_layout

\begin_layout Author
Julian Gehring, EMBL Heidelberg
\end_layout

\begin_layout Chunk
<<settings, echo=FALSE>>=
\end_layout

\begin_layout Chunk
set.seed(1)
\end_layout

\begin_layout Chunk
options(width=65)
\end_layout

\begin_layout Chunk
@
\end_layout

\begin_layout Section
Motivation
\end_layout

\begin_layout Standard
Over the last years, large efforts have been taken to characterize the somatic
 landscape of cancers.
 Many of the conducted studies make their results publicly available, providing
 a valuable resource for investigating beyond the level of individual cohorts.
 The 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
Biocpkg{SomaticCancerAlterations}
\end_layout

\end_inset

 package collects mutational data of several tumor types, currently focusing
 on the TCGA calls sets, and aims for a tight integration with 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
R{}
\end_layout

\end_inset

 and 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
Bioconductor{}
\end_layout

\end_inset

 workflows.
 In the following, we will illustrate how to access this data and give examples
 for use cases.
\end_layout

\begin_layout Chunk
<<load_package, echo=FALSE>>=
\end_layout

\begin_layout Chunk
library(SomaticCancerAlterations)
\end_layout

\begin_layout Chunk
library(GenomicRanges)
\end_layout

\begin_layout Chunk
library(ggbio)
\end_layout

\begin_layout Chunk
@
\end_layout

\begin_layout Section
Data Sets
\end_layout

\begin_layout Standard
The Cancer Genome Atlas (TCGA)
\begin_inset Foot
status open

\begin_layout Plain Layout
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://cancergenome.nih.gov
\end_layout

\end_inset


\end_layout

\end_inset

 is a consortium effort to analyze a variety of tumor types, including gene
 expression, methylation, copy number changes, and somatic mutations
\begin_inset Foot
status open

\begin_layout Plain Layout
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

https://wiki.nci.nih.gov/display/TCGA/TCGA+Home
\end_layout

\end_inset


\end_layout

\end_inset

.
 With the 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
Biocpkg{SomaticCancerAlterations}
\end_layout

\end_inset

 package, we provide the callsets of somatic mutations for all publically
 available TCGA studies.
 Over time, more studies will be added, as they become available and unrestriced
 in their usage.
\end_layout

\begin_layout Standard
To get started, we get a list of all available data sets and access the
 metadata associated with each study.
 
\end_layout

\begin_layout Chunk
<<list_datasets>>=
\end_layout

\begin_layout Chunk
all_datasets = scaListDatasets()
\end_layout

\begin_layout Chunk
print(all_datasets)
\end_layout

\begin_layout Chunk
meta_data = scaMetadata()
\end_layout

\begin_layout Chunk
print(meta_data)
\end_layout

\begin_layout Chunk
@
\end_layout

\begin_layout Standard
Next, we load a single dataset with the 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
Rfunction{sca
\backslash
_load
\backslash
_dataset}
\end_layout

\end_inset

 function.
\end_layout

\begin_layout Chunk
<<load_dataset>>=
\end_layout

\begin_layout Chunk
ov = scaLoadDatasets("ov_tcga", merge = TRUE)
\end_layout

\begin_layout Chunk
@
\end_layout

\begin_layout Section
Exploring Mutational Data
\end_layout

\begin_layout Standard
The somatic variants of each study are represented as a 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
Rclass{GRanges}
\end_layout

\end_inset

 object, ordered by genomic positions.
 Additional columns describe properties of the variant and relate it the
 the affected gene, sample, and patient.
\end_layout

\begin_layout Chunk
<<print>>=
\end_layout

\begin_layout Chunk
head(ov, 3)
\end_layout

\begin_layout Chunk
@
\end_layout

\begin_layout Chunk
<<summary>>=
\begin_inset Newline newline
\end_inset

with(mcols(ov), table(Variant_Classification, Variant_Type))
\end_layout

\begin_layout Chunk
@
\end_layout

\begin_layout Standard
With such data at hand, we can identify the samples and genes haboring the
 most mutations.
\end_layout

\begin_layout Chunk
<<tables>>=
\end_layout

\begin_layout Chunk
head(sort(table(ov$Sample_ID), decreasing = TRUE))
\end_layout

\begin_layout Chunk
head(sort(table(ov$Hugo_Symbol), decreasing = TRUE), 10)
\end_layout

\begin_layout Chunk
@
\end_layout

\begin_layout Section
Exploring Multiple Studies
\end_layout

\begin_layout Standard
Instead of focusing on an individual study, we can also import several at
 once.
 The results are stored as a 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
Rclass{GRangesList}
\end_layout

\end_inset

 in which each element corresponds to a single study.
 This can be merged into a single 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
Rclass{GRanges}
\end_layout

\end_inset

 object with 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
Rcode{merge = TRUE}
\end_layout

\end_inset

.
\end_layout

\begin_layout Chunk
<<multiple_studies>>=
\end_layout

\begin_layout Chunk
three_studies = scaLoadDatasets(all_datasets[1:3])
\end_layout

\begin_layout Chunk
print(elementNROWS(three_studies))
\end_layout

\begin_layout Chunk
class(three_studies)
\end_layout

\begin_layout Chunk
@
\end_layout

\begin_layout Chunk
<<merge_studies>>=
\end_layout

\begin_layout Chunk
merged_studies = scaLoadDatasets(all_datasets[1:3], merge = TRUE)
\end_layout

\begin_layout Chunk
class(merged_studies)
\end_layout

\begin_layout Chunk
@
\end_layout

\begin_layout Standard
We then compute the number of mutations per gene and study:
\end_layout

\begin_layout Chunk
<<mutated_genes_study>>=
\end_layout

\begin_layout Chunk
gene_study_count = with(mcols(merged_studies), table(Hugo_Symbol, Dataset))
\end_layout

\begin_layout Chunk
gene_study_count = gene_study_count[order(apply(gene_study_count, 1, sum),
 decreasing = TRUE), ]
\end_layout

\begin_layout Chunk
gene_study_count = addmargins(gene_study_count)
\end_layout

\begin_layout Chunk
head(gene_study_count)
\end_layout

\begin_layout Chunk
@
\end_layout

\begin_layout Standard
Further, we can subset the data by regions of interests, and compute descriptive
 statistics only on the subset.
\end_layout

\begin_layout Chunk
<<subset_studies>>=
\end_layout

\begin_layout Chunk
tp53_region = GRanges("17", IRanges(7571720, 7590863))
\end_layout

\begin_layout Chunk
tp53_studies = subsetByOverlaps(merged_studies, tp53_region)
\end_layout

\begin_layout Chunk
@
\end_layout

\begin_layout Standard
For example, we can investigate which type of somatic variants can be found
 in TP53 throughout the studies.
\end_layout

\begin_layout Chunk
<<variant_study_table>>=
\end_layout

\begin_layout Chunk
addmargins(table(tp53_studies$Variant_Classification, tp53_studies$Dataset))
\end_layout

\begin_layout Chunk
@
\end_layout

\begin_layout Standard
To go further, how many patients have mutations in TP53 for each cancer
 type?
\end_layout

\begin_layout Chunk
<<mutateted_genes>>=
\end_layout

\begin_layout Chunk
fraction_mutated_region = function(y, region) {
\end_layout

\begin_layout Chunk
	s = subsetByOverlaps(y, region)
\end_layout

\begin_layout Chunk
	m = length(unique(s$Patient_ID)) / metadata(s)$Number_Patients
\end_layout

\begin_layout Chunk
	return(m)
\end_layout

\begin_layout Chunk
}
\end_layout

\begin_layout Chunk
mutated_fraction = sapply(three_studies, fraction_mutated_region, tp53_region)
\end_layout

\begin_layout Chunk
mutated_fraction = data.frame(name = names(three_studies), fraction = mutated_fra
ction)
\end_layout

\begin_layout Chunk
@
\end_layout

\begin_layout Chunk
<<plot_mutated_genes, fig=TRUE, echo=TRUE, include=FALSE>>=
\end_layout

\begin_layout Chunk
library(ggplot2)
\end_layout

\begin_layout Chunk
p = ggplot(mutated_fraction) + ggplot2::geom_bar(aes(x = name, y = fraction,
 fill = name), stat = "identity") + ylim(0, 1) + xlab("Study") + ylab("Ratio")
 + theme_bw()
\end_layout

\begin_layout Chunk
print(p)
\end_layout

\begin_layout Chunk
@
\end_layout

\begin_layout Standard
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
incfig{SomaticCancerAlterations-plot_mutated_genes}{0.75
\backslash
textwidth}{Summary for TP53}{The fraction of patients with somatic mutations
 in TP53, for each study individually.}
\end_layout

\end_inset


\end_layout

\begin_layout Section
Data Provenance
\end_layout

\begin_layout Subsection
TCGA Data
\end_layout

\begin_layout Standard
When importing the mutation data from the TCGA servers, we checked the data
 for consistency and fix common ambiguities in the annotation.
\end_layout

\begin_layout Subsubsection
Processing
\end_layout

\begin_layout Enumerate
Selection of the most recent somatic variant calls for each study.
 These were stored as '*.maf' files in the TCGA data directory
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

https://tcga-data.nci.nih.gov/tcgafiles/ftp_auth/distro_ftpusers/anonymous/tumor/
\end_layout

\end_inset


\end_layout

\end_inset

.
 If both manually curated and automatically generated variant calls were
 available, the curated version was chosen.
\end_layout

\begin_layout Enumerate
Importing of the '*.maf' files into R and checking for consistency with the
 TCGA MAF specifications
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
\begin_inset Flex URL
status open

\begin_layout Plain Layout

https://wiki.nci.nih.gov/display/TCGA/Mutation+Annotation+Format+(MAF)+Specificatio
n
\end_layout

\end_inset


\end_layout

\end_inset

.
 Please note that these guidelines are currently only suggestions and most
 TCGA files violate some of these.
\end_layout

\begin_layout Enumerate
Transformation of the imported variants into a 'GRanges' object, with one
 row for each reported variant.
 Only columns related to the genomic origin of the somatic variant were
 stored, additional columns describing higher-level effects, such as mutational
 consequences and alterations at the protein level, were dropped.
 The 
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
Robject{seqlevels}
\end_layout

\end_inset

 information defining the chromosomal ranges were taken from the 1000genomes
 phase 2 reference assembly
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

ftp://ftp.1000genomes.ebi.ac.uk/vol1/ftp/technical/reference/phase2_reference_assemb
ly_sequence/
\end_layout

\end_inset


\end_layout

\end_inset

.
\end_layout

\begin_layout Enumerate
The patient barcode was extracted from the sample barcode.
\end_layout

\begin_layout Enumerate
Metadata describing the design and analysis of the study was extracted.
\end_layout

\begin_layout Enumerate
The processed variants were written to disk, with one file for each study.
 The metadata for all studies were stored as a single, separate object.
\end_layout

\begin_layout Subsubsection
Selection Criteria of Data Sets
\end_layout

\begin_layout Standard
We included data sets in the package that were
\end_layout

\begin_layout Itemize
conducted by the Broad Institute.
\end_layout

\begin_layout Itemize
cleared for unrestricted access and usage
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://cancergenome.nih.gov/abouttcga/policies/publicationguidelines
\end_layout

\end_inset


\end_layout

\end_inset

.
\end_layout

\begin_layout Itemize
sequenced with Illumina platforms.
\end_layout

\begin_layout Subsubsection
Consistency Check
\end_layout

\begin_layout Standard
According to the TCGA specifications for the 'MAF' files, we screened and
 corrected for common artifacts in the data regarding annotation.
 This included:
\end_layout

\begin_layout Itemize
Transfering of all genomic coordinates to the NCBI 37 reference notation
 (with the chromosome always depicted as 'MT')
\end_layout

\begin_layout Itemize
Checking of the entries against all allowed values for this field (currently
 for the columns 
\emph on
Hugo_Symbol
\emph default
, 
\emph on
Chromosome
\emph default
, 
\emph on
Strand
\emph default
, 
\emph on
Variant_Classification
\emph default
, 
\emph on
Variant_Type
\emph default
, 
\emph on
Reference_Allele
\emph default
, 
\emph on
Tumor_Seq_Allele1
\emph default
, 
\emph on
Tumor_Seq_Allele2
\emph default
, 
\emph on
Verification_Status
\emph default
, 
\emph on
Validation_Status
\emph default
, 
\emph on
Sequencer
\emph default
).
\end_layout

\begin_layout Section
Alternatives
\end_layout

\begin_layout Standard
The TCGA data sets can be accessed in different ways.
 First, the 
\emph on
TCGA
\emph default
 itself offers access to certain types of its collected data
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

https://tcga-data.nci.nih.gov/tcga/tcgaDownload.jsp
\end_layout

\end_inset


\end_layout

\end_inset

.
 Another approach has been taken by the 
\emph on
cBioPortal for Cancer Genomics
\emph default

\begin_inset Foot
status collapsed

\begin_layout Plain Layout
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://www.cbioportal.org/public-portal/
\end_layout

\end_inset


\end_layout

\end_inset

 which has performed high-level analyses of several TCGA data sources, such
 as gene expression and copy number changes.
 This summarized data can be queried through an R interface
\begin_inset Foot
status collapsed

\begin_layout Plain Layout
\begin_inset Flex URL
status collapsed

\begin_layout Plain Layout

http://www.cbioportal.org/public-portal/cgds_r.jsp
\end_layout

\end_inset


\end_layout

\end_inset

.
\end_layout

\begin_layout Standard
\begin_inset Newpage newpage
\end_inset


\end_layout

\begin_layout Section*
Session info
\end_layout

\begin_layout Chunk
<<sessionInfo, results=tex, echo=FALSE>>=
\end_layout

\begin_layout Chunk
toLatex(sessionInfo(), locale=FALSE)
\end_layout

\begin_layout Chunk
@
\end_layout

\end_body
\end_document
