rarefy_pq: Rarefy a phyloseq object, optionally averaging over...

In MiscMetabar: Miscellaneous Functions for Metabarcoding Analysis

Rarefy a phyloseq object, optionally averaging over repetitions

Description

Rarefy (subsample to an even depth) a phyloseq object. rarefy_pq() is a drop-in, R-version-robust replacement for phyloseq::rarefy_even_depth() that can additionally repeat the rarefaction n times and return the averaged OTU table, reducing the stochasticity of a single subsampling pass. With n = 1 (default) the behaviour matches a standard single rarefaction.

Usage

rarefy_pq(physeq, sample_size = NULL, n = 1, seed = 123, replace = FALSE, ...)

Arguments

physeq	(required) a phyloseq-class object obtained using the phyloseq package.
sample_size	(integer) the depth to rarefy to. If NULL (default), the minimum sample_sums(physeq) is used. Samples with fewer reads than sample_size are dropped.
n	(integer, default 1) number of rarefaction repetitions to average over. Values > 1 return a non-integer (averaged) OTU table.
seed	(integer, default 123) random seed. Set to FALSE to leave the random number generator untouched (i.e. use the current RNG state), mirroring the rngseed argument of phyloseq::rarefy_even_depth().
replace	(logical, default FALSE) sample with replacement? FALSE (without replacement) is the recommended, less biased default. TRUE reproduces the default behaviour of phyloseq::rarefy_even_depth().
...	Not used. Kept for backward compatibility.

Details

Rarefaction is performed internally rather than by calling phyloseq::rarefy_even_depth(), whose replace = FALSE code path relies on rep_len(x["OTUi"], x["times"]) and errors with ⁠invalid 'length.out' value⁠ under recent R-devel (see phyloseq issue 1753). For a single rarefaction (n = 1), the result is identical to phyloseq::rarefy_even_depth() with trimOTUs = FALSE for the same seed, sample_size and replace — except in the degenerate case where a retained sample has a single read, in which phyloseq triggers a sample() edge-case bug that rarefy_pq() avoids. Empty OTUs are never trimmed.

Value

A new phyloseq-class object with a rarefied (or averaged-rarefied) otu_table.

Author(s)

Adrien Taudière

See Also

phyloseq::rarefy_even_depth(), transform_pq()

Examples

data_f_rar <- rarefy_pq(data_fungi_mini, sample_size = 500, seed = 1)
sample_sums(data_f_rar)

data_f_rar5 <- rarefy_pq(data_fungi_mini, sample_size = 500, n = 5, seed = 1)
sample_sums(data_f_rar5)

MiscMetabar documentation built on June 8, 2026, 5:07 p.m.