An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

A categorical metadata column name to use for the x-axis. Or NULL, which groups all samples into a single category.

Alpha diversity metric(s) to use. Options are: "OTUs", "Shannon", "Chao1", "Simpson", and/or "InvSimpson". Set adiv=".all" to use all metrics. Multiple/abbreviated values allowed. Default: "Shannon"

One or more of c("bar", "box" ("x"), "violin", "dot", "strip", "crossbar", "errorbar", "linerange", "pointrange"). Single letter abbreviations are also accepted. For instance, c("box", "dot") is equivalent to c("x", "d") and "xd". Default: "x"

Dataset field with the statistical groups. Must be categorical. Default: NULL

Dataset field(s) to use for faceting. Must be categorical. Default: NULL

How to color the groups. Options are:

TRUE -

Automatically select colorblind-friendly colors.

FALSE or NULL -

Don't use colors.

a palette name -

Auto-select colors from this set. E.g. "okabe"

character vector -

Custom colors to use. E.g. c("red", "#00FF00")

named character vector -

Explicit mapping. E.g. c(Male = "blue", Female = "red")

See "Aesthetics" section below for additional information. Default: TRUE

Shapes for each group. Options are similar to colors's: TRUE, FALSE, NULL, shape names (typically integers 0 - 17), or a named vector mapping groups to specific shape names. See "Aesthetics" section below for additional information. Default: TRUE

Patterns for each group. Options are similar to colors's: TRUE, FALSE, NULL, pattern names ("brick", "chevron", "fish", "grid", etc), or a named vector mapping groups to specific pattern names. See "Aesthetics" section below for additional information. Default: FALSE

Transpose the axes, so that taxa are present as rows instead of columns. Default: FALSE

Shade every other x position. Default: same as flip

How to calculate min/max of the crossbar, errorbar, linerange, and pointrange layers. Options are: "ci" (confidence interval), "range", "sd" (standard deviation), "se" (standard error), and "mad" (median absolute deviation). The center mark of crossbar and pointrange represents the mean, except for "mad" in which case it represents the median. Default: "ci"

The confidence level for calculating a confidence interval. Default: 0.95

Method to use for multiple comparisons adjustment of p-values. Run p.adjust.methods for a list of available options. Default: "fdr"

Show boxplot outliers? TRUE to always show. FALSE to always hide. NULL to only hide them when overlaying a dot or strip chart. Default: NULL

Angle of the labels at the bottom of the plot. Options are "auto", '0', '30', and '90'. Default: "auto".

Minimum adjusted p-value to display on the plot with a bracket.

p.label = 0.05 -

Show p-values that are <= 0.05.

p.label = 0 -

Don't show any p-values on the plot.

p.label = 1 -

Show all p-values on the plot.

If a numeric vector with more than one value is provided, they will be used as breaks for asterisk notation. Default: 0.05

Transformation to apply. Options are: c("none", "rank", "log", "log1p", "sqrt", "percent"). "rank" is useful for correcting for non-normally distributions before applying regression statistics. Default: "none"

Add methodology caption beneath the plot. Default: TRUE

Additional parameters to pass along to ggplot2 functions. Prefix a parameter name with a layer name to pass it to only that layer. For instance, d.size = 2 ensures only the points on the dot layer have their size set to 2.

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

Dataset field with the x-axis values. Equivalent to the regr argument in stats_table(). Required.

Alpha diversity metric(s) to use. Options are: "OTUs", "Shannon", "Chao1", "Simpson", and/or "InvSimpson". Set adiv=".all" to use all metrics. Multiple/abbreviated values allowed. Default: "Shannon"

One or more of c("trend", "confidence", "point", "name", "residual"). Single letter abbreviations are also accepted. For instance, c("trend", "point") is equivalent to c("t", "p") and "tp". Default: "tc"

Dataset field with the statistical groups. Must be categorical. Default: NULL

Dataset field(s) to use for faceting. Must be categorical. Default: NULL

How to color the groups. Options are:

TRUE -

Automatically select colorblind-friendly colors.

FALSE or NULL -

Don't use colors.

a palette name -

Auto-select colors from this set. E.g. "okabe"

character vector -

Custom colors to use. E.g. c("red", "#00FF00")

named character vector -

Explicit mapping. E.g. c(Male = "blue", Female = "red")

See "Aesthetics" section below for additional information. Default: TRUE

Shapes for each group. Options are similar to colors's: TRUE, FALSE, NULL, shape names (typically integers 0 - 17), or a named vector mapping groups to specific shape names. See "Aesthetics" section below for additional information. Default: TRUE

Method for computing p-values: 'none', 'emmeans', or 'emtrends'. Default: 'emmeans'

How to fit the trendline. 'lm', 'log', or 'gam'. Default: 'gam'

Position(s) along the x-axis where the means or slopes should be evaluated. Default: NULL, which samples 100 evenly spaced positions and selects the position where the p-value is most significant.

The confidence level for calculating a confidence interval. Default: 0.95

Method to use for multiple comparisons adjustment of p-values. Run p.adjust.methods for a list of available options. Default: "fdr"

Transformation to apply. Options are: c("none", "rank", "log", "log1p", "sqrt", "percent"). "rank" is useful for correcting for non-normally distributions before applying regression statistics. Default: "none"

Alternative hypothesis direction. Options are '!=' (two-sided; not equal to mu), '<' (less than mu), or '>' (greater than mu). Default: '!='

Reference value to test against. Default: 0

Add methodology caption beneath the plot. Default: TRUE

Generate additional plots to aid in assessing data normality. Default: FALSE

Additional parameters to pass along to ggplot2 functions. Prefix a parameter name with a layer name to pass it to only that layer. For instance, p.size = 2 ensures only the points have their size set to 2.

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

Alpha diversity metric(s) to use. Options are: "OTUs", "Shannon", "Chao1", "Simpson", and/or "InvSimpson". Set adiv=".all" to use all metrics. Multiple/abbreviated values allowed. Default: ".all"

Transformation to apply. Options are: c("none", "rank", "log", "log1p", "sqrt", "percent"). "rank" is useful for correcting for non-normally distributions before applying regression statistics. Default: "none"

The number of CPUs to use. Set to NULL to use all available, or to 1 to disable parallel processing. Default: NULL

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

Dataset field with the x-axis (independent; predictive) values. Must be numeric. Default: NULL

Dataset field with the statistical groups. Must be categorical. Default: NULL

Alpha diversity metric(s) to use. Options are: "OTUs", "Shannon", "Chao1", "Simpson", and/or "InvSimpson". Set adiv=".all" to use all metrics. Multiple/abbreviated values allowed. Default: "Shannon"

Dataset field(s) that the data should be split by prior to any calculations. Must be categorical. Default: NULL

Transformation to apply. Options are: c("none", "rank", "log", "log1p", "sqrt", "percent"). "rank" is useful for correcting for non-normally distributions before applying regression statistics. Default: "none"

Method for computing p-values: 'wilcox', 'kruskal', 'emmeans', or 'emtrends'. Default: 'emmeans'

How to fit the trendline. 'lm', 'log', or 'gam'. Default: 'gam'

Position(s) along the x-axis where the means or slopes should be evaluated. Default: NULL, which samples 100 evenly spaced positions and selects the position where the p-value is most significant.

The confidence level for calculating a confidence interval. Default: 0.95

Alternative hypothesis direction. Options are '!=' (two-sided; not equal to mu), '<' (less than mu), or '>' (greater than mu). Default: '!='

Reference value to test against. Default: 0

Method to use for multiple comparisons adjustment of p-values. Run p.adjust.methods for a list of available options. Default: "fdr"

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

Alpha diversity metric(s) to use. Options are: "OTUs", "Shannon", "Chao1", "Simpson", and/or "InvSimpson". Set adiv=".all" to use all metrics. Multiple/abbreviated values allowed. Default: "Shannon"

Dataset field(s) to include in the output data frame, or '.all' to include all metadata fields. Default: '.all'

Transformation to apply. Options are: c("none", "rank", "log", "log1p", "sqrt", "percent"). "rank" is useful for correcting for non-normally distributions before applying regression statistics. Default: "none"

The number of CPUs to use. Set to NULL to use all available, or to 1 to disable parallel processing. Default: NULL

An rbiom object, such as from as_rbiom().

Not used.

An rbiom object, such as from as_rbiom().

Not used.

Object which can be coerced to an rbiom-class object. For example:

file -

Filepath or URL to a biom file.

matrix -

An abundance matrix with OTUs in rows and samples in columns.

phyloseq-class object -

From the phyloseq Bioconductor R package.

list -

With counts and optionally metadata, taxonomy, tree, etc (see details).

