Skip to contents

Summarize a MicrobiomeStat Data Object

Source: R/mStat_summarize_data_obj.R
mStat_summarize_data_obj.Rd

Provides a comprehensive summary of a MicrobiomeStat data object including feature statistics, metadata overview, and optional time-series visualization.

Usage

mStat_summarize_data_obj(
  data.obj,
  time.var = NULL,
  group.var = NULL,
  palette = NULL
)

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.

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.

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

Value

A tibble containing summary statistics for features, samples, annotations, and tree.

Details

The function first checks if each component of the MicrobiomeStat data object is not null. If a component is not null, it is summarized and added to the output list. For the feature.tab, it computes the sparsity and singleton features. For the meta.dat, it computes the number of samples and metadata fields, and the distribution of samples if a time variable is provided. The inclusion of a time variable allows the user to gain insights into how samples are distributed over time. For the feature.ann, it computes the number of features, annotations, and the proportion of NA values for each annotation. It also checks if a phylogenetic tree exists in the data object.

Examples

if (FALSE) { # \dontrun{
  # Assuming 'data.obj' is your MicrobiomeStat data object
  # Summary with time variable
  # summary_list <- mStat_summarize_data_obj(data.obj, time.var = "time")

  # Summary without time variable
  # summary_list <- mStat_summarize_data_obj(data.obj)

  # If you have a microbiome data available as a MicrobiomeStat data object
  # you can dplyr::summarize it using:
  # library(MicrobiomeStat)
  # data(data.obj)
  # Summary with time variable
  # summary_list <- mStat_summarize_data_obj(data.obj, time.var = "time")

  # Summary without time variable
  # summary_list <- mStat_summarize_data_obj(data.obj)
  data(subset_T2D.obj)
  summary <- mStat_summarize_data_obj(subset_T2D.obj, "visit_number", "subject_race")
} # }