rsem_fit_reference() computes each gene's mean and standard deviation in
a reference group of samples (for example controls or vehicle), and
rsem_apply_reference() expresses any sample as the number of reference
standard deviations it lies from the reference mean:
$$z_{gs} = (x_{gs} - \mu_{g,R}) / \sigma_{g,R}$$
where \(\mu_{g,R}\) and \(\sigma_{g,R}\) (with the \(n - 1\)
denominator) are taken over the reference samples \(R\) only.
rsem_reference_scale() does both on one table.
Usage
rsem_fit_reference(
x,
reference,
metadata = NULL,
group = NULL,
transform = "log2",
pseudocount = 1
)
rsem_apply_reference(x, reference, zero_sd = "na")
rsem_reference_scale(x, reference, ..., zero_sd = "na")Arguments
- x
The gene by sample table, as returned by
rsem_read(),rsem_filter()orrsem_normalize(), on the original scale (not log-transformed) whentransform = "log2".- reference
For
rsem_fit_reference(): the reference samples, as sample IDs, or, withmetadataandgroup, as one or more values of the columngroup. Forrsem_apply_reference(): the object returned byrsem_fit_reference().- metadata
Optional sample table (path to a CSV or a data frame with a
sample_idcolumn), as inrsem_long().- group
Column of
metadatathat holds the groups.- transform
"log2"(the default;log2(value + pseudocount)before the mean and standard deviation) or"none".- pseudocount
For
"log2". Default 1.- zero_sd
"na"(the default) or"drop", for genes whose reference standard deviation is 0.- ...
Passed from
rsem_reference_scale()torsem_fit_reference().
Value
rsem_fit_reference(): an object of class rsem_reference, a list
with mean, sd (named by gene), samples (the reference sample IDs),
transform and pseudocount. rsem_apply_reference() and
rsem_reference_scale(): a data frame of z-scores in the layout of x,
with the reference in the attribute "reference".
Details
Unlike rsem_transform(x, "zscore"), which centres on the mean of all
samples in the table, the reference stays fixed: adding or removing other
samples does not change anyone's value, and the fitted reference can be
applied to new data (for example a validation cohort, without fitting
anything on it).
Choices that are not made silently
A gene with no variation in the reference (standard deviation 0, for example zero in every reference sample) has no z-score. With
zero_sd = "na"(the default) its row isNA; with"drop"it is removed. Nothing is smoothed or borrowed from other genes.The reference needs at least two samples; one sample has no standard deviation.
Genes of the reference missing from the new table are reported; genes of the new table missing from the reference are removed and reported.
The new table must be on the same scale as the table the reference was fitted on (the same
exprand normalization); the transformation stored in the reference (log2with its pseudocount, or none) is applied again.
Examples
if (requireNamespace("org.Hs.eg.db", quietly = TRUE)) {
ex <- system.file("extdata", "example", package = "rsemverse")
tpm <- rsem_read(file.path(ex, "data"), file.path(ex, "metadata.csv"),
species = "human", expr = "tpm")
ref <- rsem_fit_reference(tpm, reference = c("S1", "S2"))
z <- rsem_apply_reference(tpm, ref)
head(z)
}
#> rsem_read: 3 samples, 44 genes -> 43 rows (species = human, expr = tpm, org.Hs.eg.db 3.23.1)
#> with symbol: 42 genes (1 symbols merged from several IDs); kept as original IDs: 2 genes
#> rsem_fit_reference: 43 genes, 2 reference samples (S1, S2); log2(value + 1); 0 genes with standard deviation 0
#> rsem_apply_reference: 43 genes x 3 samples against 2 reference samples; standard deviation 0: 0 genes (set to NA); not in the reference: 0 genes removed; reference genes missing from x: 0
#> S1 S2 S3
#> TP53 -0.7071068 0.7071068 -1.1088890
#> GAPDH 0.7071068 -0.7071068 -0.5614967
#> ACTB -0.7071068 0.7071068 0.5293780
#> MYC 0.7071068 -0.7071068 0.3792978
#> EGFR 0.7071068 -0.7071068 -0.4191932
#> BRCA1 -0.7071068 0.7071068 -5.5143569