Quick Start Guide for scTypeEval

Overview

This quick start guide demonstrates the essential steps for evaluating cell type annotations using scTypeEval. For a comprehensive tutorial, see the main vignette.

library(scTypeEval)

Minimal Workflow

From a Count Matrix

library(Matrix)

# Generate example data
set.seed(123)
counts <- Matrix(rpois(50000, 5), nrow=500, ncol=100, sparse=TRUE)
rownames(counts) <- paste0("Gene", seq_len(500))
colnames(counts) <- paste0("Cell", seq_len(100))

metadata <- data.frame(
  celltype = rep(c("TypeA", "TypeB", "TypeC", "TypeD"), each=25),
  sample = rep(paste0("S", seq_len(5)), times=20),
  row.names = colnames(counts)
)

# Create object
sceval <- create_scTypeEval(matrix=counts, metadata=metadata)

# Process data
sceval <- run_processing_data(
  sceval,
  ident = "celltype",
  sample = "sample",
  min_samples = 3,
  min_cells = 5
)
#> # Processing data for single-cell ...
#>    Transforming and filtering count matrix...
#>    Normalizing count matrix via Log1p...
#> # Processing data for pseudobulk ...
#>    Transforming and filtering count matrix...
#>    Normalizing count matrix via Log1p...

# Identify features
sceval <- run_hvg(sceval,
                  var_method = "basic",
                  ngenes = 1000)
#> Not using black gene list
#> Computing HVG...

# Run PCA
sceval <- run_pca(sceval, ndim = 20)
#> 
#> Using HVG gene list.
#> Not using black gene list
#> # Computing PCA data for single-cell ...
#>    Filtering gene list...
#>    Filtering empty rows and cols...
#>    Computing PCA space...
#>    > Returning 20 dimensions for PCA
#> # Computing PCA data for pseudobulk ...
#>    Filtering gene list...
#>    Filtering empty rows and cols...
#>    Computing PCA space...
#>    > Returning 19 dimensions for PCA

# Compute dissimilarity
sceval <- run_dissimilarity(
  sceval,
  method = "Pseudobulk:Euclidean",
  reduction = TRUE
)
#>    Running distance for euclidean...

# Get consistency
results <- get_consistency(
  sceval,
  dissimilarity_slot = "Pseudobulk:Euclidean",
  consistency_metric = "silhouette"
)
#> Computing internal validation metrics for Pseudobulk:Euclidean ...
print(results)
#>       celltype      measure consistency_metric dissimilarity_method    ident
#> TypeA    TypeA  0.009929989         silhouette Pseudobulk:Euclidean celltype
#> TypeB    TypeB -0.011988536         silhouette Pseudobulk:Euclidean celltype
#> TypeC    TypeC -0.005448364         silhouette Pseudobulk:Euclidean celltype
#> TypeD    TypeD -0.020708784         silhouette Pseudobulk:Euclidean celltype

From a Seurat Object

library(Seurat)

# Create Seurat object with example data generated earlier
seurat_obj <- Seurat::CreateSeuratObject(
  counts = counts,
  meta.data = metadata
)

sceval_seurat <- create_scTypeEval(seurat_obj)

# Continue with standard workflow

From a SingleCellExperiment Object

library(SingleCellExperiment)

# Create SCE object with example data generated earlier
sce <- SingleCellExperiment::SingleCellExperiment(
  assays = list(counts = counts),
  colData = metadata
)

sceval_sce <- create_scTypeEval(sce)

# Continue with workflow as above

Common Use Cases

Compare Multiple Dissimilarity Methods

# Compute different dissimilarity methods
sceval <- run_dissimilarity(
  sceval,
  method = "Pseudobulk:Euclidean",
  reduction = TRUE
)
#>    Running distance for euclidean...
sceval <- run_dissimilarity(
  sceval,
  method = "Pseudobulk:Cosine",
  reduction = TRUE
)
#>    Running distance for cosine...
sceval <- run_dissimilarity(
  sceval,
  method = "WasserStein",
  reduction = TRUE
)
#> Splitting matrices...
#> Computing pairwise WasserStein distance...

# Compare consistency across methods
dissimilarity_methods <- c("Pseudobulk:Euclidean",
                           "Pseudobulk:Cosine",
                           "WasserStein")
results_df <- 
  get_consistency(
    sceval,
    dissimilarity_slot = dissimilarity_methods, # compute for multiple dissimilarities
    consistency_metric = "silhouette"
  )
#> Computing internal validation metrics for Pseudobulk:Euclidean ...
#> Computing internal validation metrics for Pseudobulk:Cosine ...
#> Computing internal validation metrics for WasserStein ...

