ws_rclr_trimmed.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/singlesample-within-sample.R
\name{ws_rclr_trimmed}
\alias{ws_rclr_trimmed}
\title{Robust trimmed centred log-ratio for compositional miRNA panels}
\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{
\item{x}{Numeric vector or matrix (samples x features). For a matrix the
transformation is applied row-wise.}

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

\item{trim_upper}{Fraction of highest-abundance features to drop from the
centering subset. Default 0.10.}

\item{trim_lower}{Fraction of lowest-abundance features to drop from the
centering subset. Default 0.05.}

\item{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").}

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

\item{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 \code{x}; the rCLR-transformed values. When invoked
  on a single sample the return value carries attributes
  \code{centering_features}, \code{n_centering}, and \code{pseudocount}
  for downstream auditability.
}
\description{
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-\code{trim_upper} and bottom-\code{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
\code{min_centering_size}.
}
\examples{
\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
}

}