feat: count and filter overlaps

DESCRIPTION

@@ -52,7 +52,9 @@ Collate:
     'GroupedGInteractions-class.R'
     'anchor.R'
     'arrange.R'
+    'count-overlaps.R'
     'count.R'
+    'filter-overlaps.R'
     'filter.R'
     'find-overlaps.R'
     'flank.R'

NAMESPACE

@@ -15,7 +15,15 @@ S3method(arrange,GInteractions)
 S3method(as_ginteractions,data.frame)
 S3method(as_ginteractions,default)
 S3method(count,GInteractions)
+S3method(count_overlaps,GInteractions)
+S3method(count_overlaps,PinnedGInteractions)
+S3method(count_overlaps_directed,GInteractions)
+S3method(count_overlaps_directed,PinnedGInteractions)
 S3method(filter,GInteractions)
+S3method(filter_by_non_overlaps,GInteractions)
+S3method(filter_by_non_overlaps,PinnedGInteractions)
+S3method(filter_by_overlaps,GInteractions)
+S3method(filter_by_overlaps,PinnedGInteractions)
 S3method(find_overlaps,GInteractions)
 S3method(find_overlaps,PinnedGInteractions)
 S3method(find_overlaps_directed,GInteractions)
@@ -149,8 +157,10 @@ importFrom(GenomicRanges,GRanges)
 importFrom(GenomicRanges,granges)
 importFrom(IRanges,IRanges)
 importFrom(IRanges,ranges)
+importFrom(IRanges,subsetByOverlaps)
 importFrom(InteractionSet,GInteractions)
 importFrom(InteractionSet,anchors)
+importFrom(InteractionSet,countOverlaps)
 importFrom(InteractionSet,findOverlaps)
 importFrom(InteractionSet,regions)
 importFrom(S4Vectors,"first<-")
@@ -202,6 +212,10 @@ importFrom(plyranges,anchor_5p)
 importFrom(plyranges,anchor_center)
 importFrom(plyranges,anchor_end)
 importFrom(plyranges,anchor_start)
+importFrom(plyranges,count_overlaps)
+importFrom(plyranges,count_overlaps_directed)
+importFrom(plyranges,filter_by_non_overlaps)
+importFrom(plyranges,filter_by_overlaps)
 importFrom(plyranges,find_overlaps)
 importFrom(plyranges,find_overlaps_directed)
 importFrom(plyranges,flank_downstream)

R/count-overlaps.R

