merge into devel

.github/workflows/test-coverage.yaml

@@ -31,6 +31,7 @@ jobs:
           covr::codecov(
             quiet = FALSE,
             clean = FALSE,
+            exclusions = "R/global.R",
             install_path = file.path(normalizePath(Sys.getenv("RUNNER_TEMP"), winslash = "/"), "package")
           )
         shell: Rscript {0}

DESCRIPTION

@@ -1,20 +1,21 @@
 Package: scRepertoire
 Title: A toolkit for single-cell immune receptor profiling
-Version: 2.0.0
+Version: 2.1.1
 Authors@R: c(
     person(given = "Nick", family = "Borcherding", role = c("aut", "cre"), email = "[email protected]"), 
-    person(given = "Qile", family = "Yang", role = c("aut"), email = "[email protected]"), 
+    person(given = "Qile", family = "Yang", role = c("aut"), email = "[email protected]"), 
     person(given = "Ksenia", family = "Safina", role = c("aut"), email = "[email protected]"))
 Description: scRepertoire is a toolkit for processing and analyzing single-cell T-cell receptor (TCR) and immunoglobulin (Ig). The scRepertoire framework supports use of 10x, AIRR, BD, MiXCR, Omniscope, TRUST4, and WAT3R single-cell formats. The functionality includes basic clonal analyses, repertoire summaries, distance-based clustering and interaction with the popular Seurat and SingleCellExperiment/Bioconductor R workflows.
 License: MIT + file LICENSE 
 Encoding: UTF-8
 LazyData: true
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.2
 biocViews: Software, ImmunoOncology, SingleCell, Classification, Annotation, Sequencing
 Depends: 
-	ggplot2, 
-	R (>= 4.0)
+     ggplot2, 
+     R (>= 4.0)
 Imports: 
+    assertthat,
     cubature,
     dplyr,
     evmix,
@@ -60,4 +61,5 @@ Config/testthat/edition: 3
 Language: en-US
 LinkingTo: 
     Rcpp
-URL: https://ncborcherding.github.io/scRepertoire/
+URL: https://www.borch.dev/uploads/scRepertoire/
+BugReports: https://github.com/ncborcherding/scRepertoire/issues

NAMESPACE

@@ -31,9 +31,10 @@ export(percentAA)
 export(percentGenes)
 export(percentKmer)
 export(percentVJ)
+export(positionalEntropy)
+export(positionalProperty)
 export(subsetClones)
 export(vizGenes)
-import(dplyr)
 import(ggplot2)
 importFrom(Rcpp,sourceCpp)
 importFrom(S4Vectors,DataFrame)
@@ -44,16 +45,33 @@ importFrom(SingleCellExperiment,reducedDim)
 importFrom(SummarizedExperiment,"colData<-")
 importFrom(SummarizedExperiment,colData)
 importFrom(VGAM,dpareto)
+importFrom(assertthat,assert_that)
+importFrom(assertthat,is.flag)
+importFrom(assertthat,is.string)
 importFrom(cubature,adaptIntegrate)
 importFrom(dplyr,"%>%")
+importFrom(dplyr,across)
+importFrom(dplyr,all_of)
+importFrom(dplyr,arrange)
 importFrom(dplyr,bind_rows)
+importFrom(dplyr,coalesce)
 importFrom(dplyr,count)
+importFrom(dplyr,desc)
+importFrom(dplyr,filter)
 importFrom(dplyr,group_by)
+importFrom(dplyr,left_join)
 importFrom(dplyr,mutate)
+importFrom(dplyr,mutate_at)
+importFrom(dplyr,mutate_if)
+importFrom(dplyr,n)
 importFrom(dplyr,sample_n)
 importFrom(dplyr,select)
+importFrom(dplyr,slice_max)
 importFrom(dplyr,summarise)
+importFrom(dplyr,summarize)
 importFrom(dplyr,summarize_all)
+importFrom(dplyr,transmute)
+importFrom(dplyr,ungroup)
 importFrom(evmix,dgpd)
 importFrom(evmix,fgpd)
 importFrom(evmix,pgpd)
@@ -83,25 +101,31 @@ importFrom(igraph,components)
 importFrom(igraph,graph_from_data_frame)
 importFrom(igraph,graph_from_edgelist)
 importFrom(igraph,set_vertex_attr)
