Skip to contents

Visualize beta diversity with scatterplots and trendlines.

Source: R/corrplot.r
bdiv_corrplot.Rd

Visualize beta diversity with scatterplots and trendlines.

Usage

bdiv_corrplot(
  biom,
  x,
  bdiv = "Bray-Curtis",
  layers = "tc",
  weighted = TRUE,
  tree = NULL,
  within = NULL,
  between = NULL,
  stat.by = NULL,
  facet.by = NULL,
  colors = TRUE,
  shapes = TRUE,
  test = "emmeans",
  fit = "gam",
  at = NULL,
  level = 0.95,
  p.adj = "fdr",
  transform = "none",
  ties = "random",
  seed = 0,
  alt = "!=",
  mu = 0,
  caption = TRUE,
  check = FALSE,
  ...
)

Arguments

biom

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

x

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

bdiv

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=. Default: "Bray-Curtis"

Multiple/abbreviated values allowed.

layers

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"

weighted

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

Multiple values allowed.

tree

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

within, between

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

stat.by

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

facet.by

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

colors

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

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

test

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

fit

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

at

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.

level

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

p.adj

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

transform

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"

ties

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

seed

Random seed for permutations. Default: 0

alt

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

mu

Reference value to test against. Default: 0

caption

Add methodology caption beneath the plot. Default: TRUE

check

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.

Value

A ggplot2 plot.
The computed data points, ggplot2 command, stats table, and stats table commands are available as $data, $code, $stats, and $stats$code, respectively.

Aesthetics

All built-in color palettes are colorblind-friendly. The available categorical palette names are: "okabe", "carto", "r4", "polychrome", "tol", "bright", "light", "muted", "vibrant", "tableau", "classic", "alphabet", "tableau20", "kelly", and "fishy".

Shapes can be given as per base R - numbers 0 through 17 for various shapes, or the decimal value of an ascii character, e.g. a-z = 65:90; A-Z = 97:122 to use letters instead of shapes on the plot. Character strings may used as well.

See also

Other beta_diversity: bdiv_boxplot(), bdiv_clusters(), bdiv_heatmap(), bdiv_ord_plot(), bdiv_ord_table(), bdiv_stats(), bdiv_table(), distmat_stats()

Other visualization: adiv_boxplot(), adiv_corrplot(), bdiv_boxplot(), bdiv_heatmap(), bdiv_ord_plot(), plot_heatmap(), rare_corrplot(), rare_multiplot(), rare_stacked(), stats_boxplot(), stats_corrplot(), taxa_boxplot(), taxa_corrplot(), taxa_heatmap(), taxa_stacked()

Examples

    library(rbiom)
    
    biom <- rarefy(hmp50)
    bdiv_corrplot(biom, "Age", stat.by = "Sex", layers = "tcp")