Generate Taxa Heatmap for Single Time Point

Generates hierarchical clustered heatmaps for microbiome data at a single time point using the pheatmap package, with options for group and strata annotations.

Usage

generate_taxa_heatmap_single(
  data.obj,
  time.var = NULL,
  t.level = NULL,
  group.var = NULL,
  strata.var = NULL,
  other.vars = NULL,
  feature.level,
  feature.dat.type = c("count", "proportion", "other"),
  features.plot = NULL,
  top.k.plot = NULL,
  top.k.func = NULL,
  prev.filter = 0.01,
  abund.filter = 0.01,
  base.size = 10,
  palette = NULL,
  cluster.cols = NULL,
  cluster.rows = NULL,
  pdf = TRUE,
  file.ann = NULL,
  pdf.wid = 11,
  pdf.hei = 8.5,
  ...
)

Arguments

data.obj

A MicrobiomeStat data object, which is a list containing at minimum the following components:

feature.tab: A matrix of feature abundances (taxa/genes as rows, samples as columns)
meta.dat: A data frame of sample metadata (samples as rows)

Optional components include:

feature.ann: A matrix/data frame of feature annotations (e.g., taxonomy)
tree: A phylogenetic tree object (class "phylo")
feature.agg.list: Pre-aggregated feature tables by taxonomy

Data objects can be created using converters like mStat_convert_phyloseq_to_data_obj or importers like mStat_import_qiime2_as_data_obj.

time.var

Character string specifying the column name in meta.dat containing the time variable. Required for longitudinal and paired analyses. Supports character/factor labels (e.g., "baseline", "week4") and numeric values. Some trend/volatility methods require numeric or coercible-to-numeric time values.

t.level

Character string specifying the time level/value to subset data to. Default NULL does not subset data.

group.var

Character string specifying the column name in meta.dat containing the grouping variable (e.g., treatment, condition, phenotype). Used for between-group comparisons.

strata.var

Character string specifying the column name in meta.dat for stratification. When provided, analyses and visualizations will be performed separately within each stratum (e.g., by site, batch, or sex).

other.vars

A character vector specifying additional metadata variables to include in the heatmap annotation. Default is NULL.

feature.level

Character vector specifying the taxonomic or annotation level(s) for analysis. Should match column names in feature.ann, such as "Phylum", "Family", "Genus", etc. Use "original" to analyze at the original feature level without aggregation.

feature.dat.type

Character string specifying the data type of feature.tab. One of:

"count": Raw count data (will be normalized)
"proportion": Relative abundance data (should sum to 1 per sample)
"other": Pre-transformed data (no transformation applied)

features.plot

A character vector specifying which feature IDs to plot. Default is NULL, in which case features are selected based on `top.k.plot` and `top.k.func`.

top.k.plot

Integer specifying number of top k features to plot. Default is NULL.

top.k.func

Function to use for selecting top k features (e.g., "mean", "sd"). Default is NULL.

prev.filter

Numeric value between 0 and 1. Features with prevalence (proportion of non-zero samples) below this threshold will be excluded from analysis. Default is usually 0 (no filtering).

abund.filter

Numeric value. Features with mean abundance below this threshold will be excluded from analysis. Default is usually 0 (no filtering).

base.size

Numeric value specifying the base font size for plot text elements. Default is typically 16.

palette

Character vector of colors or a named palette for the plot. If NULL, uses default MicrobiomeStat color scheme. Can be:

A vector of color codes (e.g., c("#E41A1C", "#377EB8"))
A palette name recognized by the plotting function

cluster.cols

Logical indicating if columns should be clustered. Default is NULL.

cluster.rows

Logical indicating if rows should be clustered. Default is NULL.

pdf

Logical. If TRUE, saves the plot(s) to PDF file(s) in the current working directory. Default is TRUE.

file.ann

Character string for additional annotation to append to output filenames. Useful for distinguishing multiple outputs.

pdf.wid

Numeric value specifying the width of PDF output in inches. Default is typically 11.

pdf.hei

Numeric value specifying the height of PDF output in inches. Default is typically 8.5.

...

Additional arguments passed to the pheatmap() function.