Properties to overwrite in biom: metadata, taxonomy, tree, etc (see details). Setting underscores here will pass it to read_tree().

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

A categorical metadata column name to use for the x-axis. Or NULL, which groups all samples into a single category.

Beta diversity distance algorithm(s) to use. Options are: "Bray-Curtis", "Manhattan", "Euclidean", "Jaccard", and "UniFrac". For "UniFrac", a phylogenetic tree must be present in biom or explicitly provided via ⁠tree=⁠. Multiple/abbreviated values allowed. Default: "Bray-Curtis"

One or more of c("bar", "box" ("x"), "violin", "dot", "strip", "crossbar", "errorbar", "linerange", "pointrange"). Single letter abbreviations are also accepted. For instance, c("box", "dot") is equivalent to c("x", "d") and "xd". Default: "x"

Take relative abundances into account. When weighted=FALSE, only presence/absence is considered. Multiple values allowed. Default: TRUE

A phylo object representing the phylogenetic relationships of the taxa in biom. Only required when computing UniFrac distances. Default: biom$tree

Dataset field(s) for intra- or inter- sample comparisons. Alternatively, dataset field names given elsewhere can be prefixed with '==' or '!=' to assign them to within or between, respectively. Default: NULL

Dataset field with the statistical groups. Must be categorical. Default: NULL

Dataset field(s) to use for faceting. Must be categorical. Default: NULL

How to color the groups. Options are:

TRUE -

Automatically select colorblind-friendly colors.

FALSE or NULL -

Don't use colors.

a palette name -

Auto-select colors from this set. E.g. "okabe"

character vector -

Custom colors to use. E.g. c("red", "#00FF00")

named character vector -

Explicit mapping. E.g. c(Male = "blue", Female = "red")

See "Aesthetics" section below for additional information. Default: TRUE

Shapes for each group. Options are similar to colors's: TRUE, FALSE, NULL, shape names (typically integers 0 - 17), or a named vector mapping groups to specific shape names. See "Aesthetics" section below for additional information. Default: TRUE

Patterns for each group. Options are similar to colors's: TRUE, FALSE, NULL, pattern names ("brick", "chevron", "fish", "grid", etc), or a named vector mapping groups to specific pattern names. See "Aesthetics" section below for additional information. Default: FALSE

Transpose the axes, so that taxa are present as rows instead of columns. Default: FALSE

Shade every other x position. Default: same as flip

How to calculate min/max of the crossbar, errorbar, linerange, and pointrange layers. Options are: "ci" (confidence interval), "range", "sd" (standard deviation), "se" (standard error), and "mad" (median absolute deviation). The center mark of crossbar and pointrange represents the mean, except for "mad" in which case it represents the median. Default: "ci"

The confidence level for calculating a confidence interval. Default: 0.95

Method to use for multiple comparisons adjustment of p-values. Run p.adjust.methods for a list of available options. Default: "fdr"

Show boxplot outliers? TRUE to always show. FALSE to always hide. NULL to only hide them when overlaying a dot or strip chart. Default: NULL

Angle of the labels at the bottom of the plot. Options are "auto", '0', '30', and '90'. Default: "auto".

Minimum adjusted p-value to display on the plot with a bracket.

p.label = 0.05 -

Show p-values that are <= 0.05.

p.label = 0 -

Don't show any p-values on the plot.

p.label = 1 -

Show all p-values on the plot.

If a numeric vector with more than one value is provided, they will be used as breaks for asterisk notation. Default: 0.05

Transformation to apply. Options are: c("none", "rank", "log", "log1p", "sqrt", "percent"). "rank" is useful for correcting for non-normally distributions before applying regression statistics. Default: "none"

Add methodology caption beneath the plot. Default: TRUE

Additional parameters to pass along to ggplot2 functions. Prefix a parameter name with a layer name to pass it to only that layer. For instance, d.size = 2 ensures only the points on the dot layer have their size set to 2.

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

Beta diversity distance algorithm(s) to use. Options are: "Bray-Curtis", "Manhattan", "Euclidean", "Jaccard", and "UniFrac". For "UniFrac", a phylogenetic tree must be present in biom or explicitly provided via ⁠tree=⁠. Multiple/abbreviated values allowed. Default: "Bray-Curtis"

Take relative abundances into account. When weighted=FALSE, only presence/absence is considered. Multiple values allowed. Default: TRUE

Only changes the "Weighted UniFrac" calculation. Divides result by the total branch weights. Default: TRUE

A phylo object representing the phylogenetic relationships of the taxa in biom. Only required when computing UniFrac distances. Default: biom$tree

Number of clusters. Default: 5L

Passed on to stats::kmeans().

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

Dataset field with the x-axis values. Equivalent to the regr argument in stats_table(). Required.

Beta diversity distance algorithm(s) to use. Options are: "Bray-Curtis", "Manhattan", "Euclidean", "Jaccard", and "UniFrac". For "UniFrac", a phylogenetic tree must be present in biom or explicitly provided via ⁠tree=⁠. Multiple/abbreviated values allowed. Default: "Bray-Curtis"

One or more of c("trend", "confidence", "point", "name", "residual"). Single letter abbreviations are also accepted. For instance, c("trend", "point") is equivalent to c("t", "p") and "tp". Default: "tc"

Take relative abundances into account. When weighted=FALSE, only presence/absence is considered. Multiple values allowed. Default: TRUE

A phylo object representing the phylogenetic relationships of the taxa in biom. Only required when computing UniFrac distances. Default: biom$tree

Dataset field(s) for intra- or inter- sample comparisons. Alternatively, dataset field names given elsewhere can be prefixed with '==' or '!=' to assign them to within or between, respectively. Default: NULL

Dataset field with the statistical groups. Must be categorical. Default: NULL

Dataset field(s) to use for faceting. Must be categorical. Default: NULL

How to color the groups. Options are:

TRUE -

Automatically select colorblind-friendly colors.

FALSE or NULL -

Don't use colors.

a palette name -

Auto-select colors from this set. E.g. "okabe"

character vector -

Custom colors to use. E.g. c("red", "#00FF00")

named character vector -

Explicit mapping. E.g. c(Male = "blue", Female = "red")

See "Aesthetics" section below for additional information. Default: TRUE

Shapes for each group. Options are similar to colors's: TRUE, FALSE, NULL, shape names (typically integers 0 - 17), or a named vector mapping groups to specific shape names. See "Aesthetics" section below for additional information. Default: TRUE

Method for computing p-values: 'none', 'emmeans', or 'emtrends'. Default: 'emmeans'

How to fit the trendline. 'lm', 'log', or 'gam'. Default: 'gam'

Position(s) along the x-axis where the means or slopes should be evaluated. Default: NULL, which samples 100 evenly spaced positions and selects the position where the p-value is most significant.

The confidence level for calculating a confidence interval. Default: 0.95

Method to use for multiple comparisons adjustment of p-values. Run p.adjust.methods for a list of available options. Default: "fdr"

Transformation to apply. Options are: c("none", "rank", "log", "log1p", "sqrt", "percent"). "rank" is useful for correcting for non-normally distributions before applying regression statistics. Default: "none"

When transform="rank", how to rank identical values. Options are: c("average", "first", "last", "random", "max", "min"). See rank() for details. Default: "random"

Random seed for permutations. Must be a non-negative integer. Default: 0

Alternative hypothesis direction. Options are '!=' (two-sided; not equal to mu), '<' (less than mu), or '>' (greater than mu). Default: '!='

Reference value to test against. Default: 0

Add methodology caption beneath the plot. Default: TRUE

Generate additional plots to aid in assessing data normality. Default: FALSE

Additional parameters to pass along to ggplot2 functions. Prefix a parameter name with a layer name to pass it to only that layer. For instance, p.size = 2 ensures only the points have their size set to 2.

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

Beta diversity distance algorithm(s) to use. Options are: "Bray-Curtis", "Manhattan", "Euclidean", "Jaccard", and "UniFrac". For "UniFrac", a phylogenetic tree must be present in biom or explicitly provided via ⁠tree=⁠. Multiple/abbreviated values allowed. Default: "Bray-Curtis"

Take relative abundances into account. When weighted=FALSE, only presence/absence is considered. Multiple values allowed. Default: TRUE

A phylo object representing the phylogenetic relationships of the taxa in biom. Only required when computing UniFrac distances. Default: biom$tree

A character vector of metadata fields to display as tracks at the top of the plot. Or, a list as expected by the tracks argument of plot_heatmap(). Default: NULL

Color palette name, or a list with entries for label, colors, range, bins, na.color, and/or guide. See the Track Definitions section for details. Default: "devon"

Label the matrix rows and columns. You can supply a list or logical vector of length two to control row labels and column labels separately, for example label = c(rows = TRUE, cols = FALSE), or simply label = c(TRUE, FALSE). Other valid options are "rows", "cols", "both", "bottom", "right", and "none". Default: TRUE

