Introduction to awst
25 April 2023
Package
awst 1.8.0
1 Basics
1.1 Install awst
R is an open-source statistical environment which can be easily modified to
enhance its functionality via packages. 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
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()1.2 Required knowledge
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 SummarizedExperiment.
If you are asking yourself the question “Where do I start using Bioconductor?” you might be interested in this blog post.
1.3 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.
1.4 Citing awst
We hope that 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")
#> Warning in person1(given = given[[i]], family = family[[i]], middle =
#> middle[[i]], : It is recommended to use 'given' instead of 'middle'.
#> To cite package 'awst' in publications use:
#>
#> Risso D, Pagnotta SM (2021). "Per-sample standardization and
#> asymmetric winsorization lead to accurate clustering of RNA-seq
#> expression profiles." _Bioinformatics_.
#> doi:10.1093/bioinformatics/btab091
#> <https://doi.org/10.1093/bioinformatics/btab091>.
#>
#> A BibTeX entry for LaTeX users is
#>
#> @Article{,
#> title = {Per-sample standardization and asymmetric winsorization lead to accurate clustering of RNA-seq expression profiles},
#> author = {Davide Risso and Stefano Maria Pagnotta},
#> year = {2021},
#> journal = {Bioinformatics},
#> doi = {10.1093/bioinformatics/btab091},
#> }2 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.
3 Quick start
library(awst)
library(airway)
library(SummarizedExperiment)
library(EDASeq)
library(ggplot2)Here, we will use the data in the airway package to illustrate
the awst approach.
Please, see our paper (Risso and Pagnotta, 2021) and this repository for more extensive and biologically relevant examples.
data(airway)
airway
#> class: RangedSummarizedExperiment
#> dim: 63677 8
#> metadata(1): ''
#> assays(1): counts
#> rownames(63677): ENSG00000000003 ENSG00000000005 ... ENSG00000273492
#> ENSG00000273493
#> rowData names(10): gene_id gene_name ... seq_coord_system symbol
#> colnames(8): SRR1039508 SRR1039509 ... SRR1039520 SRR1039521
#> colData names(9): SampleName cell ... Sample BioSampleThe 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
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)
#> filter
#> FALSE TRUE
#> 47587 16090
se <- airway[filter,]We are left with 16090 genes. We are now ready to apply awst to the
data.
se <- awst(se)
se
#> class: RangedSummarizedExperiment
#> dim: 16090 8
#> metadata(1): ''
#> assays(2): counts awst
#> rownames(16090): ENSG00000000003 ENSG00000000419 ... ENSG00000273472
#> ENSG00000273486
#> rowData names(10): gene_id gene_name ... seq_coord_system symbol
#> colnames(8): SRR1039508 SRR1039509 ... SRR1039520 SRR1039521
#> colData names(9): SampleName cell ... Sample BioSample
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 (Risso and Pagnotta, 2021).
The other main function of the 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)
#> [1] 10842 8Our final dataset is made of 8 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()
4 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 (Risso and Pagnotta, 2021).
Here we show the results of awst after full-quantile normalization
(implemented in 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()
5 Reproducibility
The awst package (Risso and Pagnotta, 2021) was made possible thanks to:
- R (R Core Team, 2023)
- BiocStyle (Oleś, 2023)
- knitr (Xie, 2023)
- RefManageR (McLean, 2017)
- rmarkdown (Allaire, Xie, Dervieux, McPherson, Luraschi, Ushey, Atkins, Wickham, Cheng, Chang, and Iannone, 2023)
- sessioninfo (Wickham, Chang, Flight, Müller, and Hester, 2021)
- testthat (Wickham, 2011)
This package was developed using 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.
#> [1] "2023-04-25 16:14:05 EDT"Wallclock time spent generating the vignette.
#> Time difference of 21.949 secsR session information.
#> ─ Session info ───────────────────────────────────────────────────────────────────────────────────────────────────────
#> setting value
#> version R version 4.3.0 RC (2023-04-13 r84269)
#> os Ubuntu 22.04.2 LTS
#> system x86_64, linux-gnu
#> ui X11
#> language (EN)
#> collate C
#> ctype en_US.UTF-8
#> tz America/New_York
#> date 2023-04-25
#> pandoc 2.7.3 @ /usr/bin/ (via rmarkdown)
#>
#> ─ Packages ───────────────────────────────────────────────────────────────────────────────────────────────────────────
#> package * version date (UTC) lib source
#> airway * 1.19.1 2023-04-25 [2] Bioconductor
#> AnnotationDbi 1.62.0 2023-04-25 [2] Bioconductor
#> aroma.light 3.30.0 2023-04-25 [2] Bioconductor
#> awst * 1.8.0 2023-04-25 [1] Bioconductor
#> backports 1.4.1 2021-12-13 [2] CRAN (R 4.3.0)
#> bibtex 0.5.1 2023-01-26 [2] CRAN (R 4.3.0)
#> Biobase * 2.60.0 2023-04-25 [2] Bioconductor
#> BiocFileCache 2.8.0 2023-04-25 [2] Bioconductor
#> BiocGenerics * 0.46.0 2023-04-25 [2] Bioconductor
#> BiocIO 1.10.0 2023-04-25 [2] Bioconductor
#> BiocManager 1.30.20 2023-02-24 [2] CRAN (R 4.3.0)
#> BiocParallel * 1.34.0 2023-04-25 [2] Bioconductor
#> BiocStyle * 2.28.0 2023-04-25 [2] Bioconductor
#> biomaRt 2.56.0 2023-04-25 [2] Bioconductor
#> Biostrings * 2.68.0 2023-04-25 [2] Bioconductor
#> bit 4.0.5 2022-11-15 [2] CRAN (R 4.3.0)
#> bit64 4.0.5 2020-08-30 [2] CRAN (R 4.3.0)
#> bitops 1.0-7 2021-04-24 [2] CRAN (R 4.3.0)
#> blob 1.2.4 2023-03-17 [2] CRAN (R 4.3.0)
#> bookdown 0.33 2023-03-06 [2] CRAN (R 4.3.0)
#> bslib 0.4.2 2022-12-16 [2] CRAN (R 4.3.0)
#> cachem 1.0.7 2023-02-24 [2] CRAN (R 4.3.0)
#> cli 3.6.1 2023-03-23 [2] CRAN (R 4.3.0)
#> codetools 0.2-19 2023-02-01 [3] CRAN (R 4.3.0)
#> colorspace 2.1-0 2023-01-23 [2] CRAN (R 4.3.0)
#> crayon 1.5.2 2022-09-29 [2] CRAN (R 4.3.0)
#> curl 5.0.0 2023-01-12 [2] CRAN (R 4.3.0)
#> DBI 1.1.3 2022-06-18 [2] CRAN (R 4.3.0)
#> dbplyr 2.3.2 2023-03-21 [2] CRAN (R 4.3.0)
#> DelayedArray 0.26.0 2023-04-25 [2] Bioconductor
#> deldir 1.0-6 2021-10-23 [2] CRAN (R 4.3.0)
#> digest 0.6.31 2022-12-11 [2] CRAN (R 4.3.0)
#> dplyr 1.1.2 2023-04-20 [2] CRAN (R 4.3.0)
#> EDASeq * 2.34.0 2023-04-25 [2] Bioconductor
#> evaluate 0.20 2023-01-17 [2] CRAN (R 4.3.0)
#> fansi 1.0.4 2023-01-22 [2] CRAN (R 4.3.0)
#> farver 2.1.1 2022-07-06 [2] CRAN (R 4.3.0)
#> fastmap 1.1.1 2023-02-24 [2] CRAN (R 4.3.0)
#> filelock 1.0.2 2018-10-05 [2] CRAN (R 4.3.0)
#> generics 0.1.3 2022-07-05 [2] CRAN (R 4.3.0)
#> GenomeInfoDb * 1.36.0 2023-04-25 [2] Bioconductor
#> GenomeInfoDbData 1.2.10 2023-04-17 [2] Bioconductor
#> GenomicAlignments * 1.36.0 2023-04-25 [2] Bioconductor
#> GenomicFeatures 1.52.0 2023-04-25 [2] Bioconductor
#> GenomicRanges * 1.52.0 2023-04-25 [2] Bioconductor
#> ggplot2 * 3.4.2 2023-04-03 [2] CRAN (R 4.3.0)
#> glue 1.6.2 2022-02-24 [2] CRAN (R 4.3.0)
#> gtable 0.3.3 2023-03-21 [2] CRAN (R 4.3.0)
#> highr 0.10 2022-12-22 [2] CRAN (R 4.3.0)
#> hms 1.1.3 2023-03-21 [2] CRAN (R 4.3.0)
#> htmltools 0.5.5 2023-03-23 [2] CRAN (R 4.3.0)
#> httr 1.4.5 2023-02-24 [2] CRAN (R 4.3.0)
#> hwriter 1.3.2.1 2022-04-08 [2] CRAN (R 4.3.0)
#> interp 1.1-4 2023-03-31 [2] CRAN (R 4.3.0)
#> IRanges * 2.34.0 2023-04-25 [2] Bioconductor
#> jpeg 0.1-10 2022-11-29 [2] CRAN (R 4.3.0)
#> jquerylib 0.1.4 2021-04-26 [2] CRAN (R 4.3.0)
#> jsonlite 1.8.4 2022-12-06 [2] CRAN (R 4.3.0)
#> KEGGREST 1.40.0 2023-04-25 [2] Bioconductor
#> knitr 1.42 2023-01-25 [2] CRAN (R 4.3.0)
#> labeling 0.4.2 2020-10-20 [2] CRAN (R 4.3.0)
#> lattice 0.21-8 2023-04-05 [3] CRAN (R 4.3.0)
#> latticeExtra 0.6-30 2022-07-04 [2] CRAN (R 4.3.0)
#> lifecycle 1.0.3 2022-10-07 [2] CRAN (R 4.3.0)
#> lubridate 1.9.2 2023-02-10 [2] CRAN (R 4.3.0)
#> magrittr 2.0.3 2022-03-30 [2] CRAN (R 4.3.0)
#> Matrix 1.5-4 2023-04-04 [3] CRAN (R 4.3.0)
#> MatrixGenerics * 1.12.0 2023-04-25 [2] Bioconductor
#> matrixStats * 0.63.0 2022-11-18 [2] CRAN (R 4.3.0)
#> memoise 2.0.1 2021-11-26 [2] CRAN (R 4.3.0)
#> munsell 0.5.0 2018-06-12 [2] CRAN (R 4.3.0)
#> pillar 1.9.0 2023-03-22 [2] CRAN (R 4.3.0)
#> pkgconfig 2.0.3 2019-09-22 [2] CRAN (R 4.3.0)
#> plyr 1.8.8 2022-11-11 [2] CRAN (R 4.3.0)
#> png 0.1-8 2022-11-29 [2] CRAN (R 4.3.0)
#> prettyunits 1.1.1 2020-01-24 [2] CRAN (R 4.3.0)
#> progress 1.2.2 2019-05-16 [2] CRAN (R 4.3.0)
#> R.methodsS3 1.8.2 2022-06-13 [2] CRAN (R 4.3.0)
#> R.oo 1.25.0 2022-06-12 [2] CRAN (R 4.3.0)
#> R.utils 2.12.2 2022-11-11 [2] CRAN (R 4.3.0)
#> R6 2.5.1 2021-08-19 [2] CRAN (R 4.3.0)
#> rappdirs 0.3.3 2021-01-31 [2] CRAN (R 4.3.0)
#> RColorBrewer 1.1-3 2022-04-03 [2] CRAN (R 4.3.0)
#> Rcpp 1.0.10 2023-01-22 [2] CRAN (R 4.3.0)
#> RCurl 1.98-1.12 2023-03-27 [2] CRAN (R 4.3.0)
#> RefManageR * 1.4.0 2022-09-30 [2] CRAN (R 4.3.0)
#> restfulr 0.0.15 2022-06-16 [2] CRAN (R 4.3.0)
#> rjson 0.2.21 2022-01-09 [2] CRAN (R 4.3.0)
#> rlang 1.1.0 2023-03-14 [2] CRAN (R 4.3.0)
#> rmarkdown 2.21 2023-03-26 [2] CRAN (R 4.3.0)
#> Rsamtools * 2.16.0 2023-04-25 [2] Bioconductor
#> RSQLite 2.3.1 2023-04-03 [2] CRAN (R 4.3.0)
#> rtracklayer 1.60.0 2023-04-25 [2] Bioconductor
#> S4Vectors * 0.38.0 2023-04-25 [2] Bioconductor
#> sass 0.4.5 2023-01-24 [2] CRAN (R 4.3.0)
#> scales 1.2.1 2022-08-20 [2] CRAN (R 4.3.0)
#> sessioninfo * 1.2.2 2021-12-06 [2] CRAN (R 4.3.0)
#> ShortRead * 1.58.0 2023-04-25 [2] Bioconductor
#> stringi 1.7.12 2023-01-11 [2] CRAN (R 4.3.0)
#> stringr 1.5.0 2022-12-02 [2] CRAN (R 4.3.0)
#> SummarizedExperiment * 1.30.0 2023-04-25 [2] Bioconductor
#> tibble 3.2.1 2023-03-20 [2] CRAN (R 4.3.0)
#> tidyselect 1.2.0 2022-10-10 [2] CRAN (R 4.3.0)
#> timechange 0.2.0 2023-01-11 [2] CRAN (R 4.3.0)
#> utf8 1.2.3 2023-01-31 [2] CRAN (R 4.3.0)
#> vctrs 0.6.2 2023-04-19 [2] CRAN (R 4.3.0)
#> withr 2.5.0 2022-03-03 [2] CRAN (R 4.3.0)
#> xfun 0.39 2023-04-20 [2] CRAN (R 4.3.0)
#> XML 3.99-0.14 2023-03-19 [2] CRAN (R 4.3.0)
#> xml2 1.3.3 2021-11-30 [2] CRAN (R 4.3.0)
#> XVector * 0.40.0 2023-04-25 [2] Bioconductor
#> yaml 2.3.7 2023-01-23 [2] CRAN (R 4.3.0)
#> zlibbioc 1.46.0 2023-04-25 [2] Bioconductor
#>
#> [1] /tmp/RtmpPuL0HS/Rinst2f2d9532196324
#> [2] /home/biocbuild/bbs-3.17-bioc/R/site-library
#> [3] /home/biocbuild/bbs-3.17-bioc/R/library
#>
#> ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────6 Bibliography
This vignette was generated using BiocStyle (Oleś, 2023) with knitr (Xie, 2023) and rmarkdown (Allaire, Xie, Dervieux et al., 2023) running behind the scenes.
Citations made with RefManageR (McLean, 2017).
[1] J. Allaire, Y. Xie, C. Dervieux, et al. rmarkdown: Dynamic Documents for R. R package version 2.21. 2023. URL: https://github.com/rstudio/rmarkdown.
[2] M. W. McLean. “RefManageR: Import and Manage BibTeX and BibLaTeX References in R”. In: The Journal of Open Source Software (2017). DOI: 10.21105/joss.00338.
[3] A. Oleś. BiocStyle: Standard styles for vignettes and other Bioconductor documents. R package version 2.28.0. 2023. DOI: 10.18129/B9.bioc.BiocStyle. URL: https://bioconductor.org/packages/BiocStyle.
[4] R Core Team. R: A Language and Environment for Statistical Computing. R Foundation for Statistical Computing. Vienna, Austria, 2023. URL: https://www.R-project.org/.
[5] D. Risso and S. M. Pagnotta. “Per-sample standardization and asymmetric winsorization lead to accurate clustering of RNA-seq expression profiles”. In: Bioinformatics (2021). DOI: 10.1093/bioinformatics/btab091.
[6] H. Wickham. “testthat: Get Started with Testing”. In: The R Journal 3 (2011), pp. 5–10. URL: https://journal.r-project.org/archive/2011-1/RJournal_2011-1_Wickham.pdf.
[7] H. Wickham, W. Chang, R. Flight, et al. sessioninfo: R Session Information. R package version 1.2.2. 2021. URL: https://CRAN.R-project.org/package=sessioninfo.
[8] Y. Xie. knitr: A General-Purpose Package for Dynamic Report Generation in R. R package version 1.42. 2023. URL: https://yihui.org/knitr/.