trans_abund: Create `trans_abund` object for plotting taxonomic abundance.

Description

This class is a wrapper for the taxonomic abundance transformations and visualization. The converted data style is the long-format for ggplot2 plot. The plotting methods include bar plot, boxplot, heatmap, pie chart and line chart.

Arguments

Methods

Public methods

Method `new()`

Usage

trans_abund$new(
  dataset = NULL,
  taxrank = "Phylum",
  show = 0,
  ntaxa = 10,
  groupmean = NULL,
  group_morestats = FALSE,
  delete_full_prefix = TRUE,
  delete_part_prefix = FALSE,
  prefix = NULL,
  use_percentage = TRUE,
  input_taxaname = NULL,
  high_level = NULL,
  high_level_fix_nsub = NULL
)

Arguments

dataset: default NULL; the object of microtable class.

taxrank

default "Phylum"; taxonomic rank.

show

default 0; the relative abundance threshold for filtering the taxa with low abundance.

ntaxa

default 10; how many taxa are selected to show. Taxa are ordered by abundance from high to low. This parameter does not conflict with the parameter show. Both can be used. ntaxa = NULL means it is unavailable.

groupmean

default NULL; calculate mean abundance for each group. Select a column name in microtable$sample_table.

group_morestats

default FALSE; only available when groupmean parameter is provided; Whether output more statistics for each group, including min, max, median and quantile; Thereinto, quantile25 and quantile75 denote 25% and 75% quantiles, respectively.

delete_full_prefix

default TRUE; whether delete both the prefix of taxonomy and the character in front of them.

delete_part_prefix

default FALSE; whether only delete the prefix of taxonomy.

prefix

default NULL; character string; can be used when delete_full_prefix = T or delete_part_prefix = T; default NULL reprensents using the "letter+__", e.g. "k__" for Phylum level; Please alter this parameter when the prefix is not standard.

use_percentage

default TRUE; show the abundance percentage.

input_taxaname

default NULL; character vector; input taxa names for selecting some taxa.

high_level

default NULL; a taxonomic rank, such as "Phylum", used to add the taxonomic information of higher level. It is necessary for the legend with nested taxonomic levels in the bar plot.

high_level_fix_nsub

default NULL; an integer, used to fix the number of selected abundant taxa in each taxon from higher taxonomic level. If the total number under one taxon of higher level is less than the high_level_fix_nsub, the total number will be used. When high_level_fix_nsub is provided, the taxa number of higher level is calculated as: ceiling(ntaxa/high_level_fix_nsub). Note that ntaxa means either the parameter ntaxa or the taxonomic number obtained by filtering according to the show parameter.

Returns

data_abund stored in the object. The column 'all_mean_abund' reprensents mean relative abundance across all the samples. So the values in one taxon are all same across all the samples. If the sum of column 'Abundance' in one sample is larger than 1, the 'Abundance', 'SD' and 'SE' has been multiplied by 100.

Examples

\donttest{
data(dataset)
t1 <- trans_abund$new(dataset = dataset, taxrank = "Phylum", ntaxa = 10)
}

Method `plot_bar()`

Bar plot.

Usage

trans_abund$plot_bar(
  color_values = RColorBrewer::brewer.pal(8, "Dark2"),
  bar_type = "full",
  others_color = "grey90",
  facet = NULL,
  order_x = NULL,
  x_axis_name = NULL,
  barwidth = NULL,
  use_alluvium = FALSE,
  clustering = FALSE,
  clustering_plot = FALSE,
  cluster_plot_width = 0.2,
  facet_color = "grey95",
  strip_text = 11,
  legend_text_italic = FALSE,
  xtext_angle = 0,
  xtext_size = 10,
  xtext_keep = TRUE,
  xtitle_keep = TRUE,
  ytitle_size = 17,
  coord_flip = FALSE,
  ggnested = FALSE,
  high_level_add_other = FALSE
)

