Skip to contents

Returns the numbers behind the usual first look at a gene by sample table: principal components, correlation between samples and, for each sample, its total, the number of detected genes and how well it agrees with the other samples. Nothing is plotted or removed; the results are tables that can be passed to any plotting code.

Usage

rsem_sample_qc(
  x,
  metadata = NULL,
  transform = "log2",
  pseudocount = 1,
  min_value = 1,
  n_top = 2000,
  n_pcs = 10,
  pca_scale = FALSE,
  correlation = "spearman",
  correlation_genes = "detected"
)

Arguments

x

The gene by sample table, as returned by rsem_read(), rsem_filter() or rsem_normalize(). Needs at least three samples.

metadata

Optional sample table (path to a CSV or a data frame with a sample_id column), as in rsem_long(); its columns are added to pca_scores and sample_summary.

transform

"log2" (the default) or "none".

pseudocount

For "log2". Default 1.

min_value

Value a gene must reach to count as detected. Default 1 (TPM 1 or count 1).

n_top

Number of genes for the PCA. Default 2000.

n_pcs

Number of components to return. Default 10 (fewer when there are fewer).

pca_scale

Scale genes to unit variance before the PCA. Default FALSE.

correlation

"spearman" (the default), "pearson" or "kendall" (see stats::cor()).

correlation_genes

"detected", "all" or "variable"; see Genes used.

Value

A list of class rsem_sample_qc:

  • pca_scores: one row per sample, with sample_id, the components PC1, PC2, ... and the metadata columns;

  • pca_variance: pc, sdev, variance, proportion and cumulative (of the variance of the genes used);

  • pca_loadings: genes by components (the rotation of stats::prcomp());

  • correlation_matrix: samples by samples;

  • sample_distance: 1 - correlation_matrix;

  • sample_summary: per sample total (sum of the values), detected_genes and detected_share (of all genes in x), median_correlation, min_correlation and most_similar (the sample with the highest correlation) and the metadata columns;

  • parameters: the settings and the numbers of genes used.

Genes used

The principal components use the n_top genes with the largest variance of the transformed values (genes that are zero everywhere are never used), so that the components reflect the genes that vary. The correlation uses the genes chosen by correlation_genes, which is a separate choice because restricting the correlation to the most variable genes changes the correlations a great deal:

  • "detected" (the default): genes with a value of at least min_value in at least one sample;

  • "all": every gene that is not zero everywhere;

  • "variable": the same genes as the principal components.

Choices that are not made silently

  • transform = "log2" (the default) uses log2(value + 1); "none" uses the values as they are (for values that are already on a log scale). A table made with rsem_transform() remembers that it is log2-transformed, and transform = "log2" then stops instead of transforming twice. Rank correlation does not depend on the transformation.

  • The values are centred per gene before the PCA, but not scaled (pca_scale = FALSE): scaling gives every gene the same weight, so lowly expressed, noisy genes count as much as highly expressed ones.

  • Samples are not flagged or removed. median_correlation and the other columns are numbers to look at, and what counts as an outlier depends on the study.

Examples

set.seed(1)
m <- matrix(rexp(200 * 6, 0.05), 200, 6,
            dimnames = list(paste0("g", 1:200), paste0("S", 1:6)))
qc <- rsem_sample_qc(as.data.frame(m), n_top = 100)
#> rsem_sample_qc: 200 genes x 6 samples; PCA on 100 genes (PC1 25.8%, PC2 23% of their variance); spearman correlation on 200 genes (detected), median between samples -0.0178
qc$pca_variance[1:3, ]
#>    pc     sdev variance proportion cumulative
#> 1 PC1 8.939592 79.91630  0.2583054  0.2583054
#> 2 PC2 8.428141 71.03357  0.2295946  0.4879000
#> 3 PC3 7.962093 63.39492  0.2049050  0.6928051
qc$sample_summary
#>   sample_id    total detected_genes detected_share median_correlation
#> 1        S1 3999.937            196          0.980         0.01801095
#> 2        S2 3785.170            190          0.950        -0.04172654
#> 3        S3 4142.257            185          0.925        -0.01822996
#> 4        S4 4145.690            187          0.935        -0.01783695
#> 5        S5 4553.001            195          0.975         0.00198755
#> 6        S6 4033.748            192          0.960         0.01922898
#>   min_correlation most_similar
#> 1     -0.04172654           S6
#> 2     -0.10672167           S6
#> 3     -0.04257106           S2
#> 4     -0.10672167           S1
#> 5     -0.07603690           S6
#> 6     -0.08352209           S1