+importFrom(igraph,union)
 importFrom(methods,slot)
 importFrom(plyr,join)
 importFrom(plyr,llply)
 importFrom(quantreg,rqss)
-importFrom(reshape2,dcast)
 importFrom(reshape2,melt)
 importFrom(rjson,fromJSON)
+importFrom(rlang,"!!")
 importFrom(rlang,"%||%")
+importFrom(rlang,":=")
+importFrom(rlang,ensym)
+importFrom(rlang,sym)
 importFrom(stats,as.dist)
 importFrom(stats,hclust)
 importFrom(stats,mad)
 importFrom(stats,na.omit)
 importFrom(stats,optim)
 importFrom(stats,pgamma)
+importFrom(stats,qt)
 importFrom(stats,quantile)
 importFrom(stats,sd)
 importFrom(stats,setNames)
 importFrom(stringdist,stringdist)
 importFrom(stringr,str_c)
+importFrom(stringr,str_remove_all)
 importFrom(stringr,str_replace_all)
 importFrom(stringr,str_replace_na)
 importFrom(stringr,str_sort)

NEWS.md

@@ -1,3 +1,52 @@
+# scRepertoire VERSION 2.0.5
+
+## UNDERLYING CHANGES
+* added type checks using assertthat
+* updated conditional statements in constructConDFAndparseTCR.cpp
+* Fixed issue in ```clonalQuant()``` and factor-based **group.by** variable
+
+# scRepertoire VERSION 2.0.4
+
+## UNDERLYING CHANGES
+* ```getCirclize()``` refactored to prevent assumptions and added **include.self** argument
+* Added ```.count.clones()``` internal function for ```getCirclize()``` and ```clonalNetwork()```
+* Added **order.by** parameter to visualizations to specifically call order of plotting using a vector or can use "alphanumeric" to plot things in order
+* Fix issue with ```clonalLength()``` and NA handling
+* ```clonalCompare()``` now retains the original clonal info if using **relabel.clones**
+* Add Dandelion support in to ```loadContigs()``` and testthat
+* Fixed issue with ```positionalProperty()``` assumption that the clones will all have 20 amino acids.
+* Fixed issue with ```positionalProperty()``` and removing non-amino acids.
+* Fixed IGH/K/L mistaking gene issue in ```vizGenes()```
+* Add error message for NULL results in ```clonalCluster()``` with **export.graph = TRUE**
+* Fixed issue with "full.clones" missing in ```combineExpression()``` when using 1 chain
+
+
+# scRepertoire VERSION 2.0.3
+
+## UNDERLYING CHANGES
+
+* Modified support for Omniscope format to allow for dual chains
+* Added ParseBio support in to ```loadContigs()``` and testthat
+* Added support for productive variable to ```loadContigs()``` for BD, Omniscope, and Immcantation formats
+* Replace numerical indexing with name indexing for ```loadContigs()```
+* ```combineBCR()``` and ```combineTCR()``` no allow for unproductive contig inclusions with new **filterNonproductive** parameter.
+* ```combineBCR()``` will now prompt user if **samples** is not included instead of erroring.
+* Added base threshold by length for internal ```.lvCompare()```
+* Ensured internal ```.lvCompare()``` only looks at first set of sequences in multi-sequence chain.
+* Fixed bug in exporting graph for ```clonaCluster()```
+* Fixed conflict in functions between igraph and dplyr packages
+
+# scRepertoire VERSION 2.0.2
+
+## UNDERLYING CHANGES
+
+* ```clonalOccupy()``` rewrite counting and NA handling
+
+# scRepertoire VERSION 2.0.1 
+
+## UNDERLYING CHANGES
+
+* ```clonalOverlay()``` arguments now cutpoint and use cut.category to select either clonalProportion or clonalFrequency
 
 # scRepertoire VERSION 2.0.0 (2024-01-10)
 
@@ -8,6 +57,8 @@
 * Added ```percentVJ()```
 * Added ```percentKmer()```
 * Added ```exportClones()``` 
+* Added ```positionalEntropy()``` 
+* Added ```positionalProperty()``` 
 * Changed compareClonotypes to ```clonalCompare()```
 * Changed clonotypeSizeDistribution to ```clonalSizeDistribution()```
 * Changed scatterClonotypes to ```clonalScatter()```
