score_matrix: SCONE Evaluation: Evaluate an Expression Matrix

In YosefLab/scone: Single Cell Overview of Normalized Expression data

SCONE Evaluation: Evaluate an Expression Matrix

Description

This function evaluates a (normalized) expression matrix using SCONE criteria, producing 8 metrics based on i) Clustering, ii) Correlations and iii) Relative Expression.

Usage

score_matrix(
  expr,
  eval_pcs = 3,
  eval_proj = NULL,
  eval_proj_args = NULL,
  eval_kclust = NULL,
  bio = NULL,
  batch = NULL,
  qc_factors = NULL,
  uv_factors = NULL,
  wv_factors = NULL,
  is_log = FALSE,
  stratified_pam = FALSE,
  stratified_cor = FALSE,
  stratified_rle = FALSE
)

Arguments

expr	matrix. The expression data matrix (genes in rows, cells in columns).
eval_pcs	numeric. The number of principal components to use for evaluation (Default 3). Ignored if !is.null(eval_proj).
eval_proj	function. Projection function for evaluation (see Details). If NULL, PCA is used for projection
eval_proj_args	list. List of arguments passed to projection function as eval_proj_args (see Details).
eval_kclust	numeric. The number of clusters (> 1) to be used for pam tightness (PAM_SIL) evaluation. If an array of integers, largest average silhouette width (tightness) will be reported in PAM_SIL. If NULL, PAM_SIL will be returned NA.
bio	factor. A known biological condition (variation to be preserved), NA is allowed. If NULL, condition ASW, BIO_SIL, will be returned NA.
batch	factor. A known batch variable (variation to be removed), NA is allowed. If NULL, batch ASW, BATCH_SIL, will be returned NA.
qc_factors	Factors of unwanted variation derived from quality metrics. If NULL, qc correlations, EXP_QC_COR, will be returned NA.
uv_factors	Factors of unwanted variation derived from negative control genes (evaluation set). If NULL, uv correlations, EXP_UV_COR, will be returned NA.
wv_factors	Factors of wanted variation derived from positive control genes (evaluation set). If NULL, wv correlations, EXP_WV_COR, will be returned NA.
is_log	logical. If TRUE the expr matrix is already logged and log transformation will not be carried out prior to projection. Default FALSE.
stratified_pam	logical. If TRUE then maximum ASW is separately computed for each biological-cross-batch stratum (accepts NAs), and a weighted average silhouette width is returned as PAM_SIL. Default FALSE.
stratified_cor	logical. If TRUE then cor metrics are separately computed for each biological-cross-batch stratum (accepts NAs), and weighted averages are returned for EXP_QC_COR, EXP_UV_COR, & EXP_WV_COR. Default FALSE.
stratified_rle	logical. If TRUE then rle metrics are separately computed for each biological-cross-batch stratum (accepts NAs), and weighted averages are returned for RLE_MED & RLE_IQR. Default FALSE.

Details

Users may specify their own eval_proj function that will be used to compute Clustering and Correlation metrics. This eval_proj() function must have 2 input arguments:

• e matrix. log-transformed (+ pseudocount) expression data (genes in rows, cells in columns).

• eval_proj_args list. additional function arguments, e.g. prior data weights.

and it must output a matrix representation of the original data (cells in rows, factors in columns). The value of eval_proj_args is passed to the user-defined function from the eval_proj_args argument of the main score_matrix() function call.

Value

A list with the following metrics:

• BIO_SIL Average silhouette width by biological condition.

• BATCH_SIL Average silhouette width by batch condition.

• PAM_SIL Maximum average silhouette width from PAM clustering (see stratified_pam argument).

• EXP_QC_COR Coefficient of determination between expression pcs and quality factors (see stratified_cor argument).

• EXP_UV_COR Coefficient of determination between expression pcs and negative control gene factors (see stratified_cor argument).

• EXP_WV_COR Coefficient of determination between expression pcs and positive control gene factors (see stratified_cor argument).

• RLE_MED The mean squared median Relative Log Expression (RLE) (see stratified_rle argument).

• RLE_IQR The variance of the inter-quartile range (IQR) of the RLE (see stratified_rle argument).

Examples

set.seed(141)
bio = as.factor(rep(c(1,2),each = 2))
batch = as.factor(rep(c(1,2),2))
log_expr = matrix(rnorm(20),ncol = 4)

scone_metrics = score_matrix(log_expr,
   bio = bio, batch = batch,
   eval_kclust = 2, is_log = TRUE)

YosefLab/scone documentation built on Oct. 21, 2024, 4:39 p.m.