Skip to contents

Normalize a MicrobiomeStat Data Object

Source: R/mStat_normalize_data.R
mStat_normalize_data.Rd

Normalizes feature abundance data using various methods.

Usage

mStat_normalize_data(
  data.obj,
  method = c("Rarefy-TSS", "Rarefy", "TSS", "GMPR", "CSS", "DESeq", "TMM"),
  depth = NULL,
  seed = 123
)

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.

method

Normalization method. One of:

  • "Rarefy-TSS": Rarefaction + Total Sum Scaling (default)

  • "Rarefy": Rarefaction only

  • "TSS": Total Sum Scaling only

  • "GMPR": Geometric Mean of Pairwise Ratios

  • "CSS": Cumulative Sum Scaling (requires metagenomeSeq)

  • "DESeq": DESeq normalization

  • "TMM": Trimmed Mean of M-values (requires edgeR)

depth

Target rarefaction depth for the "Rarefy" and "Rarefy-TSS" methods. If NULL (default), the smallest per-sample total count is used. Ignored by the non-rarefaction methods.

seed

Integer seed used to make rarefaction subsampling reproducible for the "Rarefy" and "Rarefy-TSS" methods. The global RNG state is restored afterwards, so the caller's random stream is not affected. Default is 123.

Value

A list with normalized data object and scale factors.

Details

The function first checks if 'data.obj' is a list. It then retrieves the feature table and estimates the normalization/scale factor based on the chosen method. The data object is then updated with the normalized feature table and the chosen method is added as 'norm.status'. The function returns the normalized data object and the scale factor.

Examples

if (FALSE) { # \dontrun{
# Load example data object
data(peerj32.obj)

# Applying Total Sum Scaling (TSS) normalization
norm_result_tss <- mStat_normalize_data(data.obj = peerj32.obj, method = "TSS")
print(norm_result_tss$data.obj.norm)  # Display normalized data object

# Applying Rarefaction followed by Total Sum Scaling (Rarefy-TSS) with a specified depth
norm_result_rarefy_tss <- mStat_normalize_data(data.obj = peerj32.obj,
method = "Rarefy-TSS", depth = 5000)
print(norm_result_rarefy_tss$data.obj.norm)  # Display normalized data object

# Normalization using Geometric Mean of Pairwise Ratios (GMPR)
norm_result_gmpr <- mStat_normalize_data(data.obj = peerj32.obj, method = "GMPR")
print(norm_result_gmpr$data.obj.norm)  # Display normalized data object

# Utilizing the DESeq normalization method
# This is particularly useful for RNA-seq data from microbiome studies
norm_result_deseq <- mStat_normalize_data(data.obj = peerj32.obj, method = "DESeq")
print(norm_result_deseq$data.obj.norm)  # Display normalized data object

# Example of error handling when an incorrect depth is specified for the "Rarefy" method
tryCatch({
  norm_result_error <- mStat_normalize_data(data.obj = peerj32.obj,
  method = "Rarefy", depth = 10000000)
  print(norm_result_error$data.obj.norm)
}, error = function(e) {
  print(e$message)  # Print the error message if depth is not feasible
})

} # }