Value

An object of class pheatmap, the generated heatmap plot

Examples

if (FALSE) { # \dontrun{
# Load required libraries and example data
library(pheatmap)

data(peerj32.obj)
generate_taxa_heatmap_single(
  data.obj = peerj32.obj,
  time.var = "time",
  t.level = "1",
  group.var = "group",
  strata.var = "sex",
  other.vars = NULL,
  feature.level = c("Phylum", "Family", "Genus"),
  feature.dat.type = "count",
  features.plot = NULL,
  top.k.plot = NULL,
  top.k.func = NULL,
  prev.filter = 0.001,
  abund.filter = 0.01,
  base.size = 10,
  palette = NULL,
  pdf = TRUE,
  file.ann = NULL,
  pdf.wid = 11,
  pdf.hei = 8.5
)
data(peerj32.obj)
generate_taxa_heatmap_single(
  data.obj = peerj32.obj,
  time.var = "time",
  t.level = "1",
  group.var = "group",
  strata.var = "sex",
  other.vars = NULL,
  feature.level = c("Phylum", "Family", "Genus"),
  feature.dat.type = "count",
  features.plot = NULL,
  top.k.plot = NULL,
  top.k.func = NULL,
  cluster.rows = FALSE,
  prev.filter = 0.001,
  abund.filter = 0.01,
  base.size = 10,
  palette = NULL,
  pdf = TRUE,
  file.ann = NULL,
  pdf.wid = 11,
  pdf.hei = 8.5
)
generate_taxa_heatmap_single(
  data.obj = peerj32.obj,
  time.var = "time",
  t.level = "1",
  group.var = "group",
  strata.var = NULL,
  other.vars = NULL,
  feature.level = c("Phylum", "Family", "Genus"),
  feature.dat.type = "count",
  features.plot = NULL,
  top.k.plot = NULL,
  top.k.func = NULL,
  prev.filter = 0.001,
  abund.filter = 0.01,
  base.size = 10,
  palette = NULL,
  pdf = TRUE,
  file.ann = NULL,
  pdf.wid = 11,
  pdf.hei = 8.5
)
generate_taxa_heatmap_single(
  data.obj = peerj32.obj,
  time.var = "time",
  t.level = "1",
  group.var = NULL,
  strata.var = NULL,
  other.vars = NULL,
  feature.level = c("Phylum", "Family", "Genus"),
  feature.dat.type = "count",
  features.plot = NULL,
  top.k.plot = NULL,
  top.k.func = NULL,
  prev.filter = 0.001,
  abund.filter = 0.01,
  base.size = 10,
  palette = NULL,
  pdf = TRUE,
  file.ann = NULL,
  pdf.wid = 11,
  pdf.hei = 8.5
)

data(ecam.obj)
generate_taxa_heatmap_single(
  data.obj = ecam.obj,
  time.var = "month",
  t.level = "0",
  group.var = "antiexposedall",
  strata.var = "diet",
  other.vars = "delivery",
  feature.level = c("Order", "Family", "Genus"),
  feature.dat.type = "proportion",
  features.plot = NULL,
  top.k.plot = NULL,
  top.k.func = NULL,
  prev.filter = 0.001,
  abund.filter = 0.01,
  base.size = 10,
  palette = NULL,
  pdf = TRUE,
  file.ann = NULL,
  pdf.wid = 11,
  pdf.hei = 8.5
)
generate_taxa_heatmap_single(
  data.obj = ecam.obj,
  time.var = "month",
  t.level = "0",
  group.var = "antiexposedall",
  strata.var = "diet",
  other.vars = "delivery",
  feature.level = c("Genus"),
  feature.dat.type = "proportion",
  features.plot = unique(ecam.obj$feature.ann[,"Genus"])[-c(1,9)],
  top.k.plot = NULL,
  top.k.func = NULL,
  prev.filter = 0.001,
  abund.filter = 0.01,
  base.size = 10,
  palette = NULL,
  pdf = TRUE,
  file.ann = NULL,
  pdf.wid = 11,
  pdf.hei = 8.5
)
} # }

Usage

Arguments

Value

See also

Examples