#+TITLE: SomaticCancerAlterations
#+AUTHOR: Julian Gehring, EMBL Heidelberg

#+LATEX_CLASS: biocKnitrRnw
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.ebi.ac.uk/~jgehring/css/worg.css" />
#+INFOJS_OPT: view:showall toc:t ftoc:t

#+MACRO: M @@latex:\$1{@@$2@@latex:}@@
#+MACRO: R @@latex:\R{}@@
#+MACRO: Bioconductor @@latex:\Bioconductor{}@@


#+COMMENT: This is only present within latex
#+BEGIN_LaTeX
%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{SomaticCancerAlterations - PDF}
%\VignettePackage{SomaticCancerAlterations}
#+END_LaTeX

#+COMMENT: This is only present within html
#+BEGIN_HTML
<!--
%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{SomaticCancerAlterations - HTML}
%\VignettePackage{SomaticCancerAlterations}
-->
#+END_HTML

#+BEGIN_SRC R :ravel echo=FALSE :exports none
set.seed(1)
options(width=65)
opts_knit$set(progress = FALSE, background = "#FFFFFF")
#+END_SRC


* Motivation

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 {{{M(Biocpkg,SomaticCancerAlterations)}}} package collects
mutational data of several tumor types, currently focusing on the TCGA calls
sets, and aims for a tight integration with {{{R}}} and {{{Bioconductor}}}
workflows. In the following, we will illustrate how to access this data and give
examples for use cases.


#+BEGIN_SRC R :ravel echo=FALSE :exports code
  library(SomaticCancerAlterations)
  library(GenomicRanges)
  library(ggbio)
#+END_SRC


* Data Sets

