Package description

The goal of DamageDetective is to simplify the process of making informed and reproducible damaged cell filtering decisions during the pre-processing of single cell RNA sequencing data.

This requires only a count matrix to run and outputs a damage score ranging from 0 (viable, intact cell) to 1 (broken, non-viable cell). There is an option for automatic filtering using the default upper threshold damage score of 0.5.

We will demonstrate briefly using an example dataset provided upon package installation.

library(DamageDetective)
library(Matrix)
data("test_counts", package = "DamageDetective")
dim(test_counts)
#> [1] 32738   500

Prerequisites

Libraries

For an improvement in speed, load the presto package in addition to DamageDetective.

install.packages("remotes")
remotes::install_github("madsen-lab/valiDrops")

library(DamageDetective)
library(presto)

Input data formatting

Counts should be provided in the form of a compressed, column-oriented sparse matrix (dgCMatrix) in R.

# View formatting
class(test_counts)
#> [1] "dgCMatrix"
#> attr(,"package")
#> [1] "Matrix"

Counts should have gene sets formatted according to HGCN standard, i.e., MT-... rather than ENSG....

# View formatting
head(rownames(test_counts))
#> [1] "MIR1302-10"   "FAM138A"      "OR4F5"        "RP11-34P13.7" "RP11-34P13.8"
#> [6] "AL627309.1"

