diff --git a/README.Rmd b/README.Rmd
index 9c336cbd..e633314b 100644
--- a/README.Rmd
+++ b/README.Rmd
@@ -1,5 +1,8 @@
---
output: github_document
+editor_options:
+ markdown:
+ wrap: sentence
---
@@ -14,30 +17,44 @@ knitr::opts_chunk$set(
options(width = 100)
```
-# microViz 
+# microViz
-[](https://github.com/david-barnett/microViz/actions)
-[](https://codecov.io/gh/david-barnett/microViz)
+
+[](https://github.com/david-barnett/microViz/actions) [](https://codecov.io/gh/david-barnett/microViz)
+
-microViz provides functions for analysis and visualization of microbiome sequencing data. These functions are intended to be easy to use (with clear documentation) and modular (for extensibility and flexibility).
+microViz provides functions for analysis and visualization of microbiome sequencing data.
+These functions are intended to be easy to use and flexible.
microViz wraps, extends and complements popular microbial ecology packages like phyloseq, vegan, and microbiome.
-**See the documentation website for full details and examples:** https://david-barnett.github.io/microViz/
+**See the documentation website for full details and examples:**
+
+- The ["Get started"](https://david-barnett.github.io/microViz/articles/articles/microViz.html) page, and also [this ReadMe](https://david-barnett.github.io/microViz/index.html), show a few example analyses.
+
+- The [reference](https://david-barnett.github.io/microViz/reference/index.html) page lists all functions and links to their documentation and examples
+
+- Example video of [Interactive Shiny app](https://david-barnett.github.io/microViz/articles/articles/Interactive-Ordination.html) for exploring your ordination plots!
+
+- Other articles pages give tutorials and more complicated examples
+
+ - [Working with phyloseq objects](https://david-barnett.github.io/microViz/articles/articles/phyloseq.html)
-- The ["Get started"](https://david-barnett.github.io/microViz/articles/articles/microViz.html) page, and also [this ReadMe](https://david-barnett.github.io/microViz/index.html), show a few example analyses.
-- The [reference](https://david-barnett.github.io/microViz/reference/index.html) page lists all functions and links to their documentation and examples
-- Example video of [Interactive Shiny app](https://david-barnett.github.io/microViz/articles/articles/Interactive-Ordination.html) for exploring your ordination plots!
-- Other articles pages discuss and give tutorials and more complicated examples (coming soon!)
-- The [changelog](https://david-barnett.github.io/microViz/news/index.html) describes important changes in new microViz package versions
+ - [Fixing your taxa table with tax_fix](https://david-barnett.github.io/microViz/articles/articles/tax-fixing.html)
+
+ - [Visualising taxonomic compositions with customised barplots](https://david-barnett.github.io/microViz/articles/articles/Visualising-compositions.html)
+
+ - (more coming soon! raise an issue on github if you have questions/requests)
+
+- The [changelog](https://david-barnett.github.io/microViz/news/index.html) describes important changes in new microViz package versions
## Installation
You can install the latest available microViz package version using the following instructions.
``` r
-# If you are on windows you will need to install RTools so that your computer can build this package
+# If you are on Windows you will need to install RTools so that your computer can build this package
# Follow instructions here: http://jtleek.com/modules/01_DataScientistToolbox/02_10_rtools/
# If you are on macOS, you might need to install xquartz to make the heatmaps work (ComplexHeatmaps package)
@@ -55,7 +72,6 @@ BiocManager::install(c("phyloseq", "microbiome"))
# # Installing the latest version of this package # #
devtools::install_github("david-barnett/microViz@0.7.0") # check 0.7.0 is the latest version?
# advanced tip: add @ after microViz to install a version from a particular commit
-
```
## Examples below
@@ -102,20 +118,20 @@ dietswap %>%
)
```
-
## Example ordination plot workflow
Maybe visually inspecting all your samples isn't quite what you want.
-Ordination methods can also help you to visualise if overall microbial ecosystem composition differs markedly between groups, e.g. BMI.
+Ordination methods can also help you to visualise if overall microbial ecosystem composition differs markedly between groups, e.g.
+BMI.
-Here is one option to try first:
+Here is one option to try first:
-1. Filter out rare taxa (e.g. remove Genera not present in at least 10% of samples) - use `tax_filter()`
-2. Aggregate the taxa into bacterial families (for example) - use `tax_agg()`
-3. Transform the microbial data with the centre-log-ratio transformation - use `tax_transform()`
-4. Perform PCA with the clr-transformed features (equivalent to aitchison distance PCoA) - use `ord_calc()`
-5. Plot the first 2 axes of this PCA ordination, colouring samples by group and adding taxon loading arrows to visualise which taxa generally differ across your samples - use `ord_plot()`
-6. Customise the theme of the ggplot as you like and/or add features like ellipses or annotations
+1. Filter out rare taxa (e.g. remove Genera not present in at least 10% of samples) - use `tax_filter()`
+2. Aggregate the taxa into bacterial families (for example) - use `tax_agg()`
+3. Transform the microbial data with the centre-log-ratio transformation - use `tax_transform()`
+4. Perform PCA with the clr-transformed features (equivalent to aitchison distance PCoA) - use `ord_calc()`
+5. Plot the first 2 axes of this PCA ordination, colouring samples by group and adding taxon loading arrows to visualise which taxa generally differ across your samples - use `ord_plot()`
+6. Customise the theme of the ggplot as you like and/or add features like ellipses or annotations
```{r ordination-plot, dpi=300}
# perform ordination
@@ -125,7 +141,7 @@ unconstrained_aitchison_pca <-
tax_agg("Family") %>%
tax_transform("clr") %>%
ord_calc()
-# will automatically infer you want a "PCA" here
+# ord_calc will automatically infer you want a "PCA" here
# specify explicitly with method = "PCA", or you can pick another method
# create plot
@@ -148,7 +164,7 @@ customised_plot
## PERMANOVA
-You visualised your ordinated data in the plot above.
+You visualised your ordinated data in the plot above.
Below you can see how to perform a PERMANOVA to test the significance of BMI's association with overall microbial composition.
This example uses the Family-level aitchison distance to correspond with the plot above.
@@ -217,8 +233,6 @@ taxa <- sample(microbiome::top_taxa(ps_get(psq))[1:50], size = 30)
cor_heatmap(psq, taxa, anno_tax = tax_anno(undetected = 50))
```
-
-
## Session info
```{r}
diff --git a/README.md b/README.md
index f57fcbd0..f871e17b 100644
--- a/README.md
+++ b/README.md
@@ -1,38 +1,53 @@
-# microViz
+# microViz
[](https://github.com/david-barnett/microViz/actions)
[](https://codecov.io/gh/david-barnett/microViz)
+
microViz provides functions for analysis and visualization of microbiome
-sequencing data. These functions are intended to be easy to use (with
-clear documentation) and modular (for extensibility and flexibility).
-microViz wraps, extends and complements popular microbial ecology
-packages like phyloseq, vegan, and microbiome.
+sequencing data. These functions are intended to be easy to use and
+flexible. microViz wraps, extends and complements popular microbial
+ecology packages like phyloseq, vegan, and microbiome.
**See the documentation website for full details and examples:**
- - The [“Get
+- The [“Get
started”](https://david-barnett.github.io/microViz/articles/articles/microViz.html)
page, and also [this
ReadMe](https://david-barnett.github.io/microViz/index.html), show a
few example analyses.
- - The
+
+- The
[reference](https://david-barnett.github.io/microViz/reference/index.html)
page lists all functions and links to their documentation and
examples
- - Example video of [Interactive Shiny
+
+- Example video of [Interactive Shiny
app](https://david-barnett.github.io/microViz/articles/articles/Interactive-Ordination.html)
- for exploring your ordination plots\!
- - Other articles pages discuss and give tutorials and more complicated
- examples (coming soon\!)
- - The
+ for exploring your ordination plots!
+
+- Other articles pages give tutorials and more complicated examples
+
+ - [Working with phyloseq
+ objects](https://david-barnett.github.io/microViz/articles/articles/phyloseq.html)
+
+ - [Fixing your taxa table with
+ tax\_fix](https://david-barnett.github.io/microViz/articles/articles/tax-fixing.html)
+
+ - [Visualising taxonomic compositions with customised
+ barplots](https://david-barnett.github.io/microViz/articles/articles/Visualising-compositions.html)
+
+ - (more coming soon! raise an issue on github if you have
+ questions/requests)
+
+- The
[changelog](https://david-barnett.github.io/microViz/news/index.html)
describes important changes in new microViz package versions
@@ -42,7 +57,7 @@ You can install the latest available microViz package version using the
following instructions.
``` r
-# If you are on windows you will need to install RTools so that your computer can build this package
+# If you are on Windows you will need to install RTools so that your computer can build this package
# Follow instructions here: http://jtleek.com/modules/01_DataScientistToolbox/02_10_rtools/
# If you are on macOS, you might need to install xquartz to make the heatmaps work (ComplexHeatmaps package)
@@ -116,7 +131,7 @@ dietswap %>%
Maybe visually inspecting all your samples isn’t quite what you want.
Ordination methods can also help you to visualise if overall microbial
-ecosystem composition differs markedly between groups, e.g. BMI.
+ecosystem composition differs markedly between groups, e.g. BMI.
Here is one option to try first:
@@ -134,8 +149,6 @@ Here is one option to try first:
6. Customise the theme of the ggplot as you like and/or add features
like ellipses or annotations
-
-
``` r
# perform ordination
unconstrained_aitchison_pca <-
@@ -145,7 +158,7 @@ unconstrained_aitchison_pca <-
tax_transform("clr") %>%
ord_calc()
#> Proportional min_prevalence given: 0.1 --> min 23/222 samples.
-# will automatically infer you want a "PCA" here
+# ord_calc will automatically infer you want a "PCA" here
# specify explicitly with method = "PCA", or you can pick another method
# create plot
@@ -195,8 +208,8 @@ aitchison_perm <- dist_permanova(
variables = "bmi_group + female"
)
#> Dropping samples with missings: 2
-#> 2021-04-08 20:42:38 - Starting PERMANOVA with 99 perms with 1 processes
-#> 2021-04-08 20:42:38 - Finished PERMANOVA
+#> 2021-04-12 12:46:53 - Starting PERMANOVA with 99 perms with 1 processes
+#> 2021-04-12 12:46:54 - Finished PERMANOVA
# view the permanova results
perm_get(aitchison_perm) %>% as.data.frame()
#> Df SumOfSqs R2 F Pr(>F)
@@ -218,8 +231,8 @@ your permanova directly using the ord\_plot function with constraints.
``` r
perm2 <- dist_permanova(data = aitchison_dists, variables = c("weight", "female"), seed = 321)
#> Dropping samples with missings: 2
-#> 2021-04-08 20:42:38 - Starting PERMANOVA with 999 perms with 1 processes
-#> 2021-04-08 20:42:39 - Finished PERMANOVA
+#> 2021-04-12 12:46:54 - Starting PERMANOVA with 999 perms with 1 processes
+#> 2021-04-12 12:46:55 - Finished PERMANOVA
perm_get(perm2)
#> Permutation test for adonis under reduced model
#> Marginal effects of terms
@@ -292,119 +305,119 @@ devtools::session_info()
#> collate en_GB.UTF-8
#> ctype en_GB.UTF-8
#> tz Europe/Amsterdam
-#> date 2021-04-08
+#> date 2021-04-12
#>
#> ─ Packages ───────────────────────────────────────────────────────────────────────────────────────
-#> package * version date lib source
-#> ade4 1.7-16 2020-10-28 [1] CRAN (R 4.0.3)
-#> ape 5.4-1 2020-08-13 [1] CRAN (R 4.0.3)
-#> Biobase 2.50.0 2020-10-27 [1] Bioconductor
-#> BiocGenerics 0.36.0 2020-10-27 [1] Bioconductor
-#> biomformat 1.18.0 2020-10-27 [1] Bioconductor
-#> Biostrings 2.58.0 2020-10-27 [1] Bioconductor
-#> cachem 1.0.4 2021-02-13 [1] CRAN (R 4.0.3)
-#> Cairo 1.5-12.2 2020-07-07 [1] CRAN (R 4.0.3)
-#> callr 3.6.0 2021-03-28 [1] CRAN (R 4.0.3)
-#> circlize 0.4.12 2021-01-08 [1] CRAN (R 4.0.3)
-#> cli 2.4.0 2021-04-05 [1] CRAN (R 4.0.3)
-#> clue 0.3-58 2020-12-03 [1] CRAN (R 4.0.3)
-#> cluster 2.1.0 2019-06-19 [2] CRAN (R 4.0.3)
-#> codetools 0.2-18 2020-11-04 [1] CRAN (R 4.0.3)
-#> colorspace 2.0-0 2020-11-11 [1] CRAN (R 4.0.3)
-#> ComplexHeatmap 2.6.2 2020-11-12 [1] Bioconductor
-#> crayon 1.4.1 2021-02-08 [1] CRAN (R 4.0.3)
-#> data.table 1.14.0 2021-02-21 [1] CRAN (R 4.0.3)
-#> debugme 1.1.0 2017-10-22 [1] CRAN (R 4.0.3)
-#> desc 1.3.0 2021-03-05 [1] CRAN (R 4.0.3)
-#> devtools * 2.3.2 2020-09-18 [1] CRAN (R 4.0.3)
-#> digest 0.6.27 2020-10-24 [1] CRAN (R 4.0.3)
-#> dplyr * 1.0.5 2021-03-05 [1] CRAN (R 4.0.3)
-#> ellipsis 0.3.1 2020-05-15 [1] CRAN (R 4.0.3)
-#> evaluate 0.14 2019-05-28 [1] CRAN (R 4.0.3)
-#> fansi 0.4.2 2021-01-15 [1] CRAN (R 4.0.3)
-#> farver 2.1.0 2021-02-28 [1] CRAN (R 4.0.3)
-#> fastmap 1.1.0 2021-01-25 [1] CRAN (R 4.0.3)
-#> foreach 1.5.1 2020-10-15 [1] CRAN (R 4.0.3)
-#> fs 1.5.0 2020-07-31 [1] CRAN (R 4.0.3)
-#> generics 0.1.0 2020-10-31 [1] CRAN (R 4.0.3)
-#> GetoptLong 1.0.5 2020-12-15 [1] CRAN (R 4.0.3)
-#> ggplot2 * 3.3.3 2020-12-30 [1] CRAN (R 4.0.3)
-#> GlobalOptions 0.1.2 2020-06-10 [1] CRAN (R 4.0.3)
-#> glue 1.4.2 2020-08-27 [1] CRAN (R 4.0.3)
-#> gtable 0.3.0 2019-03-25 [1] CRAN (R 4.0.3)
-#> highr 0.8 2019-03-20 [1] CRAN (R 4.0.3)
-#> hms 1.0.0 2021-01-13 [1] CRAN (R 4.0.3)
-#> htmltools 0.5.1.1 2021-01-22 [1] CRAN (R 4.0.3)
-#> igraph 1.2.6 2020-10-06 [1] CRAN (R 4.0.3)
-#> IRanges 2.24.1 2020-12-12 [1] Bioconductor
-#> iterators 1.0.13 2020-10-15 [1] CRAN (R 4.0.3)
-#> jsonlite 1.7.2 2020-12-09 [1] CRAN (R 4.0.3)
-#> knitr 1.31 2021-01-27 [1] CRAN (R 4.0.3)
-#> labeling 0.4.2 2020-10-20 [1] CRAN (R 4.0.3)
-#> lattice 0.20-41 2020-04-02 [2] CRAN (R 4.0.3)
-#> lifecycle 1.0.0 2021-02-15 [1] CRAN (R 4.0.3)
-#> magick 2.7.1 2021-03-20 [1] CRAN (R 4.0.3)
-#> magrittr 2.0.1 2020-11-17 [1] CRAN (R 4.0.3)
-#> MASS 7.3-53 2020-09-09 [2] CRAN (R 4.0.3)
-#> Matrix 1.3-2 2021-01-06 [1] CRAN (R 4.0.3)
-#> matrixStats 0.58.0 2021-01-29 [1] CRAN (R 4.0.3)
-#> memoise 2.0.0 2021-01-26 [1] CRAN (R 4.0.3)
-#> mgcv 1.8-33 2020-08-27 [2] CRAN (R 4.0.3)
-#> microbiome 1.12.0 2020-10-27 [1] Bioconductor
-#> microViz * 0.7.0 2021-04-08 [1] local
-#> multtest 2.46.0 2020-10-27 [1] Bioconductor
-#> munsell 0.5.0 2018-06-12 [1] CRAN (R 4.0.3)
-#> nlme 3.1-149 2020-08-23 [2] CRAN (R 4.0.3)
-#> permute 0.9-5 2019-03-12 [1] CRAN (R 4.0.3)
-#> phyloseq * 1.34.0 2020-10-27 [1] Bioconductor
-#> pillar 1.5.1 2021-03-05 [1] CRAN (R 4.0.3)
-#> pkgbuild 1.2.0 2020-12-15 [1] CRAN (R 4.0.3)
-#> pkgconfig 2.0.3 2019-09-22 [1] CRAN (R 4.0.3)
-#> pkgdown * 1.6.1 2020-09-12 [1] CRAN (R 4.0.3)
-#> pkgload 1.2.0 2021-02-23 [1] CRAN (R 4.0.3)
-#> plyr 1.8.6 2020-03-03 [1] CRAN (R 4.0.3)
-#> png 0.1-7 2013-12-03 [1] CRAN (R 4.0.3)
-#> prettyunits 1.1.1 2020-01-24 [1] CRAN (R 4.0.3)
-#> processx 3.5.0 2021-03-23 [1] CRAN (R 4.0.3)
-#> progress 1.2.2 2019-05-16 [1] CRAN (R 4.0.3)
-#> ps 1.6.0 2021-02-28 [1] CRAN (R 4.0.3)
-#> purrr 0.3.4 2020-04-17 [1] CRAN (R 4.0.3)
-#> R6 2.5.0 2020-10-28 [1] CRAN (R 4.0.3)
-#> RColorBrewer 1.1-2 2014-12-07 [1] CRAN (R 4.0.3)
-#> Rcpp 1.0.6 2021-01-15 [1] CRAN (R 4.0.3)
-#> registry 0.5-1 2019-03-05 [1] CRAN (R 4.0.3)
-#> remotes 2.2.0 2020-07-21 [1] CRAN (R 4.0.3)
-#> reshape2 1.4.4 2020-04-09 [1] CRAN (R 4.0.3)
-#> rhdf5 2.34.0 2020-10-27 [1] Bioconductor
-#> rhdf5filters 1.2.0 2020-10-27 [1] Bioconductor
-#> Rhdf5lib 1.12.1 2021-01-26 [1] Bioconductor
-#> rjson 0.2.20 2018-06-08 [1] CRAN (R 4.0.3)
-#> rlang 0.4.10 2020-12-30 [1] CRAN (R 4.0.3)
-#> rmarkdown 2.7 2021-02-19 [1] CRAN (R 4.0.3)
-#> rprojroot 2.0.2 2020-11-15 [1] CRAN (R 4.0.3)
-#> Rtsne 0.15 2018-11-10 [1] CRAN (R 4.0.3)
-#> S4Vectors 0.28.1 2020-12-09 [1] Bioconductor
-#> scales 1.1.1 2020-05-11 [1] CRAN (R 4.0.3)
-#> seriation 1.2-9 2020-10-01 [1] CRAN (R 4.0.3)
-#> sessioninfo 1.1.1 2018-11-05 [1] CRAN (R 4.0.3)
-#> shape 1.4.5 2020-09-13 [1] CRAN (R 4.0.3)
-#> stringi 1.5.3 2020-09-09 [1] CRAN (R 4.0.3)
-#> stringr 1.4.0 2019-02-10 [1] CRAN (R 4.0.3)
-#> survival 3.2-7 2020-09-28 [2] CRAN (R 4.0.3)
-#> testthat 3.0.2 2021-02-14 [1] CRAN (R 4.0.3)
-#> tibble 3.1.0 2021-02-25 [1] CRAN (R 4.0.3)
-#> tidyr 1.1.3 2021-03-03 [1] CRAN (R 4.0.3)
-#> tidyselect 1.1.0 2020-05-11 [1] CRAN (R 4.0.3)
-#> TSP 1.1-10 2020-04-17 [1] CRAN (R 4.0.3)
-#> usethis * 2.0.1 2021-02-10 [1] CRAN (R 4.0.3)
-#> utf8 1.2.1 2021-03-12 [1] CRAN (R 4.0.3)
-#> vctrs 0.3.7 2021-03-29 [1] CRAN (R 4.0.3)
-#> vegan 2.5-7 2020-11-28 [1] CRAN (R 4.0.3)
-#> withr 2.4.1 2021-01-26 [1] CRAN (R 4.0.3)
-#> xfun 0.22 2021-03-11 [1] CRAN (R 4.0.3)
-#> XVector 0.30.0 2020-10-27 [1] Bioconductor
-#> yaml 2.2.1 2020-02-01 [1] CRAN (R 4.0.3)
-#> zlibbioc 1.36.0 2020-10-27 [1] Bioconductor
+#> package * version date lib source
+#> ade4 1.7-16 2020-10-28 [1] CRAN (R 4.0.3)
+#> ape 5.4-1 2020-08-13 [1] CRAN (R 4.0.3)
+#> Biobase 2.50.0 2020-10-27 [1] Bioconductor
+#> BiocGenerics 0.36.0 2020-10-27 [1] Bioconductor
+#> biomformat 1.18.0 2020-10-27 [1] Bioconductor
+#> Biostrings 2.58.0 2020-10-27 [1] Bioconductor
+#> cachem 1.0.4 2021-02-13 [1] CRAN (R 4.0.3)
+#> Cairo 1.5-12.2 2020-07-07 [1] CRAN (R 4.0.3)
+#> callr 3.6.0 2021-03-28 [1] CRAN (R 4.0.3)
+#> circlize 0.4.12 2021-01-08 [1] CRAN (R 4.0.3)
+#> cli 2.4.0 2021-04-05 [1] CRAN (R 4.0.3)
+#> clue 0.3-58 2020-12-03 [1] CRAN (R 4.0.3)
+#> cluster 2.1.0 2019-06-19 [2] CRAN (R 4.0.3)
+#> codetools 0.2-18 2020-11-04 [1] CRAN (R 4.0.3)
+#> colorspace 2.0-0 2020-11-11 [1] CRAN (R 4.0.3)
+#> ComplexHeatmap 2.6.2 2020-11-12 [1] Bioconductor
+#> crayon 1.4.1 2021-02-08 [1] CRAN (R 4.0.3)
+#> data.table 1.14.0 2021-02-21 [1] CRAN (R 4.0.3)
+#> debugme 1.1.0 2017-10-22 [1] CRAN (R 4.0.3)
+#> desc 1.3.0 2021-03-05 [1] CRAN (R 4.0.3)
+#> devtools * 2.3.2 2020-09-18 [1] CRAN (R 4.0.3)
+#> digest 0.6.27 2020-10-24 [1] CRAN (R 4.0.3)
+#> dplyr * 1.0.5 2021-03-05 [1] CRAN (R 4.0.3)
+#> ellipsis 0.3.1 2020-05-15 [1] CRAN (R 4.0.3)
+#> evaluate 0.14 2019-05-28 [1] CRAN (R 4.0.3)
+#> fansi 0.4.2 2021-01-15 [1] CRAN (R 4.0.3)
+#> farver 2.1.0 2021-02-28 [1] CRAN (R 4.0.3)
+#> fastmap 1.1.0 2021-01-25 [1] CRAN (R 4.0.3)
+#> foreach 1.5.1 2020-10-15 [1] CRAN (R 4.0.3)
+#> fs 1.5.0 2020-07-31 [1] CRAN (R 4.0.3)
+#> generics 0.1.0 2020-10-31 [1] CRAN (R 4.0.3)
+#> GetoptLong 1.0.5 2020-12-15 [1] CRAN (R 4.0.3)
+#> ggplot2 * 3.3.3 2020-12-30 [1] CRAN (R 4.0.3)
+#> GlobalOptions 0.1.2 2020-06-10 [1] CRAN (R 4.0.3)
+#> glue 1.4.2 2020-08-27 [1] CRAN (R 4.0.3)
+#> gtable 0.3.0 2019-03-25 [1] CRAN (R 4.0.3)
+#> highr 0.8 2019-03-20 [1] CRAN (R 4.0.3)
+#> hms 1.0.0 2021-01-13 [1] CRAN (R 4.0.3)
+#> htmltools 0.5.1.1 2021-01-22 [1] CRAN (R 4.0.3)
+#> igraph 1.2.6 2020-10-06 [1] CRAN (R 4.0.3)
+#> IRanges 2.24.1 2020-12-12 [1] Bioconductor
+#> iterators 1.0.13 2020-10-15 [1] CRAN (R 4.0.3)
+#> jsonlite 1.7.2 2020-12-09 [1] CRAN (R 4.0.3)
+#> knitr 1.31 2021-01-27 [1] CRAN (R 4.0.3)
+#> labeling 0.4.2 2020-10-20 [1] CRAN (R 4.0.3)
+#> lattice 0.20-41 2020-04-02 [2] CRAN (R 4.0.3)
+#> lifecycle 1.0.0 2021-02-15 [1] CRAN (R 4.0.3)
+#> magick 2.7.1 2021-03-20 [1] CRAN (R 4.0.3)
+#> magrittr 2.0.1 2020-11-17 [1] CRAN (R 4.0.3)
+#> MASS 7.3-53 2020-09-09 [2] CRAN (R 4.0.3)
+#> Matrix 1.3-2 2021-01-06 [1] CRAN (R 4.0.3)
+#> matrixStats 0.58.0 2021-01-29 [1] CRAN (R 4.0.3)
+#> memoise 2.0.0 2021-01-26 [1] CRAN (R 4.0.3)
+#> mgcv 1.8-33 2020-08-27 [2] CRAN (R 4.0.3)
+#> microbiome 1.12.0 2020-10-27 [1] Bioconductor
+#> microViz * 0.7.0.9001 2021-04-12 [1] local
+#> multtest 2.46.0 2020-10-27 [1] Bioconductor
+#> munsell 0.5.0 2018-06-12 [1] CRAN (R 4.0.3)
+#> nlme 3.1-149 2020-08-23 [2] CRAN (R 4.0.3)
+#> permute 0.9-5 2019-03-12 [1] CRAN (R 4.0.3)
+#> phyloseq * 1.34.0 2020-10-27 [1] Bioconductor
+#> pillar 1.5.1 2021-03-05 [1] CRAN (R 4.0.3)
+#> pkgbuild 1.2.0 2020-12-15 [1] CRAN (R 4.0.3)
+#> pkgconfig 2.0.3 2019-09-22 [1] CRAN (R 4.0.3)
+#> pkgdown * 1.6.1 2020-09-12 [1] CRAN (R 4.0.3)
+#> pkgload 1.2.0 2021-02-23 [1] CRAN (R 4.0.3)
+#> plyr 1.8.6 2020-03-03 [1] CRAN (R 4.0.3)
+#> png 0.1-7 2013-12-03 [1] CRAN (R 4.0.3)
+#> prettyunits 1.1.1 2020-01-24 [1] CRAN (R 4.0.3)
+#> processx 3.5.0 2021-03-23 [1] CRAN (R 4.0.3)
+#> progress 1.2.2 2019-05-16 [1] CRAN (R 4.0.3)
+#> ps 1.6.0 2021-02-28 [1] CRAN (R 4.0.3)
+#> purrr 0.3.4 2020-04-17 [1] CRAN (R 4.0.3)
+#> R6 2.5.0 2020-10-28 [1] CRAN (R 4.0.3)
+#> RColorBrewer 1.1-2 2014-12-07 [1] CRAN (R 4.0.3)
+#> Rcpp 1.0.6 2021-01-15 [1] CRAN (R 4.0.3)
+#> registry 0.5-1 2019-03-05 [1] CRAN (R 4.0.3)
+#> remotes 2.2.0 2020-07-21 [1] CRAN (R 4.0.3)
+#> reshape2 1.4.4 2020-04-09 [1] CRAN (R 4.0.3)
+#> rhdf5 2.34.0 2020-10-27 [1] Bioconductor
+#> rhdf5filters 1.2.0 2020-10-27 [1] Bioconductor
+#> Rhdf5lib 1.12.1 2021-01-26 [1] Bioconductor
+#> rjson 0.2.20 2018-06-08 [1] CRAN (R 4.0.3)
+#> rlang 0.4.10 2020-12-30 [1] CRAN (R 4.0.3)
+#> rmarkdown 2.7 2021-02-19 [1] CRAN (R 4.0.3)
+#> rprojroot 2.0.2 2020-11-15 [1] CRAN (R 4.0.3)
+#> Rtsne 0.15 2018-11-10 [1] CRAN (R 4.0.3)
+#> S4Vectors 0.28.1 2020-12-09 [1] Bioconductor
+#> scales 1.1.1 2020-05-11 [1] CRAN (R 4.0.3)
+#> seriation 1.2-9 2020-10-01 [1] CRAN (R 4.0.3)
+#> sessioninfo 1.1.1 2018-11-05 [1] CRAN (R 4.0.3)
+#> shape 1.4.5 2020-09-13 [1] CRAN (R 4.0.3)
+#> stringi 1.5.3 2020-09-09 [1] CRAN (R 4.0.3)
+#> stringr 1.4.0 2019-02-10 [1] CRAN (R 4.0.3)
+#> survival 3.2-7 2020-09-28 [2] CRAN (R 4.0.3)
+#> testthat 3.0.2 2021-02-14 [1] CRAN (R 4.0.3)
+#> tibble 3.1.0 2021-02-25 [1] CRAN (R 4.0.3)
+#> tidyr 1.1.3 2021-03-03 [1] CRAN (R 4.0.3)
+#> tidyselect 1.1.0 2020-05-11 [1] CRAN (R 4.0.3)
+#> TSP 1.1-10 2020-04-17 [1] CRAN (R 4.0.3)
+#> usethis * 2.0.1 2021-02-10 [1] CRAN (R 4.0.3)
+#> utf8 1.2.1 2021-03-12 [1] CRAN (R 4.0.3)
+#> vctrs 0.3.7 2021-03-29 [1] CRAN (R 4.0.3)
+#> vegan 2.5-7 2020-11-28 [1] CRAN (R 4.0.3)
+#> withr 2.4.1 2021-01-26 [1] CRAN (R 4.0.3)
+#> xfun 0.22 2021-03-11 [1] CRAN (R 4.0.3)
+#> XVector 0.30.0 2020-10-27 [1] Bioconductor
+#> yaml 2.2.1 2020-02-01 [1] CRAN (R 4.0.3)
+#> zlibbioc 1.36.0 2020-10-27 [1] Bioconductor
#>
#> [1] /home/david/R/x86_64-pc-linux-gnu-library/4.0
#> [2] /opt/R/4.0.3/lib/R/library
diff --git a/vignettes/articles/phyloseq.Rmd b/vignettes/articles/phyloseq.Rmd
new file mode 100644
index 00000000..8e57ea6c
--- /dev/null
+++ b/vignettes/articles/phyloseq.Rmd
@@ -0,0 +1,164 @@
+---
+title: "Working with phyloseq objects"
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+ collapse = TRUE,
+ comment = "#>"
+)
+```
+
+## Intro
+
+This tutorial will show you how microViz makes working with phyloseq objects easier.
+
+```{r setup}
+library(dplyr)
+library(phyloseq)
+library(microViz)
+```
+
+## Getting your data into phyloseq
+
+phyloseq objects are probably the most commonly used data format for working with microbiome data in R.
+
+The creator of phyloseq, [Paul J. McMurdie](https://github.com/joey711), explains the structure of phyloseq objects and how to construct them on the [phyloseq website](https://joey711.github.io/phyloseq/import-data.html#phyloseq-ize_data_already_in_r).
+
+- [biom format](http://biom-format.org/) files can be imported to phyloseq with the [`import_biom`](https://joey711.github.io/phyloseq/import-data.html#the_import_family_of_functions) function. Such biom files are generated (or can be) from many processing tools including QIIME [1](http://qiime.org/tutorials/index.html) / [2](https://docs.qiime2.org/2021.2/tutorials/exporting/), [MetaPhlAn](http://segatalab.cibio.unitn.it/tools/metaphlan/), and [NG-Tax](https://doi.org/10.3389/fgene.2019.01366).
+
+- [mothur](https://mothur.org/) output is also directly supported via phyloseq's [`import_mothur`](https://joey711.github.io/phyloseq/import-data.html#_import_mothur) function.
+
+- [DADA2](https://benjjneb.github.io/dada2/) output can converted to phyloseq according to these [DADA2 handoff instructions](https://benjjneb.github.io/dada2/tutorial.html#bonus-handoff-to-phyloseq)
+
+Don't worry too much about getting all of your sample metadata into your biom file or phyloseq object at the start, as `ps_join()` makes it easy to add sample data later.
+
+```{r example data}
+# This tutorial will just use some example data
+# It is already available as a phyloseq object from the corncob package
+example_ps <- corncob::ibd_phylo
+example_ps
+```
+
+### Validating your phyloseq
+
+phyloseq checks that your sample and taxa names are consistent across the different slots of the phyloseq object. microViz provides `phyloseq_validate()` to check for and fix other possible problems with your phyloseq that might cause problems in later analyses. It is recommended to run this at the start of your analyses, and fix any problems identified.
+
+```{r validate ps}
+example_ps <- phyloseq_validate(example_ps, remove_undetected = TRUE)
+example_ps <- tax_fix(example_ps)
+
+```
+
+## microViz and phyloseq overview
+
+Once you have a valid phyloseq object, microViz provides several helpful functions for manipulating that object. The names and syntax of some functions will be familiar to users of dplyr, and reading [the dplyr help pages](https://dplyr.tidyverse.org/) may be useful for getting the most out of these functions.
+
+- Add a data.frame of metadata to the sample_data slot with `ps_join()`
+
+- Compute new sample_data variables with `ps_mutate()`
+
+- Subset or reorder variables in sample_data with `ps_select()`
+
+- Subset samples based on sample_data variables with `ps_filter()`
+
+- Reorder samples (can be useful for examining sample data or plotting) with:
+
+ - `ps_reorder()` : manually set sample order
+
+ - `ps_arrange()` : order samples using sample_data variables
+
+ - `ps_seriate()` : order samples according to microbiome similarity
+
+- Remove duplicated/repeated samples with `ps_dedupe()`
+
+- Remove samples with missing values in sample_data with `ps_drop_incomplete()`
+
+Check out the examples section on each function's [reference](https://david-barnett.github.io/microViz/reference/index.html#section-manipulating-sample-data) page for extensive usage examples.
+
+## Example sample manipulation
+
+Lets look at the sample data already in our example phyloseq.
+
+```{r example data tbl}
+# 91 samples, with 15 sample_data variables
+example_ps
+# return sample data as a tibble for pretty printing
+samdat_tbl(example_ps)
+```
+
+Maybe you want to only select participants who have IBD (not controls). You can do that by filtering samples based on the values of the sample data variable: ibd
+
+```{r select ibd}
+example_ps %>% ps_filter(ibd == "ibd") # it is essential to use `==` , not just one `=`
+# notice that taxa that no longer appear in the remaining 67 samples have been removed!
+```
+
+More complicated filtering rules can be applied. Let's say you want female IBD patients with "mild" or "severe" activity, who are at least 13 years old.
+
+```{r select ibd 2}
+partial_ps <- example_ps %>%
+ ps_filter(
+ gender == "female",
+ activity %in% c("mild", "severe"),
+ age >= 13
+ )
+partial_ps
+```
+
+Let's have a look at the sample data of these participants. We will also arrange the samples grouped by disease and in descending age order, and select only a few interesting variables to show.
+
+```{r arrange and select}
+partial_ps %>%
+ ps_arrange(DiseaseState, desc(age)) %>%
+ ps_select(DiseaseState, age, matches("activ"), abx) %>% # selection order is respected
+ samdat_tbl() # this adds the .sample_name variable
+```
+
+You can also sort sample by microbiome similarity with `ps_seriate()`.
+
+```{r seriate and plot}
+partial_ps %>%
+ tax_agg("Genus") %>%
+ ps_seriate(dist = "bray", method = "OLO_ward") %>% # these are the defaults
+ comp_barplot(tax_level = "Genus", sample_order = "default", n_taxa = 10)
+# note that comp_barplot with sample_order = "bray" will run
+# this ps_seriate call internally, so you don't have to!
+
+```
+
+You can also arrange samples by abundance of one of more microbes using `ps_arrange()` with `.target = "otu_table"`. Arranging by taxon can only be done at the current taxonomic rank, so we will aggregate to Genus level first.
+
+```{r arrange by taxon}
+# Arranging by decreasing Bacteroides abundance
+partial_ps %>%
+ tax_agg("Genus") %>%
+ ps_arrange(desc(Bacteroides), .target = "otu_table") %>%
+ otu_get() %>% # get the otu table
+ .[, 1:7] # show only a subset of the otu_table
+
+# Plot samples' compositions in this order
+partial_ps %>%
+ tax_agg("Genus") %>%
+ ps_arrange(desc(Bacteroides), .target = "otu_table") %>%
+ comp_barplot(tax_level = "Genus", sample_order = "default", n_taxa = 10)
+# Notice this is sorted by bacteroides counts
+# (this doesn't quite match relative abundance % due to sequencing depth variation)
+```
+
+## Other notes:
+
+### `ps_filter()` vs. `phyloseq::subset_samples()`
+
+As well as filtering your samples, `ps_filter()` might also modify the otu_table and tax_table of the phyloseq object (unlike `phyloseq::subset_samples()`, which never does this).
+
+Why does it do this? \
+If you remove many samples from your dataset, often your phyloseq object will be left with taxa that never occur in any of the remaining samples (i.e. total counts of zero). `ps_filter()` removes those absent taxa by default.
+
+If you don't want this, you can set the `.keep_all_taxa` argument to `TRUE` in `ps_filter`.
+
+## Technical log
+
+```{r session info}
+devtools::session_info()
+```