Add simple T/BCR doublet detector, use markdown for roxygen, and slight refactoring of combineExpression

.github/workflows/R-CMD-check.yaml

@@ -4,7 +4,7 @@ on:
   push:
     branches: [main, master, v2]
   pull_request:
-    branches: [main, master, v2]
+    branches: [main, master, v2, dev]
 
 name: R-CMD-check
 

.gitignore

@@ -1,10 +1,64 @@
 .Rproj.user
 .DS_Store
 .Rhistory
-.Rhistory
 local_tests.R
 .RData
 docs
 vignettes/articles/scRep_example_full.rds
 .vscode
-qile
+dev
+
+# remove if linting is ever strictly enforced / a standard is set
+.lintr
+
+# below is the github R gitignore
+
+# History files
+.Rhistory
+.Rapp.history
+
+# Session Data files
+.RData
+.RDataTmp
+
+# User-specific files
+.Ruserdata
+
+# Example code in package build process
+*-Ex.R
+
+# Output files from R CMD build
+/*.tar.gz
+
+# Output files from R CMD check
+/*.Rcheck/
+
+# RStudio files
+.Rproj.user/
+
+# produced vignettes
+vignettes/*.html
+vignettes/*.pdf
+
+# OAuth2 token, see https://github.com/hadley/httr/releases/tag/v0.3
+.httr-oauth
+
+# knitr and R markdown default cache directories
+*_cache/
+/cache/
+
+# Temporary files created by R markdown
+*.utf8.md
+*.knit.md
+
+# R Environment Variables
+.Renviron
+
+# pkgdown site
+docs/
+
+# translation temp files
+po/*~
+
+# RStudio Connect folder
+rsconnect/

DESCRIPTION

@@ -43,7 +43,10 @@ Imports:
     truncdist,
     utils,
     VGAM,
-    hash
+    hash,
+    purrr,
+    lifecycle,
+    withr
 Suggests: 
     BiocManager,
     BiocStyle,
@@ -63,3 +66,4 @@ LinkingTo:
     Rcpp
 URL: https://www.borch.dev/uploads/scRepertoire/
 BugReports: https://github.com/ncborcherding/scRepertoire/issues
+Roxygen: list(markdown = TRUE)

NAMESPACE

@@ -25,6 +25,7 @@ export(combineTCR)
 export(createHTOContigList)
 export(exportClones)
 export(getCirclize)
+export(getContigDoublets)
 export(highlightClones)
 export(loadContigs)
 export(percentAA)
@@ -102,6 +103,7 @@ importFrom(igraph,graph_from_data_frame)
 importFrom(igraph,graph_from_edgelist)
 importFrom(igraph,set_vertex_attr)
 importFrom(igraph,union)
+importFrom(lifecycle,deprecated)
 importFrom(methods,slot)
 importFrom(plyr,join)
 importFrom(plyr,llply)

NEWS.md

@@ -1,10 +1,16 @@
 # scRepertoire VERSION 2.0.8
 
+## NEW FEATURES
+* Added ```getContigDoublets()``` experimental function to identify TCR and BCR doublets as a preprocessing step to ```combineExpression()```
+
 ## UNDERLYING CHANGES
 * Fixed issue with single chain output for ```clonalLength()```
 * Removed unnecessary code remnant in ```clonalLength()```
 * Allow one sample to be plotted by ```percentVJ()```
 * Fixed issue with ```positionalProperty()``` and exportTable
+* convert documentation to use markdown (`roxygen2md`)
+* import `lifecycle`, `purrr`, `withr`
+* suppressed "using discrete variable for alpha is not recommended" warning in alluvialClones unit tests.
 
 # scRepertoire VERSION 2.0.7
 

R/addVariable.R

@@ -1,10 +1,10 @@
 #' Adding variables after combineTCR() or combineBCR()
 #'
-#' This function adds variables to the product of \code{\link{combineTCR}}, 
-#' or \code{\link{combineBCR}} to be used in later visualizations. 
+#' This function adds variables to the product of [combineTCR()], 
+#' or [combineBCR()] to be used in later visualizations. 
 #' For each element, the function will add a column (labeled by 
-#' \strong{variable.name}) with the variable. The length of the 
-#' \strong{variables} parameter needs to match the length of the 
+#' **variable.name**) with the variable. The length of the 
+#' **variables** parameter needs to match the length of the 
 #' combined object.
 #'
 #' @examples
@@ -15,8 +15,8 @@
 #'                         variable.name = "Type", 
 #'                         variables = rep(c("B", "L"), 4))
 #'
-#' @param input.data The product of \code{\link{combineTCR}} or 
-#' \code{\link{combineBCR}}.
+#' @param input.data The product of [combineTCR()] or 
+#' [combineBCR()].
 #' @param variable.name The new column name/header.
 #' @param variables The exact values to add to each element of the list.
 #' @export

R/alluvialClones.R

@@ -20,7 +20,7 @@
 #' Alluvial plotting for single-cell object meta data
 #'
 #' View the proportional contribution of clones by Seurat or SCE object 
-#' meta data after \code{\link{combineExpression}}. The visualization 
+#' meta data after [combineExpression()]. The visualization 
 #' is based on the ggalluvial package, which requires the aesthetics 
 #' to be part of the axes that are visualized. Therefore, alpha, facet, 
 #' and color should be part of the the axes you wish to view or will 
@@ -46,10 +46,10 @@
 #'                    color = "ident")
 #' 
 #' @param sc.data The single-cell object to visualize 
-#' after \code{\link{combineExpression}}. 
-#' @param cloneCall How to call the clone - VDJC gene (\strong{gene}), 
-#' CDR3 nucleotide (\strong{nt}), CDR3 amino acid (\strong{aa}),
-#' VDJC gene + CDR3 nucleotide (\strong{strict}) or a custom variable 
+#' after [combineExpression()]. 
+#' @param cloneCall How to call the clone - VDJC gene (**gene**), 
+#' CDR3 nucleotide (**nt**), CDR3 amino acid (**aa**),
+#' VDJC gene + CDR3 nucleotide (**strict**) or a custom variable 
 #' in the data. 
 #' @param chain indicate if both or a specific chain should be used - 
 #' e.g. "both", "TRA", "TRG", "IGH", "IGL".
@@ -61,7 +61,7 @@
 #' @param exportTable Exports a table of the data into the global 
 #' environment in addition to the visualization.
 #' @param palette Colors to use in visualization - input any 
-#' \link[grDevices]{hcl.pals}.
+#' [hcl.pals][grDevices::hcl.pals].
 #' 
 #' @import ggplot2
 #' @importFrom ggalluvial StatStratum geom_flow geom_stratum to_lodes_form geom_alluvium

R/clonalAbundance.R

@@ -1,92 +1,89 @@
 #' Demonstrate the relative abundance of clones by group or sample
 #'
-#' Displays the number of clones at specific frequencies by sample
+#' Displays the number of clones at specific frequencies by sample 
 #' or group. Visualization can either be a line graph (
-#' \strong{scale} = FALSE) using calculated numbers or density
-#' plot (\strong{scale} = TRUE). Multiple sequencing runs can
-#' be group together using the group parameter. If a matrix
-#' output for the data is preferred, set
-#' \strong{exportTable} = TRUE.
+#' **scale** = FALSE) using calculated numbers or density 
+#' plot (**scale** = TRUE). Multiple sequencing runs can 
+#' be group together using the group parameter. If a matrix 
+#' output for the data is preferred, set 
+#' **exportTable** = TRUE.
 #'
 #' @examples
 #' #Making combined contig data
-#' combined <- combineTCR(contig_list,
-#'                         samples = c("P17B", "P17L", "P18B", "P18L",
+#' combined <- combineTCR(contig_list, 
+#'                         samples = c("P17B", "P17L", "P18B", "P18L", 
 #'                                     "P19B","P19L", "P20B", "P20L"))
-#' clonalAbundance(combined,
-#'                 cloneCall = "gene",
+#' clonalAbundance(combined, 
+#'                 cloneCall = "gene", 
 #'                 scale = FALSE)
 #'
-#' @param input.data The product of \code{\link{combineTCR}},
-#' \code{\link{combineBCR}}, or \code{\link{combineExpression}}.
-#' @param cloneCall How to call the clone - VDJC gene (\strong{gene}),
-#' CDR3 nucleotide (\strong{nt}), CDR3 amino acid (\strong{aa}),
-#' VDJC gene + CDR3 nucleotide (\strong{strict}) or a custom variable
-#' in the data.
-#' @param chain indicate if both or a specific chain should be used -
+#' @param input.data The product of [combineTCR()], 
+#' [combineBCR()], or [combineExpression()].
+#' @param cloneCall How to call the clone - VDJC gene (**gene**), 
+#' CDR3 nucleotide (**nt**), CDR3 amino acid (**aa**),
+#' VDJC gene + CDR3 nucleotide (**strict**) or a custom variable 
+#' in the data. 
+#' @param chain indicate if both or a specific chain should be used - 
 #' e.g. "both", "TRA", "TRG", "IGH", "IGL"
 #' @param group.by The variable to use for grouping
 #' @param order.by A vector of specific plotting order or "alphanumeric"
 #' to plot groups in order
-#' @param scale Converts the graphs into density plots in order to show
+#' @param scale Converts the graphs into density plots in order to show 
 #' relative distributions.
 #' @param exportTable Returns the data frame used for forming the graph
 #' to the visualization.
-#' @param palette Colors to use in visualization - input any
-#' \link[grDevices]{hcl.pals}.
+#' @param palette Colors to use in visualization - input any 
+#' [hcl.pals][grDevices::hcl.pals].
 #' @importFrom ggplot2 ggplot
 #' @export
 #' @concept Visualizing_Clones
-#' @return ggplot of the total or relative abundance of clones
+#' @return ggplot of the total or relative abundance of clones 
 #' across quanta
-clonalAbundance <- function(input.data,
-                            cloneCall = "strict",
-                            chain = "both",
-                            scale=FALSE,
-                            group.by = NULL,
+clonalAbundance <- function(input.data, 
+                            cloneCall = "strict", 
+                            chain = "both", 
+                            scale=FALSE, 
+                            group.by = NULL, 
                             order.by = NULL,
                             exportTable = FALSE,
                             palette = "inferno") {
   Con.df <- NULL
   xlab <- "Abundance"
-  input.data <- .data.wrangle(input.data,
-                              group.by,
-                              .theCall(input.data, cloneCall, check.df = FALSE),
+  input.data <- .data.wrangle(input.data, 
+                              group.by, 
+                              .theCall(input.data, cloneCall, check.df = FALSE), 
                               chain)
   cloneCall <- .theCall(input.data, cloneCall)
-
+  
   names <- names(input.data)
   if (!is.null(group.by)) {
     for (i in seq_along(input.data)) {
       data1 <- .parseContigs(input.data, i, names, cloneCall)
       label <- input.data[[i]][1,group.by]
       data1[,paste(group.by)] <- label
-      Con.df<- rbind.data.frame(Con.df, data1)
+      Con.df<- rbind.data.frame(Con.df, data1) 
     }
     Con.df <- data.frame(Con.df)
-    if (exportTable == TRUE) {
-      return(Con.df)
-    }
     col <- length(unique(Con.df[,group.by]))
     fill <- group.by
     if(!is.null(order.by)) {
         Con.df <- .ordering.function(vector = order.by,
-                                     group.by = group.by,
+                                     group.by = group.by, 
                                      data.frame =  Con.df)
     }
-    if (scale == TRUE) {
+    if (scale == TRUE) { 
         ylab <- "Density of Clones"
         plot <- ggplot(Con.df, aes(x=Abundance, fill=Con.df[,group.by])) +
-                      geom_density(aes(y=after_stat(scaled)),
-                                   alpha=0.5,
-                                   lwd=0.25,
-                                   color="black",
+                      geom_density(aes(y=after_stat(scaled)), 
+                                   alpha=0.5, 
+                                   lwd=0.25, 
+                                   color="black", 
                                    bw=0.5)  +
                       scale_fill_manual(values = .colorizer(palette,col)) +
                       labs(fill = fill)
-    } else {
+    } else { 
         ylab <- "Number of Clones"
-        plot <- ggplot(Con.df, aes(x=Abundance, group.by = values,
+        plot <- ggplot(Con.df, aes(x=Abundance, group.by = values, 
                                color = Con.df[,group.by])) +
                         geom_line(stat="count") +
                         scale_color_manual(values = .colorizer(palette,col)) +
@@ -95,39 +92,39 @@ clonalAbundance <- function(input.data,
   } else {
     for (i in seq_along(input.data)) {
       data1 <- .parseContigs(input.data, i, names, cloneCall)
-      Con.df<- rbind.data.frame(Con.df, data1)
+      Con.df<- rbind.data.frame(Con.df, data1) 
     }
     Con.df <- data.frame(Con.df)
-    if (exportTable == TRUE) {
-      return(Con.df)
-    }
     if(!is.null(order.by)) {
       Con.df <- .ordering.function(vector = order.by,
-                                   group.by = "values",
+                                   group.by = "values", 
                                    data.frame = Con.df)
     }
-
+    
     col <- length(unique(Con.df$values))
     fill <- "Samples"
-    if (scale == TRUE) {
+    if (scale == TRUE) { 
       ylab <- "Density of Clones"
       plot <- ggplot(Con.df, aes(Abundance, fill=values)) +
-                      geom_density(aes(y=after_stat(scaled)),
-                                   alpha=0.5,
-                                   lwd=0.25,
-                                   color="black",
+                      geom_density(aes(y=after_stat(scaled)), 
+                                   alpha=0.5, 
+                                   lwd=0.25, 
+                                   color="black", 
                                    bw=0.5) +
                       scale_fill_manual(values = .colorizer(palette,col)) +
                       labs(fill = fill)
-    } else {
+    } else { 
       ylab <- "Number of Clones"
-      plot <- ggplot(Con.df, aes(x=Abundance, group = values,
+      plot <- ggplot(Con.df, aes(x=Abundance, group = values, 
                                color = values)) +
                       geom_line(stat="count") +
                       scale_color_manual(values = .colorizer(palette,col)) +
                       labs(color = fill)
   } }
+  if (exportTable == TRUE) { 
+    return(Con.df) 
+  }
   plot <- plot + scale_x_log10() + ylab(ylab) + xlab(xlab) +
     theme_classic()
-  return(plot)
+  return(plot) 
 }