Dev

.github/workflows/bioc-check.yaml

@@ -0,0 +1,26 @@
+# workflow derived from: https://github.com/insightsengineering/bioc-check-action
+
+
+on:
+  push:
+    branches: main
+  pull_request:
+    branches: main
+
+name: bioc-check
+
+jobs:
+  bioc-check:
+    runs-on: ubuntu-latest
+    name: BiocCheck
+    steps:
+      - uses: actions/checkout@v3
+      - uses: r-lib/actions/setup-pandoc@v2
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          r-version: release
+          http-user-agent: release
+          use-public-rspm: true
+      - uses: r-lib/actions/setup-r-dependencies@v2
+      - name: Run BiocCheck
+        uses: insightsengineering/bioc-check-action@v1

.github/workflows/render-README.yaml

@@ -10,7 +10,7 @@ name: render-README
 
 jobs:
   render:
-    runs-on: ubuntu-latest
+    runs-on: macos-latest
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
     steps:
@@ -22,9 +22,9 @@ jobs:
       - uses: r-lib/actions/setup-pandoc@v2
 
       - name: install CRAN packages
-        run: Rscript -e 'install.packages(c("rmarkdown","ggplot2", "dplyr", "purrr", "remotes", "devtools", "BiocManager", "Seurat"), dependencies = TRUE)'
+        run: Rscript -e 'install.packages(c("rmarkdown","ggplot2", "dplyr", "purrr", "remotes", "devtools", "BiocManager", "Seurat"), force = TRUE)'
       - name: install BioConductor packages
-        run: Rscript -e 'BiocManager::install(c("SingleCellExperiment", "scater", "scran", "scuttle", "bluster"))'
+        run: Rscript -e 'BiocManager::install(c("SingleCellExperiment", "scater", "scran", "scuttle", "bluster"), force = TRUE)'
       - name: install GitHub packages
         run: Rscript -e 'remotes::install_github("jr-leary7/scLANE")'
       - name: render README

DESCRIPTION

@@ -63,6 +63,7 @@ Suggests:
     BiocStyle, 
     slingshot, 
     gprofiler2,
+    BiocParallel, 
     BiocGenerics, 
     BiocNeighbors, 
     testthat (>= 3.0.0),

NEWS.md

@@ -4,6 +4,8 @@
 * Better compression of included datasets.
 * Added `geneProgramScoring()` for module scoring of dynamic gene clusters.
 * Added `plotModelCoefs()` to annotate gene dynamics plots with a table of model coefficients. 
+* Added citation file with link to Zenodo repository (until preprint is up).
+* Added runnable examples to most functions. 
 
 # `scLANE` v0.7.6
 

R/GetResultsDE.R

@@ -16,12 +16,8 @@
 #' @seealso \code{\link{testDynamic}}
 #' @seealso \code{\link[stats]{p.adjust}}
 #' @examples
