Package 'rbiom'

Description

Visualize alpha diversity with boxplots.

Usage

adiv_boxplot(
  biom,
  x = NULL,
  adiv = "Shannon",
  layers = "x",
  stat.by = x,
  facet.by = NULL,
  colors = TRUE,
  shapes = TRUE,
  patterns = FALSE,
  test = "auto",
  flip = FALSE,
  stripe = NULL,
  ci = "ci",
  level = 0.95,
  p.adj = "fdr",
  outliers = NULL,
  xlab.angle = "auto",
  p.label = 0.05,
  transform = "none",
  strata = NULL,
  caption = TRUE,
  ...
)

Arguments

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".

Patterns are added using the fillpattern R package, which must be installed to use patterns. Options are "brick", "chevron", "fish", "grid", "herringbone", "hexagon", "octagon", "rain", "saw", "shingle", "rshingle", "stripe", and "wave", optionally abbreviated and/or suffixed with modifiers. For example, "hex10_sm" for the hexagon pattern rotated 10 degrees and shrunk by 2x. See fillpattern::fill_pattern() for complete documentation of options.

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.

The dot and strip layers use the ggbeeswarm package when it is installed, and jittered points otherwise.

See Also

Other alpha_diversity: adiv_corrplot(), adiv_stats(), adiv_table()

Other visualization: adiv_corrplot(), bdiv_boxplot(), bdiv_corrplot(), 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)

    adiv_boxplot(biom, x="Body Site", stat.by="Body Site")

    adiv_boxplot(biom, x="Sex", stat.by="Body Site", adiv=c("otu", "shan"), layers = "bld")

    adiv_boxplot(biom, x="body", stat.by="sex", adiv=c('sha', 'sim'), flip=TRUE, layers="p")


    # Each plot object includes additional information.
    fig <- adiv_boxplot(biom, x="Body Site")

    ## Computed Data Points -------------------
    fig$data

    ## Statistics Table -----------------------
    fig$stats

    ## ggplot2 Command ------------------------
    fig$code

Description

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,
  strata = NULL,
  caption = TRUE,
  check = FALSE,
  ...
)

Arguments

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 alpha_diversity: adiv_boxplot(), adiv_stats(), adiv_table()

Other visualization: adiv_boxplot(), bdiv_boxplot(), bdiv_corrplot(), 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)

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

    p

    p$stats

    p$code

Description

A convenience wrapper for adiv_table() + stats_table().

Usage

adiv_stats(
  biom,
  regr = NULL,
  stat.by = NULL,
  adiv = "Shannon",
  split.by = NULL,
  strata = NULL,
  transform = "none",
  test = "emmeans",
  fit = "gam",
  at = NULL,
  level = 0.95,
  alt = "!=",
  mu = 0,
  p.adj = "fdr"
)

Arguments

Value

A tibble data.frame with the fields below. The R code used to generate the statistics is in ⁠$code⁠.

Tests

Which quantity is tested depends on test and on whether regr and stat.by are given. Rows with an NA in any of the regr, resp, stat.by, split.by, or strata fields are dropped (with a message).

For fit = "log", the slope is with respect to log(regr). mu and alt apply to the mean or slope being tested; they are ignored for pairwise comparisons (always ⁠!= 0⁠) and for the smooth-term test. Pairwise comparisons fit a separate model to each pair of groups. Without regr, fit is irrelevant: the model is resp ~ stat.by.

test = "wilcox" runs stats::wilcox.test() (one-sample against mu, or two-sample for each pair of stat.by groups) with exact = NULL, so R chooses an exact or normal-approximation p-value based on the sample sizes and ties. test = "kruskal" runs stats::kruskal.test() across all stat.by groups.

See Also

Other alpha_diversity: adiv_boxplot(), adiv_corrplot(), adiv_table()

Other stats_tables: bdiv_stats(), distmat_stats(), stats_table(), taxa_stats()

Examples

library(rbiom)

    biom <- rarefy(hmp50)

    adiv_stats(biom, stat.by = "Sex")[,1:6]

    adiv_stats(biom, stat.by = "Sex", split.by = "Body Site")[,1:6]

    adiv_stats(biom, stat.by = "Body Site", test = "kruskal")

    adiv_stats(biom, regr = "Age", fit = "lm")

Description

Calculate the alpha diversity of each sample.

Usage

adiv_table(
  biom,
  adiv = "shannon",
  md = ".all",
  tree = NULL,
  transform = "none",
  ties = "random",
  seed = 0,
  cpus = n_cpus()
)

adiv_matrix(
  biom,
  adiv = c("observed", "shannon", "simpson"),
  tree = NULL,
  transform = "none",
  ties = "random",
  seed = 0,
  cpus = n_cpus()
)

adiv_vector(
  biom,
  adiv = "shannon",
  tree = NULL,
  transform = "none",
  ties = "random",
  seed = 0,
  cpus = n_cpus()
)

Arguments

Value

adiv_vector() -

A named numeric vector.

adiv_matrix() -

A matrix of samples x metric. The first column, 'depth', is never transformed.

adiv_table() -

A tibble data.frame of alpha diversity values. Each combination of sample/adiv has its own row. Column names are .sample, .depth, .adiv, and .diversity, followed by any metadata fields requested by md.

Each result carries ⁠$code⁠: the R code that regenerates it, including the steps that produced biom.

See Also

sample_sums() for sample depths.

Other alpha_diversity: adiv_boxplot(), adiv_corrplot(), adiv_stats()

Examples

library(rbiom)

    biom <- hmp50[1:5]

    adiv_table(biom)

    biom <- rarefy(biom)
    adiv_table(biom, md = NULL)

    adiv_vector(biom, 'faith')

    adiv_matrix(biom)

    adiv_matrix(biom)$code

Description

Construct an rbiom object. The returned object is an R6 reference class. Use b <- a$clone() to create copies, not b <- a.

Usage

as_rbiom(biom, ...)

Arguments

Value

An rbiom object.

Examples