Arguments

color_values: default RColorBrewer::brewer.pal(8, "Dark2"); colors palette for the bars.

bar_type

default "full"; "full" or "notfull"; if "full", total abundance are summed to 1 or 100 percentage.

others_color

default "grey90"; the color for "others" taxa.

facet

default NULL; a character vector for the facet; group column name of sample_table, such as, "Group"; If multiple facets are needed, please provide ordered names, such as c("Group", "Type"). The latter should have a finer scale than the former one; Please adjust the facet orders in the plot by assigning factors in sample_table before creating trans_abund object or assigning factors in the data_abund table of trans_abund object. When multiple facets are used, please first install package ggh4x using the command install.packages("ggh4x").

order_x

default NULL; vector; used to order the sample names in x axis; must be the samples vector, such as c("S1", "S3", "S2").

x_axis_name

NULL; a character string; a column name of sample_table in dataset; used to show the sample names in x axis.

barwidth

default NULL; bar width, see width in geom_bar.

use_alluvium

default FALSE; whether add alluvium plot. If TRUE, please first install ggalluvial package.

clustering

default FALSE; whether order samples by the clustering.

clustering_plot

default FALSE; whether add clustering plot. If clustering_plot = TRUE, clustering will be also TRUE in any case for the clustering.

cluster_plot_width

default 0.2, the dendrogram plot width; available when clustering_plot = TRUE.

facet_color

default "grey95"; facet background color.

strip_text

default 11; facet text size.

legend_text_italic

default FALSE; whether use italic in legend.

xtext_angle

default 0; number ranging from 0 to 90; used to adjust x axis text angle to reduce text overlap;

xtext_size

default 10; x axis text size.

xtext_keep

default TRUE; whether retain x text.

xtitle_keep

default TRUE; whether retain x title.

ytitle_size

default 17; y axis title size.

coord_flip

default FALSE; whether flip cartesian coordinates so that horizontal becomes vertical, and vertical becomes horizontal.

ggnested