@@ -25,7 +76,7 @@
 * **.theCall()** now allows for a custom header/variable and checks the colnames. 
 * Replaced data arguments to be more descriptive: *df* is now *input.data*, *dir* is now *input*, and *sc* is now *sc.data*
 * Deep clean on the documentation for each function for increased consistency and explainability
-* ```Startracdiversity()``` metric re-implemented to remove startrac-class object intermediary
+* ```StartracDiversity()``` metric re-implemented to remove startrac-class object intermediary
 * Implemented powerTCR locally to reduce dependencies and continue support
 * Universalized underlying function language and intermediate variables
 * License change to MIT
@@ -38,14 +89,14 @@
 * ```clonalDiversity()``` no longer automatically orders samples.
 * Remove **order** parameter from ```clonalQuant()```, ```clonalLength()```, and ```clonalAbundance()```
 * **x.axis** parameter in ```clonalDiversity()``` separated from **group.by** parameter
+* filtering chains will not eliminate none matching chains.
 
 ## DEPRECATED AND DEFUNCT
 
 * Deprecate stripBarcodes()
 * Deprecate expression2List() (now only an internal function).
 * Deprecate checkContigs()
 
-
 # scRepertoire VERSION 1.11.0
 
 * Rebasing for the purposes of bioconductor version

R/clonalAbundance.R

@@ -26,6 +26,8 @@
 #' @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 
 #' relative distributions.
 #' @param exportTable Returns the data frame used for forming the graph
@@ -42,7 +44,8 @@ clonalAbundance <- function(input.data,
                             chain = "both", 
                             scale=FALSE, 
                             group.by = NULL, 
-                            exportTable = FALSE, 
+                            order.by = NULL,
+                            exportTable = FALSE,
                             palette = "inferno") {
   Con.df <- NULL
   xlab <- "Abundance"
@@ -58,11 +61,17 @@ clonalAbundance <- function(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 <- data.frame(Con.df)
-      col <- length(unique(Con.df[,group.by]))
-      fill <- group.by
-      if (scale == TRUE) { 
+      Con.df<- rbind.data.frame(Con.df, data1) 
+    }
+    Con.df <- data.frame(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, 
+                                     data.frame =  Con.df)
+    }
+    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)), 
@@ -86,6 +95,12 @@ clonalAbundance <- function(input.data,
       Con.df<- rbind.data.frame(Con.df, data1) 
     }
     Con.df <- data.frame(Con.df)