@@ -0,0 +1,137 @@
+#' Count overlaps between a query GInteractions and a GRanges
+#'
+#' @section Pinned `GInteractions`:  
+#' 
+#' When using `count_overlaps()` with a `PinnedGInteractions` object, 
+#' only the pinned anchors are used to check for overlap with `y`. 
+#' This is equivalent to specifying `use.region="both"` in 
+#' \code{\href{https://bioconductor.org/packages/release/bioc/vignettes/InteractionSet/inst/doc/interactions.html#27_Overlap_methods}{InteractionSet::countOverlaps()}}.
+#' 
+#' @param x A (Pinned)GInteractions object
+#' @param y A GRanges object
+#' @param maxgap,minoverlap See \code{?\link[GenomicRanges]{countOverlaps}} 
+#' in the \pkg{GenomicRanges} package for a description of these arguments
+#'
+#' @importFrom plyranges count_overlaps
+#' @importFrom plyranges count_overlaps_directed
+#' @importFrom InteractionSet countOverlaps
+#' 
+#' @return An integer vector of same length as x.
+#'
+#' @name ginteractions-count-overlaps
+#' 
+#' @examples
+#' gi <- read.table(text = "  
+#'     chr1 11 20 - chr1 21 30 + 
+#'     chr1 11 20 - chr1 51 55 + 
+#'     chr1 21 30 - chr1 51 55 + 
+#'     chr1 21 30 - chr2 51 60 +",  
+#'     col.names = c("seqnames1", "start1", "end1", "strand1", "seqnames2", "start2", "end2", "strand2")
+#' ) |> as_ginteractions() |> mutate(id = 1:4, type = 'gi')
+#' 
+#' gr <- GenomicRanges::GRanges(c("chr1:20-30:+", "chr2:55-65:-")) |> plyranges::mutate(id = 1:2, type = 'gr')
+#' 
+#' gi
+#' 
+#' gr
+#' 
+#' ####################################################################
+#' # 1. Count overlaps between GInteractions and a subject GRanges
+#' ####################################################################
+#' 
+#' count_overlaps(gi, gr)
+#' 
+#' count_overlaps_directed(gi, gr)
+#' 
+#' ####################################################################
+#' # 2. Count overlaps between PinnedGInteractions and a subject GRanges
+#' ####################################################################
+#' 
+#' gi |> pin_by("first") |> count_overlaps(gr)
+#' 
+#' gi |> pin_by("second") |> count_overlaps(gr)
+#' 
+#' gi |> pin_by("first") |> count_overlaps_directed(gr)
+#' 
+#' gi |> pin_by("second") |> count_overlaps_directed(gr)
+NULL
+
+#' @rdname ginteractions-count-overlaps
+#' @export
+count_overlaps.PinnedGInteractions <- function(
+    x, y, maxgap = -1L, minoverlap = 0L
+) {
+
+    InteractionSet::countOverlaps( 
+        query = unpin(x), 
+        subject = y, 
+        maxgap = maxgap, 
+        minoverlap = minoverlap,
+        type = 'any', 
+        ignore.strand = TRUE, 
+        use.region = switch(
+            as.character(pin(x)), 
+            "1" = "first",
+            "2" = "second"
+        )
+    )
+
+}
+
+#' @rdname ginteractions-count-overlaps
+#' @export
+count_overlaps.GInteractions <- function(
+    x, y, maxgap = -1L, minoverlap = 0L, suffix = c(".x", ".y")
+) {
+
+    InteractionSet::countOverlaps( 
+        query = x, 
+        subject = y, 
+        maxgap = maxgap, 
+        minoverlap = minoverlap,
+        type = 'any', 
+        ignore.strand = TRUE, 
+        use.region = 'both'
+    )
+
+}
+
+#' @rdname ginteractions-count-overlaps
+#' @export
+count_overlaps_directed.PinnedGInteractions <- function(
+    x, y, maxgap = -1L, minoverlap = 0L, suffix = c(".x", ".y")
+) {
+
+    InteractionSet::countOverlaps( 
+        query = unpin(x), 
+        subject = y, 
+        maxgap = maxgap, 
+        minoverlap = minoverlap,
+        type = 'any', 
+        ignore.strand = FALSE, 
+        use.region = switch(
+            as.character(pin(x)), 
+            "1" = "first",
+            "2" = "second"
+        )
+    )
+
+}
+
+#' @rdname ginteractions-count-overlaps
+#' @export
+count_overlaps_directed.GInteractions <- function(
+    x, y, maxgap = -1L, minoverlap = 0L, suffix = c(".x", ".y")
+) {
+
+    InteractionSet::countOverlaps( 
+        query = x, 
+        subject = y, 
+        maxgap = maxgap, 
+        minoverlap = minoverlap,
+        type = 'any', 
+        ignore.strand = FALSE, 
+        use.region = 'both'
+    )
+
+}

R/filter-overlaps.R