library(rbiom)

    # create a simple matrix ------------------------
    mtx <- matrix(
      data     = floor(runif(24) * 1000),
      nrow     = 6,
      dimnames = list(paste0("OTU", 1:6), paste0("Sample", 1:4)) )
    mtx

    # and some sample metadata ----------------------
    df <- data.frame(
      .sample   = paste0("Sample", 1:4),
      treatment = c("A", "B", "A", "B"),
      days      = c(12, 3, 7, 8) )

    # convert data set to rbiom ---------------------
    biom <- as_rbiom(mtx, metadata = df, id = "My BIOM")
    biom

Description

Convert an rbiom object to a base R list.

Usage

## S3 method for class 'rbiom'
as.list(x, ...)

Arguments

Value

A list with names c('counts', 'metadata', 'taxonomy', 'tree', 'sequences', 'id', 'comment', 'date', 'generated_by').

See Also

Other conversion: as.matrix.rbiom()

Description

Identical to running as.matrix(biom$counts).

Usage

## S3 method for class 'rbiom'
as.matrix(x, ...)

Arguments

Value

A base R matrix with OTUs as rows and samples as columns.

See Also

Other conversion: as.list.rbiom()

Examples

library(rbiom)

    as.matrix(hmp50)[1:5,1:5]

Description

Longitudinal Stool Samples from Infants (n = 2,684)

Usage

babies

Format

An rbiom object with 2,684 samples. Includes metadata and taxonomy.

Subject ID -

ID1, ID2, ..., ID12

Sex -

Male or Female

Age (days) -

1 - 266

Child's diet -

"Breast milk", "Breast milk and formula", or "Formula"

Sample collection -

"Frozen upon collection" or "Stored in alcohol"

Antibiotic exposure -

Yes or No

Antifungal exposure -

Yes or No

Delivery mode -

Cesarean or Vaginal

Solid food introduced (Age) -

116 - 247

Source

https://www.nature.com/articles/s41467-018-04641-7 and doi:10.1038/s41467-017-01973-8

See Also

Other Built-In Datasets: gems, hmp50

Examples

babies
head(babies$metadata$Age)

Description

Visualize BIOM data with boxplots.

Usage

bdiv_boxplot(
  biom,
  x = NULL,
  bdiv = "bray",
  layers = "x",
  weighted = NULL,
  tree = NULL,
  within = NULL,
  between = NULL,
  stat.by = x,
  facet.by = NULL,
  colors = TRUE,
  shapes = TRUE,
  patterns = FALSE,
  test = "auto",
  flip = FALSE,
  stripe = NULL,
  ci = "ci",
  level = 0.95,
  p.adj = "fdr",
  outliers = NULL,
  xlab.angle = "auto",
  p.label = 0.05,
  transform = "none",
  strata = NULL,
  seed = 0,
  permutations = 999,
  caption = TRUE,
  alpha = 0.5,
  cpus = n_cpus(),
  ...
)

Arguments

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".

Patterns are added using the fillpattern R package, which must be installed to use patterns. Options are "brick", "chevron", "fish", "grid", "herringbone", "hexagon", "octagon", "rain", "saw", "shingle", "rshingle", "stripe", and "wave", optionally abbreviated and/or suffixed with modifiers. For example, "hex10_sm" for the hexagon pattern rotated 10 degrees and shrunk by 2x. See fillpattern::fill_pattern() for complete documentation of options.

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.

The dot and strip layers use the ggbeeswarm package when it is installed, and jittered points otherwise.

See Also

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

Other visualization: adiv_boxplot(), adiv_corrplot(), bdiv_corrplot(), 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_boxplot(biom, x="==Body Site", bdiv="unweighted_unifrac", stat.by="Body Site")

Description

Partitions the samples around k medoids with cluster::pam(), which works directly on the dissimilarity matrix. (k-means is not a valid clustering of a dissimilarity matrix, since it would treat the rows of the matrix as coordinates.)

Usage

bdiv_clusters(
  biom,
  bdiv = "bray",
  weighted = NULL,
  normalized = NULL,
  tree = NULL,
  k = 5,
  seed = 0,
  alpha = 0.5,
  cpus = n_cpus(),
  ...
)

Arguments

Value

A numeric factor assigning samples to clusters.

See Also

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

Other clustering: taxa_clusters()

Examples

library(rbiom)

    biom <- rarefy(hmp50)
    biom$metadata$bray_cluster <- bdiv_clusters(biom)

    pull(biom, 'bray_cluster')[1:10]

    bdiv_ord_plot(biom, stat.by = "bray_cluster")

Description

Visualize beta diversity with scatterplots and trendlines.

Usage

bdiv_corrplot(
  biom,
  x,
  bdiv = "bray",
  layers = "tc",
  weighted = NULL,
  tree = NULL,
  within = NULL,
  between = NULL,
  stat.by = NULL,
  facet.by = NULL,
  colors = TRUE,
  shapes = TRUE,
  test = "mantel",
  fit = "gam",
  at = NULL,
  level = 0.95,
  p.adj = "fdr",
  transform = "none",
  ties = "random",
  seed = 0,
  permutations = 999,
  alt = "!=",
  mu = 0,
  strata = NULL,
  caption = TRUE,
  check = FALSE,
  alpha = 0.5,
  cpus = n_cpus(),
  ...
)

Arguments

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")

Description

Display beta diversities in an all vs all grid.

Usage

bdiv_heatmap(
  biom,
  bdiv = "bray",
  tree = NULL,
  tracks = NULL,
  grid = "devon",
  label = TRUE,
  label_size = NULL,
  rescale = "none",
  clust = "complete",
  trees = TRUE,
  asp = 1,
  tree_height = 10,
  track_height = 10,
  legend = "right",
  title = TRUE,
  xlab.angle = "auto",
  alpha = 0.5,
  cpus = n_cpus(),
  ...
)

Arguments

Value

A ggplot2 plot. The computed data points and ggplot command are available as ⁠$data⁠ and ⁠$code⁠, respectively.

