Skip to contents

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() or rsem_normalize(), on the original scale (not log-transformed) when transform = "log2".

reference

For rsem_fit_reference(): the reference samples, as sample IDs, or, with metadata and group, as one or more values of the column group. For rsem_apply_reference(): the object returned by rsem_fit_reference().

metadata

Optional sample table (path to a CSV or a data frame with a sample_id column), as in rsem_long().

group

Column of metadata that 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() to rsem_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 is NA; 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 expr and normalization); the transformation stored in the reference (log2 with 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