Remove the removeSingletons option.

Changing the default value of keepSingletonsAbove from `Inf` to `0` keeps
the standard behaviour.

The `clusterCTSS()` function had five expression filtering options:
  - removeSingletons,
  - keepSingletonsAbove,
  - threshold,
  - nrPassThreshold,
  - thresholdIsTpm

I always found it difficult to review code that uses all these options.

Author: Charles Plessy

NEWS.md

@@ -13,6 +13,9 @@ BACKWARDS-INCOMPATIBLE CHANGES
     the newer `CustomConsensusClusters` function.
 -   The `exportToTrack` function now exports scores of _tag clusters_ and
     _consensus clusters_ instead of setting them to zero.
+-   The `removeSingletons` option of clustering methods is removed and the
+    default value of `keepSingletonsAbove` is set to `0`, which keeps the
+    standard behavior.
 
 BUG FIXES
 

R/AggregationMethods.R

@@ -151,7 +151,7 @@ setMethod( "aggregateTagClusters", "CAGEr"
   if (any(countOverlaps(clusters.gr, ctss) == 0))
     stop("Some TCs do not overlap any CTSS!")
 
-  clusters.gr <- .ctss_summary_for_clusters(ctss, clusters.gr, removeSingletons = FALSE)
+  clusters.gr <- .ctss_summary_for_clusters(ctss, clusters.gr)
 
   names(clusters.gr) <- as.character(clusters.gr)
   .ConsensusClusters(clusters.gr)

R/ClusteringFunctions.R

@@ -11,9 +11,9 @@ NULL
 #' (clusters <- GRanges('chr1', IRanges(start = c(1,9), end = c(8,10)), '+'))
 #' 
 #' # The function assumes that all CTSSes have a score above zero
-#' .ctss_summary_for_clusters(ctss[score(ctss)>0], clusters, removeSingletons = TRUE)
+#' .ctss_summary_for_clusters(ctss[score(ctss)>0], clusters, keepSingletonsAbove = Inf)
 #' # If not the case, it will give incorrect nr_ctss and  fail to remove singletons
-#' .ctss_summary_for_clusters(ctss, clusters, removeSingletons = TRUE)
+#' .ctss_summary_for_clusters(ctss, clusters, keepSingletonsAbove = Inf)
 #' 
 #' # The function needs its output to be sorted and is not going to check it.
 #' .ctss_summary_for_clusters(rev(ctss), clusters)
@@ -23,7 +23,7 @@ NULL
 #' # This may create a small bias.
 #' .ctss_summary_for_clusters(ctss |> plyranges::mutate(strand = '-'), clusters |> plyranges::mutate(strand = '-'))
 
-.ctss_summary_for_clusters <- function(ctss, clusters, removeSingletons = FALSE, keepSingletonsAbove = Inf) {
+.ctss_summary_for_clusters <- function(ctss, clusters, keepSingletonsAbove = 0) {
   # Match the clusters and the CTSS
   o <- findOverlaps(clusters, ctss)
 
@@ -60,8 +60,7 @@ NULL
   clusters$nr_ctss <- rl
 
   # Remove clusters that match only one CTSS unless their expression is high enough
-  if(removeSingletons)
-    clusters <- subset(clusters, clusters$nr_ctss > 1 | score(clusters) >= keepSingletonsAbove)
+  clusters <- subset(clusters, clusters$nr_ctss > 1 | score(clusters) >= keepSingletonsAbove)
 
   # Give numerical names to the clusters
   names(clusters) <- seq_along(clusters)

R/ClusteringMethods.R

@@ -22,14 +22,9 @@
 #'        part of the same cluster.  Used only when `method = "distclu"`,
 #'        otherwise ignored.
 #' 
-#' @param removeSingletons Logical indicating if tag clusters containing only
-#'        one CTSS be removed.
-#' 
-#' @param keepSingletonsAbove Controls which singleton tag clusters will be
-#'        removed.  When `removeSingletons = TRUE`, only singletons with signal
-#'        `< keepSingletonsAbove` will be removed.  Useful to prevent removing
-#'        highly supported singleton tag clusters.  Default value `Inf` results
-#'        in removing all singleton TCs when `removeSingletons = TRUE`.
+#' @param keepSingletonsAbove Remove "singleton" tag clusters of width 1 with
+#'        signal `< keepSingletonsAbove`.  Default value `0` results in keeping
+#'        all TCs by default.  Setting it to `Inf` removes all singletons.
 #' 
 #' @param minStability Minimal stability of the cluster, where stability is
 #'        defined as ratio between maximal and minimal density value for which
@@ -58,7 +53,7 @@
 #' `"paraclu"` is an implementation of Paraclu algorithm for parametric
 #' clustering of data attached to sequences (Frith _et al._, Genome Research,
 #' 2007).  Since Paraclu finds clusters within clusters (unlike distclu),
-#' additional parameters (`removeSingletons`, `keepSingletonsAbove`,
+#' additional parameters (`keepSingletonsAbove`,
 #' `minStability`, `maxLength` and `reduceToNonoverlapping`) can be specified to
 #' simplify the output by discarding too small (singletons) or too big clusters,
 #' and to reduce the clusters to a final set of non-overlapping clusters.
@@ -89,13 +84,13 @@
 #' # Using 'distclu', notice argument 'maxDist'
 #' ce <- clusterCTSS( exampleCAGEexp, threshold = 50, thresholdIsTpm = TRUE
 #'            , nrPassThreshold = 1, method = "distclu", maxDist = 20
-#'            , removeSingletons = TRUE, keepSingletonsAbove = 100)
+#'            , keepSingletonsAbove = 100)
 #' tagClustersGR(ce, "Zf.30p.dome")
 #' 
 #' # Using 'paraclu', notice arguments 'maxLength' and 'minStability'
 #' ce <- clusterCTSS( exampleCAGEexp, threshold = 50, thresholdIsTpm = TRUE
 #'            , nrPassThreshold = 1, method = "paraclu"
-#'            , removeSingletons = TRUE, keepSingletonsAbove = 100
+#'            , keepSingletonsAbove = 100
 #'            , maxLength = 500, minStability = 1
 #'            , reduceToNonoverlapping = TRUE)
 #' tagClustersGR(ce, "Zf.30p.dome")
@@ -106,7 +101,7 @@ setGeneric( "clusterCTSS"
           , function( object
                     , threshold = 1, nrPassThreshold = 1, thresholdIsTpm = TRUE
                     , method = c("distclu", "paraclu"), maxDist = 20
-                    , removeSingletons = FALSE, keepSingletonsAbove = Inf
+                    , keepSingletonsAbove = 0
                     , minStability = 1, maxLength = 500
                     , reduceToNonoverlapping = TRUE
                     , useMulticore = FALSE, nrCores = NULL)
@@ -116,7 +111,7 @@ setGeneric( "clusterCTSS"
 
 setMethod( "clusterCTSS", "CAGEexp"
          , function( object, threshold, nrPassThreshold, thresholdIsTpm, method, maxDist
-                   , removeSingletons, keepSingletonsAbove, minStability, maxLength
+                   , keepSingletonsAbove, minStability, maxLength
                    , reduceToNonoverlapping, useMulticore, nrCores) {
 
   assay <- ifelse(isTRUE(thresholdIsTpm), "normalizedTpmMatrix", "counts")
@@ -137,12 +132,10 @@ setMethod( "clusterCTSS", "CAGEexp"
 
   if (method == "distclu") {
     ctss.cluster.list <-  distclu( object = data[decode(filteredCTSSidx(object)),]
-                                 , max.dist = maxDist, removeSingletons = removeSingletons
-                                 , keepSingletonsAbove = keepSingletonsAbove)
+                                 , max.dist = maxDist, keepSingletonsAbove = keepSingletonsAbove)
   } else if (method == "paraclu") {
     ctss.cluster.list <-  paraclu( object = data[decode(filteredCTSSidx(object)),]
                                  , minStability = minStability, maxLength = maxLength
-                                 , removeSingletons = removeSingletons
                                  , keepSingletonsAbove = keepSingletonsAbove
                                  , reduceToNonoverlapping = reduceToNonoverlapping
                                  , useMulticore = useMulticore, nrCores = nrCores)

R/Distclu.R

@@ -9,23 +9,9 @@ NULL
 #' @param max.dist Maximal distance between two neighbouring CTSSs for them to
 #'        be part of the same cluster.
 #' 
-#' @param removeSingletons Logical indicating if tag clusters containing only
-#'        one CTSS be removed.
-#' 
-#' @param keepSingletonsAbove Controls which singleton tag clusters will be
-#'        removed.  When `removeSingletons = TRUE`, only singletons with signal
-#'        `< keepSingletonsAbove` will be removed.  Useful to prevent removing
-#'        highly supported singleton tag clusters.  Default value `Inf` results
-#'        in removing all singleton TCs when `removeSingletons = TRUE`.
-#'        
-#' @param removeSingletons Logical indicating if tag clusters containing only
-#'        one CTSS be removed.
-#' 
-#' @param keepSingletonsAbove Controls which singleton tag clusters will be
-#'        removed.  When `removeSingletons = TRUE`, only singletons with signal
-#'        `< keepSingletonsAbove` will be removed.  Useful to prevent removing
-#'        highly supported singleton tag clusters.  Default value `Inf` results
-#'        in removing all singleton TCs when `removeSingletons = TRUE`.
+#' @param keepSingletonsAbove Remove "singleton" tag clusters of width 1 with
+#'        signal `< keepSingletonsAbove`.  Default value `0` results in keeping
+#'        all TCs by default.  Setting it to `Inf` removes all singletons.
 #'        
 #' @family CAGEr clustering methods
 #' 
@@ -42,14 +28,13 @@ setGeneric("distclu",
   function(
     object,
     max.dist = 20,
-    removeSingletons = FALSE,
-    keepSingletonsAbove = Inf
+    keepSingletonsAbove = 0
     ) standardGeneric("distclu"))
 
 #' @rdname distclu
 
 setMethod("distclu", "SummarizedExperiment",
-          function(object, max.dist, removeSingletons, keepSingletonsAbove) {
+          function(object, max.dist, keepSingletonsAbove) {
   ctss.cluster.list <- GRangesList()
   for(s in colnames(object)) {
     message("\t-> ", s)
@@ -58,16 +43,14 @@ setMethod("distclu", "SummarizedExperiment",
     d <- subset(d, score(d) > 0)
     ctss.cluster.list[[s]] <-
       distclu(d, max.dist = max.dist,
-                removeSingletons = removeSingletons,
                 keepSingletonsAbove = keepSingletonsAbove)
   }
   endoapply(ctss.cluster.list, as, "TagClusters")
 })
 
-.distclu_CTSS <- function(object, max.dist, removeSingletons, keepSingletonsAbove) {
+.distclu_CTSS <- function(object, max.dist, keepSingletonsAbove) {
   clusters <- reduce(GRanges(object), min = max.dist)
   clusters <- .ctss_summary_for_clusters(object, clusters,
-                                         removeSingletons    = removeSingletons,
                                          keepSingletonsAbove = keepSingletonsAbove)
   names(clusters) <- seq_along(clusters)
   as(clusters, "TagClusters")

R/GetMethods.R

@@ -544,7 +544,7 @@ setMethod( "consensusClustersGR", "CAGEexp"
     ctss <- CTSScoordinatesGR(object)
     score(ctss) <- CTSSnormalizedTpmDF(object) |> rowSums.RleDataFrame()
     ctss <- ctss[ctss$filteredCTSSidx]
-    cc <- .ctss_summary_for_clusters(ctss, cc, removeSingletons = FALSE)
+    cc <- .ctss_summary_for_clusters(ctss, cc)
     if (! is.null(qLow) & ! is.null(qUp)) {
       qLowName <- paste0("q_", qLow)
       qUpName  <- paste0("q_", qUp)

R/Paraclu.R

@@ -15,14 +15,9 @@
 #' @param maxLength Maximal length of cluster in base-pairs.  Clusters with length
 #'        `> maxLength` will be discarded.
 #' 
-#' @param removeSingletons Logical indicating if tag clusters containing only
-#'        one CTSS be removed.
-#' 
-#' @param keepSingletonsAbove Controls which singleton tag clusters will be
-#'        removed.  When `removeSingletons = TRUE`, only singletons with signal
-#'        `< keepSingletonsAbove` will be removed.  Useful to prevent removing
-#'        highly supported singleton tag clusters.  Default value `Inf` results
-#'        in removing all singleton TCs when `removeSingletons = TRUE`.
+#' @param keepSingletonsAbove Remove "singleton" tag clusters of width 1 with
+#'        signal `< keepSingletonsAbove`.  Default value `0` results in keeping
+#'        all TCs by default.  Setting it to `Inf` removes all singletons.
 #' 
 #' @param reduceToNonoverlapping Logical, should smaller clusters contained
 #'        within bigger cluster be removed to make a final set of tag clusters
@@ -47,8 +42,8 @@
 #' Running Paraclu on a `CTSS` object dispatches the computation on each strand
 #' of each sequence level of the object, collects the `IRanges` and assemble
 #' them back in a [`TagClusters`] object after filtering them by size and by
-#' expression following the `minStability`, `maxLength`, `removeSingletons`,
-#' `keepSingletonsAbove` and `reduceToNonoverlapping` parameters.
+#' expression following the `minStability`, `maxLength`, `keepSingletonsAbove`
+#' and `reduceToNonoverlapping` parameters.
 #' 
 #' Running Paraclu on a [`RangedSummarizedExperiment`] object will loop on each
 #' sample, and return the results as a [`GRangesList`] of `TagClusters`.
@@ -72,7 +67,7 @@
 setGeneric("paraclu",
   function( object
           , minStability = 1, maxLength = 500
-          , removeSingletons = FALSE, keepSingletonsAbove = Inf
+          , keepSingletonsAbove = 0
           , reduceToNonoverlapping = TRUE
           , useMulticore = FALSE, nrCores = NULL)
    standardGeneric("paraclu"))
@@ -116,7 +111,7 @@ setGeneric("paraclu",
 setMethod("paraclu", "Pairs",
   function( object
           , minStability = 1, maxLength = 500
-          , removeSingletons = FALSE, keepSingletonsAbove = Inf
+          , keepSingletonsAbove = 0
           , reduceToNonoverlapping = TRUE
           , useMulticore = FALSE, nrCores = NULL) {
   if (length(object) == 0) return(IRanges())
@@ -129,7 +124,7 @@ setMethod("paraclu", "Pairs",
 setMethod("paraclu", "CTSS",
   function( object
           , minStability = 1, maxLength = 500
-          , removeSingletons = FALSE, keepSingletonsAbove = Inf
+          , keepSingletonsAbove = 0
           , reduceToNonoverlapping = TRUE
           , useMulticore = FALSE, nrCores = NULL) {
   # Sort and remove null ranges
@@ -157,7 +152,6 @@ setMethod("paraclu", "CTSS",
   # Compute score and dominant CTSs, and remove singletons as wanted.
   clusters <-
     .ctss_summary_for_clusters( object, clusters
-                              , removeSingletons = removeSingletons
                               , keepSingletonsAbove = keepSingletonsAbove)
   # Reduce to non-overlapping as wanted
   if(reduceToNonoverlapping == TRUE){
@@ -178,12 +172,12 @@ setMethod("paraclu", "CTSS",
 setMethod("paraclu", "GRanges",
   function( object
           , minStability = 1, maxLength = 500
-          , removeSingletons = FALSE, keepSingletonsAbove = Inf
+          , keepSingletonsAbove = 0
           , reduceToNonoverlapping = TRUE
           , useMulticore = FALSE, nrCores = NULL) {
   stopifnot(all(width(object) == 1))
   paraclu( as(object, "CTSS"), minStability = minStability, maxLength = maxLength
-         , removeSingletons = removeSingletons, keepSingletonsAbove = keepSingletonsAbove
+         , keepSingletonsAbove = keepSingletonsAbove
          , reduceToNonoverlapping = reduceToNonoverlapping
          , useMulticore = useMulticore, nrCores = nrCores)
 })
@@ -193,7 +187,7 @@ setMethod("paraclu", "GRanges",
 setMethod("paraclu", "SummarizedExperiment",
   function( object
           , minStability = 1, maxLength = 500
-          , removeSingletons = FALSE, keepSingletonsAbove = Inf
+          , keepSingletonsAbove = 0
           , reduceToNonoverlapping = TRUE
           , useMulticore = FALSE, nrCores = NULL) {
 
@@ -205,7 +199,6 @@ setMethod("paraclu", "SummarizedExperiment",
     tag.cluster.list[[s]] <-
       paraclu( gr
              , minStability = minStability, maxLength = maxLength
-             , removeSingletons = removeSingletons
              , keepSingletonsAbove = keepSingletonsAbove
              , reduceToNonoverlapping = reduceToNonoverlapping
              , useMulticore = useMulticore, nrCores = nrCores)