results_df
#>        celltype      measure consistency_metric dissimilarity_method    ident
#> TypeA     TypeA  0.009929989         silhouette Pseudobulk:Euclidean celltype
#> TypeB     TypeB -0.011988536         silhouette Pseudobulk:Euclidean celltype
#> TypeC     TypeC -0.005448364         silhouette Pseudobulk:Euclidean celltype
#> TypeD     TypeD -0.020708784         silhouette Pseudobulk:Euclidean celltype
#> TypeA1    TypeA -0.003214443         silhouette    Pseudobulk:Cosine celltype
#> TypeB1    TypeB -0.002765134         silhouette    Pseudobulk:Cosine celltype
#> TypeC1    TypeC -0.013348235         silhouette    Pseudobulk:Cosine celltype
#> TypeD1    TypeD -0.022767009         silhouette    Pseudobulk:Cosine celltype
#> TypeA2    TypeA  0.034467516         silhouette          WasserStein celltype
#> TypeB2    TypeB -0.026486930         silhouette          WasserStein celltype
#> TypeC2    TypeC -0.026580578         silhouette          WasserStein celltype
#> TypeD2    TypeD -0.043527673         silhouette          WasserStein celltype

Evaluate Multiple Consistency Metrics

# Compute multiple consistency metrics
consistency_metrics <- c("silhouette",
                         "NeighborhoodPurity",
                         "Average_similarity")

all_metrics <- 
  get_consistency(
    sceval,
    dissimilarity_slot = "Pseudobulk:Euclidean",
    consistency_metric = consistency_metrics
  )
#> Computing internal validation metrics for Pseudobulk:Euclidean ...

all_metrics
#>        celltype      measure consistency_metric dissimilarity_method    ident
#> TypeA     TypeA  0.009929989         silhouette Pseudobulk:Euclidean celltype
#> TypeB     TypeB -0.011988536         silhouette Pseudobulk:Euclidean celltype
#> TypeC     TypeC -0.005448364         silhouette Pseudobulk:Euclidean celltype
#> TypeD     TypeD -0.020708784         silhouette Pseudobulk:Euclidean celltype
#> TypeA1    TypeA  0.320000000 NeighborhoodPurity Pseudobulk:Euclidean celltype
#> TypeB1    TypeB  0.240000000 NeighborhoodPurity Pseudobulk:Euclidean celltype
#> TypeC1    TypeC  0.240000000 NeighborhoodPurity Pseudobulk:Euclidean celltype
#> TypeD1    TypeD  0.200000000 NeighborhoodPurity Pseudobulk:Euclidean celltype
#> TypeA2    TypeA  0.504617271 Average_similarity Pseudobulk:Euclidean celltype
#> TypeB2    TypeB  0.500755570 Average_similarity Pseudobulk:Euclidean celltype
#> TypeC2    TypeC  0.501285885 Average_similarity Pseudobulk:Euclidean celltype
#> TypeD2    TypeD  0.498308342 Average_similarity Pseudobulk:Euclidean celltype

Visualize Results

# Heatmap of dissimilarities
plot_heatmap(
  sceval,
  dissimilarity_slot = "Pseudobulk:Euclidean",
  sort_consistency = "silhouette"
)
#> Computing consistency metric for silhouette.
#> Consistency computed.


# Pseudobulk PCA per sample & cell type
plot_pca(
  sceval,
  reduction_slot = "pseudobulk"
)

Using Marker Genes Instead of HVGs

# Identify cell type markers
sceval <- run_gene_markers(
  sceval,
  method = "scran.findMarkers",
  ngenes_celltype = 50
)
#> Not using black gene list
#> Computing cell type markers for celltype...

# Use markers for dissimilarity calculation
sceval <- run_dissimilarity(
  sceval,
  method = "Pseudobulk:Euclidean",
  gene_list = "scran.findMarkers", # gene list recently added
  reduction = FALSE
)
#> 
#> Using scran.findMarkers gene list.
#> Not using black gene list
#>    Filtering gene list...
#>    Filtering empty rows and cols...
#>    Running distance for euclidean...

Focus on Specific Gene Sets

# Add custom gene list
immune_genes <- c("CD3D", "CD4", "CD8A", "CD19", "CD14", "NCAM1")
sceval <- add_gene_list(
  sceval,
  gene_list = list("immune_markers" = immune_genes) # add a named list
)

# Run analysis on custom genes
sceval <- run_dissimilarity(
  sceval,
  method = "Pseudobulk:Euclidean",
  gene_list = "immune_markers" # name of the list to use
)
#>    Running distance for euclidean...

Interpreting Results

What Low Scores Mean

Low consistency scores may indicate:

  • Ambiguous cell type boundaries between related types
  • Heterogeneous populations needing refinement
  • Annotation inconsistencies across samples

Next Steps for Low-Scoring Cell Types

  1. Visualize using plot_heatmap() or plot_pca() to identify problematic samples
  2. Investigate biological differences (e.g., disease vs. healthy)
  3. Refine annotations by splitting or merging cell types

Available Methods and Metrics

Dissimilarity Methods

  • Pseudobulk:Euclidean - Euclidean distance on pseudobulk profiles
  • Pseudobulk:Cosine - Cosine distance on pseudobulk profiles
  • Pseudobulk:Pearson - Pearson correlation distance on pseudobulk profiles
  • WasserStein - Wasserstein distance between cell distributions
  • recip_classif:Match - Reciprocal classification matching
  • recip_classif:Score - Reciprocal classification scoring

