Robust trimmed centred log-ratio for compositional miRNA panels

Computes a robust trimmed centred log-ratio (rCLR) on a single sample or a samples x features matrix. The centering subset excludes a configurable set of contaminating miRNAs (default: the haemolysis and platelet-activation panel) and trims the top-trim_upper and bottom-trim_lower fractions of the remaining features by abundance before computing the geometric mean used as the CLR denominator. Falls back to a global CLR (with warning) when the centering subset shrinks below min_centering_size.

Usage

ws_rclr_trimmed(
  x,
  pseudocount = NULL,
  trim_upper = 0.1,
  trim_lower = 0.05,
  exclude_features = c("hsa-miR-451a", "hsa-miR-16-5p", "hsa-miR-486-5p",
    "hsa-miR-144-3p", "hsa-miR-223-3p"),
  zero_policy = c("pseudocount", "detected_only"),
  min_centering_size = 8L
)

Arguments

x

Numeric vector or matrix (samples x features). For a matrix the transformation is applied row-wise.

pseudocount

Additive pseudocount to avoid log(0). Default 1e-6 of the sample sum.

trim_upper

Fraction of highest-abundance features to drop from the centering subset. Default 0.10.

trim_lower

Fraction of lowest-abundance features to drop from the centering subset. Default 0.05.

exclude_features

Named vector or character vector of features to always drop from the centering subset (e.g., known haemolysis markers). Default = c("hsa-miR-451a","hsa-miR-16-5p","hsa-miR-486-5p","hsa-miR-144-3p","hsa-miR-223-3p").

zero_policy

"pseudocount" (default) replaces zeros with the pseudocount; "detected_only" excludes zeros from the centering subset (rCLR convention; Vandeputte et al. 2017).

min_centering_size

Minimum number of features that must remain after trim + exclusion to compute the rCLR. If fewer remain, falls back to global CLR with a warning. Default 8.

Value

Same shape as x; the rCLR-transformed values. When invoked on a single sample the return value carries attributes centering_features, n_centering, and pseudocount for downstream auditability.

Examples

if (FALSE) { # \dontrun{
set.seed(42)
x <- rlnorm(50, meanlog = 5, sdlog = 1.2)
names(x) <- c(paste0("hsa-miR-", sprintf("%03d", seq_len(45))),
              "hsa-miR-451a", "hsa-miR-16-5p", "hsa-miR-486-5p",
              "hsa-miR-144-3p", "hsa-miR-223-3p")
z <- ws_rclr_trimmed(x)
attr(z, "n_centering")  # number of features used for centering
} # }