---
title: "Visualizing VCF data 2"
author: "Brian Knaus"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Visualization 2}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


In the vignette 'Visualizing VCF data I' we began to explore how to plot information contained in [variant call format (vcf)](http://samtools.github.io/hts-specs/ "VCF format at hts-specs") files.
This perspective was mostly one of summaries over all samples for each variant.
Here we build on this by exploring data based on each sample's genotype information.


## Data


As in other vignettes, we begin by loading the example data.



```{r}
library(vcfR)

vcf_file <- system.file("extdata", "pinf_sc50.vcf.gz", package = "pinfsc50")
dna_file <- system.file("extdata", "pinf_sc50.fasta", package = "pinfsc50")
gff_file <- system.file("extdata", "pinf_sc50.gff", package = "pinfsc50")

vcf <- read.vcfR(vcf_file, verbose = FALSE)
dna <- ape::read.dna(dna_file, format = "fasta")
gff <- read.table(gff_file, sep="\t", quote="")

chrom <- create.chromR(name="Supercontig", vcf=vcf, seq=dna, ann=gff, verbose=FALSE)
chrom <- masker(chrom, min_DP = 300, max_DP = 700)
chrom <- proc.chromR(chrom, verbose = FALSE)

```



## Genotype data

In the vignette 'Visualizing VCF data I' we explored summaries of variants made across all samples.
If all samples are fairly homogenous in the qualities of these metrics, than a summary across all samples may be appropriate.
However, if a few samples have very low quality, or some samples are exceptional, this may be masked by looking at summaries across all samples.
By looking at the individual samples, these differences may be discovered.



In order to look at the per sample information, we first need to determine what sort of data we have there.
We can use the function head() to summarize the information in our Chrom object.


```{r}
head(chrom)
```



Recall from the vignette 'vcf data' that the genotype information begins at column nine from the file.
This column specifies the format of all subsequent columns.
All columns subsequent to this column contain information for each sample where each column corresponds to a sample.
We see form the output of head() that our genotype data contains `r chrom@vcf@gt[1,1]` data.
These abbreviations are defined in the meta portion of the file.
Observation of the first few rows of genotype information shows the format as `r chrom@vcf@gt[1,2]`.
These are colon delimited values, as in the format column.
Because the genotypes are not strictly numeric (they contain a slash to delimit unphased data and a pipe to delimit phased data) we won't be able to treat this as numeric information.
Read depth (DP) is numeric, and we'll use that in subsequent examples.


## Using extract.gt


The genotype region of VCF data contains several values for each sample and each variant.
We can extract one of these colon delimited values using the function **extract.gt()**.
This function determines the position of the desired element in the FORMAT column and uses this information to extract the same position from all of the other samples in that row.
This is performed on a row by row basis so that files containing heterogeneous FORMAT specifications can be processed.
Here we've asked the function to convert the resulting matrix to a numeric matrix.
This is because we've determined, above, that this is indeed numeric data.
But be careful with this option!
If the data are not numeric it will do its best to convert the data and will probably not throw an error.
It's up to the user (*this means you*) to make sure this is a reasonable decision.


```{r}
dp <- extract.gt(chrom, element="DP", as.numeric=TRUE)
rownames(dp) <- 1:nrow(dp)
head(dp)
```


Once we've extracted the desired element, we'll want to visualize the resulting matrix of data.
The head() statement above gives us a peak at what it looks like.
But it doesn't allow us to view the entire matrix.
The function **heatmap.bp()** helps us to visualize a matrix of data.


```{r, fig.height=7, fig.width=7}
heatmap.bp(dp[1001:1500,])
```


The plot that results from heatmap.bp() shows samples in columns and variants in rows.
Marginal barplots summarize sums of the rows and columns.
The color ramp, at the right, is parameterized for continuous data.
In the above plot, yellow is a high number of high quality bases violet is a low number of high quality bases.
If you ask the function to visualize more values than the screen has pixels, some form of interpolation is performed.
Because of this I suggest using this function for no more than about 1,000 variants.



## Interpretation of zeros


The presence of zeros in a dataset presents a conundrum.
Sometimes, the presence of zero valued data represents the positive determination that there is zero valued data.
For example, if we went to the grocery store and at the checkout counter we could count that we have three bananas, two oranges but zero apples when we know the store had apples.
This means that we know that we did not want any apples as opposed to the store not having apples, or perhaps we just forgot to look, or a number of other scenarios.
Alternatively, the presences of zero valued data indicates that there is missing data.
This would be similar to counting how many bananas and oranges are in our basket, but not reporting on the number of apples.
We do not know if there are zero apples, or we just didn't count the apples.
For our sequence depth, a zero value may indicate that the nucleotide exists in the reference sequence but not in the resequenced sample.
Alternatively, it may mean that the resequenced sample was not sequenced at sufficient depth to detect its presence.
In the present example, we may interpret zero data as missing data.
Therefore, we should re-encode zero data as NA data.


```{r}
is.na(dp[na.omit(dp == 0)]) <- TRUE
```


And re-visualize.


```{r, fig.height=7, fig.width=7}
heatmap.bp(dp[1001:1500,])
```


There are some important differences among the two above plots.
In the first plot there are missing data, but there are also sites where there is a read depth of zero.
The difference is that in the first plot, zero data are coded as dark violet while missing data are coded as white (a color that is not present in the color ramp).
In the second plot, the zero data were recoded as missing so they now stand out better.
One of the downsides of the heatmap is that it tells up what is high valued or low, but it does not tell us the actual values.
We can use a barplot to inform us of this information.


```{r, fig.height=4, fig.width=7}
par(mar=c(8,4,4,2))
barplot(apply(dp, MARGIN=2, mean, na.rm=TRUE), las=3)
par(mar=c(5,4,4,2))
```


Here we see that the mean number of high quality bases per variant is quite high for most samples.
The sample p1362 appears to have an abundance of missing data in the heatmap.
In the barplot we've validated that this sample lacks information.
At the other end of the spectrum, the sample NL07434 has a high average coverage as seen in the heatmap, and in the barplot we can see that this value is just over 40.



## Conclusion


Now that we know our way around our chromosome it may be time to make some decisions.
Regions which do not meet our expectations may need extra work to make sure they are of high quality.
Alternatively, we may simply wish to censor these regions and focus on the high quality fraction of the data.
Once we've gained a familiarity with the data contained in our VCF file we can make informed decisions on how best to process it.




