Adding new methods to sparrow

Steve Lianoglou

2 December 2024

Source: vignettes/WIP/adding-new-methods-to-sparrow.Rmd

Abstract

There may be new gsea methods you would like to invoke through sparrow, and we describe how to do that here.

Overview

If you would like sparrow to support a new method, please file an issue on the project’s github issue tracker.

This document is meant to be used as notes by the developer of sparrow, and not for use by casual useres.

Suppose we wanted to add a new GSEA method named superGSEA to the methods that the seas() function can delegate to via its methods argument, we need to add the following internal sparrow methods.

  • validate.inputs.superGSEA: Choose either .validate.inputs.full.design or .validate.inputs.preranked depending on whether or not the method needs:
    • a full expression,design,contrast tripple like roast, romer, or camera, use .validate.inputs.full.design;
    • or a preranked set of stats vector like cameraPR or fgsea, use .validate.inputs.preranked
  • validate.x.superGSEA: this is redundant, just put validate.X. This will be fixed in a future release
  • do.superGSEA: this method should take the parameters listed below, and return the result of the superGSEA call unmodified from its original form that the superGSEA method that is being wrapped returns it. The parameters of the do.superGSEA function are:
    • gsd: the pre-conformed GeneSetDb
    • x: the expression matrix or pre-ranked stats vector
    • design: the design matrix. If the method uses a pre-ranked stats vector just ignore this argument in the do.superGSEA function body.
    • contrast: the contrast to test. If the method uses a pre-ranked stats vector just ignore this argument in the do.superGSEA function body.
    • gsd.idxs: this will be a list of gene sets. The names are the collection;;name tuples pasted together, and the values are integers indices into the rows of x for each gene in the gene set. Genes in the gene set that are not in x have already been removed.
    • any custom parameters you want to set the defaults for in superGSEA when the default values are not what you want.
    • ...: any other formal arguments defined in superGSEA will be passed into here, and it will be your responsibility to extract them and pass them down into the superGSEA call.
  • mgres.superGSEA: The function takes the output from do.superGSEA and turns it into a data.table that minimally has collection, name, pval, and padj columns.

Look to the implementation in the do.camera.R file for a reference.

Reproducibility

Session Information 
## R Under development (unstable) (2024-11-27 r87386)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 24.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.26.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: UTC
## tzcode source: system (glibc)
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] BiocStyle_2.35.0
## 
## loaded via a namespace (and not attached):
##  [1] digest_0.6.37       desc_1.4.3          R6_2.5.1           
##  [4] bookdown_0.41       fastmap_1.2.0       xfun_0.49          
##  [7] cachem_1.1.0        knitr_1.49          htmltools_0.5.8.1  
## [10] rmarkdown_2.29      lifecycle_1.0.4     cli_3.6.3          
## [13] sass_0.4.9          pkgdown_2.1.1       textshaping_0.4.0  
## [16] jquerylib_0.1.4     systemfonts_1.1.0   compiler_4.5.0     
## [19] tools_4.5.0         ragg_1.3.3          evaluate_1.0.1     
## [22] bslib_0.8.0         yaml_2.3.10         BiocManager_1.30.25
## [25] jsonlite_1.8.9      rlang_1.1.4         fs_1.6.5           
## [28] htmlwidgets_1.6.4