---
title: "Visualizing Large-scale Copy Number Variation in Single-Cell RNA-Seq Expression Data"
author: 
- name: Timothy Tickle
  affiliation: &kco Klarman Cell Observatory, Broad Institute of MIT and Harvard, Cambridge, MA, USA
- name: Itay Tirosh
  affiliation: 
    - *kco
    - Weizmann Institute of Science, Rehovot, Israel
- name: Christophe Georgescu
  affiliation: *kco
- name: Maxwell Brown
  affiliation: *kco
- name: Brian Haas
  affiliation: *kco
date: "`r Sys.Date()`"
output:
  BiocStyle::html_document: default
package: infercnv
abstract: >
  InferCNV is used to explore tumor single cell RNA-Seq data to identify evidence for large-scale chromosomal copy number variations, such as gains or deletions of entire chromosomes or large segments of chromosomes. This is done by exploring expression intensity of genes across positions of the genome in comparison to the average or a set of reference 'normal' cells. A heatmap is generated illustrating the relative expression intensities across each chromosome, and it becomes readily apparent as to which regions of the genome are over-abundant or less-abundant as compared to normal cells (or the average, if reference normal cells are not provided).
vignette: >
  %\VignetteIndexEntry{Visualizing Large-scale Copy Number Variation in Single-Cell RNA-Seq Expression Data}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
---


# Installation
## Required dependencies

_inferCNV_ uses the _R_ packages `r CRANpkg("ape")`, `r Biocpkg("BiocGenerics")`, `r CRANpkg("binhf")`, `r CRANpkg("caTools")`, `r CRANpkg("coda")`, `r CRANpkg("coin")`, `r CRANpkg("dplyr")`, `r CRANpkg("doparallel")`, `r Biocpkg("edgeR")`, `r CRANpkg("fastcluster")`, `r CRANpkg("fitdistrplus")`, `r CRANpkg("foreach")`, `r CRANpkg("futile.logger")`, `r CRANpkg("future")`, `r CRANpkg("gplots")`, `r CRANpkg("ggplot2")`, `r CRANpkg("HiddenMarkov")`, `r CRANpkg("reshape")`, `r CRANpkg("rjags")`, `r CRANpkg("RColorBrewer")`, `r Biocpkg("SingleCellExperiment")`, `r Biocpkg("SummarizedExperiment")` and imports functions from the archived `r CRANpkg("GMD")`.

<!--
[https://cran.r-project.org/web/packages/ape/index.html]
[https://bioconductor.org/packages/release/bioc/html/BiocGenerics.html]
[https://cran.r-project.org/web/packages/binhf/index.html]
[https://cran.r-project.org/web/packages/caTools/index.html]
[https://cran.r-project.org/web/packages/coda/index.html]
[https://cran.r-project.org/web/packages/coin/index.html]
[https://cran.r-project.org/web/packages/doParallel/index.html]
[https://cran.r-project.org/web/packages/dplyr/index.html]
[https://bioconductor.org/packages/release/bioc/html/edgeR.html]
[https://cran.r-project.org/web/packages/fastcluster/index.html]
[https://cran.r-project.org/web/packages/fitdistrplus/index.html]
[https://cran.r-project.org/web/packages/foreach/index.html]
[https://cran.r-project.org/web/packages/futile.logger/index.html]
[https://cran.r-project.org/web/packages/future/index.html]
[https://cran.r-project.org/web/packages/ggplot2/index.html]
[https://cran.r-project.org/web/packages/gplots/index.html]
[https://cran.r-project.org/web/packages/HiddenMarkov/index.html]
[https://cran.r-project.org/web/packages/reshape/index.html]
[https://cran.r-project.org/web/packages/rjags/index.html]
[https://cran.r-project.org/web/packages/RColorBrewer/index.html]
[https://cran.r-project.org/web/packages/Seurat/index.html]
[https://bioconductor.org/packages/release/bioc/html/SingleCellExperiment.html]
[https://bioconductor.org/packages/release/bioc/html/SummarizedExperiment.html]
[https://cran.r-project.org/src/contrib/Archive/GMD/]
-->


## Installing
```{r install, eval=FALSE}
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("infercnv")
```


## Optional extension
If you want to use the interactive heatmap visualization, please check the add-on packge _R_ `r Githubpkg ("broadinstitute/inferCNV_NGCHM")` after installing the packages `r CRANpkg("tibble")`, `r Githubpkg("bmbroom/tsvio")` and `r Githubpkg("bmbroom/NGCHMR")`. To install optional packages, type the following in an R command window:

<!--
[https://cran.r-project.org/web/packages/tibble/index.html]
[https://github.com/bmbroom/tsvio]
[https://github.com/bmbroom/NGCHMR]
-->

```{r install-optionals, eval = FALSE}
install.packages("tibble")

install.packages("devtools")
devtools::install_github("bmbroom/tsvio")
devtools::install_github("bmbroom/NGCHMR", ref="stable")
devtools::install_github("broadinstitute/inferCNV_NGCHM")

```

And download the NGCHM java application by typing the following in a regular shell:
```{bash, eval = FALSE}
wget http://tcga.ngchm.net/NGCHM/ShaidyMapGen.jar
```



```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
library(infercnv)

```

# Running InferCNV
## Create the InferCNV Object

Reading in the raw counts matrix and meta data, populating the infercnv object

```{r}
infercnv_obj = CreateInfercnvObject(
  raw_counts_matrix="../inst/extdata/oligodendroglioma_expression_downsampled.counts.matrix.gz",
  annotations_file="../inst/extdata/oligodendroglioma_annotations_downsampled.txt",
  delim="\t",
  gene_order_file="../inst/extdata/gencode_downsampled.EXAMPLE_ONLY_DONT_REUSE.txt",
  ref_group_names=c("Microglia/Macrophage","Oligodendrocytes (non-malignant)"))

```



## Running the full default analysis
```{r, results="hide"}
out_dir = tempfile()
infercnv_obj_default = infercnv::run(
    infercnv_obj,
    cutoff=1, # cutoff=1 works well for Smart-seq2, and cutoff=0.1 works well for 10x Genomics
    out_dir=out_dir,
    cluster_by_groups=TRUE, 
    plot_steps=FALSE,
    denoise=TRUE,
    HMM=FALSE,
    no_prelim_plot=TRUE,
    png_res=60
)

```

Basic ouput from running inferCNV.
```{r, echo=FALSE}
knitr::include_graphics(paste(out_dir, "infercnv.png", sep="/"))
```



# Additional Information
## Online Documentation

For additional explanations on files, usage, and a tutorial please visit the [wiki](https://github.com/broadinstitute/inferCNV/wiki).


## TrinityCTAT
This tool is a part of the TrinityCTAT toolkit focused on leveraging the use of RNA-Seq to better understand cancer transcriptomes. To find out more please visit [TrinityCTAT](https://github.com/NCIP/Trinity_CTAT/wiki)


## Applications

This methodology was used in:

[Anoop P. Patel et al. Single-cell RNA-seq highlights intratumoral heterogeneity in primary glioblastoma. Science. 2014 Jun 20: 1396-1401](http://www.ncbi.nlm.nih.gov/pmc/articles/PMC4123637/)

[Tirosh I et al.Dissecting the multicellular ecosystem of metastatic melanoma by single-cell RNA-seq. Science. 2016 Apr 8;352(6282):189-96](http://www.ncbi.nlm.nih.gov/pubmed/27124452)




# Session info

```{r sessioninfo, echo=FALSE, tidy=TRUE, tidy.opts=list(width.cutoff=60), out.width=60}
sessionInfo()
```