normalise: (Re)normalise a nacho object

View source: R/normalise.R

normaliseR Documentation

(Re)normalise a nacho object

Description

(Re)normalise a nacho object

Usage

normalise(
  nacho_object,
  housekeeping_genes = nacho_object@settings[["housekeeping_genes"]],
  housekeeping_predict = nacho_object@settings[["housekeeping_predict"]],
  housekeeping_norm = nacho_object@settings[["housekeeping_norm"]],
  normalisation_method = nacho_object@settings[["normalisation_method"]],
  background = nacho_object@settings[["background"]],
  background_mode = nacho_object@settings[["background_mode"]],
  ruv_k = nacho_object@settings[["ruv_k"]],
  n_comp = nacho_object@settings[["n_comp"]],
  outliers_thresholds = nacho_object@thresholds,
  ...
)

Arguments

nacho_object

A nacho object from load_rcc() or normalise().

housekeeping_genes

[character] A vector of names of the miRNAs/mRNAs that should be used as housekeeping genes. Default is NULL.

housekeeping_predict

[logical] Boolean to indicate whether the housekeeping genes should be predicted (TRUE) or not (FALSE). Default is FALSE. Prediction picks the five most stable genes by geNorm on the raw counts. It is skipped for the miRNA methods of normalisation_method.

housekeeping_norm

[logical] Boolean to indicate whether the housekeeping normalisation should be performed. The default is the setting stored in nacho_object, which is TRUE or FALSE.

normalisation_method

[character] "GEO" (the default) or "GLM" scale samples by their positive controls, with the geometric mean or a Poisson model, then by the housekeeping genes; "RUVg" scales by the positive controls with the geometric mean, then removes ruv_k factors of unwanted variation estimated from the housekeeping genes, which nacho_samples() returns as W_1, W_2, ... for use as covariates. For miRNA panels, "stable_mirna", "total_mirna", "spike_in" and "ligation" scale by the five most stable miRNAs, the miRNAs above 50 counts, the spike-in controls or the ligation positive controls, in the order Bruker recommends for plasma and serum. These methods ignore housekeeping_genes, housekeeping_predict and housekeeping_norm, and give their scaling factor as House_factor. When a GLM fit fails, NACHO warns and uses the geometric mean instead, as normalise() describes.

background

[character] How to estimate each sample's background from its negative controls: "none" (the default), "mean", "mean_2sd" (mean plus two standard deviations), "median", "max" or "geo" (geometric mean).

background_mode

[character] What to do with that background: "threshold" (the default) raises lower counts to it, which Bruker recommends when fold changes matter, and "subtract" removes it and floors at 0.

ruv_k

[numeric] The number of unwanted factors RUVg removes. normalise() reuses the ruv_k stored in the object, so pass ruv_k = NULL to have suggest_ruv_k() choose again. A ruv_k above two less than the number of samples, or one less than the number of control genes, is lowered with a nacho_warning_ruv_k_reduced warning. Other methods ignore it.

n_comp

[numeric] Number indicating the number of principal components to compute. Cannot be more than n-1 samples. Default is 10.

outliers_thresholds

A list of quality-control thresholds, as returned by nacho_thresholds().

...

Must be empty.

Details

When only the limits in outliers_thresholds change and the preset stays the same, normalise() keeps the counts and stores the new thresholds; the flags follow them whenever you read nacho_qc(). Otherwise it computes the quality-control metrics, the normalisation factors, the normalised counts and the PCA again.

nacho_qc() lists the flags, and exclude_outliers() drops the flagged samples.

With normalisation_method = "GLM", each sample's positive and negative control counts plus 1 are fitted against their known concentrations with a Poisson GLM and an identity link, and the positive factor is the mean slope over the sample's slope. When the fit fails for any sample, NACHO warns and uses the geometric mean for every sample, so all samples stay on the same scale. The recorded normalisation_method then becomes "GEO", and the failed samples are listed in provenance$glm_fallback.

The normalisation runs in this order: raw counts, negative probe exclusion, background (background and background_mode), positive control factor (normalisation_method), then content factor (housekeeping genes when housekeeping_norm is TRUE). RUVg works on log2(count + 1) after the positive factor and returns counts on the count scale, floored at 0. It replaces the housekeeping scaling, so housekeeping_norm has no effect and House_factor is not computed, and it corrects only the endogenous and housekeeping probes. The miRNA methods "stable_mirna", "total_mirna", "spike_in" and "ligation" also ignore housekeeping_norm, housekeeping_genes and housekeeping_predict. They store their factor in House_factor, which is judged against the House_factor threshold, and the probes they used in provenance$content_probes. Normalised counts are otherwise neither rounded nor floored; use nacho_counts(x, normalised = TRUE, log2 = TRUE) for log2(count + 1).

Value

A nacho object.

Examples

data(GSE74821)
GSE74821_geo <- normalise(GSE74821, normalisation_method = "GEO")
nacho_qc(GSE74821_geo)

NACHO documentation built on Nov. 2, 2026, 5:09 p.m.