The font size to use for the row and column labels. You can supply a numeric vector of length two to control row label sizes and column label sizes separately, for example c(rows = 20, cols = 8), or simply c(20, 8). Default: NULL, which computes: pmax(8, pmin(20, 100 / dim(mtx)))

Rescale rows or columns to all have a common min/max. Options: "none", "rows", or "cols". Default: "none"

Clustering algorithm for reordering the rows and columns by similarity. You can supply a list or character vector of length two to control the row and column clustering separately, for example clust = c(rows = "complete", cols = NA), or simply clust = c("complete", NA). Options are:

FALSE or NA -

Disable reordering.

An hclust class object

E.g. from stats::hclust().

A method name -

"ward.D", "ward.D2", "single", "complete", "average", "mcquitty", "median", or "centroid".

Default: "complete"

Draw a dendrogram for rows (left) and columns (top). You can supply a list or logical vector of length two to control the row tree and column tree separately, for example trees = c(rows = TRUE, cols = FALSE), or simply trees = c(TRUE, FALSE). Other valid options are "rows", "cols", "both", "left", "top", and "none". Default: TRUE

Aspect ratio (height/width) for entire grid. Default: 1 (square)

The height of the dendrogram or annotation tracks as a percentage of the overall grid size. Use a numeric vector of length two to assign c(top, left) independently. Default: 10 (10% of the grid's height)

Where to place the legend. Options are: "right" or "bottom". Default: "right"

Plot title. Set to TRUE for a default title, NULL for no title, or any character string. Default: TRUE

Angle of the labels at the bottom of the plot. Options are "auto", '0', '30', and '90'. Default: "auto".

When parsing the tree, should underscores be kept as is? By default they will be converted to spaces (unless the entire ID is quoted). Default FALSE

Additional arguments to pass on to ggplot2::theme(). For example, labs.subtitle = "Plot subtitle".

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

Beta diversity distance algorithm(s) to use. Options are: "Bray-Curtis", "Manhattan", "Euclidean", "Jaccard", and "UniFrac". For "UniFrac", a phylogenetic tree must be present in biom or explicitly provided via ⁠tree=⁠. Multiple/abbreviated values allowed. Default: "Bray-Curtis"

Method for reducing dimensionality. Options are:

"PCoA" -

Principal coordinate analysis; ape::pcoa().

"UMAP" -

Uniform manifold approximation and projection; uwot::umap().

"NMDS" -

Nonmetric multidimensional scaling; vegan::metaMDS().

"tSNE" -

t-distributed stochastic neighbor embedding; tsne::tsne().

Multiple/abbreviated values allowed. Default: "PCoA"

Take relative abundances into account. When weighted=FALSE, only presence/absence is considered. Multiple values allowed. Default: TRUE

One or more of c("point", "spider", "ellipse", "name", "mean", "taxon", "arrow"). The first four are sample-centric; the last three are taxa-centric. Single letter abbreviations are also accepted. For instance, c("point", "ellipse") is equivalent to c("p", "e") and "pe". Default: "pe"

The categorical or numeric metadata field over which statistics should be calculated. Required.

Dataset field(s) to use for faceting. Must be categorical. Default: NULL

How to color the groups. Options are:

TRUE -

Automatically select colorblind-friendly colors.

FALSE or NULL -

Don't use colors.

a palette name -

Auto-select colors from this set. E.g. "okabe"

character vector -

Custom colors to use. E.g. c("red", "#00FF00")

named character vector -

Explicit mapping. E.g. c(Male = "blue", Female = "red")

See "Aesthetics" section below for additional information. Default: TRUE

Shapes for each group. Options are similar to colors's: TRUE, FALSE, NULL, shape names (typically integers 0 - 17), or a named vector mapping groups to specific shape names. See "Aesthetics" section below for additional information. Default: TRUE

A phylo object representing the phylogenetic relationships of the taxa in biom. Only required when computing UniFrac distances. Default: biom$tree

Permutational test for accessing significance. Options are:

"adonis2" -

Permutational MANOVA; vegan::adonis2().

"mrpp" -

Multiple response permutation procedure; vegan::mrpp().

"none" -

Don't run any statistics.

Abbreviations are allowed. Default: "adonis2"

Random seed for permutations. Must be a non-negative integer. Default: 0

Number of random permutations to use. Default: 999

What rank(s) of taxa to display. E.g. "Phylum", "Genus", ".otu", etc. An integer vector can also be given, where 1 is the highest rank, 2 is the second highest, -1 is the lowest rank, -2 is the second lowest, and 0 is the OTU "rank". Run biom$ranks to see all options for a given rbiom object. Default: -1.

Which taxa to display. An integer value will show the top n most abundant taxa. A value 0 <= n < 1 will show any taxa with that mean abundance or greater (e.g. 0.1 implies >= 10%). A character vector of taxa names will show only those named taxa. Default: 6.

Only display taxa with the most significant differences in abundance. If p.top is >= 1, then the p.top most significant taxa are displayed. If p.top is less than one, all taxa with an adjusted p-value <= p.top are displayed. Recommended to be used in combination with the taxa parameter to set a lower bound on the mean abundance of considered taxa. Default: Inf

Method to use for multiple comparisons adjustment of p-values. Run p.adjust.methods for a list of available options. Default: "fdr"

How to handle unclassified, uncultured, and similarly ambiguous taxa names. Options are:

"singly" -

Replaces them with the OTU name.

"grouped" -

Replaces them with a higher rank's name.

"drop" -

Excludes them from the result.

"asis" -

To not check/modify any taxa names.

Abbreviations are allowed. Default: "singly"

Add methodology caption beneath the plot. Default: TRUE

When parsing the tree, should underscores be kept as is? By default they will be converted to spaces (unless the entire ID is quoted). Default FALSE

Parameters for layer geoms (e.g. ggplot2::geom_point()). Prefixing parameter names with a layer name ensures that a particular parameter is passed to, and only to, that layer. For instance, point.size = 2 or p.size = 2 ensures only the points have their size set to 2. Points can also be controlled with the pt. prefix.

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

Beta diversity distance algorithm(s) to use. Options are: "Bray-Curtis", "Manhattan", "Euclidean", "Jaccard", and "UniFrac". For "UniFrac", a phylogenetic tree must be present in biom or explicitly provided via ⁠tree=⁠. Multiple/abbreviated values allowed. Default: "Bray-Curtis"

Method for reducing dimensionality. Options are:

"PCoA" -

Principal coordinate analysis; ape::pcoa().

"UMAP" -

Uniform manifold approximation and projection; uwot::umap().

"NMDS" -

Nonmetric multidimensional scaling; vegan::metaMDS().

"tSNE" -

t-distributed stochastic neighbor embedding; tsne::tsne().

Multiple/abbreviated values allowed. Default: "PCoA"

Take relative abundances into account. When weighted=FALSE, only presence/absence is considered. Multiple values allowed. Default: TRUE

Dataset field(s) to include in the output data frame, or '.all' to include all metadata fields. Default: '.all'

Number of ordination dimensions to return. Either 2L or 3L. Default: 2L

The categorical or numeric metadata field over which statistics should be calculated. Required.

Dataset field(s) that the data should be split by prior to any calculations. Must be categorical. Default: NULL

A phylo object representing the phylogenetic relationships of the taxa in biom. Only required when computing UniFrac distances. Default: biom$tree

Permutational test for accessing significance. Options are:

"adonis2" -

Permutational MANOVA; vegan::adonis2().

"mrpp" -

Multiple response permutation procedure; vegan::mrpp().

"none" -

Don't run any statistics.

Abbreviations are allowed. Default: "adonis2"

Random seed for permutations. Must be a non-negative integer. Default: 0

Number of random permutations to use. Default: 999

What rank(s) of taxa to compute biplot coordinates and statistics for, or NULL to disable. E.g. "Phylum", "Genus", ".otu", etc. An integer vector can also be given, where 1 is the highest rank, 2 is the second highest, -1 is the lowest rank, -2 is the second lowest, and 0 is the OTU "rank". Run biom$ranks to see all options for a given rbiom object. Default: NULL.

Which taxa to display. An integer value will show the top n most abundant taxa. A value 0 <= n < 1 will show any taxa with that mean abundance or greater (e.g. 0.1 implies >= 10%). A character vector of taxa names will show only those named taxa. Default: 6.

Only display taxa with the most significant differences in abundance. If p.top is >= 1, then the p.top most significant taxa are displayed. If p.top is less than one, all taxa with an adjusted p-value <= p.top are displayed. Recommended to be used in combination with the taxa parameter to set a lower bound on the mean abundance of considered taxa. Default: Inf

Method to use for multiple comparisons adjustment of p-values. Run p.adjust.methods for a list of available options. Default: "fdr"

How to handle unclassified, uncultured, and similarly ambiguous taxa names. Options are:

"singly" -

Replaces them with the OTU name.

"grouped" -

Replaces them with a higher rank's name.

"drop" -

Excludes them from the result.

"asis" -

To not check/modify any taxa names.

Abbreviations are allowed. Default: "singly"

When parsing the tree, should underscores be kept as is? By default they will be converted to spaces (unless the entire ID is quoted). Default FALSE

Additional arguments to pass on to uwot::umap(), ape::pcoa(), vegan::metaMDS(), or tsne::tsne().

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

Dataset field with the x-axis (independent; predictive) values. Must be numeric. Default: NULL

Dataset field with the statistical groups. Must be categorical. Default: NULL

Beta diversity distance algorithm(s) to use. Options are: "Bray-Curtis", "Manhattan", "Euclidean", "Jaccard", and "UniFrac". For "UniFrac", a phylogenetic tree must be present in biom or explicitly provided via ⁠tree=⁠. Multiple/abbreviated values allowed. Default: "Bray-Curtis"

Take relative abundances into account. When weighted=FALSE, only presence/absence is considered. Multiple values allowed. Default: TRUE

A phylo object representing the phylogenetic relationships of the taxa in biom. Only required when computing UniFrac distances. Default: biom$tree

Dataset field(s) for intra- or inter- sample comparisons. Alternatively, dataset field names given elsewhere can be prefixed with '==' or '!=' to assign them to within or between, respectively. Default: NULL

Dataset field(s) that the data should be split by prior to any calculations. Must be categorical. Default: NULL

Transformation to apply. Options are: c("none", "rank", "log", "log1p", "sqrt", "percent"). "rank" is useful for correcting for non-normally distributions before applying regression statistics. Default: "none"

Method for computing p-values: 'wilcox', 'kruskal', 'emmeans', or 'emtrends'. Default: 'emmeans'

How to fit the trendline. 'lm', 'log', or 'gam'. Default: 'gam'

Position(s) along the x-axis where the means or slopes should be evaluated. Default: NULL, which samples 100 evenly spaced positions and selects the position where the p-value is most significant.

The confidence level for calculating a confidence interval. Default: 0.95

Alternative hypothesis direction. Options are '!=' (two-sided; not equal to mu), '<' (less than mu), or '>' (greater than mu). Default: '!='

Reference value to test against. Default: 0

Method to use for multiple comparisons adjustment of p-values. Run p.adjust.methods for a list of available options. Default: "fdr"

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

Beta diversity distance algorithm(s) to use. Options are: "Bray-Curtis", "Manhattan", "Euclidean", "Jaccard", and "UniFrac". For "UniFrac", a phylogenetic tree must be present in biom or explicitly provided via ⁠tree=⁠. Multiple/abbreviated values allowed. Default: "Bray-Curtis"

Take relative abundances into account. When weighted=FALSE, only presence/absence is considered. Multiple values allowed. Default: TRUE

Only changes the "Weighted UniFrac" calculation. Divides result by the total branch weights. Default: TRUE

A phylo object representing the phylogenetic relationships of the taxa in biom. Only required when computing UniFrac distances. Default: biom$tree

Dataset field(s) to include in the output data frame, or '.all' to include all metadata fields. Default: '.all'

Dataset field(s) for intra- or inter- sample comparisons. Alternatively, dataset field names given elsewhere can be prefixed with '==' or '!=' to assign them to within or between, respectively. Default: NULL

For numeric metadata, report the absolute difference in values for the two samples, for instance 2 instead of "10 vs 12". Default: TRUE

Transformation to apply. Options are: c("none", "rank", "log", "log1p", "sqrt", "percent"). "rank" is useful for correcting for non-normally distributions before applying regression statistics. Default: "none"

When transform="rank", how to rank identical values. Options are: c("average", "first", "last", "random", "max", "min"). See rank() for details. Default: "random"

Random seed for permutations. Must be a non-negative integer. Default: 0

The number of CPUs to use. Set to NULL to use all available, or to 1 to disable parallel processing. Default: NULL

When parsing the tree, should underscores be kept as is? By default they will be converted to spaces (unless the entire ID is quoted). Default FALSE

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

A character vector of metadata fields. Each unique combination of values in these columns will be used to create a subsetted rbiom object to pass to FUN. If NULL, biom will be passed to FUN unaltered. Unambiguous abbreviations of metadata fields are also accepted.

The function to execute on each subset of biom. For bdply(), the returned value will be coerced to a data.frame. For blply(), any returned value is unmodified.

Additional arguments to pass on to FUN.

A named list of values to pass to FUN. Unlike ..., these will be iterated over in all combinations. Default: list()

When TRUE, prefixes the names in in iters with a '.' in the final data.frame or 'split_labels' attribute. Default: FALSE

Any number of rbiom objects (e.g. from as_rbiom()), lists of rbiom objects, or valid arguments to the biom parameter of as_rbiom() (for instance file names).

Replace the corresponding data in the merged rbiom object with these values. Set to NULL to not inherit a particular component. The default, NA, will attempt to create the component based on ... values. The merged phylogenetic tree cannot be inferred.

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

Not Used.

A dist-class distance matrix, as returned from bdiv_distmat() or stats::dist(). Required.

Method for reducing dimensionality. Options are:

"PCoA" -

Principal coordinate analysis; ape::pcoa().

"UMAP" -

Uniform manifold approximation and projection; uwot::umap().

"NMDS" -

Nonmetric multidimensional scaling; vegan::metaMDS().

"tSNE" -

t-distributed stochastic neighbor embedding; tsne::tsne().

Multiple/abbreviated values allowed. Default: "PCoA"

Number of ordination dimensions to return. Either 2L or 3L. Default: 2L

Additional arguments for ord.

A dist-class distance matrix, as returned from bdiv_distmat() or stats::dist(). Required.

A named vector of grouping values. The names should correspond to attr(dm, 'Labels'). Values can be either categorical or numeric. Required.

Permutational test for accessing significance. Options are:

"adonis2" -

Permutational MANOVA; vegan::adonis2().

"mrpp" -

Multiple response permutation procedure; vegan::mrpp().

"none" -

Don't run any statistics.

Abbreviations are allowed. Default: "adonis2"

Random seed for permutations. Must be a non-negative integer. Default: 0

Number of random permutations to use. Default: 999

An rbiom object, such as from as_rbiom().

An rbiom object, such as from as_rbiom().

An rbiom object, such as from as_rbiom().

An rbiom object, such as from as_rbiom().

An rbiom object, such as from as_rbiom().

Number of clusters. Default: 5L

Which taxa rank to use. E.g. "Phylum", "Genus", ".otu", etc. An integer can also be given, where 1 is the highest rank, 2 is the second highest, -1 is the lowest rank, -2 is the second lowest, and 0 is the OTU "rank". Run biom$ranks to see all options for a given rbiom object. Default: .otu.

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

A matrix-like object.

A phylo object representing the phylogenetic relationships of the taxa in biom. Only required when computing UniFrac distances. Default: biom$tree

When parsing the tree, should underscores be kept as is? By default they will be converted to spaces (unless the entire ID is quoted). Default FALSE

Dataset field(s) to include in the output data frame, or '.all' to include all metadata fields. Default: '.all'

Alpha diversity metric(s) to use. Options are: "OTUs", "Shannon", "Chao1", "Simpson", and/or "InvSimpson". Set adiv=".all" to use all metrics. Multiple/abbreviated values allowed. Default: "Shannon"

Beta diversity distance algorithm(s) to use. Options are: "Bray-Curtis", "Manhattan", "Euclidean", "Jaccard", and "UniFrac". For "UniFrac", a phylogenetic tree must be present in biom or explicitly provided via ⁠tree=⁠. Multiple/abbreviated values allowed. Default: "Bray-Curtis"

Which taxa to display. An integer value will show the top n most abundant taxa. A value 0 <= n < 1 will show any taxa with that mean abundance or greater (e.g. 0.1 implies >= 10%). A character vector of taxa names will show only those named taxa. Default: 6.

Method for reducing dimensionality. Options are:

"PCoA" -

Principal coordinate analysis; ape::pcoa().

"UMAP" -

Uniform manifold approximation and projection; uwot::umap().

"NMDS" -

Nonmetric multidimensional scaling; vegan::metaMDS().

"tSNE" -

t-distributed stochastic neighbor embedding; tsne::tsne().

Multiple/abbreviated values allowed. Default: "PCoA"

Take relative abundances into account. When weighted=FALSE, only presence/absence is considered. Multiple values allowed. Default: TRUE

Only changes the "Weighted UniFrac" calculation. Divides result by the total branch weights. Default: TRUE

For numeric metadata, report the absolute difference in values for the two samples, for instance 2 instead of "10 vs 12". Default: TRUE

What rank(s) of taxa to display. E.g. "Phylum", "Genus", ".otu", etc. An integer vector can also be given, where 1 is the highest rank, 2 is the second highest, -1 is the lowest rank, -2 is the second lowest, and 0 is the OTU "rank". Run biom$ranks to see all options for a given rbiom object. Default: -1.

Include all ranks in the name of the taxa. For instance, setting to TRUE will produce ⁠Bacteria; Actinobacteria; Coriobacteriia; Coriobacteriales⁠. Otherwise the taxa name will simply be Coriobacteriales. You want to set this to TRUE when unc = "asis" and you have taxa names (such as Incertae_Sedis) that map to multiple higher level ranks. Default: FALSE

How to handle unclassified, uncultured, and similarly ambiguous taxa names. Options are:

"singly" -

Replaces them with the OTU name.

"grouped" -

Replaces them with a higher rank's name.

"drop" -

Excludes them from the result.

"asis" -

To not check/modify any taxa names.

Abbreviations are allowed. Default: "singly"

Sum all non-itemized taxa into an "Other" taxa. When FALSE, only returns taxa matched by the taxa argument. Specifying TRUE adds "Other" to the returned set. A string can also be given to imply TRUE, but with that value as the name to use instead of "Other". Default: FALSE

If TRUE, returns a slam::simple_triplet_matrix(), otherwise returns a normal R matrix object. Default: FALSE

Only display taxa with the most significant differences in abundance. If p.top is >= 1, then the p.top most significant taxa are displayed. If p.top is less than one, all taxa with an adjusted p-value <= p.top are displayed. Recommended to be used in combination with the taxa parameter to set a lower bound on the mean abundance of considered taxa. Default: Inf

The transformation to apply to the y-axis. Visualizing differences of both high- and low-abundance taxa is best done with a non-linear axis. Options are:

"sqrt" -

square-root transformation

"log1p" -

log(y + 1) transformation

"none" -

no transformation

These methods allow visualization of both high- and low-abundance taxa simultaneously, without complaint about 'zero' count observations. Default: "sqrt" Use xaxis.transform or yaxis.transform to pass custom values directly to ggplot2's ⁠scale_*⁠ functions.

Transpose the axes, so that taxa are present as rows instead of columns. Default: FALSE

Shade every other x position. Default: same as flip

How to calculate min/max of the crossbar, errorbar, linerange, and pointrange layers. Options are: "ci" (confidence interval), "range", "sd" (standard deviation), "se" (standard error), and "mad" (median absolute deviation). The center mark of crossbar and pointrange represents the mean, except for "mad" in which case it represents the median. Default: "ci"

Minimum adjusted p-value to display on the plot with a bracket.

p.label = 0.05 -

Show p-values that are <= 0.05.

p.label = 0 -

Don't show any p-values on the plot.

p.label = 1 -

Show all p-values on the plot.

If a numeric vector with more than one value is provided, they will be used as breaks for asterisk notation. Default: 0.05

The confidence level for calculating a confidence interval. Default: 0.95

Add methodology caption beneath the plot. Default: TRUE

Show boxplot outliers? TRUE to always show. FALSE to always hide. NULL to only hide them when overlaying a dot or strip chart. Default: NULL

Angle of the labels at the bottom of the plot. Options are "auto", '0', '30', and '90'. Default: "auto".

Number of ordination dimensions to return. Either 2L or 3L. Default: 2L

Dataset field(s) that the data should be split by prior to any calculations. Must be categorical. Default: NULL

A dist-class distance matrix, as returned from bdiv_distmat() or stats::dist(). Required.

A named vector of grouping values. The names should correspond to attr(dm, 'Labels'). Values can be either categorical or numeric. Required.

The dataset (data.frame or tibble object). "Dataset fields" mentioned below should match column names in df. Required.

Dataset field with the x-axis (independent; predictive) values. Must be numeric. Default: NULL

Dataset field with the y-axis (dependent; response) values, such as taxa abundance or alpha diversity. Default: attr(df, 'response')

Dataset field with the statistical groups. Must be categorical. Default: NULL

Dataset field with the group to color by. Must be categorical. Default: stat.by

Dataset field with the group for shapes. Must be categorical. Default: stat.by

Dataset field(s) to use for faceting. Must be categorical. Default: NULL

How to color the groups. Options are:

TRUE -

Automatically select colorblind-friendly colors.

FALSE or NULL -

Don't use colors.

a palette name -

Auto-select colors from this set. E.g. "okabe"

character vector -

Custom colors to use. E.g. c("red", "#00FF00")

named character vector -

Explicit mapping. E.g. c(Male = "blue", Female = "red")

See "Aesthetics" section below for additional information. Default: TRUE

Shapes for each group. Options are similar to colors's: TRUE, FALSE, NULL, shape names (typically integers 0 - 17), or a named vector mapping groups to specific shape names. See "Aesthetics" section below for additional information. Default: TRUE

Patterns for each group. Options are similar to colors's: TRUE, FALSE, NULL, pattern names ("brick", "chevron", "fish", "grid", etc), or a named vector mapping groups to specific pattern names. See "Aesthetics" section below for additional information. Default: FALSE

Method for computing p-values: 'wilcox', 'kruskal', 'emmeans', or 'emtrends'. Default: 'emmeans'

How to fit the trendline. 'lm', 'log', or 'gam'. Default: 'gam'

Position(s) along the x-axis where the means or slopes should be evaluated. Default: NULL, which samples 100 evenly spaced positions and selects the position where the p-value is most significant.

Alternative hypothesis direction. Options are '!=' (two-sided; not equal to mu), '<' (less than mu), or '>' (greater than mu). Default: '!='

Reference value to test against. Default: 0

Generate additional plots to aid in assessing data normality. Default: FALSE

Dataset field(s) for intra- or inter- sample comparisons. Alternatively, dataset field names given elsewhere can be prefixed with '==' or '!=' to assign them to within or between, respectively. Default: NULL

Random seed for permutations. Must be a non-negative integer. Default: 0

The number of CPUs to use. Set to NULL to use all available, or to 1 to disable parallel processing. Default: NULL

Number of random permutations to use. Default: 999

Method to use for multiple comparisons adjustment of p-values. Run p.adjust.methods for a list of available options. Default: "fdr"

Rarefaction depths to show in the plot, or NULL to auto-select. Default: NULL

Where to draw a horizontal line on the plot, intended to show a particular rarefaction depth. Set to TRUE to show an auto-selected rarefaction depth or FALSE to not show a line. Default: NULL

Create a copy of biom before modifying. If FALSE, biom is modified in place as a side-effect. See speed ups for use cases. Default: TRUE

Show sample names under each bar. Default: FALSE

Transformation to apply. Options are: c("none", "rank", "log", "log1p", "sqrt", "percent"). "rank" is useful for correcting for non-normally distributions before applying regression statistics. Default: "none"

When transform="rank", how to rank identical values. Options are: c("average", "first", "last", "random", "max", "min"). See rank() for details. Default: "random"

The categorical or numeric metadata field over which statistics should be calculated. Required.

Permutational test for accessing significance. Options are:

"adonis2" -

Permutational MANOVA; vegan::adonis2().

"mrpp" -

Multiple response permutation procedure; vegan::mrpp().

"none" -

Don't run any statistics.

Abbreviations are allowed. Default: "adonis2"

Color palette name, or a list with entries for label, colors, range, bins, na.color, and/or guide. See the Track Definitions section for details. Default: list(label = "Grid Value", colors = "imola")

Label the matrix rows and columns. You can supply a list or logical vector of length two to control row labels and column labels separately, for example label = c(rows = TRUE, cols = FALSE), or simply label = c(TRUE, FALSE). Other valid options are "rows", "cols", "both", "bottom", "right", and "none". Default: TRUE

The font size to use for the row and column labels. You can supply a numeric vector of length two to control row label sizes and column label sizes separately, for example c(rows = 20, cols = 8), or simply c(20, 8). Default: NULL, which computes: pmax(8, pmin(20, 100 / dim(mtx)))

Rescale rows or columns to all have a common min/max. Options: "none", "rows", or "cols". Default: "none"

Draw a dendrogram for rows (left) and columns (top). You can supply a list or logical vector of length two to control the row tree and column tree separately, for example trees = c(rows = TRUE, cols = FALSE), or simply trees = c(TRUE, FALSE). Other valid options are "rows", "cols", "both", "left", "top", and "none". Default: TRUE

Clustering algorithm for reordering the rows and columns by similarity. You can supply a list or character vector of length two to control the row and column clustering separately, for example clust = c(rows = "complete", cols = NA), or simply clust = c("complete", NA). Options are:

FALSE or NA -

Disable reordering.

An hclust class object

E.g. from stats::hclust().

A method name -

"ward.D", "ward.D2", "single", "complete", "average", "mcquitty", "median", or "centroid".

Default: "complete"

Distance algorithm to use when reordering the rows and columns by similarity. You can supply a list or character vector of length two to control the row and column clustering separately, for example dist = c(rows = "euclidean", cols = "maximum"), or simply dist = c("euclidean", "maximum"). Options are:

A dist class object

E.g. from stats::dist() or bdiv_distmat().

A method name -

"euclidean", "maximum", "manhattan", "canberra", "binary", or "minkowski".

Default: "euclidean"

The height of the dendrogram or annotation tracks as a percentage of the overall grid size. Use a numeric vector of length two to assign c(top, left) independently. Default: 10 (10% of the grid's height)

Aspect ratio (height/width) for entire grid. Default: 1 (square)

Where to place the legend. Options are: "right" or "bottom". Default: "right"

Plot title. Set to TRUE for a default title, NULL for no title, or any character string. Default: TRUE

Additional arguments to pass on to ggplot2::theme().

What rank(s) of taxa to compute biplot coordinates and statistics for, or NULL to disable. E.g. "Phylum", "Genus", ".otu", etc. An integer vector can also be given, where 1 is the highest rank, 2 is the second highest, -1 is the lowest rank, -2 is the second lowest, and 0 is the OTU "rank". Run biom$ranks to see all options for a given rbiom object. Default: 2.

What rank(s) of taxa to compute biplot coordinates and statistics for, or NULL to disable. E.g. "Phylum", "Genus", ".otu", etc. An integer vector can also be given, where 1 is the highest rank, 2 is the second highest, -1 is the lowest rank, -2 is the second lowest, and 0 is the OTU "rank". Run biom$ranks to see all options for a given rbiom object. Default: NULL.

Which taxa to display. An integer value will show the top n most abundant taxa. A value 0 <= n < 1 will show any taxa with that mean abundance or greater (e.g. 0.1 implies >= 10%). A character vector of taxa names will show only those named taxa. Default: 4.

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

Where to save the files. If the directory doesn't exist, it will be created. Default: tempfile()

A string to prepend to each file name. Default: 'biom_'

An rbiom object, such as from as_rbiom().

Width of output. See pillar::glimpse() documentation. Default: NULL

Not used.

An rbiom object, such as from as_rbiom().

Passed on to dplyr::mutate() or dplyr::rename().

Create a copy of biom before modifying. If FALSE, biom is modified in place as a side-effect. See speed ups for use cases. Default: TRUE

A numeric matrix with named rows and columns.

Color palette name, or a list with entries for label, colors, range, bins, na.color, and/or guide. See the Track Definitions section for details. Default: list(label = "Grid Value", colors = "imola")

List of track definitions. See details below. Default: NULL.

Label the matrix rows and columns. You can supply a list or logical vector of length two to control row labels and column labels separately, for example label = c(rows = TRUE, cols = FALSE), or simply label = c(TRUE, FALSE). Other valid options are "rows", "cols", "both", "bottom", "right", and "none". Default: TRUE

The font size to use for the row and column labels. You can supply a numeric vector of length two to control row label sizes and column label sizes separately, for example c(rows = 20, cols = 8), or simply c(20, 8). Default: NULL, which computes: pmax(8, pmin(20, 100 / dim(mtx)))

Rescale rows or columns to all have a common min/max. Options: "none", "rows", or "cols". Default: "none"

Draw a dendrogram for rows (left) and columns (top). You can supply a list or logical vector of length two to control the row tree and column tree separately, for example trees = c(rows = TRUE, cols = FALSE), or simply trees = c(TRUE, FALSE). Other valid options are "rows", "cols", "both", "left", "top", and "none". Default: TRUE

Clustering algorithm for reordering the rows and columns by similarity. You can supply a list or character vector of length two to control the row and column clustering separately, for example clust = c(rows = "complete", cols = NA), or simply clust = c("complete", NA). Options are:

FALSE or NA -

Disable reordering.

An hclust class object

E.g. from stats::hclust().

A method name -

"ward.D", "ward.D2", "single", "complete", "average", "mcquitty", "median", or "centroid".

Default: "complete"

Distance algorithm to use when reordering the rows and columns by similarity. You can supply a list or character vector of length two to control the row and column clustering separately, for example dist = c(rows = "euclidean", cols = "maximum"), or simply dist = c("euclidean", "maximum"). Options are:

A dist class object

E.g. from stats::dist() or bdiv_distmat().

A method name -

"euclidean", "maximum", "manhattan", "canberra", "binary", or "minkowski".

Default: "euclidean"

Aspect ratio (height/width) for entire grid. Default: 1 (square)

The height of the dendrogram or annotation tracks as a percentage of the overall grid size. Use a numeric vector of length two to assign c(top, left) independently. Default: 10 (10% of the grid's height)

Where to place the legend. Options are: "right" or "bottom". Default: "right"

Plot title. Default: NULL.

Angle of the labels at the bottom of the plot. Options are "auto", '0', '30', and '90'. Default: "auto".

Additional arguments to pass on to ggplot2::theme().

An rbiom object, such as from as_rbiom().

The metadata field name specified as:

• The metadata field name to retrieve. Can be abbreviated.

• A positive integer, giving the position counting from the left.

• A negative integer, giving the position counting from the right.

Default: -1

The column to be used as names for a named vector. Specified in a similar manner as var. Default: ".sample"

Not used.

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

Alpha diversity metric(s) to use. Options are: "OTUs", "Shannon", "Chao1", "Simpson", and/or "InvSimpson". Set adiv=".all" to use all metrics. Multiple/abbreviated values allowed. Default: "Shannon"

One or more of c("trend", "confidence", "point", "name", "residual"). Single letter abbreviations are also accepted. For instance, c("trend", "point") is equivalent to c("t", "p") and "tp". Default: "tc"

Where to draw a horizontal line on the plot, intended to show a particular rarefaction depth. Set to TRUE to show an auto-selected rarefaction depth or FALSE to not show a line. Default: NULL

Dataset field with the statistical groups. Must be categorical. Default: NULL

Dataset field(s) to use for faceting. Must be categorical. Default: NULL

How to color the groups. Options are:

TRUE -

Automatically select colorblind-friendly colors.

FALSE or NULL -

Don't use colors.

a palette name -

Auto-select colors from this set. E.g. "okabe"

character vector -

Custom colors to use. E.g. c("red", "#00FF00")

named character vector -

Explicit mapping. E.g. c(Male = "blue", Female = "red")

See "Aesthetics" section below for additional information. Default: TRUE

Shapes for each group. Options are similar to colors's: TRUE, FALSE, NULL, shape names (typically integers 0 - 17), or a named vector mapping groups to specific shape names. See "Aesthetics" section below for additional information. Default: TRUE

Method for computing p-values: 'none', 'emmeans', or 'emtrends'. Default: 'emmeans'

How to fit the trendline. Options are 'lm', 'log', and 'gam'. Default: 'log'

Position(s) along the x-axis where the means or slopes should be evaluated. Default: NULL, which samples 100 evenly spaced positions and selects the position where the p-value is most significant.

The confidence level for calculating a confidence interval. Default: 0.95

Method to use for multiple comparisons adjustment of p-values. Run p.adjust.methods for a list of available options. Default: "fdr"

Transformation to apply. Options are: c("none", "rank", "log", "log1p", "sqrt", "percent"). "rank" is useful for correcting for non-normally distributions before applying regression statistics. Default: "none"

Alternative hypothesis direction. Options are '!=' (two-sided; not equal to mu), '<' (less than mu), or '>' (greater than mu). Default: '!='

Reference value to test against. Default: 0

Add methodology caption beneath the plot. Default: TRUE

Generate additional plots to aid in assessing data normality. Default: FALSE

Additional parameters to pass along to ggplot2 functions. Prefix a parameter name with a layer name to pass it to only that layer. For instance, p.size = 2 ensures only the points have their size set to 2.

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

Alpha diversity metric(s) to use. Options are: "OTUs", "Shannon", "Chao1", "Simpson", and/or "InvSimpson". Set adiv=".all" to use all metrics. Multiple/abbreviated values allowed. Default: "Shannon"

One or more of c("trend", "confidence", "point", "name", "residual"). Single letter abbreviations are also accepted. For instance, c("trend", "point") is equivalent to c("t", "p") and "tp". Default: "tc"

Where to draw a horizontal line on the plot, intended to show a particular rarefaction depth. Set to TRUE to show an auto-selected rarefaction depth or FALSE to not show a line. Default: NULL

Dataset field with the statistical groups. Must be categorical. Default: NULL

Dataset field(s) to use for faceting. Must be categorical. Default: NULL

How to color the groups. Options are:

TRUE -

Automatically select colorblind-friendly colors.

FALSE or NULL -

Don't use colors.

a palette name -

Auto-select colors from this set. E.g. "okabe"

character vector -

Custom colors to use. E.g. c("red", "#00FF00")

named character vector -

Explicit mapping. E.g. c(Male = "blue", Female = "red")

See "Aesthetics" section below for additional information. Default: TRUE

Shapes for each group. Options are similar to colors's: TRUE, FALSE, NULL, shape names (typically integers 0 - 17), or a named vector mapping groups to specific shape names. See "Aesthetics" section below for additional information. Default: TRUE

Method for computing p-values: 'none', 'emmeans', or 'emtrends'. Default: 'emmeans'

How to fit the trendline. Options are 'lm', 'log', and 'gam'. Default: 'log'

Position(s) along the x-axis where the means or slopes should be evaluated. Default: NULL, which samples 100 evenly spaced positions and selects the position where the p-value is most significant.

The confidence level for calculating a confidence interval. Default: 0.95

Method to use for multiple comparisons adjustment of p-values. Run p.adjust.methods for a list of available options. Default: "fdr"

Transformation to apply. Options are: c("none", "rank", "log", "log1p", "sqrt", "percent"). "rank" is useful for correcting for non-normally distributions before applying regression statistics. Default: "none"

Alternative hypothesis direction. Options are '!=' (two-sided; not equal to mu), '<' (less than mu), or '>' (greater than mu). Default: '!='

Reference value to test against. Default: 0

Add methodology caption beneath the plot. Default: TRUE

Generate additional plots to aid in assessing data normality. Default: FALSE

Additional parameters to pass along to ggplot2 functions. Prefix a parameter name with a layer name to pass it to only that layer. For instance, p.size = 2 ensures only the points have their size set to 2.

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

Where to draw a horizontal line on the plot, intended to show a particular rarefaction depth. Set to TRUE to show an auto-selected rarefaction depth, FALSE to not show a line, or an integer for a custom position. Default: TRUE.

Display the number of samples and reads remaining after rarefying to rline reads per sample. Default: TRUE.

Show sample names under each bar. Default: TRUE.

Y-axis transformation. Options are "log10" or "none". Default: "log10". Use xaxis.transform or yaxis.transform to pass custom values directly to ggplot2's ⁠scale_*⁠ functions.

Additional parameters to pass along to ggplot2 functions. Prefix a parameter name with r. to ensure it gets passed to (and only to) geom_hline. For instance, r.color = "black" ensures only the horizontal rarefaction line has its color set to "black".

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

How many observations to keep per sample. When ⁠0 < depth < 1⁠, it is taken as the minimum percentage of the dataset's observations to keep. Ignored when n is specified. Default: 0.1

The number of samples to keep. When ⁠0 < n < 1⁠, it is taken as the percentage of samples to keep. If negative, that number or percentage of samples is dropped. If 0, all samples are kept. If NULL, depth is used instead. Default: NULL

An integer seed for randomizing which observations to keep or drop. If you need to create different random rarefactions of the same data, set the seed to a different number each time.

Create a copy of biom before modifying. If FALSE, biom is modified in place as a side-effect. See speed ups for use cases. Default: TRUE

The number of CPUs to use. Set to NULL to use all available, or to 1 to disable parallel processing. Default: NULL

A matrix-like object.

How many observations to keep per sample. When ⁠0 < depth < 1⁠, it is taken as the minimum percentage of the dataset's observations to keep. Ignored when n is specified. Default: 0.1

The number of samples to keep. When ⁠0 < n < 1⁠, it is taken as the percentage of samples to keep. If negative, that number or percentage of samples is dropped. If 0, all samples are kept. If NULL, depth is used instead. Default: NULL

A positive integer to use for seeding the random number generator. If you need to create different random rarefactions of the same matrix, set this seed value to a different number each time.

The number of CPUs to use. Set to NULL to use all available, or to 1 to disable parallel processing. Default: NULL

Input data as either a file path, URL, or JSON string. BIOM files can be formatted according to version 1.0 (JSON) or 2.1 (HDF5) specifications, or as classical tabular format. URLs must begin with http://, https://, ftp://, or ftps://. JSON files must have { as their first character. Compressed (gzip or bzip2) BIOM files are also supported. NOTE: to read HDF5 formatted BIOM files, the BioConductor R package rhdf5 must be installed.

Properties to set in the new rbiom object, for example, metadata, id, comment, or tree.

A file/URL with fasta-formatted sequences. Can optionally be compressed with gzip, bzip2, xz, or lzma.

Character vector of IDs to retrieve. The default, NULL, will retrieve everything.

Input data as either a file path, URL, or Newick string. Compressed (gzip or bzip2) files are also supported.

When parsing the tree, should underscores be kept as is? By default they will be converted to spaces (unless the entire ID is quoted). Default FALSE

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

What rank(s) of taxa to display. E.g. "Phylum", "Genus", ".otu", etc. An integer vector can also be given, where 1 is the highest rank, 2 is the second highest, -1 is the lowest rank, -2 is the second lowest, and 0 is the OTU "rank". Run biom$ranks to see all options for a given rbiom object. Default: -1.

Sort the result. Options: NULL - don't sort; "asc" - in ascending order (smallest to largest); "desc" - in descending order (largest to smallest). Ignored when the result is not a simple numeric vector. Default: NULL

How to handle unclassified, uncultured, and similarly ambiguous taxa names. Options are:

"singly" -

Replaces them with the OTU name.

"grouped" -

Replaces them with a higher rank's name.

"drop" -

Excludes them from the result.

"asis" -

To not check/modify any taxa names.

Abbreviations are allowed. Default: "singly"

The function to apply to each column of taxa_matrix().

Optional arguments to FUN.

An rbiom object, such as from as_rbiom().

For slice(), integer row indexes. For other ⁠slice_*()⁠ functions, not used. See dplyr::slice().

<tidy-select> Optionally, a selection of columns to group by for just this operation, functioning as an alternative to group_by(). For details and examples, see ?dplyr_by.

Relevant when the .data input is grouped. If .preserve = FALSE (the default), the grouping structure is recalculated based on the resulting data, otherwise the grouping is kept as is.

Create a copy of biom before modifying. If FALSE, biom is modified in place as a side-effect. See speed ups for use cases. Default: TRUE

Provide either n, the number of rows, or prop, the proportion of rows to select. If neither are supplied, n = 1 will be used. If n is greater than the number of rows in the group (or prop > 1), the result will be silently truncated to the group size. prop will be rounded towards zero to generate an integer number of rows.

A negative value of n or prop will be subtracted from the group size. For example, n = -2 with a group of 5 rows will select 5 - 2 = 3 rows; prop = -0.25 with 8 rows will select 8 * (1 - 0.25) = 6 rows.

<data-masking> Variable or function of variables to order by. To order by multiple variables, wrap them in a data frame or tibble.

Should ties be kept together? The default, TRUE, may return more rows than you request. Use FALSE to ignore ties, and return the first n rows.

Should missing values in order_by be removed from the result? If FALSE, NA values are sorted to the end (like in arrange()), so they will only be included if there are insufficient non-missing values to reach n/prop.

<data-masking> Sampling weights. This must evaluate to a vector of non-negative numbers the same length as the input. Weights are automatically standardised to sum to 1.

Should sampling be performed with (TRUE) or without (FALSE, the default) replacement.

The dataset (data.frame or tibble object). "Dataset fields" mentioned below should match column names in df. Required.

A categorical metadata column name to use for the x-axis. Or NULL, which groups all samples into a single category.

A numeric metadata column name to use for the y-axis. Default: attr(df, 'response')

One or more of c("bar", "box" ("x"), "violin", "dot", "strip", "crossbar", "errorbar", "linerange", "pointrange"). Single letter abbreviations are also accepted. For instance, c("box", "dot") is equivalent to c("x", "d") and "xd". Default: "x"

Dataset field with the statistical groups. Must be categorical. Default: NULL

Dataset field(s) to use for faceting. Must be categorical. Default: NULL

How to color the groups. Options are:

TRUE -

Automatically select colorblind-friendly colors.

FALSE or NULL -

Don't use colors.

a palette name -

Auto-select colors from this set. E.g. "okabe"

character vector -

Custom colors to use. E.g. c("red", "#00FF00")

named character vector -

Explicit mapping. E.g. c(Male = "blue", Female = "red")

See "Aesthetics" section below for additional information. Default: TRUE

Shapes for each group. Options are similar to colors's: TRUE, FALSE, NULL, shape names (typically integers 0 - 17), or a named vector mapping groups to specific shape names. See "Aesthetics" section below for additional information. Default: TRUE

Patterns for each group. Options are similar to colors's: TRUE, FALSE, NULL, pattern names ("brick", "chevron", "fish", "grid", etc), or a named vector mapping groups to specific pattern names. See "Aesthetics" section below for additional information. Default: FALSE

Method for computing p-values: 'auto' or 'none'. 'auto' will choose Wilcox or Kruskal-Wallis depending on the number of groups.

Transpose the axes, so that taxa are present as rows instead of columns. Default: FALSE

Shade every other x position. Default: same as flip

How to calculate min/max of the crossbar, errorbar, linerange, and pointrange layers. Options are: "ci" (confidence interval), "range", "sd" (standard deviation), "se" (standard error), and "mad" (median absolute deviation). The center mark of crossbar and pointrange represents the mean, except for "mad" in which case it represents the median. Default: "ci"

The confidence level for calculating a confidence interval. Default: 0.95

Method to use for multiple comparisons adjustment of p-values. Run p.adjust.methods for a list of available options. Default: "fdr"

Only display taxa with the most significant differences in abundance. If p.top is >= 1, then the p.top most significant taxa are displayed. If p.top is less than one, all taxa with an adjusted p-value <= p.top are displayed. Recommended to be used in combination with the taxa parameter to set a lower bound on the mean abundance of considered taxa. Default: Inf

Show boxplot outliers? TRUE to always show. FALSE to always hide. NULL to only hide them when overlaying a dot or strip chart. Default: NULL

Angle of the labels at the bottom of the plot. Options are "auto", '0', '30', and '90'. Default: "auto".

Minimum adjusted p-value to display on the plot with a bracket.

p.label = 0.05 -

Show p-values that are <= 0.05.

p.label = 0 -

Don't show any p-values on the plot.

p.label = 1 -

Show all p-values on the plot.

If a numeric vector with more than one value is provided, they will be used as breaks for asterisk notation. Default: 0.05

Add methodology caption beneath the plot. Default: TRUE

Additional parameters to pass along to ggplot2 functions. Prefix a parameter name with a layer name to pass it to only that layer. For instance, d.size = 2 ensures only the points on the dot layer have their size set to 2.

The dataset (data.frame or tibble object). "Dataset fields" mentioned below should match column names in df. Required.

Dataset field with the x-axis values. Equivalent to the regr argument in stats_table(). Required.

A numeric metadata column name to use for the y-axis. Default: attr(df, 'response')

One or more of c("trend", "confidence", "point", "name", "residual"). Single letter abbreviations are also accepted. For instance, c("trend", "point") is equivalent to c("t", "p") and "tp". Default: "tc"

Dataset field with the statistical groups. Must be categorical. Default: NULL

Dataset field(s) to use for faceting. Must be categorical. Default: NULL

How to color the groups. Options are:

TRUE -

Automatically select colorblind-friendly colors.

FALSE or NULL -

Don't use colors.

a palette name -

Auto-select colors from this set. E.g. "okabe"

character vector -

Custom colors to use. E.g. c("red", "#00FF00")

named character vector -

Explicit mapping. E.g. c(Male = "blue", Female = "red")

See "Aesthetics" section below for additional information. Default: TRUE

Shapes for each group. Options are similar to colors's: TRUE, FALSE, NULL, shape names (typically integers 0 - 17), or a named vector mapping groups to specific shape names. See "Aesthetics" section below for additional information. Default: TRUE

Method for computing p-values: 'none', 'emmeans', or 'emtrends'. Default: 'emmeans'

How to fit the trendline. 'lm', 'log', or 'gam'. Default: 'gam'

Position(s) along the x-axis where the means or slopes should be evaluated. Default: NULL, which samples 100 evenly spaced positions and selects the position where the p-value is most significant.

The confidence level for calculating a confidence interval. Default: 0.95

Method to use for multiple comparisons adjustment of p-values. Run p.adjust.methods for a list of available options. Default: "fdr"

Only display taxa with the most significant differences in abundance. If p.top is >= 1, then the p.top most significant taxa are displayed. If p.top is less than one, all taxa with an adjusted p-value <= p.top are displayed. Recommended to be used in combination with the taxa parameter to set a lower bound on the mean abundance of considered taxa. Default: Inf

Alternative hypothesis direction. Options are '!=' (two-sided; not equal to mu), '<' (less than mu), or '>' (greater than mu). Default: '!='

Reference value to test against. Default: 0

Add methodology caption beneath the plot. Default: TRUE

Generate additional plots to aid in assessing data normality. Default: FALSE

Additional parameters to pass along to ggplot2 functions. Prefix a parameter name with a layer name to pass it to only that layer. For instance, p.size = 2 ensures only the points have their size set to 2.

The dataset (data.frame or tibble object). "Dataset fields" mentioned below should match column names in df. Required.

Dataset field with the x-axis (independent; predictive) values. Must be numeric. Default: NULL

Dataset field with the y-axis (dependent; response) values, such as taxa abundance or alpha diversity. Default: attr(df, 'response')

Dataset field with the statistical groups. Must be categorical. Default: NULL

Dataset field(s) that the data should be split by prior to any calculations. Must be categorical. Default: NULL

Method for computing p-values: 'wilcox', 'kruskal', 'emmeans', or 'emtrends'. Default: 'emmeans'

How to fit the trendline. 'lm', 'log', or 'gam'. Default: 'gam'

Position(s) along the x-axis where the means or slopes should be evaluated. Default: NULL, which samples 100 evenly spaced positions and selects the position where the p-value is most significant.

The confidence level for calculating a confidence interval. Default: 0.95

Alternative hypothesis direction. Options are '!=' (two-sided; not equal to mu), '<' (less than mu), or '>' (greater than mu). Default: '!='

Reference value to test against. Default: 0

Method to use for multiple comparisons adjustment of p-values. Run p.adjust.methods for a list of available options. Default: "fdr"

An rbiom object, such as from as_rbiom().

Logical expression for rows to keep. See base::subset().

Create a copy of biom before modifying. If FALSE, biom is modified in place as a side-effect. See speed ups for use cases. Default: TRUE

Not used.

The sample or OTU names to keep. Or a logical/integer vector indicating which sample names from biom$samples or biom$otus to keep. Subsetting with ⁠[i]⁠ takes i as samples, whereas ⁠[i,j]⁠ takes i as otus and j as samples (corresponding to ⁠[rows, cols]⁠ in the underlying biom$counts matrix).

Not used

An rbiom object, such as from as_rbiom().

Which metadata field(s) to check for NAs, or ".all" to check all metadata fields.

An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.

A categorical metadata column name to use for the x-axis. Or NULL, which puts taxa along the x-axis. Default: NULL

What rank(s) of taxa to display. E.g. "Phylum", "Genus", ".otu", etc. An integer vector can also be given, where 1 is the highest rank, 2 is the second highest, -1 is the lowest rank, -2 is the second lowest, and 0 is the OTU "rank". Run biom$ranks to see all options for a given rbiom object. Default: -1.

One or more of c("bar", "box" ("x"), "violin", "dot", "strip", "crossbar", "errorbar", "linerange", "pointrange"). Single letter abbreviations are also accepted. For instance, c("box", "dot") is equivalent to c("x", "d") and "xd". Default: "x"

Which taxa to display. An integer value will show the top n most abundant taxa. A value 0 <= n < 1 will show any taxa with that mean abundance or greater (e.g. 0.1 implies >= 10%). A character vector of taxa names will show only those named taxa. Default: 6.

How to handle unclassified, uncultured, and similarly ambiguous taxa names. Options are:

"singly" -

Replaces them with the OTU name.

"grouped" -

Replaces them with a higher rank's name.

"drop" -

Excludes them from the result.

"asis" -

To not check/modify any taxa names.

Abbreviations are allowed. Default: "singly"

Sum all non-itemized taxa into an "Other" taxa. When FALSE, only returns taxa matched by the taxa argument. Specifying TRUE adds "Other" to the returned set. A string can also be given to imply TRUE, but with that value as the name to use instead of "Other". Default: FALSE

Only display taxa with the most significant differences in abundance. If p.top is >= 1, then the p.top most significant taxa are displayed. If p.top is less than one, all taxa with an adjusted p-value <= p.top are displayed. Recommended to be used in combination with the taxa parameter to set a lower bound on the mean abundance of considered taxa. Default: Inf

Dataset field with the statistical groups. Must be categorical. Default: NULL

Dataset field(s) to use for faceting. Must be categorical. Default: NULL