%\VignetteIndexEntry{Introduction to QDNAseq} \documentclass{article} <>= BiocStyle::latex() @ \begin{document} \title{Introduction to QDNAseq} \author{Ilari Scheinin} \maketitle \tableofcontents \section{Running QDNAseq} This is a short tutorial on how to use the \Biocpkg{QDNAseq} package. It covers an example run using the included data set of chromosomes 7--10 of a low grade glioma (LGG) sample. First step is naturally to load the package. <<>>= library(QDNAseq) @ <>= ## Send verbose output to stdout instead of stderr options("QDNAseq::verbose"=NA) options(width=40) @ \subsection{Bin annotations} Then we need to obtain bin annotations. These are available pre-calculated for genome build hg19 and bin sizes 1, 5, 10, 15, 30, 50, 100, 500, and 1000 kbp. They are available in the \Biocpkg{QDNAseq.hg19} package, which has to be installed from Bioconductor separately. With that package installed, the bin annotations can be acquired as: \begin{Schunk} \begin{Sinput} > bins <- getBinAnnotations(binSize=15) Loaded bin annotations for genome 'hg19', bin size 15 kbp, and experiment type 'SR50' from annotation package QDNAseq.hg19 v1.14.0 > bins QDNAseq bin annotations for Hsapiens, build hg19. Created by Ilari Scheinin with QDNAseq 0.7.5, 2014-02-06 12:48:04. An object of class 'AnnotatedDataFrame' rowNames: 1:1-15000 1:15001-30000 ... Y:59370001-59373566 (206391 total) varLabels: chromosome start ... use (9 total) varMetadata: labelDescription \end{Sinput} \end{Schunk} If you are working with another genome build (or another species), see the section on generating the bin annotations. \subsection{Processing BAM files} Next step is to load the sequencing data from BAM files. This can be done for example with one of the commands below. <>= readCounts <- binReadCounts(bins) # all files ending in .bam from the current working directory # or readCounts <- binReadCounts(bins, bamfiles="tumor.bam") # file 'tumor.bam' from the current working directory # or readCounts <- binReadCounts(bins, path="tumors") # all files ending in .bam from the subdirectory 'tumors' @ This will return an object of class \Rclass{QDNAseqReadCounts}. If the same BAM files will be used as input in future \R{} sessions, option \Rcode{cache=TRUE} can be used to cache intermediate files, which will speed up future analyses. Caching is done with package \CRANpkg{R.cache}. For large BAM files it is advisable to use the \Rcode{chunkSize} parameter to control memory usage. A non-\Rcode{NULL}, non-numeric value will use the length of the longest chromosome, effectively chunking by chromosome. A numeric value will use that many reads at a time. Note that total peak memory usage is controlled both by the chunk size and the number of parallel workers. See \autoref{sec:parallel}. For the purpose of this tutorial, we load an example data set of chromosomes 7--10 of low grade glioma sample LGG150. <<>>= data(LGG150) readCounts <- LGG150 readCounts @ Plot a raw copy number profile (read counts across the genome), and highlight bins that will be removed with default filtering (Figure~\ref{fig:rawprofile}). <>= png("rawprofile.png") @ <>= plot(readCounts, logTransform=FALSE, ylim=c(-50, 200)) highlightFilters(readCounts, logTransform=FALSE, residual=TRUE, blacklist=TRUE) @ <>= dev.off() @ \begin{figure}[h] \centering \caption{Read counts per bins. Highlighted with red are bins that will be filtered out.} \label{fig:rawprofile} \includegraphics{rawprofile} \end{figure} Apply filters and plot median read counts as a function of GC content and mappability (Figure~\ref{fig:isobar}). As the example data set only contains a subset of the chromosomes, the distribution looks slightly less smooth than expected for the entire genome. <<>>= readCountsFiltered <- applyFilters(readCounts, residual=TRUE, blacklist=TRUE) @ <>= png("isobar.png") @ <>= isobarPlot(readCountsFiltered) @ <>= dev.off() @ \begin{figure}[h] \centering \caption{Median read counts per bin shown as a function of GC content and mappability.} \label{fig:isobar} \includegraphics{isobar} \end{figure} Estimate the correction for GC content and mappability, and make a plot for the relationship between the observed standard deviation in the data and its read depth (Figure~\ref{fig:noise}). The theoretical expectation is a linear relationship, which is shown in the plot with a black line. Samples with low-quality DNA will be noisier than expected and appear further above the line than good-quality samples. <<>>= readCountsFiltered <- estimateCorrection(readCountsFiltered) @ <>= png("noise.png") @ <>= noisePlot(readCountsFiltered) @ <>= dev.off() @ \begin{figure}[h] \centering \caption{The relationship between sequence depth and noise.} \label{fig:noise} \includegraphics{noise} \end{figure} Next, we apply the correction for GC content and mappability. This will return a \Rclass{QDNAseqCopyNumbers} object, which we then normalize, smooth outliers, and plot the copy number profile (Figure~\ref{fig:profile}). <<>>= copyNumbers <- correctBins(readCountsFiltered) copyNumbers copyNumbersNormalized <- normalizeBins(copyNumbers) copyNumbersSmooth <- smoothOutlierBins(copyNumbersNormalized) @ <>= png("profile.png") @ <>= plot(copyNumbersSmooth) @ <>= dev.off() @ \begin{figure}[h] \centering \caption{Copy number profile after correcting for GC content and mappability.} \label{fig:profile} \includegraphics{profile} \end{figure} Data is now ready to be analyzed with a downstream package of choice. For analysis with an external program or for visualizations in \software{IGV}, the data can be exported to a file. <>= exportBins(copyNumbersSmooth, file="LGG150.txt") exportBins(copyNumbersSmooth, file="LGG150.igv", format="igv") exportBins(copyNumbersSmooth, file="LGG150.bed", format="bed") @ \subsection{Downstream analyses} Segmentation with the \software{CBS} algorithm from \Biocpkg{DNAcopy}, and calling copy number aberrations with \Biocpkg{CGHcall} or cutoffs have been implemented for convenience. By default, segmentation uses a $\log_2$-transformation, but a sqrt(x + 3/8) can also be used as it stabilizes the variance of a Poisson distribution (Anscombe transform): <<>>= copyNumbersSegmented <- segmentBins(copyNumbersSmooth, transformFun="sqrt") copyNumbersSegmented <- normalizeSegmentedBins(copyNumbersSegmented) @ <>= png("segments.png") @ <>= plot(copyNumbersSegmented) @ <>= dev.off() @ \begin{figure}[h] \centering \caption{Copy number profile after segmenting.} \label{fig:segments} \includegraphics{segments} \end{figure} Tune segmentation parameters and iterate until satisfied. Next, call aberrations, and plot the final results. <<>>= copyNumbersCalled <- callBins(copyNumbersSegmented) @ <>= png("calls.png") @ <>= plot(copyNumbersCalled) @ <>= dev.off() @ \begin{figure}[h] \centering \caption{Copy number profile after calling gains and losses.} \label{fig:calls} \includegraphics{calls} \end{figure} Called data can be exported as VCF file or SEG for further downstream analysis. <>= exportBins(copyNumbersCalled, format="vcf") exportBins(copyNumbersCalled, format="seg") @ It should be noted that \Biocpkg{CGHcall} (which \Rfunction{callBins()} uses by default) was developed for the analysis of sets of cancer samples. It is based on a mixture model, and when there are not enough aberrations present in the data, model fitting can fail. This can happen especially with non-cancer samples, and/or when analyzing individual cases instead of larger data sets. If \Biocpkg{CGHcall} fails, \Rfunction{callBins()} can also perform simple cutoff-based calling by setting parameter \Rcode{method="cutoff"}. The default cutoff values are based on the assumption of uniform cell populations, and in case of cancer samples will most likely need calibration by adjusting parameter \Rcode{cutoffs}. Finally, for other downstream analyses, such as running \Biocpkg{CGHregions}, it might be useful to convert to a \Rclass{cghCall} object. <<>>= cgh <- makeCgh(copyNumbersCalled) cgh @ This command can also be used to generate \Rclass{cghRaw} or \Rclass{cghSeg} objects by running it before segmentation or calling. % caching % 661 BAM files = 445G % cache/reads = 13G % cache/readCounts/15kbp = 139M % cache/readCounts/30kbp = 82M % cache/readCounts/100kbp = 32M % cache/readCounts/1000kbp = 5.2M \clearpage \section{Parallel computation} \label{sec:parallel} \Biocpkg{QDNAseq} supports parallel computing via the \CRANpkg{future} package. All that is required is to select an appropriate \textit{plan}. The instructions below apply to all of \Biocpkg{QDNAseq}'s own functions that support parallel processing. At the moment these include \Rfunction{estimateCorrection()}, \Rfunction{segmentBins()}, \Rfunction{createBins()}, and \Rfunction{calculateBlacklist()}. \Rfunction{binReadCounts()} parallelizes by chromosome when \Rcode{chunkSize} is used. However, when argument \Rcode{method="CGHcall"} (which is the default), function \Rfunction{callBins()} calls function \Rfunction{CGHcall()} from package \Biocpkg{CGHcall}, which uses another mechanism for parallel computation. For that, the number of processes to use should be specified with argument \Rcode{ncpus}, with something along the lines of: <>= copyNumbers <- callBins(..., ncpus=4) @ \subsection{Non-parallel processing} The default is to use single-core processing via ``sequential'' futures. This can be set explicitly with: <>= future::plan("sequential") @ \subsection{Parallel processing on the current machine} To process data in parallel using multiple processes on the current machine, use the following: <>= future::plan("multiprocess") @ After that, all functions that support parallel processing will automatically use it. The \Rpackage{future} framework attempts to play nice with the current compute environment. It will automatically respect environment variables and \R{} options that are used to limit the number of parallel works. It will also respect environment variables such as number of cores assigned to job scripts in high-performance compute (HPC) clusters. If no such restrictions are set, the default is to use all cores available. To explicitly set, and override other settings, the number of parallel workers, use argument \textit{workers}, e.g. <>= future::plan("multiprocess", workers=4) @ For more details, see the \Rpackage{future} documentation. \subsection{Parallel processing on an ad-hoc cluster} To process data using multiple \R{} sessions running on different machines, use something along the lines of: <>= cl <- future::makeClusterPSOCK(...) future::plan("cluster", cluster=cl) @ See package \Rpackage{future} for more details. \clearpage \section{Sex chromosomes} By default, \Biocpkg{QDNAseq} ignores sex chromosomes. In order to include them in the analysis, function \Rfunction{applyFilters()} should be run with argument \Rcode{chromosomes=NA} to include both X and Y, or \Rcode{chromosomes="Y"} to include X only. However, this will also affect which chromosomes are used when calculating the LOESS correction with \Rfunction{estimateCorrection()}. Unless the data set consists of only females, this could be undesirable. The solution is to first filter out the sex chromosomes, run \Rfunction{estimateCorrection()}, and then reverse the filtering of sex chromosomes: <>= readCounts <- binReadCounts(getBinAnnotations(15)) readCounts <- applyFilters(readCounts) readCounts <- estimateCorrection(readCounts) readCounts <- applyFilters(readCounts, chromosomes=NA) copyNumbers <- correctBins(readCounts) @ Running \Rfunction{estimateCorrection()} and \Rfunction{correctBins()} with a different set of bins can have one side effect. This is caused by the fact that there can be bins in the sex chromosomes with a combination of GC content and mappability that is not found anywhere else in the genome. This will cause those bins to miss a correction estimate altogether, and these bins will be filtered out from subsequent steps by \Rfunction{correctBins()}. If this happens, it will print out a message specifying the number of bins affected. Another possible approach is to allow extrapolation while calculating the LOESS correction. But please do note that the effect of extrapolation has not been properly evaluated. <>= readCounts <- estimateCorrection(readCounts, control=loess.control(surface="direct")) @ \clearpage \section{Generating bin annotations} This section describes how bin annotations have been created for the hg19 build of the human reference genome, and can be applied for other genome builds and species. The first step is to create the bins based on chromosome sizes, and calculate their GC content and proportion of characterized nucleotides (non-N bases in the reference sequence). For this, the corresponding \Biocpkg{BSgenome} package is needed. <>= # load required packages for human reference genome build hg19 library(QDNAseq) library(Biobase) library(BSgenome.Hsapiens.UCSC.hg19) # set the bin size binSize <- 15 # create bins from the reference genome bins <- createBins(bsgenome=BSgenome.Hsapiens.UCSC.hg19, binSize=binSize) @ The result is a \Rclass{data.frame} with columns \Robject{chromosome}, \Robject{start}, \Robject{end}, \Robject{gc}, and \Robject{bases}. Next step is to calculate the average mappabilities, which requires a mappability file in the \Rcode{bigWig} format and the \software{bigWigAverageOverBed} binary. The mappability file can be generated with \software{GEnomic Multi-Tool (GEM) Mapper} part of the \software{\href{https://sourceforge.net/projects/gemlibrary/}{GEM library}} from the reference genome sequence. Or it might be available directly, as was the case for hg19, and file \file{wgEncodeCrgMapabilityAlign50mer.bigWig} downloaded from \href{https://genome.ucsc.edu/cgi-bin/hgFileUi?db=hg19&g=wgEncodeMapability} {ENCODE's download section of the UCSC Genome Browser}. The \software{bigWigAverageOverBed} binary can also be downloaded from \href{https://hgdownload.soe.ucsc.edu/admin/exe/}{UCSC Genome Browser's Other utilities section}. <>= # calculate mappabilites per bin from ENCODE mapability tracks bins$mappability <- calculateMappability(bins, bigWigFile="/path/to/wgEncodeCrgMapabilityAlign50mer.bigWig", bigWigAverageOverBed="/path/to/bigWigAverageOverBed") @ If there are genomic regions that should excluded from analyses, such as ENCODE's Blacklisted Regions, the percentage overlap between the generated bins and these regions can be calculated as follows. The regions to be excluded need to be in the \Rcode{BED} format, like files \file{wgEncodeDacMapabilityConsensusExcludable.bed} and \file{wgEncodeDukeMapabilityRegionsExcludable.bed} that were downloaded from \href{https://genome.ucsc.edu/cgi-bin/hgFileUi?db=hg19&g=wgEncodeMapability}{ ENCODE's download section of the UCSC Genome Browser} for hg19. <>= # calculate overlap with ENCODE blacklisted regions bins$blacklist <- calculateBlacklist(bins, bedFiles=c("/path/to/wgEncodeDacMapabilityConsensusExcludable.bed", "/path/to/wgEncodeDukeMapabilityRegionsExcludable.bed")) @ For any list of regions, the percentage of bin overlap can be calculated by using the following command. <>= # generic calculation of overlap with blacklisted regions bins$blacklist <- calculateBlacklistByRegions(bins, cbind(chromosome, bpStart, bpEnd)) @ To calculate median residuals of the LOESS fit from a control dataset, the following command can be used. For the pre-generated annotations, the control set used is 38 samples from the \href{https://www.internationalgenome.org/}{1000 Genomes Project}. See the next section on how those were downloaded. <>= # load data for the 1000 Genomes (or similar) data set, and generate residuals ctrl <- binReadCounts(bins, path="/path/to/control-set/bam/files") ctrl <- applyFilters(ctrl, residual=FALSE, blacklist=FALSE, mappability=FALSE, bases=FALSE) bins$residual <- iterateResiduals(ctrl) @ The column \Robject{use} specifies whether each bin should be used for subsequent analyses by default. The command \Rfunction{applyFilters()} will change its value accordingly. By default, bins in the sex chromosomes, or with only uncharacterized nucleotides (N's) in their reference sequence, are flagged for exclusion. <>= # by default, use all autosomal bins that have a reference sequence # (i.e. not only N's) bins$use <- bins$chromosome %in% as.character(1:22) & bins$bases > 0 @ Optionally, the resulting \Rclass{data.frame} can be converted to an \Rclass{AnnotateDataFrame} and metadata added for the columns. <>= # convert to AnnotatedDataFrame and add metadata bins <- AnnotatedDataFrame(bins, varMetadata=data.frame(labelDescription=c( "Chromosome name", "Base pair start position", "Base pair end position", "Percentage of non-N nucleotides (of full bin size)", "Percentage of C and G nucleotides (of non-N nucleotides)", "Average mappability of 50mers with a maximum of 2 mismatches", "Percent overlap with ENCODE blacklisted regions", "Median loess residual from 1000 Genomes (50mers)", "Whether the bin should be used in subsequent analysis steps"), row.names=colnames(bins))) @ For the pre-generated annotations, some additional descriptive metadata has also been added. <>= attr(bins, "QDNAseq") <- list( author="Ilari Scheinin", date=Sys.time(), organism="Hsapiens", build="hg19", version=packageVersion("QDNAseq"), md5=digest::digest(bins@data), sessionInfo=sessionInfo()) @ \clearpage \section{Downloading 1000 Genomes samples} This section defines the criteria that were used to download samples from the 1000 Genomes Project for the pre-generated bin annotations. <>= # download table of samples urlroot <- "ftp://ftp.1000genomes.ebi.ac.uk/vol1/ftp" g1k <- read.table(file.path(urlroot, "sequence.index"), header=TRUE, sep="\t", as.is=TRUE, fill=TRUE) # keep cases that are Illumina, low coverage, single-read, and not withdrawn g1k <- g1k[g1k$INSTRUMENT_PLATFORM == "ILLUMINA", ] g1k <- g1k[g1k$ANALYSIS_GROUP == "low coverage", ] g1k <- g1k[g1k$LIBRARY_LAYOUT == "SINGLE", ] g1k <- g1k[g1k$WITHDRAWN == 0, ] # keep cases with read lengths of at least 50 bp g1k <- g1k[!g1k$BASE_COUNT %in% c("not available", ""), ] g1k$BASE_COUNT <- as.numeric(g1k$BASE_COUNT) g1k$READ_COUNT <- as.integer(g1k$READ_COUNT) g1k$readLength <- g1k$BASE_COUNT / g1k$READ_COUNT g1k <- g1k[g1k$readLength > 50, ] # keep samples with a minimum of one million reads readCountPerSample <- aggregate(g1k$READ_COUNT, by=list(sample=g1k$SAMPLE_NAME), FUN=sum) g1k <- g1k[g1k$SAMPLE_NAME %in% readCountPerSample$sample[readCountPerSample$x >= 1e6], ] g1k$fileName <- basename(g1k$FASTQ_FILE) # download FASTQ files for (i in rownames(g1k)) { sourceFile <- file.path(urlroot, g1k[i, "FASTQ_FILE"]) destFile <- g1k[i, "fileName"] if (!file.exists(destFile)) download.file(sourceFile, destFile, mode="wb") } @ Next, reads were trimmed to 50 bp, and the multiple files for each sample (as defined by column SAMPLE\_NAME) were combined by concatenating the FASTQ files together. Finally, they were aligned with \software{BWA} allowing two mismatches and end-trimming of bases with qualities below 40 (options \Rcode{-n 2 -q 40}). \clearpage \section{Session information} The version number of \R{} and packages loaded for generating the vignette were: <>= toLatex(sessionInfo()) @ \end{document} % EOF