-#' \dontrun{
-#' getResultsDE(gene_stats)
-#' getResultsDE(gene_stats,
-#'              p.adj.method = "BH",
-#'              fdr.cutoff = 5e-3)
-#' }
+#' data(scLANE_models)
+#' scLANE_de_res <- getResultsDE(scLANE_models)
 
 getResultsDE <- function(test.dyn.res = NULL,
                          p.adj.method = "holm",

R/clusterGenes.R

@@ -23,19 +23,12 @@
 #' @seealso \code{\link{plotClusteredGenes}}
 #' @export
 #' @examples
-#' \dontrun{
-#' clusterGenes(gene_stats, pt = pt_df)
-#' clusterGenes(gene_stats,
-#'              pt = pt_df,
-#'              size.factor.offset = createCellOffset(sce_obj),
-#'              clust.algo = "kmeans",
-#'              use.pca = TRUE,
-#'              n.PC = 10,
-#'              lineages = "B")
-#' clusterGenes(gene_stats,
-#'              pt = pt_df,
-#'              lineages = c("A", "C"))
-#' }
+#' data(sim_pseudotime)
+#' data(scLANE_models)
+#' cell_offset <- createCellOffset(sim_counts)
+#' gene_clusters <- clusterGenes(scLANE_models,
+#'                               pt = sim_pseudotime,
+#'                               size.factor.offset = cell_offset)
 
 clusterGenes <- function(test.dyn.res = NULL,
                          pt = NULL,

R/createCellOffset.R

@@ -13,11 +13,8 @@
 #' @seealso \code{\link[scuttle]{computeLibraryFactors}}
 #' @export
 #' @examples
-#' \dontrun{
-#' createCellOffset(expr.mat = sce_obj)
-#' createCellOffset(expr.mat = counts(sce_obj))
-#' createCellOffset(expr.mat = seu_obj, scale.factor = 1e5)
-#' }
+#' data(sim_counts)
+#' cell_offset <- createCellOffset(sim_counts)
 
 createCellOffset <- function(expr.mat = NULL, scale.factor = 1e4) {
   # check inputs

R/createSlopeTestData.R

@@ -11,13 +11,6 @@
 #' @return A data.frame containing model data.
 #' @seealso \code{\link{marge2}}
 #' @seealso \code{\link{testSlope}}
-#' @examples
-#' \dontrun{
-#' createSlopeTestData(marge_mod, pt_df)
-#' createSlopeTestData(marge_mod,
-#'                     pt = pt_df,
-#'                     is.glmm = TRUE)
-#' }
 
 createSlopeTestData <- function(marge.model = NULL,
                                 pt = NULL,

R/data.R

@@ -17,3 +17,11 @@
 #' }
 #' @usage data(sim_pseudotime)
 "sim_pseudotime"
+
+#' An object of class \code{scLANE}.
+#'
+#' Contains the results from running \code{\link{testDynamic}} on \code{\link{sim_counts}}.
+#'
+#' @format An object of class \code{scLANE}.
+#' @usage data(scLANE_models)
+"scLANE_models"

R/embedGenes.R

@@ -17,14 +17,16 @@
 #' @param k.param (Optional) The value of nearest-neighbors used in creating the SNN graph prior to clustering & in running UMAP. Defaults to 20.
 #' @param resolution.param (Optional) The value of the resolution parameter for the Leiden algorithm. If unspecified, silhouette scoring is used to select an optimal value. Defaults to NULL.
 #' @param random.seed (Optional) The random seed used to control stochasticity in the clustering algorithm. Defaults to 312.
+#' @param n.cores (Optional) Integer specifying the number of threads used by \code{\link[uwot]{umap}} and in \code{\link[bluster]{makeSNNGraph}}. Defaults to 2.
 #' @return A data.frame containing embedding coordinates, cluster IDs, and metadata for each gene.
 #' @export
 #' @examples
-#' \dontrun{
-#' embedGenes(smoothed_counts$Lineage_A,
-#'            pcs.return = 3,
-#'            cluster.genes = TRUE)
-#' }
+#' data(sim_pseudotime)
+#' data(scLANE_models)
+#' smoothed_dynamics <- smoothedCountsMatrix(scLANE_models,
+#'                                           pt = sim_pseudotime,
+#'                                           n.cores = 1L)
+#' gene_embed <- embedGenes(smoothed_dynamics$Lineage_A, n.cores = 1L)
 
 embedGenes <- function(smoothed.counts = NULL,
                        genes = NULL,
@@ -35,7 +37,8 @@ embedGenes <- function(smoothed.counts = NULL,
                        gene.meta.data = NULL,
                        k.param = 20,
                        resolution.param = NULL,
-                       random.seed = 312) {
+                       random.seed = 312,
+                       n.cores = 2L) {
   # check inputs
   if (is.null(smoothed.counts)) { stop("You forgot to provide a smoothed counts matrix to embedGenes().") }
   genes <- colnames(smoothed.counts)
@@ -52,28 +55,32 @@ embedGenes <- function(smoothed.counts = NULL,
                                        n_neighbors = k.param,
                                        init = "spectral",
                                        nn_method = "annoy",
-                                       seed = random.seed)
+                                       seed = random.seed,
+                                       n_threads = n.cores)
   } else {
     smoothed_counts_umap <- uwot::umap(smoothed.counts,
                                        n_components = 2,
                                        metric = "cosine",
                                        n_neighbors = k.param,
                                        init = "spectral",
                                        nn_method = "annoy",
-                                       seed = random.seed)
+                                       seed = random.seed,
+                                       n_threads = n.cores)
   }
   # clustering w/ silhouette score parameter tuning
   if (cluster.genes) {
     if (pca.init) {
       smoothed_counts_snn <- bluster::makeSNNGraph(smoothed_counts_pca$x,
                                                    k = k.param,
                                                    type = "jaccard",
-                                                   BNPARAM = BiocNeighbors::AnnoyParam(distance = "Cosine"))
+                                                   BNPARAM = BiocNeighbors::AnnoyParam(distance = "Cosine"),
+                                                   BPPARAM = BiocParallel::SnowParam(workers = n.cores))
     } else {
       smoothed_counts_snn <- bluster::makeSNNGraph(smoothed.counts,
                                                    k = k.param,
                                                    type = "jaccard",
-                                                   BNPARAM = BiocNeighbors::AnnoyParam(distance = "Cosine"))
+                                                   BNPARAM = BiocNeighbors::AnnoyParam(distance = "Cosine"),
+                                                   BPPARAM = BiocParallel::SnowParam(workers = n.cores))
     }
     if (is.null(resolution.param)) {
       if (pca.init) {

R/enrichDynamicGenes.R

@@ -12,12 +12,9 @@
 #' @seealso \code{\link[gprofiler2]{gost}}
 #' @export
 #' @examples
-#' \dontrun{
-#' enrichDynamicGenes(scLANE.de.res = de_stats)
-#' enrichDynamicGenes(scLANE.de.res = de_stats,
-#'                    lineage = "B",
-#'                    species = "mmusculus")
-#' }
+#' data(scLANE_models)
+#' scLANE_de_res <- getResultsDE(scLANE_models)
+#' enr_res <- enrichDynamicGenes(scLANE_de_res)
 
 enrichDynamicGenes <- function(scLANE.de.res = NULL,
                                lineage = NULL,

R/extractBreakpoints.R

@@ -8,9 +8,13 @@
 #' @return A data.frame of breakpoints & their directions.
 #' @export
 #' @examples
-#' \dontrun{
-#' extractBreakpoints(model = marge_mod)
-#' }
+#' data(sim_counts)
+#' data(sim_pseudotime)
+#' cell_offset <- createCellOffset(sim_counts)
+#' marge_model <- marge2(sim_pseudotime,
+#'                       Y = BiocGenerics::counts(sim_counts)[4, ],
+#'                       Y.offset = cell_offset)
+#' breakpoint_df <- extractBreakpoints(model = marge_model)
 
 extractBreakpoints <- function(model = NULL, directions = TRUE) {
   # check inputs

R/fitGLMM.R

@@ -22,12 +22,13 @@
 #' @seealso \code{\link{modelLRT}}
 #' @export
 #' @examples
-#' \dontrun{
-#' fitGLMM(X_pred = pt_df,
-#'         Y = raw_counts,
-#'         Y.offset = size_factor_vec,
-#'         id.vec = subject_vec)
-#' }
+#' data(sim_counts)
+#' data(sim_pseudotime)
+#' cell_offset <- createCellOffset(sim_counts)
+#' glmm_mod <- fitGLMM(X_pred = sim_pseudotime,
+#'                     Y = BiocGenerics::counts(sim_counts)[4, ],
+#'                     Y.offset = cell_offset,
+#'                     id.vec = sim_counts$subject)
 
 fitGLMM <- function(X_pred = NULL,
                     Y = NULL,

R/geneProgramScoring.R

@@ -15,18 +15,22 @@
 #' @return Either a \code{Seurat} or \code{SingleCellExperiment} object if \code{expr.mat} is in either form, or a data.frame containing per-cell program scores if \code{expr.mat} is a matrix.
 #' @export
 #' @examples
-#' \dontrun{
-#' geneProgramScoring(seu_obj,
-#'                    genes = gene_embed$gene,
-#'                    gene.clusters = gene_embed$leiden,
-#'                    program.labels = c("cell cycle", "organogenesis"))
-#' }
+#' data(sim_pseudotime)
+#' data(scLANE_models)
+#' smoothed_dynamics <- smoothedCountsMatrix(scLANE_models,
+#'                                           pt = sim_pseudotime,
+#'                                           n.cores = 1L)
+#' gene_embed <- embedGenes(smoothed_dynamics$Lineage_A, n.cores = 1L)
+#' sim_counts <- geneProgramScoring(sim_counts,
+#'                                  genes = gene_embed$gene,
+#'                                  gene.clusters = gene_embed$leiden,
+#'                                  n.cores = 1L)
 
 geneProgramScoring <- function(expr.mat = NULL,
                                genes = NULL,
                                gene.clusters = NULL,
                                program.labels = NULL,
-                               n.cores = 2) {
+                               n.cores = 2L) {
   # check inputs
   if (is.null(expr.mat) || is.null(genes) || is.null(gene.clusters)) { stop("Arguments to geneProgramScoring() are missing.") }
   if (!is.factor(gene.clusters)) {

R/getFittedValues.R

@@ -20,14 +20,13 @@
 #' @return A data.frame containing depth- and log1p-normalized expression, model predictions, and cell-level metadata.
 #' @export
 #' @examples
-#' \dontrun{
-#' getFittedValues(gene_stats,
-#'                 genes = c("Neurog3", "Epcam", "Krt19"),
-#'                 pt = pt_df,
-#'                 expr.mat = seu_obj,
-#'                 cell.meta.data = seu_obj@meta.data,
-#'                 ci.alpha = 0.05)
-#' }
+#' data(sim_counts)
+#' data(sim_pseudotime)
+#' data(scLANE_models)
+#' fitted_vals <- getFittedValues(scLANE_models,
+#'                                genes = sample(names(scLANE_models), 5),
+#'                                pt = sim_pseudotime,
+#'                                expr.mat = sim_counts)
 
 getFittedValues <- function(test.dyn.res = NULL,
                             genes = NULL,

R/getKnotDist.R

@@ -11,9 +11,8 @@
 #' @return A data.frame containing gene name, lineage ID, and knot location in pseudotime.
 #' @export
 #' @examples
-#' \dontrun{
-#' getKnotDist(gene_stats)
-#' }
+#' data(scLANE_models)
+#' knot_dist <- getKnotDist(scLANE_models)
 
 getKnotDist <- function(test.dyn.res = NULL, dyn.genes = NULL) {
   # check inputs

R/marge2.R

@@ -42,24 +42,12 @@
 #' @seealso \code{\link[geeM]{geem}}
 #' @export
 #' @examples
-#' \dontrun{
-#'   marge2(pseudotime_df,
-#'          Y = expr_vec,
-#'          M = 3)
-#'   marge2(pseudotime_df,
-#'          Y = expr_vec,
-#'          Y.offset = size_factor_vec,
-#'          is.gee = TRUE,
-#'          id.vec = subject_vec,
-#'          cor.structure = "exchangeable")
-#'   marge2(pseudotime_df,
-#'          Y = expr_vec,
-#'          is.gee = TRUE,
-#'          id.vec = subject_vec,
-#'          cor.structure = "ar1",
-#'          n.knot.max = 10,
-#'          return.basis = TRUE)
-#' }
+#' data(sim_counts)
+#' data(sim_pseudotime)
+#' cell_offset <- createCellOffset(sim_counts)
+#' marge_model <- marge2(sim_pseudotime,
+#'                       Y = BiocGenerics::counts(sim_counts)[4, ],
+#'                       Y.offset = cell_offset)
 
 marge2 <- function(X_pred = NULL,
                    Y = NULL,

R/nbGAM.R

@@ -21,18 +21,14 @@
 #' @seealso \code{\link[gamlss.dist]{NBI}}
 #' @export
 #' @examples
-#' \dontrun{
-#' nbGAM(expr_vec, pt_df)
-#' nbGAM(expr_vec,
-#'       pt = pt_df,
-#'       id.vec = subject_ids,
-#'       random.slopes = TRUE)
-#' nbGAM(expr_vec,
-#'       pt = pt_df,
-#'       Y.offset = size_factor_vec,
-#'       penalize.spline = TRUE,
-#'       spline.df = 10)
-#' }
+#' data(sim_counts)
+#' data(sim_pseudotime)
+#' cell_offset <- createCellOffset(sim_counts)
+#' gam_mod <- nbGAM(BiocGenerics::counts(sim_counts)[4, ],
+#'                  pt = sim_pseudotime,
+#'                  Y.offset = cell_offset,
+#'                  penalize.spline = TRUE,
+#'                  spline.df = 10)
 
 nbGAM <- function(expr = NULL,
                   pt = NULL,