> See [biomaRt](https://bioconductor.org/packages/release/bioc/html/biomaRt.html) for conversion assistance or use the automated `Seurat` functions for working with alignment output, [ReadMtx](https://satijalab.org/seurat/reference/readmtx).

DamageDetective supports data of human and mouse, specified using the organism parameter. To analyse a non-standard organism, provide a list with patterns that matches the set of mitochondrially encoded genes and ribosomal genes and genes with a confirmed, permanent nuclear residence.

Example using humans as organism of interest

organism = list(mito_pattern = "^MT-",
                ribo_pattern = "^(RPS|RPL)",
                nuclear = c("NEAT1","XIST", "MALAT1"))

For more information on data preparation, view the package articles on our website

Parameter selection

`select_penalty`

While detect_damage requires only a count matrix as input, additional parameters control aspects of the function’s computations. Of these, we recommend ribosome_penalty be adjusted for each dataset using the select_penalty function.

This parameter ranges from 0 to 1 and adjusts the likelihood of ribosomal RNA loss during simulation, correcting for observed discrepancies where ribosomal RNA is retained more than expected based on transcript abundance.

penalty <- select_penalty(
  count_matrix = test_counts, 
  max_penalty_trials = 3 # Shortened for the vignette
)
#> Testing penalty of 0.1...
#> Testing penalty of 0.15...
#> Testing penalty of 0.2...
#> Maximum penalty trials reached (3). Stopping.
penalty
#> [1] 0.15

`filter_threshold`

DamageDetective offers the upper threshold 0.5 as the damage score above which cells are filtered, where values greater than 0.5 reflect more permissive filtering and values closer to 0 reflect more stringent filtering. We recommend the default, but suggest that if adjustments are made, they are informed by the output detect_damage plots, generate_plot = TRUE.

For more information on parameters, please view the function documentation available on our website under References.

Running damaged cell detection

Damage detection is run using the count matrix and ribosomal penalty as inputs. Below, we have additionally specified for filter_counts parameter to be TRUE. This will use the default filter_threshold and return the filtered count matrix that can be used immediately for the remainder of pre-processing.

# Perform damage detection
detection_results <- detect_damage(
  count_matrix = test_counts,
  ribosome_penalty = penalty,
  display_plot = FALSE,
  filter_counts = TRUE
)
#> Clustering cells...
#> Checking clusters...
#> Simulating damage...
#> Computing pANN...
#> Suggested pANN threshold : 0.5
#> Completed.

# View the resulting count matrix
dim(detection_results$output)
#> [1] 32738   458

# View the plot 
detection_results$plot

Session Information

#> R version 4.6.1 (2026-06-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.04 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] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] future_1.70.0          Matrix_1.7-5           DamageDetective_2.0.15
#> [4] rmarkdown_2.31        
#> 
#> loaded via a namespace (and not attached):
#>   [1] RColorBrewer_1.1-3     sys_3.4.3              jsonlite_2.0.0        
#>   [4] magrittr_2.0.5         spatstat.utils_3.2-3   farver_2.1.2          
#>   [7] vctrs_0.7.3            ROCR_1.0-12            spatstat.explore_3.8-1
#>  [10] rstatix_1.0.0          htmltools_0.5.9        broom_1.0.13          
#>  [13] Formula_1.2-5          sass_0.4.10            sctransform_0.4.3     
#>  [16] parallelly_1.48.0      KernSmooth_2.23-26     bslib_0.11.0          
#>  [19] htmlwidgets_1.6.4      ica_1.0-3              plyr_1.8.9            
#>  [22] plotly_4.12.0          zoo_1.8-15             cachem_1.1.0          
#>  [25] buildtools_1.0.0       igraph_2.3.3           mime_0.13             
#>  [28] lifecycle_1.0.5        pkgconfig_2.0.3        R6_2.6.1              
#>  [31] fastmap_1.2.0          fitdistrplus_1.2-6     shiny_1.14.0          
#>  [34] digest_0.6.39          patchwork_1.3.2        Seurat_5.5.1          
#>  [37] tensor_1.5.1           RSpectra_0.16-2        irlba_2.3.7           
#>  [40] ggpubr_1.0.0           labeling_0.4.3         progressr_1.0.0       
#>  [43] spatstat.sparse_3.2-0  httr_1.4.8             polyclip_1.10-7       
#>  [46] abind_1.4-8            compiler_4.6.1         proxy_0.4-29          
#>  [49] withr_3.0.3            S7_0.2.2               backports_1.5.1       
#>  [52] carData_3.0-6          fastDummies_1.7.6      ggsignif_0.6.4        
#>  [55] MASS_7.3-65            tools_4.6.1            lmtest_0.9-40         
#>  [58] otel_0.2.0             httpuv_1.6.17          future.apply_1.20.2   
#>  [61] goftest_1.2-3          glue_1.8.1             nlme_3.1-169          
#>  [64] promises_1.5.0         grid_4.6.1             Rtsne_0.17            
#>  [67] cluster_2.1.8.2        reshape2_1.4.5         generics_0.1.4        
#>  [70] gtable_0.3.6           spatstat.data_3.1-9    class_7.3-23          
#>  [73] tidyr_1.3.2            data.table_1.18.4      sp_2.2-1              
#>  [76] car_3.1-5              spatstat.geom_3.8-1    RcppAnnoy_0.0.23      
#>  [79] ggrepel_0.9.8          RANN_2.6.2             pillar_1.11.1         
#>  [82] stringr_1.6.0          spam_2.11-4            RcppHNSW_0.7.0        
#>  [85] later_1.4.8            splines_4.6.1          dplyr_1.2.1           
#>  [88] lattice_0.22-9         survival_3.8-9         deldir_2.0-4          
#>  [91] tidyselect_1.2.1       maketools_1.3.2        miniUI_0.1.2          
#>  [94] pbapply_1.7-4          knitr_1.51             gridExtra_2.3.1       
#>  [97] scattermore_1.2        xfun_0.60              matrixStats_1.5.0     
#> [100] stringi_1.8.7          lazyeval_0.2.3         yaml_2.3.12           
#> [103] evaluate_1.0.5         codetools_0.2-20       tibble_3.3.1          
#> [106] cli_3.6.6              uwot_0.2.4             xtable_1.8-8          
#> [109] reticulate_1.46.0      jquerylib_0.1.4        Rcpp_1.1.2            
#> [112] globals_0.19.1         spatstat.random_3.5-0  png_0.1-9             
#> [115] spatstat.univar_3.2-0  parallel_4.6.1         ggplot2_4.0.3         
#> [118] dotCall64_1.2          listenv_1.0.0          viridisLite_0.4.3     
#> [121] scales_1.4.0           ggridges_0.5.7         e1071_1.7-17          
#> [124] SeuratObject_5.4.0     purrr_1.2.2            rlang_1.3.0           
#> [127] cowplot_1.2.0

DamageDetective Overview