+    if(!is.null(order.by)) {
+      Con.df <- .ordering.function(vector = order.by,
+                                   group.by = "values", 
+                                   data.frame = Con.df)
+    }
+
     col <- length(unique(Con.df$values))
     fill <- "Samples"
     if (scale == TRUE) { 

R/clonalCluster.R

@@ -6,6 +6,8 @@
 #' \code{\link{combineBCR}} or \code{\link{combineExpression}} and amends a 
 #' cluster to the data frame or meta data. If \strong{exportGraph} is set 
 #' to TRUE, the function returns an igraph object of the connected sequences. 
+#' If multiple sequences per chain are present, this function only compares
+#' the first sequence.
 #' 
 #' @examples
 #' # Getting the combined contigs
@@ -28,17 +30,20 @@
 #' The higher the number the more similarity of sequence will be 
 #' used for clustering.
 #' @param group.by The column header used for to group contigs.
+#' If (\strong{NULL}), clusters will be calculated across samples.
 #' @param exportGraph Return an igraph object of connected 
 #' sequences (\strong{TRUE}) or the amended input with a
 #' new cluster-based variable (\strong{FALSE}).
 #' @importFrom stringdist stringdist
-#' @importFrom igraph set_vertex_attr V
+#' @importFrom igraph set_vertex_attr V union
 #' @importFrom plyr join
-#' @importFrom dplyr bind_rows
+#' @importFrom dplyr bind_rows summarize
 #' @importFrom stringr str_split str_replace_all
 #' @importFrom rlang %||%
 #' @importFrom SummarizedExperiment colData<- colData
 #' @importFrom stats na.omit
+#' @importFrom S4Vectors DataFrame
+#' 
 #' @export
 #' @concept Visualizing_Clones
 #' @return Either amended input with edit-distanced clusters added 
@@ -94,18 +99,23 @@ clonalCluster <- function(input.data,
 
   if (!is.null(group.by)) {
     bound <- bind_rows(dat, .id = "group.by")
+    bound <- bound[!is.na(bound[,ref2]),]
+    retain.ref <- data.frame(old = bound[,ref2], new = str_split(bound[,ref2], ";", simplify = TRUE)[,1])
+    bound[,ref2] <- str_split(bound[,ref2], ";", simplify = TRUE)[,1]
     graph.variables <- bound %>%
                           group_by(bound[,ref2]) %>%
                           dplyr::summarize(sample_count = n(),
                                     unique_samples = paste0(unique(group.by), collapse = ","))
-    dictionary <- list(bound)
   } else {
     bound <- bind_rows(dat)
-    graph.variables <- bind_rows(dat) %>%
+    bound <- bound[!is.na(bound[,ref2]),]
+    retain.ref <- data.frame(old = bound[,ref2], new = str_split(bound[,ref2], ";", simplify = TRUE)[,1])
+    bound[,ref2] <- str_split(bound[,ref2], ";", simplify = TRUE)[,1]
+    graph.variables <- bound %>%
                           group_by(bound[,ref2]) %>%
                           dplyr::summarize(sample_count = n())
-    dictionary <- dat
   }
+  dictionary <- dat
   #Generating Connected Component
   output.list <- lapply(dictionary, function(x) {
     cluster <- .lvCompare(x, 
@@ -118,25 +128,30 @@ clonalCluster <- function(input.data,
   #Grabbing column order for later return
   column.order <- colnames(bound)
 
-  #Returning the igraph object if eexportGraph = TRUE
+  #Returning the igraph object if exportGraph = TRUE
   if(exportGraph) {
-    cluster <- output.list[[1]]
-    vertex <- names(V(cluster))
-    data_df <- unique(data.frame(
-      id = V(cluster)$name
-    ))
-    data_df <- merge(data_df, graph.variables, by = 1)
-    cluster <- set_vertex_attr(cluster, 
-                               name = "size", 
-                               index = data_df$id, 
-                               value = data_df[,2])
-    if(ncol(data_df) == 3) { #add grouping variable
+    if(length(is.null(output.list)) == length(output.list)) {
+      stop("No clusters detected with current parameters.")
+    } else {
+      output.list <- output.list[lapply(output.list,length)>0]
+      cluster <- do.call(igraph::union, output.list)
+      vertex <- names(V(cluster))
+      data_df <- unique(data.frame(
+        id = vertex
+      ))
+      data_df <- merge(data_df, graph.variables, by = 1)
       cluster <- set_vertex_attr(cluster, 
-                                 name = "group", 
+                                 name = "size", 
                                  index = data_df$id, 
-                                 value = data_df[,3])
+                                 value = data_df[,2])
+      if(ncol(data_df) == 3) { #add grouping variable
+        cluster <- set_vertex_attr(cluster, 
+                                   name = "group", 
+                                   index = data_df$id, 
+                                   value = data_df[,3])
+      }
+      return(cluster)
     }
-    return(cluster)
   }
 
   cluster.list <- lapply(seq_len(length(output.list)), function(x) {
@@ -169,10 +184,11 @@ clonalCluster <- function(input.data,
       col.name <- names(PreMeta) %||% colnames(PreMeta)
       input.data[[col.name]] <- PreMeta
     } else {
-      rownames <- rownames(colData(input.data))
-      colData(input.data) <- cbind(colData(input.data), 
-                                   PreMeta[rownames,])[, union(colnames(colData(input.data)),  colnames(PreMeta))]
-      rownames(colData(input.data)) <- rownames 
+      combined_col_names <- unique(c(colnames(colData(sc.data)), colnames(PreMeta)))
+      full_data <- merge(colData(sc.data), PreMeta[rownames, , drop = FALSE], by = "row.names", all.x = TRUE)
+      rownames(full_data) <- full_data[, 1]
+      full_data  <- full_data[, -1]
+      colData(sc.data) <- DataFrame(full_data[, combined_col_names])
     }
   } else {
     #Reorder columns