@@ -0,0 +1,139 @@
+#' Filter GInteractions overlapping with a GRanges
+#'
+#' @section Pinned `GInteractions`:  
+#' 
+#' When using `filter_by_overlaps()` with a `PinnedGInteractions` object, 
+#' only the pinned anchors are used to check for overlap with `y`. 
+#' This is equivalent to specifying `use.region="both"` in 
+#' \code{\href{https://bioconductor.org/packages/release/bioc/vignettes/InteractionSet/inst/doc/interactions.html#27_Overlap_methods}{InteractionSet::countOverlaps()}}.
+#' 
+#' @param x A (Pinned)GInteractions object
+#' @param y A GRanges object
+#' @param maxgap,minoverlap See \code{?\link[GenomicRanges]{countOverlaps}} 
+#' in the \pkg{GenomicRanges} package for a description of these arguments
+#'
+#' @importFrom plyranges filter_by_overlaps
+#' @importFrom plyranges filter_by_non_overlaps
+#' @importFrom IRanges subsetByOverlaps
+#' 
+#' @return An integer vector of same length as x.
+#'
+#' @name ginteractions-filter-overlaps
+#' 
+#' @examples
+#' gi <- read.table(text = "  
+#'     chr1 11 20 - chr1 21 30 + 
+#'     chr1 11 20 - chr1 51 55 + 
+#'     chr1 21 30 - chr1 51 55 + 
+#'     chr1 21 30 - chr2 51 60 +",  
+#'     col.names = c("seqnames1", "start1", "end1", "strand1", "seqnames2", "start2", "end2", "strand2")
+#' ) |> as_ginteractions() |> mutate(id = 1:4, type = 'gi')
+#' 
+#' gr <- GenomicRanges::GRanges(c("chr1:20-30:+", "chr2:55-65:-")) |> plyranges::mutate(id = 1:2, type = 'gr')
+#' 
+#' gi
+#' 
+#' gr
+#' 
+#' ####################################################################
+#' # 1. Filter GInteractions overlapping with a subject GRanges
+#' ####################################################################
+#' 
+#' filter_by_overlaps(gi, gr)
+#' 
+#' filter_by_non_overlaps(gi, gr)
+#' 
+#' ####################################################################
+#' # 2. Filter PinnedGInteractions overlapping with a subject GRanges
+#' ####################################################################
+#' 
+#' gi |> pin_by("first") |> filter_by_overlaps(gr)
+#' 
+#' gi |> pin_by("first") |> filter_by_non_overlaps(gr)
+#' 
+#' gi |> pin_by("second") |> filter_by_overlaps(gr)
+#' 
+#' gi |> pin_by("second") |> filter_by_non_overlaps(gr)
+NULL
+
+#' @rdname ginteractions-filter-overlaps
+#' @export
+filter_by_overlaps.PinnedGInteractions <- function(
+    x, y, maxgap = -1L, minoverlap = 0L
+) {
+
+    IRanges::subsetByOverlaps( 
+        unpin(x), 
+        y, 
+        maxgap = maxgap, 
+        minoverlap = minoverlap,
+        type = 'any', 
+        ignore.strand = TRUE, 
+        use.region = switch(
+            as.character(pin(x)), 
+            "1" = "first",
+            "2" = "second"
+        )
+    )
+
+}
+
+#' @rdname ginteractions-filter-overlaps
+#' @export
+filter_by_overlaps.GInteractions <- function(
+    x, y, maxgap = -1L, minoverlap = 0L, suffix = c(".x", ".y")
+) {
+
+    IRanges::subsetByOverlaps( 
+        x, 
+        y, 
+        maxgap = maxgap, 
+        minoverlap = minoverlap,
+        type = 'any', 
+        ignore.strand = TRUE, 
+        use.region = 'both'
+    )
+
+}
+
+#' @rdname ginteractions-filter-overlaps
+#' @export
+filter_by_non_overlaps.PinnedGInteractions <- function(
+    x, y, maxgap = -1L, minoverlap = 0L
+) {
+
+    IRanges::subsetByOverlaps( 
+        unpin(x), 
+        y, 
+        maxgap = maxgap, 
+        minoverlap = minoverlap,
+        type = 'any', 
+        ignore.strand = TRUE, 
+        use.region = switch(
+            as.character(pin(x)), 
+            "1" = "first",
+            "2" = "second"
+        ), 
+        invert = TRUE
+    )
+
+}
+
+#' @rdname ginteractions-filter-overlaps
+#' @export
+filter_by_non_overlaps.GInteractions <- function(
+    x, y, maxgap = -1L, minoverlap = 0L, suffix = c(".x", ".y")
+) {
+
+    IRanges::subsetByOverlaps( 
+        x, 
+        y, 
+        maxgap = maxgap, 
+        minoverlap = minoverlap,
+        type = 'any', 
+        ignore.strand = TRUE, 
+        use.region = 'both', 
+        invert = TRUE
+    )
+
+}

R/find-overlaps.R

@@ -1,13 +1,20 @@
 #' Find overlaps between a query GInteractions and a GRanges
 #'
-#' @details 
+#' @section Rationale:  
 #' 
 #' `find_overlaps()` will search for any overlap between `GInteractions` 
 #' in `x` and `GRanges` in `y`. It will return a `GInteractions` object of length 
 #' equal to the number of times `x` overlaps `y`. This `GInteractions` will 
 #' have additional metadata columns corresponding to the metadata from `y`. 
 #' `find_overlaps_directed()` takes the strandness of each object into account. 
 #' 
+#' @section Pinned `GInteractions`:  
+#' 
+#' When using `find_overlaps()` with a `PinnedGInteractions` object, 
+#' only the pinned anchors are used to check for overlap with `y`. 
+#' This is equivalent to specifying `use.region="both"` in 
+#' \code{\href{https://bioconductor.org/packages/release/bioc/vignettes/InteractionSet/inst/doc/interactions.html#27_Overlap_methods}{InteractionSet::findOverlaps()}}.
+#' 
 #' @param x A (Pinned)GInteractions object
 #' @param y A GRanges object
 #' @param maxgap,minoverlap See \code{?\link[GenomicRanges]{findOverlaps}} 
@@ -49,7 +56,7 @@
 #' find_overlaps_directed(gi, gr)
 #' 
 #' ####################################################################
-#' # 1. Find overlaps between PinnedGInteractions and a subject GRanges
+#' # 2. Find overlaps between PinnedGInteractions and a subject GRanges
 #' ####################################################################
 #' 
 #' gi |> pin_by("first") |> find_overlaps(gr)

_pkgdown.yml

@@ -37,6 +37,8 @@ reference:
 - title: "Overlapping GInteractions"
   contents: 
   - ginteractions-find-overlaps
+  - ginteractions-count-overlaps
+  - ginteractions-filter-overlaps
 - title: "Pinning GInteractions"
   contents: 
   - pin