Skip to contents

Check Whether Simulated Null Data Outperform ClusterDE's Default Null Data

Source: R/precheck.R
checkNullData.Rd

Evaluate simulated null count matrices against ClusterDE's default null-data baseline using two reference datasets, A549_seurat and monocyte_10x_v3_seurat, from the ClusterDE package. The comparison uses eleven metrics that assess the quality of simulated null data from different perspectives.

Usage

checkNullData(
  new_null_data,
  new_null_data_monocyte,
  threshold,
  seed = 123,
  housekeeping_gmt =
    "https://data.broadinstitute.org/gsea-msigdb/msigdb/release/2026.1.Hs/msigdb.v2026.1.Hs.symbols.gmt",
  compare = F
)

Arguments

new_null_data

A list of simulated null count matrices generated base on the A549_seurat data included in the ClusterDE package. For the fairest comparison with the baseline, this should ideally contain 20 elements. One matrix is sampled at random for distributional, QQ, PCA, FR, LISI, and silhouette checks; the full list is used to calculate null p-values in ClusterDE.

new_null_data_monocyte

A list of simulated null count matrices generated base on the monocyte_10x_v3_seurat data included in the ClusterDE package. For the fairest comparison with the baseline, this should ideally contain 20 elements. The full list is used to calculate null p-values in ClusterDE for the monocyte differential expression check.

threshold

A named numeric vector giving pass/fail thresholds for mean, var, cor, qq_mae, pc_mse, fr, lisi, silhouette, celline, monocyte_marker, and monocyte_housekeeping.

seed

Integer seed used for reproducible sampling, PCA/UMAP, and clustering. The default is 123.

housekeeping_gmt

Local path or URL to a GMT file containing housekeeping genes. By default, the function reads the MSigDB v2026.1 human symbols GMT file. The MSigDB gene-set card for this housekeeping set is available at https://www.gsea-msigdb.org/gsea/msigdb/cards/HSIAO_HOUSEKEEPING_GENES.

compare

Logical. If TRUE, compare the calculated metrics with the values supplied in threshold and return the overall pass status together with a detailed comparison table. If FALSE, return only the calculated metrics. Defaults to FALSE.

Value

If compare = FALSE, a named numeric vector containing the eleven unrounded calculated metrics. If compare = TRUE, a list with two elements:

pass

Logical value indicating whether more than five checks pass.

comparison_result

Data frame comparing the default thresholds, observed metrics, check directions, and pass/fail results.

Examples

if (FALSE) {
library(ClusterDE)

utils::data(A549_seurat, package = "ClusterDE")
utils::data(monocyte_10x_v3_seurat, package = "ClusterDE")

RNGkind("L\'Ecuyer-CMRG")
set.seed(123)

cellline_null <- constructNull(
  A549_seurat,
  nRep = 20,
  corrCut = 0
)

monocyte_null <- constructNull(
  monocyte_10x_v3_seurat,
  nRep = 20,
  corrCut = 0
)

threshold <- checkNullData(
  cellline_null,
  monocyte_null,
  compare = FALSE
)

# Replace cellline_null and monocyte_null with null datasets generated
# from the A549 and monocyte reference datasets, respectively, using the
# simulator you want to evaluate.
df <- checkNullData(
  cellline_null,
  monocyte_null,
  threshold = threshold,
  compare = TRUE
)
}