Annotation Tracks

Metadata can be displayed as colored tracks above the heatmap. Common use cases are provided below, with more thorough documentation available at https://cmmr.github.io/rbiom .

## Categorical ----------------------------
tracks = "Body Site"
tracks = list('Body Site' = "bright")
tracks = list('Body Site' = c('Stool' = "blue", 'Saliva' = "green"))

## Numeric --------------------------------
tracks = "Age"
tracks = list('Age' = "reds")

## Multiple Tracks ------------------------
tracks = c("Body Site", "Age")
tracks = list('Body Site' = "bright", 'Age' = "reds")
tracks = list(
  'Body Site' = c('Stool' = "blue", 'Saliva' = "green"),
  'Age'       = list('colors' = "reds") )

The following entries in the track definitions are understood:

colors -

A pre-defined palette name or custom set of colors to map to.

range -

The c(min,max) to use for scale values.

label -

Label for this track. Defaults to the name of this list element.

side -

Options are "top" (default) or "left". taxa_heatmap() places all tracks on top.

na.color -

The color to use for NA values.

bins -

Bin a gradient into this many bins/steps.

guide -

A list of arguments for guide_colorbar() or guide_legend().

All built-in color palettes are colorblind-friendly.

Categorical palette names: "okabe", "carto", "r4", "polychrome", "tol", "bright", "light", "muted", "vibrant", "tableau", "classic", "alphabet", "tableau20", "kelly", and "fishy".

Numeric palette names: "reds", "oranges", "greens", "purples", "grays", "acton", "bamako", "batlow", "bilbao", "buda", "davos", "devon", "hawaii", "imola", "lajolla", "lapaz", "nuuk", "oslo", "tokyo", "turku", "bam", "berlin", "broc", "cork", "lisbon", "roma", "tofino", "vanimo", and "vik".

See Also

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

Other visualization: adiv_boxplot(), adiv_corrplot(), bdiv_boxplot(), bdiv_corrplot(), 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)

    # Subset to 10 samples and rarefy them.
    hmp10 <- rarefy(hmp50[1:10])

    bdiv_heatmap(hmp10, tracks=c("Body Site", "Age"))

    bdiv_heatmap(hmp10, bdiv=c("u_unifrac", "n_unifrac"), tracks="sex")

Description

Ordinate samples and taxa on a 2D plane based on beta diversity distances.

Usage

bdiv_ord_plot(
  biom,
  bdiv = "bray",
  ord = "PCoA",
  layers = "petm",
  stat.by = NULL,
  facet.by = NULL,
  colors = TRUE,
  shapes = TRUE,
  tree = NULL,
  test = "adonis2",
  seed = 0,
  permutations = 999,
  rank = -1,
  taxa = 4,
  p.top = Inf,
  p.adj = "fdr",
  unc = "singly",
  strata = NULL,
  caption = TRUE,
  alpha = 0.5,
  cpus = n_cpus(),
  ...
)

Arguments

Details

The ellipse layer draws 95% normal-distribution ellipses (ggplot2::stat_ellipse() with type = "norm"); groups with fewer than four samples get no ellipse. The taxon layer uses the ggrepel package to avoid overlapping labels when it is installed, and plain labels otherwise. Facet strips (or the subtitle) show the test statistic, R-squared (PERMANOVA), and p-value from ⁠$stats⁠.

Value

A ggplot2 plot. The computed sample coordinates and ggplot command are available as $data and $code respectively. If stat.by is given, then $stats and $stats$code are set. If rank is given, then $data$taxa_coords, $taxa_stats, and $taxa_stats$code are set.

See Also

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

Other ordination: bdiv_ord_table(), distmat_ord_table()

Other visualization: adiv_boxplot(), adiv_corrplot(), bdiv_boxplot(), bdiv_corrplot(), bdiv_heatmap(), 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_ord_plot(biom, layers="pemt", stat.by="Body Site", rank="g")

Description

The biplot parameters (taxa, unc, p.top, and p.adj) only only have an effect when rank is not NULL.

Usage

bdiv_ord_table(
  biom,
  bdiv = "bray",
  ord = "PCoA",
  weighted = NULL,
  md = NULL,
  k = 2,
  stat.by = NULL,
  split.by = NULL,
  strata = NULL,
  tree = NULL,
  test = "adonis2",
  seed = 0,
  permutations = 999,
  rank = NULL,
  taxa = 6,
  p.top = Inf,
  p.adj = "fdr",
  unc = "singly",
  alpha = 0.5,
  cpus = n_cpus(),
  ...
)

Arguments

Details

Distances are computed from biom as given (not relativized first), so they are identical to bdiv_distmat() on the same object. Relative abundances are used only for the taxa biplot.

Value

