tax_transform: Transform taxa in phyloseq object and record transformation

In david-barnett/microViz: Microbiome Data Analysis and Visualization

Transform taxa in phyloseq object and record transformation

Description

Transform taxa features, and optionally aggregate at specified taxonomic rank beforehand. You can pipe the results of tax_agg into tax_transform, or equivalently set the rank argument in tax_transform.

Usage

tax_transform(
  data,
  trans,
  rank = NA,
  keep_counts = TRUE,
  chain = FALSE,
  zero_replace = 0,
  add = 0,
  transformation = NULL,
  ...
)

Arguments

data	a phyloseq object or psExtra output from tax_agg
trans	any valid taxa transformation (e.g. from microbiome::transform)
rank	If data is phyloseq: data are aggregated at this rank before transforming. If NA, runs tax_agg(data, rank = NA). If rank is NA and data is already psExtra, any preceding aggregation is left as is.
keep_counts	if TRUE, store the pre-transformation count data in psExtra counts slot
chain	if TRUE, transforming again is possible when data are already transformed i.e. multiple transformations can be chained with multiple tax_transform calls
zero_replace	Replace any zeros with this value before transforming. Either a numeric, or "halfmin" which replaces zeros with half of the smallest value across the entire dataset. Beware: the choice of zero replacement is not tracked in the psExtra output.
add	Add this value to the otu_table before transforming. If add != 0, zero_replace does nothing. Either a numeric, or "halfmin". Beware: this choice is not tracked in the psExtra output.
transformation	deprecated, use trans instead!
...	any extra arguments passed to microbiome::transform or pass undetected = ⁠a number⁠ when using trans = "binary"

Details

This function often uses microbiome::transform internally and can perform the same transformations, including many from vegan::decostand (where the default MARGIN = 2). See below for notes about some of the available transformations.

tax_transform returns a psExtra containing the transformed phyloseq object and extra info (used for annotating ord_plot ordinations):

• tax_transform (a string recording the transformation),

• tax_agg (a string recording the taxonomic aggregation rank if specified here or earlier in tax_agg).

A few commonly used transformations:

• "clr", or "rclr", perform the centered log ratio transformation, or the robust clr, using microbiome::transform

• "compositional" converts the data into proportions, from 0 to 1.

• "identity" does not transform the data, and records this choice for ord_plot

• "binary" can be used to transform tax abundances into presence/abundance data.

• "log2" which performs a log base 2 transformation (don't forget to set zero_replace if there are any zeros in your data)

Value

psExtra object including phyloseq and extra info

(r)clr transformation note

If any values are zero, the clr transform routine first adds a small pseudocount of min(relative abundance)/2 to all values. To avoid this, you can replace any zeros in advance by setting zero_replace to a number > 0.

The rclr transform does not replace zeros. Instead, only non-zero features are transformed, using the geometric mean of non-zero features as denominator.

Binary transformation notes

By default, otu_table values of 0 are kept as 0, and all positive values are converted to 1 (like decostand(method = "pa")). You can set a different threshold, by passing e.g. undetected = 10, for example, in which case all abundances of 10 or below would be converted to 0. All abundances above 10 would be converted to 1s.

Beware that the choice of detection threshold is not tracked in the psExtra.

See Also

microbiome::transform for some more info on available transformations

vegan::decostand for even more transformation options

tax_agg

Examples

data("dietswap", package = "microbiome")

# aggregate taxa at Phylum level and center log ratio transform the phyla counts
tax_transform(dietswap, trans = "clr", rank = "Phylum")

# this is equivalent to the two-step method (agg then transform)
tax_agg(dietswap, rank = "Phylum") %>% tax_transform("clr")

# does nothing except record tax_agg as "unique" and tax_transform as "identity" in psExtra info
dietswap %>% tax_transform("identity", rank = NA)

# binary transformation (convert abundances to presence/absence or detected/undetected)
tax_transform(dietswap, trans = "binary", rank = "Genus")
# change detection threshold by setting undetected argument (default is 0)
tax_transform(dietswap, trans = "binary", rank = "Genus", undetected = 50) %>%
  otu_get() %>%
  .[1:6, 1:4]

# log2 transformation after replacing all zeros with a pseudocount of 1
tax_transform(dietswap, trans = "log2", rank = "Family", zero_replace = 1)

# log2 transformation after replacing all zeros with a pseudocount of half
# the minimum non-zero count value in the aggregated dataset
tax_transform(dietswap, trans = "log2", rank = "Family", zero_replace = "halfmin")

david-barnett/microViz documentation built on April 17, 2025, 4:25 a.m.