Generate Circular Cladogram with Heatmap for Taxonomic Data

Generates a circular cladogram with integrated heatmap for taxonomic differential abundance results. Visualizes phylogenetic relationships and effect sizes across taxonomic levels.

Usage

generate_taxa_cladogram_single(
  data.obj,
  test.list = NULL,
  group.var = NULL,
  feature.level,
  feature.mt.method = "none",
  cutoff = 1,
  color.group.level = NULL,
  palette = NULL,
  pdf = FALSE,
  pdf.width = 10,
  pdf.height = 10,
  time.var = NULL,
  t.level = NULL,
  adj.vars = NULL,
  prev.filter = 0.1,
  abund.filter = 1e-04,
  feature.dat.type = c("count", "proportion", "other")
)

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.

test.list

A list of data frames containing test results (coefficients, P-values) for taxa at each taxonomic level. If NULL, results are generated internally.

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.

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.mt.method

Character string specifying the multiple testing correction method. Options: "fdr", "bonferroni", "holm", "hochberg", "hommel", "BH", "BY", or "none" (default).

cutoff

Numeric. Significance threshold for filtering taxa. Default is 1 (no filtering).

color.group.level

Character string. Taxonomic level for color-coding branches. Defaults to the first level in `feature.level`.

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

pdf

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

pdf.width

Numeric. PDF width in inches. Default is 10.

pdf.height

Numeric. PDF height in inches. Default is 10.

time.var

Character string specifying the column name in meta.dat containing the time variable. Required for longitudinal and paired analyses. Should be a factor or character with meaningful time point labels.

t.level

Character string specifying time point to subset data. Default is NULL.

adj.vars

Character vector specifying column names in meta.dat to be used as covariates for adjustment in statistical models. These variables will be included as fixed effects.

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

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)

Value

A list of `ggplot` objects. Each element in the list corresponds to a comparison group (derived from `test.list` or `group.var`) and contains the circular cladogram with its heatmap. If there's only one comparison, the list will contain a single `ggplot` object.

Examples

if (FALSE) { # \dontrun{
data(subset_T2D.obj)

test.list <- generate_taxa_test_single(
    data.obj = subset_T2D.obj,
    time.var = "visit_number",
    t.level = NULL,
    group.var = "subject_race",
    adj.vars = "subject_gender",
    feature.level = c("Phylum", "Class", "Order", "Family", "Genus", "Species"),
    feature.dat.type = "count",
    prev.filter = 0.1,
    abund.filter = 0.0001,
)

plot.list <- generate_taxa_cladogram_single(
  data.obj = subset_T2D.obj,
  test.list = test.list,
  group.var = "subject_gender",
  feature.level = c("Phylum", "Class", "Order", "Family", "Genus", "Species"),
  feature.mt.method = "none",
  cutoff = 0.9,
  color.group.level = "Order"
)

test.list <- generate_taxa_test_single(
    data.obj = subset_T2D.obj,
    time.var = "visit_number",
    t.level = NULL,
    group.var = "subject_race",
    adj.vars = "subject_gender",
    feature.level = c("Order"),
    feature.dat.type = "count",
    prev.filter = 0.1,
    abund.filter = 0.0001,
)

plot.list <- generate_taxa_cladogram_single(
  data.obj = subset_T2D.obj,
  test.list = test.list,
  group.var = "subject_gender",
  feature.level = c("Order"),
  feature.mt.method = "none",
  cutoff = 0.9,
  color.group.level = "Order"
)

data(peerj32.obj)

test.list <- generate_taxa_test_single(
    data.obj = peerj32.obj,
    time.var = "time",
    t.level = NULL,
    group.var = "group",
    adj.vars = "sex",
    feature.level = c("Phylum","Family","Genus"),
    feature.dat.type = "count",
    prev.filter = 0.1,
    abund.filter = 0.0001,
)

plot.list <- generate_taxa_cladogram_single(
  data.obj = peerj32.obj,
  test.list = test.list,
  group.var = "group",
  feature.level = c("Phylum", "Family", "Genus"),
  cutoff = 0.3,
  color.group.level = "Family"
)
} # }