Nothing
#' @include stability.R
NULL
#' Remove unwanted variation with control genes
#'
#' RUVg (Risso et al. 2014, Nature Biotechnology 32, 896) on log values.
#' The unwanted factors `W` are the first `k` left singular vectors of the
#' centred control genes.
#' Each gene is corrected by its regression on `W`.
#' This follows `RUVSeq::RUVg(isLog = TRUE)`.
#'
#' @noRd
ruvg <- function(
log_expr,
controls,
k,
tolerance = 1e-8,
call = rlang::caller_env()
) {
control_expr <- log_expr[, controls, drop = FALSE]
if (anyNA(control_expr)) {
missing_genes <- colnames(control_expr)[colSums(is.na(control_expr)) > 0] # nolint: object_usage_linter.
nacho_abort(
c(
"RUVg needs every count of its control genes.",
x = "Missing counts in: {.val {utils::head(missing_genes, 5)}}."
),
class = "bad_argument",
call = call
)
}
if (ncol(control_expr) == 0 && k > 0) {
nacho_abort(
c(
"RUVg needs control genes.",
x = "No gene is marked as a control."
),
class = "bad_argument",
call = call
)
}
no_factor <- list(
W = matrix(
numeric(0),
nrow(log_expr),
0,
dimnames = list(rownames(log_expr), NULL)
),
corrected = log_expr
)
if (k == 0) {
return(no_factor)
}
decomposition <- svd(scale(control_expr, center = TRUE, scale = FALSE))
usable <- sum(decomposition[["d"]] > tolerance)
if (usable == 0) {
return(no_factor)
}
k <- min(k, usable)
w <- decomposition[["u"]][, seq_len(k), drop = FALSE]
dimnames(w) <- list(rownames(log_expr), paste0("W_", seq_len(k)))
corrected <- log_expr
for (gene in seq_len(ncol(log_expr))) {
seen <- !is.na(log_expr[, gene])
if (sum(seen) <= k) {
next
}
w_seen <- w[seen, , drop = FALSE]
alpha <- solve(crossprod(w_seen), crossprod(w_seen, log_expr[seen, gene]))
corrected[seen, gene] <- log_expr[seen, gene] - w_seen %*% alpha
}
list(W = w, corrected = corrected)
}
#' Relative log expression of a log expression matrix
#'
#' Each gene minus its median over samples.
#' `margin` is 2 when genes are the columns and 1 when they are the rows.
#'
#' @noRd
rle_centre <- function(log_expr, margin) {
sweep(
log_expr,
margin,
apply(log_expr, margin, stats::median, na.rm = TRUE)
)
}
#' Mean spread of the relative log expression
#'
#' The interquartile range of each sample of the centred values, averaged.
#' `rle_centre()` does the centring.
#'
#' @noRd
rle_iqr <- function(log_expr) {
rle <- rle_centre(log_expr, 2)
mean(apply(rle, 1, stats::IQR, na.rm = TRUE))
}
#' The log expression matrix and control flags that RUVg needs
#'
#' @param scaled The background-applied, positive-scaled counts.
#' @param probes The probe table, with `CodeClass` and `Name`.
#' @param housekeeping_genes The names of the control genes.
#'
#' @return A list: `log_expr` (samples by genes), `controls` and `rows`.
#'
#' @noRd
ruv_input_from_scaled <- function(
scaled,
probes,
housekeeping_genes,
call = rlang::caller_env()
) {
rows <- grepl("Endogenous|Housekeeping", probes[["CodeClass"]])
log_expr <- t(log2(scaled[rows, , drop = FALSE] + 1))
colnames(log_expr) <- probes[["Name"]][rows]
controls <- colnames(log_expr) %in% housekeeping_genes
if (sum(controls) < 2) {
nacho_abort(
c(
"RUVg needs at least two housekeeping genes as controls.",
i = "Set {.arg housekeeping_genes}, or use {.code normalisation_method = \"GEO\"}."
),
class = "bad_argument",
call = call
)
}
list(log_expr = log_expr, controls = controls, rows = rows)
}
#' Rebuild the scaled counts of an object, then its RUVg input
#'
#' @noRd
ruv_input <- function(
counts,
probes,
samples,
settings,
housekeeping_genes,
call = rlang::caller_env()
) {
scaled <- scale_counts(
counts,
if (all(is.na(samples[["Background"]]))) NULL else samples[["Background"]],
settings[["background_mode"]],
samples[["Positive_factor"]]
)
ruv_input_from_scaled(scaled, probes, housekeeping_genes, call = call)
}
#' The names of the housekeeping genes of an object
#'
#' @noRd
housekeeping_names <- function(x) {
x@probes[["Name"]][x@probes[["is_housekeeping"]]]
}
#' RLE and PCA diagnostic for each k
#'
#' @noRd
ruv_k_table <- function(
log_expr,
controls,
max_k,
call = rlang::caller_env()
) {
max_k <- min(max_k, sum(controls) - 1L, nrow(log_expr) - 2L)
table <- data.frame(k = 0:max(max_k, 0L))
corrected <- lapply(table[["k"]], function(k) {
ruvg(log_expr, controls, k, call = call)[["corrected"]]
})
table[["rle_iqr"]] <- vapply(corrected, rle_iqr, numeric(1))
table[["pc1_variance"]] <- vapply(
corrected,
function(y) {
d <- svd(scale(
y[, colSums(is.na(y)) == 0, drop = FALSE],
scale = FALSE
))[["d"]]
if (sum(d^2) < .Machine$double.eps) NA_real_ else d[1]^2 / sum(d^2)
},
numeric(1)
)
best <- min(table[["rle_iqr"]])
table[["suggested"]] <- table[["k"]] ==
min(table[["k"]][table[["rle_iqr"]] <= 1.05 * best])
table
}
#' Suggest how many unwanted factors RUVg should remove
#'
#' For each `k` from 0 to `max_k`, corrects the log2 positive-normalised
#' counts with RUVg, using the housekeeping genes as controls, and reports the
#' mean interquartile range of the relative log expression (RLE) and the share
#' of variance on the first principal component.
#' The suggested `k` is the smallest whose RLE spread is within 5 % of the
#' smallest one: removing more factors risks removing biology.
#'
#' @param x A `nacho` object from [load_rcc()] or [normalise()].
#' @param max_k The largest `k` to try.
#' It is lowered to one less than the number of housekeeping genes, and to
#' two less than the number of samples, when those are smaller.
#' A `k` above that cap fits the samples exactly and flattens the RLE
#' spread, so it is never tried.
#' With one or two samples only `k = 0` is tried.
#'
#' @return A data frame with `k`, `rle_iqr`, `pc1_variance` and `suggested`.
#' `pc1_variance` is `NA` when the corrected values have no variance, as
#' with one sample.
#' @export
#' @examples
#' data(GSE74821)
#' suggest_ruv_k(GSE74821)
suggest_ruv_k <- function(x, max_k = 5) {
check_nacho(x)
check_count(max_k, min = 0)
input <- ruv_input(
x@counts,
x@probes,
x@samples,
x@settings,
housekeeping_names(x)
)
ruv_k_table(input[["log_expr"]], input[["controls"]], as.integer(max_k))
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.