Visualize alpha diversity with scatterplots and trendlines.

Usage

adiv_corrplot(
  biom,
  x,
  adiv = "Shannon",
  layers = "tc",
  stat.by = NULL,
  facet.by = NULL,
  colors = TRUE,
  shapes = TRUE,
  test = "emmeans",
  fit = "gam",
  at = NULL,
  level = 0.95,
  p.adj = "fdr",
  transform = "none",
  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.

adiv

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

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"

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"

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.

Examples

    library(rbiom)
    
    p <- adiv_corrplot(babies, "age", stat.by = "deliv", fit = "gam")
    
    p

    
    p$stats
#> # Model:    gam(c(.diversity ~ s(`Age (days)`, by = `Delivery mode`, bs = "cs")
#> #   + , `Delivery mode`), method = "REML")
#> # A tibble: 1 × 15
#>   `Age (days)` `Delivery mode`   .mean.diff .h1     .p.val   .adj.p .effect.size
#>          <dbl> <fct>                  <dbl> <fct>    <dbl>    <dbl>        <dbl>
#> 1         218. Cesarean - Vagin…      0.414 != 0  2.68e-11 2.68e-11        0.694
#> # ℹ 8 more variables: .se <dbl>, .n <int>, .df <int>, .t.ratio <dbl>,
#> #   .adj.r <dbl>, .aic <dbl>, .bic <dbl>, .loglik <dbl>
    
    p$code
#> ggplot(data, aes(x = `Age (days)`, y = .diversity)) +
#>   geom_ribbon(
#>     mapping   = aes(ymin = .ymin, ymax = .ymax, color = `Delivery mode`, fill = `Delivery mode`), 
#>     data      = ~attr(., "fit"), 
#>     alpha     = 0.25, 
#>     linewidth = 0.2 ) +
#>   geom_line(
#>     mapping = aes(color = `Delivery mode`), 
#>     data    = ~attr(., "fit") ) +
#>   geom_vline(
#>     mapping  = aes(xintercept = `Age (days)`), 
#>     data     = ~attr(., "stat_vline"), 
#>     alpha    = 0.2, 
#>     linetype = "dotdash" ) +
#>   geom_label(
#>     mapping    = aes(label = .label, hjust = .hjust, vjust = .vjust), 
#>     data       = ~attr(., "stat_labels"), 
#>     label.size = NA, 
#>     size       = 4 ) +
#>   labs(
#>     caption = "Low p-value indicates trendline means are different.", 
#>     y       = "Shannon Diversity" ) +
#>   scale_color_manual(values = c("#1F77B4", "#FF7F0E")) +
#>   scale_fill_manual(values = c("#1F77B4", "#FF7F0E")) +
#>   scale_x_continuous() +
#>   scale_y_continuous(expand = c(0.15, 0, 0.15, 0)) +
#>   theme_bw() +
#>   theme(
#>     text               = element_text(size = 14), 
#>     panel.grid.major.x = element_blank(), 
#>     panel.grid.minor.x = element_blank(), 
#>     plot.caption       = element_text(face = "italic", size = 9) )