default FALSE; whether use nested legend. Need ggnested package to be installed (https://github.com/gmteunisse/ggnested). To make it available, please assign high_level parameter when creating the object.

high_level_add_other

default FALSE; whether add 'Others' (all the unknown taxa) in each taxon of higher taxonomic level. Only available when ggnested = TRUE.

Returns

ggplot2 object.

Examples

\donttest{
t1$plot_bar(facet = "Group", xtext_keep = FALSE)
}

Method `plot_heatmap()`

Plot the heatmap.

Usage

trans_abund$plot_heatmap(
  color_values = rev(RColorBrewer::brewer.pal(n = 11, name = "RdYlBu")),
  facet = NULL,
  x_axis_name = NULL,
  order_x = NULL,
  withmargin = TRUE,
  plot_numbers = FALSE,
  plot_text_size = 4,
  plot_breaks = NULL,
  margincolor = "white",
  plot_colorscale = "log10",
  min_abundance = 0.01,
  max_abundance = NULL,
  strip_text = 11,
  xtext_size = 10,
  ytext_size = 11,
  xtext_keep = TRUE,
  xtitle_keep = TRUE,
  grid_clean = TRUE,
  xtext_angle = 0,
  legend_title = "% Relative\nAbundance",
  pheatmap = FALSE,
  ...
)

Arguments

color_values: default rev(RColorBrewer::brewer.pal(n = 11, name = "RdYlBu")); colors palette for the plotting.

facet

default NULL; a character vector for the facet; a group column name of sample_table, such as, "Group"; If multiple facets are needed, please provide ordered names, such as c("Group", "Type"). The latter should have a finer scale than the former one; Please adjust the facet orders in the plot by assigning factors in sample_table before creating trans_abund object or assigning factors in the data_abund table of trans_abund object. When multiple facets are used, please first install package ggh4x using the command install.packages("ggh4x").

x_axis_name

NULL; a character string; a column name of sample_table used to show the sample names in x axis.

order_x

default NULL; vector; used to order the sample names in x axis; must be the samples vector, such as, c("S1", "S3", "S2").

withmargin

default TRUE; whether retain the tile margin.

plot_numbers

default FALSE; whether plot the number in heatmap.

plot_text_size

default 4; If plot_numbers TRUE, text size in plot.

plot_breaks

default NULL; The legend breaks.

margincolor

default "white"; If withmargin TRUE, use this as the margin color.

plot_colorscale

default "log10"; color scale.

min_abundance

default .01; the minimum abundance percentage in plot.

max_abundance

default NULL; the maximum abundance percentage in plot, NULL reprensent the max percentage.

strip_text

default 11; facet text size.

xtext_size

default 10; x axis text size.

ytext_size

default 11; y axis text size.

xtext_keep

default TRUE; whether retain x text.

xtitle_keep

default TRUE; whether retain x title.

grid_clean

default TRUE; whether remove grid lines.

xtext_angle

default 0; number ranging from 0 to 90; used to adjust x axis text angle to reduce text overlap;

legend_title

default "% Relative\nAbundance"; legend title text.

pheatmap

default FALSE; whether use pheatmap package to plot the heatmap.

...

paremeters pass to pheatmap when pheatmap = TRUE.

Returns

ggplot2 object or grid object based on pheatmap.

Examples

\donttest{
t1 <- trans_abund$new(dataset = dataset, taxrank = "Genus", ntaxa = 40)
t1$plot_heatmap(facet = "Group", xtext_keep = FALSE, withmargin = FALSE)
}

Method `plot_box()`

Box plot.

Usage

trans_abund$plot_box(
  color_values = RColorBrewer::brewer.pal(8, "Dark2"),
  group = NULL,
  show_point = FALSE,
  point_color = "black",
  point_size = 3,
  point_alpha = 0.3,
  plot_flip = FALSE,
  boxfill = TRUE,
  middlecolor = "grey95",
  middlesize = 1,
  xtext_angle = 0,
  xtext_size = 10,
  ytitle_size = 17,
  ...
)

Arguments

color_values: default RColorBrewer::brewer.pal(8, "Dark2"); colors palette for the box.

group

default NULL; a column name of sample table to show abundance across groups.

show_point

default FALSE; whether show points in plot.

point_color

default "black"; If show_point TRUE; use the color

point_size

default 3; If show_point TRUE; use the size

point_alpha

default .3; If show_point TRUE; use the transparency.

plot_flip

default FALSE; Whether rotate plot.

boxfill

default TRUE; Whether fill the box with colors.

middlecolor

default "grey95"; The middle line color.

middlesize

default 1; The middle line size.

xtext_angle

default 0; number ranging from 0 to 90; used to adjust x axis text angle to reduce text overlap;

xtext_size

default 10; x axis text size.

ytitle_size

default 17; y axis title size.

...

parameters pass to geom_boxplot function.

Returns

ggplot2 object.

Examples

\donttest{
t1$plot_box(group = "Group")
}

Method `plot_line()`

Plot the line chart.

Usage

trans_abund$plot_line(
  color_values = RColorBrewer::brewer.pal(8, "Dark2"),
  plot_SE = TRUE,
  position = position_dodge(0.1),
  errorbar_size = 1,
  errorbar_width = 0.1,
  point_size = 3,
  point_alpha = 0.8,
  line_size = 0.8,
  line_alpha = 0.8,
  line_type = 1,
  xtext_angle = 0,
  xtext_size = 10,
  ytitle_size = 17
)

Arguments

color_values: default RColorBrewer::brewer.pal(8, "Dark2"); colors palette for the points and lines.

plot_SE

default TRUE; TRUE: the errorbar is $mean±se$; FALSE: the errorbar is $mean±sd$.

position

default position_dodge(0.1); Position adjustment, either as a string (such as "identity"), or the result of a call to a position adjustment function.

errorbar_size

default 1; errorbar size.

errorbar_width

default 0.1; errorbar width.

point_size

default 3; point size for taxa.

point_alpha

default 0.8; point transparency.

line_size

default 0.8; line size.

line_alpha

default 0.8; line transparency.

line_type

default 1; an integer; line type.

xtext_angle

default 0; number ranging from 0 to 90; used to adjust x axis text angle to reduce text overlap;

xtext_size

default 10; x axis text size.

ytitle_size

default 17; y axis title size.

Returns

ggplot2 object.

Examples

\donttest{
t1 <- trans_abund$new(dataset = dataset, taxrank = "Genus", ntaxa = 5)
t1$plot_line(point_size = 3)
t1 <- trans_abund$new(dataset = dataset, taxrank = "Genus", ntaxa = 5, groupmean = "Group")
t1$plot_line(point_size = 5, errorbar_size = 1, xtext_angle = 30)
}

Method `plot_pie()`

Pie chart.

Usage

trans_abund$plot_pie(
  color_values = RColorBrewer::brewer.pal(8, "Dark2"),
  facet_nrow = 1,
  strip_text = 11,
  add_label = FALSE,
  legend_text_italic = FALSE
)

Arguments

color_values: default RColorBrewer::brewer.pal(8, "Dark2"); colors palette for each section.

facet_nrow

default 1; how many rows in the plot.

strip_text

default 11; sample title size.

add_label

default FALSE; Whether add the percentage label in each section of pie chart.

legend_text_italic

default FALSE; whether use italic in legend.

Returns

ggplot2 object.

Examples

\donttest{
t1 <- trans_abund$new(dataset = dataset, taxrank = "Phylum", ntaxa = 6, groupmean = "Group")
t1$plot_pie(facet_nrow = 1)
}

Method `plot_donut()`

Donut chart based on the ggpubr::ggdonutchart function.

Usage

trans_abund$plot_donut(
  color_values = RColorBrewer::brewer.pal(8, "Dark2"),
  label = TRUE,
  facet_nrow = 1,
  legend_text_italic = FALSE,
  ...
)

Arguments

color_values: default RColorBrewer::brewer.pal(8, "Dark2"); colors palette for the donut.

label

default TRUE; whether show the percentage label.

facet_nrow

default 1; how many rows in the plot.

legend_text_italic

default FALSE; whether use italic in legend.

...

parameters passed to ggpubr::ggdonutchart.

Returns

combined ggplot2 objects list, generated by ggpubr::ggarrange function.

Examples

\dontrun{
t1 <- trans_abund$new(dataset = dataset, taxrank = "Phylum", ntaxa = 6, groupmean = "Group")
t1$plot_donut(label = TRUE)
}

Method `plot_radar()`

Radar chart based on the ggradar package (https://github.com/ricardo-bion/ggradar).

Usage

trans_abund$plot_radar(
  color_values = RColorBrewer::brewer.pal(8, "Dark2"),
  ...
)

Arguments

color_values: default RColorBrewer::brewer.pal(8, "Dark2"); colors palette for samples.

...

parameters passed to ggradar::ggradar function except group.colours parameter.

Returns

ggplot2 object.

Examples

\dontrun{
t1 <- trans_abund$new(dataset = dataset, taxrank = "Phylum", ntaxa = 6, groupmean = "Group")
t1$plot_radar()
}

Method `plot_tern()`

Ternary diagrams based on the ggtern package.

Usage

trans_abund$plot_tern(
  color_values = RColorBrewer::brewer.pal(8, "Dark2"),
  color_legend_guide_size = 4
)

Arguments

color_values: default RColorBrewer::brewer.pal(8, "Dark2"); colors palette for the samples.

color_legend_guide_size

default 4; The size of legend guide for color.

Returns

ggplot2 object.

Examples

\dontrun{
t1 <- trans_abund$new(dataset = dataset, taxrank = "Phylum", ntaxa = 6, groupmean = "Group")
t1$plot_tern()
}

Method `print()`

Print the trans_abund object.

Usage

trans_abund$print()

Method `clone()`

The objects of this class are cloneable with this method.

Usage

trans_abund$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

Run this code


## ------------------------------------------------
## Method `trans_abund$new`
## ------------------------------------------------

# \donttest{
data(dataset)
t1 <- trans_abund$new(dataset = dataset, taxrank = "Phylum", ntaxa = 10)
# }

## ------------------------------------------------
## Method `trans_abund$plot_bar`
## ------------------------------------------------

# \donttest{
t1$plot_bar(facet = "Group", xtext_keep = FALSE)
# }

## ------------------------------------------------
## Method `trans_abund$plot_heatmap`
## ------------------------------------------------

# \donttest{
t1 <- trans_abund$new(dataset = dataset, taxrank = "Genus", ntaxa = 40)
t1$plot_heatmap(facet = "Group", xtext_keep = FALSE, withmargin = FALSE)
# }

## ------------------------------------------------
## Method `trans_abund$plot_box`
## ------------------------------------------------

# \donttest{
t1$plot_box(group = "Group")
# }

## ------------------------------------------------
## Method `trans_abund$plot_line`
## ------------------------------------------------

# \donttest{
t1 <- trans_abund$new(dataset = dataset, taxrank = "Genus", ntaxa = 5)
t1$plot_line(point_size = 3)
t1 <- trans_abund$new(dataset = dataset, taxrank = "Genus", ntaxa = 5, groupmean = "Group")
t1$plot_line(point_size = 5, errorbar_size = 1, xtext_angle = 30)
# }

## ------------------------------------------------
## Method `trans_abund$plot_pie`
## ------------------------------------------------

# \donttest{
t1 <- trans_abund$new(dataset = dataset, taxrank = "Phylum", ntaxa = 6, groupmean = "Group")
t1$plot_pie(facet_nrow = 1)
# }

## ------------------------------------------------
## Method `trans_abund$plot_donut`
## ------------------------------------------------

if (FALSE) {
t1 <- trans_abund$new(dataset = dataset, taxrank = "Phylum", ntaxa = 6, groupmean = "Group")
t1$plot_donut(label = TRUE)
}

## ------------------------------------------------
## Method `trans_abund$plot_radar`
## ------------------------------------------------

if (FALSE) {
t1 <- trans_abund$new(dataset = dataset, taxrank = "Phylum", ntaxa = 6, groupmean = "Group")
t1$plot_radar()
}

## ------------------------------------------------
## Method `trans_abund$plot_tern`
## ------------------------------------------------

if (FALSE) {
t1 <- trans_abund$new(dataset = dataset, taxrank = "Phylum", ntaxa = 6, groupmean = "Group")
t1$plot_tern()
}

Run the code above in your browser using DataLab

Description

Arguments

Methods

Public methods

Method new()

Usage

Arguments

Returns

Examples

Method plot_bar()

Usage

Arguments

Returns

Examples

Method plot_heatmap()

Usage

Arguments

Returns

Examples

Method plot_box()

Usage

Arguments

Returns

Examples

Method plot_line()

Usage

Arguments

Returns

Examples

Method plot_pie()

Usage

Arguments

Returns

Examples

Method plot_donut()

Usage

Arguments

Returns

Examples

Method plot_radar()

Usage

Arguments

Returns

Examples

Method plot_tern()

Usage

Arguments

Returns

Examples

Method print()

Usage

Method clone()

Usage

Arguments

Examples

Method `new()`

Method `plot_bar()`

Method `plot_heatmap()`

Method `plot_box()`

Method `plot_line()`

Method `plot_pie()`

Method `plot_donut()`

Method `plot_radar()`

Method `plot_tern()`

Method `print()`

Method `clone()`