The Cancer Genome Atlas (TCGA)[fn::http://cancergenome.nih.gov] is a consortium effort
to analyze a variety of tumor types, including gene expression, methylation,
copy number changes, and somatic
mutations[fn::https://wiki.nci.nih.gov/display/TCGA/TCGA+Home]. With the
{{{M(Biocpkg,SomaticCancerAlterations)}}} 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.

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

#+NAME: list_datasets
#+BEGIN_SRC R
  all_datasets = scaListDatasets()
  print(all_datasets)
  meta_data = scaMetadata()
  print(meta_data)
#+END_SRC

Next, we load a single dataset with the {{{M(Rfunction,scaLoadDataset)}}} function.

#+NAME: load_dataset
#+BEGIN_SRC R
  ov = scaLoadDatasets("ov_tcga", merge = TRUE)
#+END_SRC


* Exploring Mutational Data

The somatic variants of each study are represented as a {{{Rclass(GRanges)}}} object,
ordered by genomic positions. Additional columns describe properties of the
variant and relate it the the affected gene, sample, and patient.

#+NAME: print
#+BEGIN_SRC R
  head(ov, 3)
#+END_SRC

#+NAME: summary
#+BEGIN_SRC R
  with(mcols(ov), table(Variant_Classification, Variant_Type))
#+END_SRC

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

#+BEGIN_SRC R
  head(sort(table(ov$Sample_ID), decreasing = TRUE))
  head(sort(table(ov$Hugo_Symbol), decreasing = TRUE), 10)
#+END_SRC


* Exploring Multiple Studies

Instead of focusing on an individual study, we can also import several at
once. The results are stored as a {{{M(Rclass,GRangesList)}}} in which each
element corresponds to a single study. This can be merged into a single {{{M(Rclass,GRanges)}}}
object with =merge = TRUE=.

#+NAME: multiple_studies
#+BEGIN_SRC R
  three_studies = scaLoadDatasets(all_datasets[1:3])
  
  print(elementNROWS(three_studies))
  
  class(three_studies)
#+END_SRC

#+NAME: merge_studies
#+BEGIN_SRC R
  merged_studies = scaLoadDatasets(all_datasets[1:3], merge = TRUE)
  
  class(merged_studies)
#+END_SRC

We then compute the number of mutations per gene and study:

#+NAME: mutated_genes_study
#+BEGIN_SRC R
  gene_study_count = with(mcols(merged_studies), table(Hugo_Symbol, Dataset))
  
  gene_study_count = gene_study_count[order(apply(gene_study_count, 1, sum), decreasing = TRUE), ]
  
  gene_study_count = addmargins(gene_study_count)
  
  head(gene_study_count)
#+END_SRC

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

#+NAME: subset_studies
#+BEGIN_SRC R 
  tp53_region = GRanges("17", IRanges(7571720, 7590863))
  
  tp53_studies = subsetByOverlaps(merged_studies, tp53_region)
#+END_SRC

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

#+NAME: variant_study_table
#+BEGIN_SRC R
  addmargins(table(tp53_studies$Variant_Classification, tp53_studies$Dataset))
#+END_SRC

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

#+NAME: mutateted_genes
#+BEGIN_SRC R
  fraction_mutated_region = function(y, region) {
      s = subsetByOverlaps(y, region)
      m = length(unique(s$Patient_ID)) / metadata(s)$Number_Patients
      return(m)
  }
  
  mutated_fraction = sapply(three_studies, fraction_mutated_region, tp53_region)
  
  mutated_fraction = data.frame(name = names(three_studies), fraction =
  mutated_fraction)
#+END_SRC


#+NAME: plot_mutated_genes
#+BEGIN_SRC R
  library(ggplot2)
  
  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()
  
  print(p)
#+END_SRC


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


* Data Provenance

** TCGA Data

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

*** Processing

1. Selection of the most recent somatic variant calls for each study. These were
   stored as =*.maf= files in the TCGA data
   directory[fn::https://tcga-data.nci.nih.gov/tcgafiles/ftp_auth/distro_ftpusers/anonymous/tumor/]. If
   both manually curated and automatically generated variant calls were
   available, the curated version was chosen.

2. Importing of the =*.maf= files into {{{R}}} and checking for consistency with the
   TCGA MAF
   specifications[fn::https://wiki.nci.nih.gov/display/TCGA/Mutation+Annotation+Format+(MAF)+Specification]. Please
   note that these guidelines are currently only suggestions and most TCGA files
   violate some of these.

3. Transformation of the imported variants into a {{{M(Robject,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 {{{M(Robject,seqlevels)}}} information defining the
   chromosomal ranges were taken from the 1000genomes phase 2 reference assembly[fn::ftp://ftp.1000genomes.ebi.ac.uk/vol1/ftp/technical/reference/phase2_reference_assembly_sequence/].

4. The patient barcode was extracted from the sample barcode.

5. Metadata describing the design and analysis of the study was extracted.

6. 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.


*** Selection Criteria of Data Sets

We included data sets in the package that were

- conducted by the Broad Institute.

- cleared for unrestricted access and usage[fn::http://cancergenome.nih.gov/abouttcga/policies/publicationguidelines].

- sequenced with Illumina platforms.


*** Consistency Check

According to the TCGA specifications for the =MAF= files, we screened and
corrected for common artifacts in the data regarding annotation. This included:

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

- Checking of the entries against all allowed values for this field (currently
  for the columns =Hugo_Symbol=, =Chromosome=, =Strand=, =Variant_Classification=,
  =Variant_Type=, =Reference_Allele=, =Tumor_Seq_Allele1=, =Tumor_Seq_Allele2=,
  =Verification_Status=, =Validation_Status=, =Sequencer=).


* Alternatives

The TCGA data sets can be accessed in different ways. First, the TCGA itself
offers access to certain types of its collected
data[fn::https://tcga-data.nci.nih.gov/tcga/tcgaDownload.jsp]. Another approach
has been taken by the cBioPortal for Cancer
Genomics[fn::http://www.cbioportal.org/public-portal] 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[fn::http://www.cbioportal.org/public-portal/cgds_r.jsp].


* Session Info

#+BEGIN_SRC R :ravel echo=FALSE
  sessionInfo()
#+END_SRC