A data.frame with columns .sample, .bdiv, .ord, .x, .y, and (optionally) .z. Any columns given by md, split.by, and stat.by are included as well. If stat.by is given, then $stats and $stats$code are set (see distmat_stats()). If rank is given, then $taxa_coords, $taxa_stats, and $taxa_stats$code are set: ⁠$taxa_stats⁠ has one row per taxon and ordination with .r.sqr (the squared correlation of the taxon's relative abundance with the ordination axes, from vegan::envfit()), .p.val (its permutation p-value), and .adj.p (adjusted across all tested taxa, before any p.top filtering); ⁠$taxa_coords⁠ holds the arrow for each taxon (.x0/.y0 at the centroid of the samples, .x/.y at its tip, scaled to fit the sample cloud) and .size, its mean relative abundance. The 'axes' attribute gives the axis labels (see distmat_ord_table()).

See Also

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

Other ordination: bdiv_ord_plot(), distmat_ord_table()

Examples

library(rbiom)

    ord <- bdiv_ord_table(hmp50, "bray", "pcoa", stat.by="Body Site", rank="g")
    head(ord)

    ord$stats

    ord$taxa_stats

Description

Pairwise distances are not independent observations, so beta diversity is tested with permutation tests in which samples, not distances, are permuted: PERMANOVA and friends for a categorical stat.by, or a Mantel test for a numeric regr. See distmat_stats() for the tests.

Usage

bdiv_stats(
  biom,
  regr = NULL,
  stat.by = NULL,
  bdiv = "bray",
  weighted = NULL,
  tree = NULL,
  within = NULL,
  between = NULL,
  split.by = NULL,
  strata = NULL,
  test = if (is.null(regr)) "adonis2" else "mantel",
  seed = 0,
  permutations = 999,
  p.adj = "fdr",
  alpha = 0.5,
  cpus = n_cpus()
)

Arguments

Details

With strata (e.g. repeated samples per subject), the permutation scheme depends on the variable being tested. A variable that varies within strata (e.g. time point) is permuted within each stratum. A variable that is constant within every stratum (e.g. delivery mode, with subject as the stratum) is permuted at the stratum level: whole strata exchange their values, so the effective sample size is the number of strata. When the number of distinct arrangements is no larger than permutations, all of them are enumerated and the p-value is exact. The scheme is chosen separately for each row of the table (a pair of groups can be a between-strata comparison even when the omnibus test is not) and is reported in the table header. See distmat_stats() for details.

Value

A tibble data.frame with one row per test. With a categorical stat.by and more than two groups, each split.by stratum (and bdiv metric) gets an omnibus test across all groups plus one pairwise test per pair of groups, computed on that pair's samples. The columns are:

split.by fields, .bdiv -

The stratum. .bdiv is only present when several bdiv metrics were requested.

stat.by field -

The groups compared, joined by " vs ". The omnibus row lists all groups.

.groups -

The number of groups in the comparison: 2 for pairwise rows, more for the omnibus row.

.n, .stat, .r.sqr, .z, .p.val -

See distmat_stats().

.adj.p -

.p.val adjusted for multiple comparisons across the whole table.

With a numeric regr, one Mantel test per stratum, with .n, .stat (Spearman's r), .p.val, and .adj.p. The R code used to compute the table is in ⁠$code⁠.

See Also

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

Other stats_tables: adiv_stats(), distmat_stats(), stats_table(), taxa_stats()

Examples

library(rbiom)

    biom <- rarefy(hmp50)

    bdiv_stats(biom, stat.by = "Sex", bdiv = c("bray", "w_unifrac"))

    biom <- subset(biom, `Body Site` %in% c('Saliva', 'Stool', 'Buccal mucosa'))
    bdiv_stats(biom, stat.by = "Body Site", split.by = "Sex")

    bdiv_stats(biom, regr = "Age")

    # Repeated measures: delivery mode is constant within each subject,
    # so whole subjects are permuted.
    b <- rarefy(subset(babies, `Age (days)` <= 30))
    bdiv_stats(b, stat.by = "Delivery mode", strata = "Subject ID")

Description

Distance / dissimilarity between samples.

Usage

bdiv_table(
  biom,
  bdiv = "bray",
  weighted = NULL,
  normalized = NULL,
  tree = NULL,
  md = ".all",
  within = NULL,
  between = NULL,
  delta = ".all",
  norm = "none",
  pseudocount = NULL,
  power = 1.5,
  alpha = 0.5,
  transform = "none",
  ties = "random",
  seed = 0,
  cpus = n_cpus(),
  ...
)

bdiv_matrix(
  biom,
  bdiv = "bray",
  weighted = NULL,
  normalized = NULL,
  tree = NULL,
  within = NULL,
  between = NULL,
  norm = "none",
  pseudocount = NULL,
  power = 1.5,
  alpha = 0.5,
  transform = "none",
  ties = "random",
  seed = 0,
  cpus = n_cpus()
)

bdiv_distmat(
  biom,
  bdiv = "bray",
  weighted = NULL,
  normalized = NULL,
  tree = NULL,
  within = NULL,
  between = NULL,
  norm = "none",
  pseudocount = NULL,
  power = 1.5,
  alpha = 0.5,
  transform = "none",
  ties = "random",
  seed = 0,
  cpus = n_cpus()
)

Arguments

Value

bdiv_matrix() -

An R matrix of samples x samples.

bdiv_distmat() -

A dist-class distance matrix.

bdiv_table() -

A tibble data.frame with columns named .sample1, .sample2, .bdiv, .distance, and any fields requested by md. Numeric metadata fields will be returned as abs(x - y); categorical metadata fields as "x", "y", or "x vs y".

Each result carries ⁠$code⁠: the R code that regenerates it, including the steps that produced biom.

Metadata Comparisons

Prefix metadata fields with == or != to limit comparisons to within or between groups, respectively. For example, stat.by = '==Sex' will run calculations only for intra-group comparisons, returning "Male" and "Female", but NOT "Female vs Male". Similarly, setting stat.by = '!=Body Site' will only show the inter-group comparisons, such as "Saliva vs Stool", "Anterior nares vs Buccal mucosa", and so on.

The same effect can be achieved by using the within and between parameters. stat.by = '==Sex' is equivalent to ⁠stat.by = 'Sex', within = 'Sex'⁠.

See Also

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

Examples

library(rbiom)

    # Subset to four samples
    biom <- hmp50[c("HMP18", "HMP19", "HMP20", "HMP21")]

    # Return in long format with metadata
    bdiv_table(biom, 'w_unifrac', md = ".all")

    # Only look at distances among the stool samples
    bdiv_table(biom, 'w_unifrac', md = c("==Body Site", "Sex"))

    # Or between males and females
    bdiv_table(biom, 'w_unifrac', md = c("Body Site", "!=Sex"))

    # All-vs-all matrix
    bdiv_matrix(biom, 'w_unifrac')

    # All-vs-all distance matrix
    dm <- bdiv_distmat(biom, 'w_unifrac')
    dm
    plot(hclust(dm))

Description

blply() and bdply() let you divide your biom dataset into smaller pieces, run a function on those smaller rbiom objects, and return the results as a data.frame or list.

Usage

bdply(biom, vars, FUN, ..., iters = list(), prefix = FALSE)

blply(biom, vars, FUN, ..., iters = list(), prefix = FALSE)

Arguments

Details

You can also specify additional variables for your function to iterate over in unique combinations.

Each subset passed to FUN is a proper rbiom object whose history records how it was made, e.g. subset(biom, Sex == "Male"), so that results computed from it (and their ⁠$code⁠) are reproducible.

Value

For bdply(), a tibble data.frame comprising the accumulated outputs of FUN, along with the columns specified by vars and iters. For blply(), a named list that has details about vars and iters in attr(,'split_labels').

See Also

Other metadata: glimpse.rbiom()

Other biom: biom_merge()

Examples

library(rbiom)

    bdply(hmp50, "Sex", `$`, 'n_samples')

    blply(hmp50, "Sex", `$`, 'n_samples') %>% unlist()

    bdply(hmp50, c("Body Site", "Sex"), function (b) {
      adm <- adiv_matrix(b)[,c("shannon", "simpson")]
      apply(adm, 2L, mean)
    })

    iters <- list(d = c("bray", "euclid"))
    bdply(hmp50, "Sex", iters = iters, function (b, d) {
      r <- range(bdiv_distmat(biom = b, bdiv = d))
      round(data.frame(min = r[[1]], max = r[[2]]))
    })

Description

Scaling a matrix of proportions (or counts) to a new target depth, rounding to integers while preserving the original total abundance sum exactly.

Usage

biom_inflate(biom, depth = NULL, clone = TRUE)

Arguments

Value

An rbiom object.

Rounding (Largest Remainder Method)

To ensure the sum of the resulting counts equals the target depth exactly (avoiding drift caused by simple rounding), this function uses the Largest Remainder Method (also known as the Hare-Niemeyer method).

It assigns the integer part of the scaled value to each feature, and then distributes the remaining counts to the features with the largest fractional parts.

See Also

suggest_inflate_depths() for details on how target depths are estimated when depth = NULL.

Other transformations: biom_relativize(), biom_rescale(), modify_metadata, rarefy(), slice_metadata, subset, with

Examples

library(rbiom)

    biom <- hmp50[1:5]
    sample_sums(biom)

    biom <- biom_relativize(biom)
    sample_sums(biom)

    biom <- biom_inflate(biom)
    sample_sums(biom)

Description

WARNING: It is generally ill-advised to merge BIOM datasets, as OTUs mappings are dependent on upstream clustering and are not equivalent between BIOM files.

Usage

biom_merge(
  ...,
  metadata = NA,
  taxonomy = NA,
  tree = NA,
  sequences = NA,
  id = NA,
  comment = NA
)

Arguments

Details

Samples present in more than one input must have identical counts; otherwise an error is raised. OTUs are matched by name.

With the default NA arguments:

• metadata and taxonomy are the union of the inputs' tables. A field whose type differs between inputs (for example numeric in one and categorical in another) is converted to categorical, with a single warning listing the affected fields. An OTU with different lineages in different inputs keeps the most detailed one (one summarizing warning).

• sequences are the union of the inputs' sequences. If only some inputs have sequences, OTUs without one get NA and a warning is issued once.

• tree is taken from the first input whose tree contains every OTU of the merged object (pruned to those OTUs). This is the case when the inputs are subsets of one dataset. If no input tree covers all of the OTUs, the merged object has no tree and a message says so; a merged tree can't be inferred, so supply ⁠tree=⁠ in that case.

• id and comment are kept when all inputs agree, and are otherwise "Merged BIOM" and "".

The merged object's ⁠$history⁠ nests the histories of its inputs, so its ⁠$code⁠ reproduces the entire pipeline.

Value

An rbiom object.

See Also

Other biom: bdply()

Examples

library(rbiom)

    b1 <- as_rbiom(hmp50$counts[,1:4])
    b2 <- as_rbiom(hmp50$counts[,5:8])

    biom <- biom_merge(b1, b2)
    print(biom)

    biom$tree     <- hmp50$tree
    biom$metadata <- subset(hmp50$metadata, .sample %in% biom$samples)
    print(biom)

    # Subsets of one dataset keep its tree, and record their history.
    biom <- biom_merge(hmp50[1:10], hmp50[11:20])
    biom$code

Description

This function normalizes the data by dividing each observation by the total library size of its sample. The resulting values represent the proportion (0 to 1) of the sample composed of that specific feature.

This is a common transformation for microbiome data, as it accounts for differences in sequencing depth across samples, allowing for comparison of community composition. The result has biom$relative == TRUE.

Usage

biom_relativize(biom, clone = TRUE)

Arguments

Details

Convert absolute counts to relative abundances (proportions) where each sample sums to 1.

Value

An rbiom object.

See Also

Other transformations: biom_inflate(), biom_rescale(), modify_metadata, rarefy(), slice_metadata, subset, with

Examples

library(rbiom)

    biom <- hmp50[1:5]

    # Raw counts sum to different library sizes
    sample_sums(biom)

    # Relativized counts sum to 1
    biom_rel <- biom_relativize(biom)
    sample_sums(biom_rel)
    biom_rel$relative

Description

This function performs a min-max scaling on each sample independently.

It is useful for normalization techniques that require data to be within a specific bounded range, or for visualization purposes where maintaining the relative distances between values is important but the absolute magnitude needs adjustment.

Usage

biom_rescale(biom, range = c(0, 1), clone = TRUE)

Arguments

Details

Linearly rescale each sample's values to lie between a specified minimum and maximum.

Value

An rbiom object.

Mathematical Transformation

The rescaling is performed in two steps:

1. Normalize: Divide values by the maximum value in that sample, scaling them to a ⁠[0, 1]⁠ range relative to the sample's peak.

2. Scale and Shift: Apply the target range using the formula:

   $x_{new} = x_{norm} \times (max - min) + min$

Note

If range starts at a non-zero value (e.g., c(1, 10)), the sparsity of the matrix will be destroyed because all zero counts will be shifted to the minimum value. This can significantly increase memory usage for large datasets.

See Also

Other transformations: biom_inflate(), biom_relativize(), modify_metadata, rarefy(), slice_metadata, subset, with

Examples

library(rbiom)

    biom <- hmp50[1:5]

    # Original range
    range(as.matrix(biom))

    # Rescaled to 0-1
    biom_01 <- biom_rescale(biom)
    range(as.matrix(biom_01))

    # Rescaled to 0-100 (Percentages)
    biom_100 <- biom_rescale(biom, range = c(0, 100))
    range(as.matrix(biom_100))

Description

Converts your rbiom object into other common Bioconductor data structures. Each function requires the corresponding target package to be installed.

Usage

convert_to_animalcules(biom, ...)

convert_to_biomformat(biom, ...)

convert_to_phyloseq(biom, ...)

convert_to_SE(biom, ...)

convert_to_TSE(biom, ...)

Arguments

Details

• convert_to_animalcules(): Converts to a MultiAssayExperiment object tailored for the animalcules interactive microbiome analysis toolkit. Includes: counts, metadata, and taxonomy.

• convert_to_biomformat(): Converts to a biom object used by the biomformat package, the standard Bioconductor class for reading and writing BIOM data. Includes: counts, metadata, and taxonomy.

• convert_to_phyloseq(): Converts to a phyloseq object for use with the comprehensive phyloseq ecosystem. Rank names, metadata field names, and metadata column types are preserved. Sequences are included only when every OTU has one (requires the Biostrings package). Includes: counts, metadata, taxonomy, phylogenetic tree, and sequences.

• convert_to_SE(): Converts to a SummarizedExperiment object, a core SummarizedExperiment Bioconductor container for matrix-like data and annotations. Includes: counts, metadata, and taxonomy.

• convert_to_TSE(): Converts to a TreeSummarizedExperiment object. This extends the SE class to natively support hierarchical TreeSummarizedExperiment relationships. The tree and sequences are included when present. Includes: counts, metadata, taxonomy, phylogenetic tree, and sequences.

Value

An animalcules (MultiAssayExperiment class), biomformat (biom class), phyloseq, SummarizedExperiment, or TreeSummarizedExperiment object.

Examples

library(rbiom)

    print(hmp50)

    
    # Requires 'animalcules' dependencies, Bioconductor R packages
    if (requireNamespace("MultiAssayExperiment", quietly = TRUE) &&
        requireNamespace("SummarizedExperiment", quietly = TRUE)) {
      ani <- convert_to_animalcules(hmp50)
      print(ani)
    }

    # Requires 'biomformat', a Bioconductor R package
    if (requireNamespace("biomformat", quietly = TRUE)) {
      bio <- convert_to_biomformat(hmp50)
      print(bio)
    }

    # Requires 'phyloseq', a Bioconductor R package
    if (requireNamespace("phyloseq", quietly = TRUE)) {
      phy <- convert_to_phyloseq(hmp50)
      print(phy)
    }

    # Requires 'SummarizedExperiment', a Bioconductor R package
    if (requireNamespace("SummarizedExperiment", quietly = TRUE)) {
      se <- convert_to_SE(hmp50)
      print(se)
    }

    # Requires 'TreeSummarizedExperiment', a Bioconductor R package
    if (requireNamespace("TreeSummarizedExperiment", quietly = TRUE)) {
      tse <- convert_to_TSE(hmp50)
      print(tse)
    }

Description

Run ordinations on a distance matrix.

Usage

distmat_ord_table(dm, ord = "PCoA", k = 2L, seed = 0, ...)

Arguments

Value

A tibble data.frame with columns .ord, .sample, .x, .y, and (optionally) .z. The attribute 'axes' is a tibble with one row per axis (.ord, .axis, .label, .var): for PCoA, .var is the percent of the variance (the positive eigenvalues) explained by that axis and .label reads e.g. "PCoA 1 (24.3%)"; for the other ordinations .var is NA.

See Also

Other ordination: bdiv_ord_plot(), bdiv_ord_table()

Examples

library(rbiom)

    dm  <- bdiv_distmat(hmp50, "bray")
    ord <- distmat_ord_table(dm, "PCoA")
    head(ord)

    attr(ord, 'axes')

Description

Tests whether the distances in dm are structured by groups, using permutation tests. Samples, not distances, are the unit of permutation, so the n(n-1)/2 pairwise distances are never treated as independent observations.

Usage

distmat_stats(
  dm,
  groups,
  test = "adonis2",
  seed = 0,
  permutations = 999,
  strata = NULL
)

Arguments

Details

Permutation schemes with strata. Samples from the same stratum (e.g. repeated samples of one subject) are not independent, so they can't be shuffled freely. Which restriction is valid depends on groups:

• Within-strata variable (groups varies within at least one stratum, e.g. time point or a within-subject treatment): labels are permuted only within each stratum, using permute::how(nperm = permutations, blocks = strata) with the vegan function for test.

• Between-strata variable (groups is constant within every stratum, e.g. delivery mode with subject as the stratum): permuting within strata would never change the labels (every permutation would reproduce the observed statistic, giving p = 1). Instead, the stratum-level values are permuted among whole strata (strata may have different sizes), and the statistic is recomputed on all samples. The p-value is ⁠(1 + #{permuted >= observed}) / (1 + permutations)⁠. When there are no more distinct arrangements of the values among strata than permutations, all of them are enumerated instead and the p-value is exact: the proportion of arrangements (including the observed one) with a statistic at least as large. The statistics are computed by rbiom with the same formulas as vegan: the PERMANOVA pseudo-F and R-squared from the Gower-centred matrix of squared distances, and Spearman's r between the distances and pairwise differences in groups. The effective sample size is the number of strata, so a warning is given when the null distribution is coarse (e.g. a group present in only one stratum). Only test = "adonis2" and test = "mantel" support this scheme; "mrpp" and "betadisper" give an error.

The scheme used, and the number of permutations or enumerated arrangements, is reported in the table header.

Value

A tibble data.frame with one row and the columns:

.n -

The number of samples in the distance matrix.

.stat -

The observed test statistic: the pseudo-F ratio (adonis2, betadisper), the weighted mean within-group distance delta (mrpp), or Spearman's r (mantel).

.r.sqr -

adonis2 only: the proportion of the total sum of squares explained by groups.

.z -

mrpp only: the observed statistic minus the mean of the permuted statistics, divided by their standard deviation.

.p.val -

The permutation p-value: the probability, under the null hypothesis, of a statistic at least as extreme as the observed one, estimated from the permutations (plus the observed data). Its resolution is limited by permutations (or by the number of distinct arrangements of whole strata; see Details).

The R code used to calculate these statistics is in ⁠$code⁠. The groups (and strata) values are embedded in that code so that it can be re-run as is.

See Also

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

Other stats_tables: adiv_stats(), bdiv_stats(), stats_table(), taxa_stats()

Examples

library(rbiom)

    hmp10 <- hmp50[1:10]

    dm <- bdiv_distmat(hmp10, 'w_unifrac')

    distmat_stats(dm, groups = pull(hmp10, 'Body Site'))

    distmat_stats(dm, groups = pull(hmp10, 'Age'), test = "mantel")

    # See the R code used to calculate these statistics:
    stats <- distmat_stats(dm, groups = pull(hmp10, 'Age'), test = "mantel")
    stats$code

    # Repeated measures: delivery mode is constant within each subject,
    # so whole subjects are permuted (all 220 arrangements of the 12
    # infants are enumerated, giving an exact p-value).
    b  <- rarefy(subset(babies, `Age (days)` <= 10))
    dm <- bdiv_distmat(b, 'bray')
    distmat_stats(dm, pull(b, 'Delivery mode'), strata = pull(b, 'Subject ID'))

Description

Populates a directory with the following files, formatted according to QIIME 2 or mothur's specifications.

• biom_counts.tsv

• biom_metadata.tsv

• biom_taxonomy.tsv

• biom_tree.nwk

• biom_seqs.fna

biom_counts.tsv will always be created. The others are dependent on whether the content is present in the biom argument.

For QIIME 2, metadata columns are typed numeric or categorical (logical and Date fields are categorical; dates are written as YYYY-MM-DD). For mothur, taxonomy rows use the OTU IDs from the counts file, and missing ranks are written as unclassified.

Usage

write_mothur(biom, dir = tempfile(), prefix = "biom_", overwrite = FALSE)

write_qiime2(biom, dir = tempfile(), prefix = "biom_", overwrite = FALSE)

Arguments

Value

The normalized directory path that was written to (invisibly).

Examples

library(rbiom)

    tdir <- tempfile()

    write_qiime2(hmp50, tdir, 'qiime2_')
    write_mothur(hmp50, tdir, 'mothur_')

    list.files(tdir)

    readLines(file.path(tdir, 'qiime2_metadata.tsv'), n = 4)

    readLines(file.path(tdir, 'mothur_taxonomy.tsv'), n = 3)

    unlink(tdir, recursive = TRUE)

Description

Global Enteric Multicenter Study (n = 1,006)

Usage

gems

Format

An rbiom object with 1,006 samples. Includes metadata and taxonomy.

diarrhea -

Case or Control

age -

0 - 4.8 (years old)

country -

Bangladesh, Gambia, Kenya, or Mali

Source

doi:10.1186/gb-2014-15-6-r76 and doi:10.1093/nar/gkx1027

See Also

Other Built-In Datasets: babies, hmp50

Examples

gems
table(gems$metadata$country)

Description

Get a glimpse of your metadata.

Usage

## S3 method for class 'rbiom'
glimpse(x, width = NULL, ...)

Arguments

Value

The original biom, invisibly.

See Also

Other metadata: bdply()

Examples

library(rbiom)

    glimpse(hmp50)

Description

Human Microbiome Project - demo dataset (n = 50)

Usage

hmp50

Format

An rbiom object with 50 samples. Includes metadata, taxonomy, phylogeny, and sequences.

Sex -

Male or Female

Body Site -

Anterior nares, Buccal mucosa, Mid vagina, Saliva, or Stool

Age -

21 - 40

BMI -

19 - 32

Source

doi:10.1101/gr.096651.109

See Also

Other Built-In Datasets: babies, gems

Examples

hmp50
hmp50$metadata

Description

A collection of transformations that operate directly on matrices.

Usage

mtx_rarefy(
  mtx,
  margin = 2L,
  depth = 0.1,
  n = NULL,
  seed = 0L,
  upsample = NULL,
  cpus = NULL
)

mtx_percent(mtx, margin = 2L)

mtx_rescale(mtx, margin = 2L, range = c(0, 1))

rarefy_cols(mtx, depth = 0.1, n = NULL, seed = 0L, cpus = NULL)

rescale_rows(mtx)

rescale_cols(mtx)

Arguments

Value

A A numeric matrix or sparse matrix, depending on the input type, with the same dimensions as mtx.

Examples

mtx <- matrix(1:12, ncol = 3, dimnames = list(paste0("OTU", 1:4), paste0("Sample", 1:3)))

    mtx

    suppressWarnings({

      mtx_rarefy(mtx)

      rarefy_cols(mtx)

      mtx_percent(mtx)

      mtx_rescale(mtx)

      rescale_rows(mtx)

      rescale_cols(mtx)

    })

Description

mutate() creates new fields in ⁠$metadata⁠ that are functions of existing metadata fields. It can also modify (if the name is the same as an existing field) and delete fields (by setting their value to NULL).

Usage

## S3 method for class 'rbiom'
mutate(.data, ..., clone = TRUE)

## S3 method for class 'rbiom'
rename(.data, ..., clone = TRUE)

Arguments

Value

An rbiom object.

See Also

Other transformations: biom_inflate(), biom_relativize(), biom_rescale(), rarefy(), slice_metadata, subset, with

Examples

library(rbiom)

    biom <- slice_max(hmp50, BMI, n = 6)
    biom$metadata

    # Add a new field to the metadata
    biom <- mutate(biom, Obsese = BMI >= 30)
    biom$metadata

    # Rename a metadata field
    biom <- rename(biom, 'Age (years)' = "Age")
    biom$metadata

Description

Create a heatmap with tracks and dendrograms from any matrix.

Usage

plot_heatmap(
  mtx,
  grid = list(label = "Grid Value", colors = "imola"),
  tracks = NULL,
  label = TRUE,
  label_size = NULL,
  rescale = "none",
  trees = TRUE,
  clust = "complete",
  dist = "euclidean",
  asp = 1,
  tree_height = 10,
  track_height = 10,
  legend = "right",
  title = NULL,
  xlab.angle = "auto",
  ...
)

Arguments

Value

A ggplot2 plot. The computed data points and ggplot command are available as ⁠$data⁠ and ⁠$code⁠, respectively.

Track Definitions

One or more colored tracks can be placed on the left and/or top of the heatmap grid to visualize associated metadata values.

## Categorical ----------------------------
cat_vals <- sample(c("Male", "Female"), 10, replace = TRUE)
tracks   <- list('Sex' = cat_vals)
tracks   <- list('Sex' = list(values = cat_vals, colors = "bright"))
tracks   <- list('Sex' = list(
  values = cat_vals,
  colors = c('Male' = "blue", 'Female' = "red")) )

## Numeric --------------------------------
num_vals <- sample(25:40, 10, replace = TRUE)
tracks   <- list('Age' = num_vals)
tracks   <- list('Age' = list(values = num_vals, colors = "greens"))
tracks   <- list('Age' = list(values = num_vals, range = c(0,50)))
tracks   <- list('Age' = list(
  label  = "Age (Years)",
  values = num_vals,
  colors = c("azure", "darkblue", "darkorchid") ))

## Multiple Tracks ------------------------
tracks <- list('Sex' = cat_vals, 'Age' = num_vals)
tracks <- list(
  list(label = "Sex", values = cat_vals, colors = "bright"),
  list(label = "Age", values = num_vals, colors = "greens") )


mtx           <- matrix(sample(1:50), ncol = 10)
dimnames(mtx) <- list(letters[1:5], LETTERS[1:10])
plot_heatmap(mtx = mtx, tracks = tracks)

The following entries in the track definitions are understood:

values -

The metadata values. When unnamed, order must match matrix.

range -

The c(min,max) to use for scale values.

label -

Label for this track. Defaults to the name of this list element.

side -

Options are "top" (default) or "left".

colors -

A pre-defined palette name or custom set of colors to map to.

na.color -

The color to use for NA values.

bins -

Bin a gradient into this many bins/steps.

guide -

A list of arguments for guide_colorbar() or guide_legend().

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".

The available numeric palette names are: "reds", "oranges", "greens", "purples", "grays", "acton", "bamako", "batlow", "bilbao", "buda", "davos", "devon", "hawaii", "imola", "lajolla", "lapaz", "nuuk", "oslo", "tokyo", "turku", "bam", "berlin", "broc", "cork", "lisbon", "roma", "tofino", "vanimo", and "vik".

See Also

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

Examples

library(rbiom)

    set.seed(123)
    mtx <- matrix(runif(5*8), nrow = 5, dimnames = list(LETTERS[1:5], letters[1:8]))

    plot_heatmap(mtx)
    plot_heatmap(mtx, grid="oranges")
    plot_heatmap(mtx, grid=list(colors = "oranges", label = "Litres"))

    # Tracks go on top (one value per column) unless side = "left"
    # (one value per row).
    tracks <- list(
      'Number' = sample(1:ncol(mtx)),
      'Person' = list(
        values = factor(sample(c("Alice", "Bob"), ncol(mtx), TRUE)),
        colors = c('Alice' = "purple", 'Bob' = "darkcyan") ),
      'State' = list(
        side   = "left",
        values = sample(c("TX", "OR", "WA"), nrow(mtx), TRUE),
        colors = "bright" )
    )

    plot_heatmap(mtx, tracks=tracks)

Description

Map sample names to metadata field values.

Usage

## S3 method for class 'rbiom'
pull(.data, var = -1, name = ".sample", ...)

Arguments

Value

A vector of metadata values, named with sample names.

See Also

taxa_map()

Other samples: sample_sums()

Examples

library(rbiom)

    pull(hmp50, 'Age') %>% head()

    pull(hmp50, 'bod') %>% head(4)

Description

Visualize rarefaction curves with scatterplots and trendlines.

Usage

rare_corrplot(
  biom,
  adiv = "Shannon",
  layers = "tc",
  rline = TRUE,
  stat.by = NULL,
  facet.by = NULL,
  colors = TRUE,
  shapes = TRUE,
  test = "none",
  fit = "log",
  at = NULL,
  level = 0.95,
  p.adj = "fdr",
  transform = "none",
  alt = "!=",
  mu = 0,
  caption = TRUE,
  check = FALSE,
  cpus = n_cpus(),
  ...
)

Arguments

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 rarefaction: rare_multiplot(), rare_stacked(), sample_sums()

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

Examples

library(rbiom)

    biom <- subset(hmp50, `Body Site` %in% c('Saliva', 'Stool'))
    rare_corrplot(biom, stat.by = "body", adiv = c("sh", "o"), facet.by = "Sex")

Description

Combines rare_corrplot and rare_stacked into a single figure.

Usage

rare_multiplot(
  biom,
  adiv = "Shannon",
  layers = "tc",
  rline = TRUE,
  stat.by = NULL,
  facet.by = NULL,
  colors = TRUE,
  shapes = TRUE,
  test = "none",
  fit = "log",
  at = NULL,
  level = 0.95,
  p.adj = "fdr",
  transform = "none",
  alt = "!=",
  mu = 0,
  caption = TRUE,
  check = FALSE,
  cpus = n_cpus(),
  ...
)

Arguments