Consistency Metrics

  • silhouette - Standard silhouette coefficient
  • 2label_silhouette - Two-label silhouette variant
  • NeighborhoodPurity - K-nearest neighbor purity
  • ward_PropMatch - Ward clustering proportion match
  • Orbital_medoid - Medoid-based orbital metric
  • Average_similarity - Average within-group similarity

Tips and Best Practices

  1. Always use multiple samples (minimum 3-5 per cell type)
  2. Compare different methods - no single method is perfect
  3. Use PCA for speed - similar results, much faster
  4. Start with HVGs - then try marker genes if needed
  5. Check sample sizes - ensure adequate cells per type per sample
  6. Interpret in context - consider biological heterogeneity

Getting Help

Session Info

sessionInfo()
#> R version 4.6.2 (2026-10-29)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.04.1 LTS
#> 
#> Matrix products: default
#> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so;  LAPACK version 3.12.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> time zone: Etc/UTC
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats4    stats     graphics  grDevices utils     datasets  methods  
#> [8] base     
#> 
#> other attached packages:
#>  [1] SingleCellExperiment_1.35.2 SummarizedExperiment_1.43.0
#>  [3] Biobase_2.73.2              GenomicRanges_1.65.4       
#>  [5] Seqinfo_1.3.2               IRanges_2.47.5             
#>  [7] S4Vectors_0.51.10           BiocGenerics_0.59.13       
#>  [9] generics_0.1.4              MatrixGenerics_1.25.0      
#> [11] matrixStats_1.5.0           Seurat_6.0.0               
#> [13] SeuratObject_5.4.0          sp_2.2-4                   
#> [15] Matrix_1.7-6                scTypeEval_1.1.2           
#> [17] BiocStyle_2.41.0           
#> 
#> loaded via a namespace (and not attached):
#>   [1] pbapply_1.7-5       gridExtra_2.3.1     rlang_1.3.0        
#>   [4] magrittr_2.0.5      RcppAnnoy_0.0.23    otel_0.3.0         
#>   [7] ggridges_0.5.7      compiler_4.6.2      png_0.1-9          
#>  [10] vctrs_0.7.3         reshape2_1.4.5      stringr_1.6.0      
#>  [13] pkgconfig_2.0.3     fastmap_1.2.0       XVector_0.53.0     
#>  [16] scuttle_1.23.2      labeling_0.4.3      rmarkdown_2.32     
#>  [19] xfun_0.62           bluster_1.23.1      beachmat_2.29.3    
#>  [22] cachem_1.1.0        jsonlite_2.0.0      DelayedArray_0.39.8
#>  [25] BiocParallel_1.47.0 irlba_2.4.1         parallel_4.6.2     
#>  [28] cluster_2.1.8.3     R6_2.6.1            ica_1.0-3          
#>  [31] bslib_0.12.0        stringi_1.8.9       RColorBrewer_1.1-3 
#>  [34] limma_3.99.4        parallelly_1.50.0   jquerylib_0.1.4    
#>  [37] scattermore_1.2     Rcpp_1.1.2          knitr_1.52         
#>  [40] future.apply_1.21.0 sctransform_0.4.3   igraph_2.3.4       
#>  [43] tidyselect_1.2.1    abind_1.4-8         yaml_2.3.12        
#>  [46] codetools_0.2-20    listenv_1.1.0       lattice_0.23-1     
#>  [49] tibble_3.3.1        plyr_1.8.9          withr_3.0.3        
#>  [52] S7_0.2.2            evaluate_1.0.5      Rtsne_0.17         
#>  [55] future_1.82.0       fastDummies_1.7.6   pillar_1.11.1      
#>  [58] BiocManager_1.30.27 KernSmooth_2.23-27  RcppHNSW_0.7.0     
#>  [61] ggplot2_4.0.3       scales_1.4.0        globals_0.20.0     
#>  [64] glue_1.8.1          metapod_1.21.0      maketools_1.3.2    
#>  [67] tools_4.6.2         data.table_1.18.6.1 BiocNeighbors_2.7.3
#>  [70] sys_3.4.3           ScaledMatrix_1.21.0 RSpectra_0.16-2    
#>  [73] RANN_2.6.3          scran_1.41.1        buildtools_1.0.0   
#>  [76] dotCall64_1.2       cowplot_1.2.0       grid_4.6.2         
#>  [79] edgeR_4.99.12       patchwork_1.3.2     BiocSingular_1.29.2
#>  [82] rsvd_2.0.0          cli_3.6.6           spam_2.11-4        
#>  [85] S4Arrays_1.13.2     dplyr_1.2.1         uwot_0.2.5         
#>  [88] gtable_0.3.6        pls_2.9-0           sass_0.4.10        
#>  [91] digest_0.6.39       progressr_1.1.0     dqrng_0.4.1        
#>  [94] SparseArray_1.13.4  ggrepel_0.9.8       farver_2.1.2       
#>  [97] htmltools_0.5.9     lifecycle_1.0.5     httr_1.4.9         
#> [100] statmod_1.5.2       transport_0.15-4    MASS_7.3-66