In drisso/awst: Asymmetric Within-Sample Transformation

knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    crop = NULL
)

## Track time spent on making the vignette
startTime <- Sys.time()

## Bib setup
library("RefManageR")

## Write bibliography information
bib <- c(
    R = citation(),
    BiocStyle = citation("BiocStyle")[1],
    knitr = citation("knitr")[1],
    RefManageR = citation("RefManageR")[1],
    rmarkdown = citation("rmarkdown")[1],
    sessioninfo = citation("sessioninfo")[1],
    testthat = citation("testthat")[1],
    awst = citation("awst")[1]
)

Basics

Install awst

R is an open-source statistical environment which can be easily modified to enhance its functionality via packages. r Biocpkg("awst") is a R package available via the Bioconductor repository for packages. R can be installed on any operating system from CRAN after which you can install r Biocpkg("awst") by using the following commands in your R session:

if (!requireNamespace("BiocManager", quietly = TRUE)) {
    install.packages("BiocManager")
}

BiocManager::install("awst")

## Check that you have a valid Bioconductor installation
BiocManager::valid()

Required knowledge

r Biocpkg("awst") is based on many other packages and in particular in those that have implemented the infrastructure needed for dealing with RNA-seq data. That is, packages like r Biocpkg("SummarizedExperiment").

If you are asking yourself the question "Where do I start using Bioconductor?" you might be interested in this blog post.

Asking for help

As package developers, we try to explain clearly how to use our packages and in which order to use the functions. But R and Bioconductor have a steep learning curve so it is critical to learn where to ask for help. The blog post quoted above mentions some but we would like to highlight the Bioconductor support site as the main resource for getting help: remember to use the awst tag and check the older posts. Other alternatives are available such as creating GitHub issues and tweeting. However, please note that if you want to receive help you should adhere to the posting guidelines. It is particularly critical that you provide a small reproducible example and your session information so package developers can track down the source of the error.

Citing awst

We hope that r Biocpkg("awst") will be useful for your research. Please use the following information to cite the package and the overall approach. Thank you!

## Citation info
citation("awst")

What does awst does?

AWST aims to regularize the original read counts to reduce the effect of noise on the clustering of samples. In fact, gene expression data are characterized by high levels of noise in both lowly expressed features, which suffer from background effects and low signal-to-noise ratio, and highly expressed features, which may be the result of amplification bias and other experimental artifacts. These effects are of utmost importance in highly degraded or low input material samples, such as tumor samples and single cells.

AWST comprises two main steps. In the first one, namely the standardization step, we standardize the counts by centering and scaling them, exploiting the log-normal probability distribution. We refer to the standardized counts as z-counts. The second step, namely the smoothing step, leverages a highly skewed transformation that decreases the noise while preserving the influence of genes to separate molecular subtypes. These two steps are implemented in the awst function.

A further filtering method, implemented in the gene_filter function, is suggested to remove those features that only contribute noise to the clustering.

Quick start

library(awst)
library(airway)
library(SummarizedExperiment)
library(EDASeq)
library(ggplot2)

Here, we will use the data in the r Biocpkg("airway") package to illustrate the awst approach.

Please, see our paper r Citep(bib[["awst"]]) and this repository for more extensive and biologically relevant examples.

data(airway)
airway

The data are stored in a RangedSummarizedExperiment, a special case of the SummarizedExperiment class, one of the central classes in Bioconductor. If you are not familiar with it, I recomment to look at its vignette available at r Biocpkg("SummarizedExperiment").

First, we filter out non-expressed genes. For simplicity, we remove those genes with fewer than 10 reads on average across samples.

filter <- rowMeans(assay(airway)) >= 10
table(filter)

se <- airway[filter,]

We are left with r sum(filter) genes. We are now ready to apply awst to the data.

se <- awst(se)
se
plot(density(assay(se, "awst")[,1]), main = "Sample 1")

We can see that the majority of the values have been shrunk around −2, while the others values gradually increase up to around 4. The effect of reducing the contribution of lowly expressed genes, and of the winsorization for the highly expressed ones, results in a better separation of the samples, reflecting biological differences r Citep(bib[["awst"]]).

The other main function of the r Biocpkg("awst") package is gene_filter. It can be used to remove those genes that contribute little to nothing to the distance between samples. The function uses an entropy measure to remove the uninformative genes.

filtered <- gene_filter(se)
dim(filtered)

Our final dataset is made of r ncol(filtered) genes.

We can see how the awst transformation leads to separation between treatment (along PC1) and cell line (along PC2).

res_pca <- prcomp(t(assay(filtered, "awst")))
df <- as.data.frame(cbind(res_pca$x, colData(airway)))
ggplot(df, aes(x = PC1, y = PC2, color = dex, shape = cell)) +
    geom_point() + theme_classic()

Role of normalization

Although in this example awst applied to raw data works well, a prior normalization step can help. We have found that full-quantile normalization works well and has the computational advantage of allowing awst to estimate the parameters only once for all samples r Citep(bib[["awst"]]).

Here we show the results of awst after full-quantile normalization (implemented in r Biocpkg("EDASeq")).

assay(se, "fq") <- betweenLaneNormalization(assay(se), which="full")
se <- awst(se, expr_values = "fq")

res_pca <- prcomp(t(assay(se, "awst")))
df <- as.data.frame(cbind(res_pca$x, colData(airway)))
ggplot(df, aes(x = PC1, y = PC2, color = dex, shape = cell)) +
    geom_point() + theme_classic()

Reproducibility

The r Biocpkg("awst") package r Citep(bib[["awst"]]) was made possible thanks to:

• R r Citep(bib[["R"]])
• r Biocpkg("BiocStyle") r Citep(bib[["BiocStyle"]])
• r CRANpkg("knitr") r Citep(bib[["knitr"]])
• r CRANpkg("RefManageR") r Citep(bib[["RefManageR"]])
• r CRANpkg("rmarkdown") r Citep(bib[["rmarkdown"]])
• r CRANpkg("sessioninfo") r Citep(bib[["sessioninfo"]])
• r CRANpkg("testthat") r Citep(bib[["testthat"]])

This package was developed using r BiocStyle::Biocpkg("biocthis").

Code for creating the vignette

## Create the vignette
library("rmarkdown")
system.time(render("awst_intro.Rmd", "BiocStyle::html_document"))

## Extract the R code
library("knitr")
knit("awst_intro.Rmd", tangle = TRUE)

Date the vignette was generated.

## Date the vignette was generated
Sys.time()

Wallclock time spent generating the vignette.

## Processing time in seconds
totalTime <- diff(c(startTime, Sys.time()))
round(totalTime, digits = 3)

R session information.

## Session info
library("sessioninfo")
options(width = 120)
session_info()

Bibliography

This vignette was generated using r Biocpkg("BiocStyle") r Citep(bib[["BiocStyle"]]) with r CRANpkg("knitr") r Citep(bib[["knitr"]]) and r CRANpkg("rmarkdown") r Citep(bib[["rmarkdown"]]) running behind the scenes.

Citations made with r CRANpkg("RefManageR") r Citep(bib[["RefManageR"]]).

## Print bibliography
PrintBibliography(bib, .opts = list(hyperlink = "to.doc", style = "html"))

drisso/awst documentation built on Jan. 29, 2024, 3:42 p.m.