Skip to content

overlaps with character arguments as seqlevels? #52

Open

Description

@LTLA

I was recently in the situation where I needed to write some code that would detect whether a GRanges or GRangesList contained elements on a particular chromosome. Well, no problem, I'll just look at the seqnames:

example(GenomicRanges, echo=FALSE)
as.logical(seqnames(gr) %in% "chr1")
##  [1] FALSE FALSE FALSE FALSE  TRUE  TRUE FALSE FALSE FALSE FALSE

So far so good. But then I realized that the same approach would not work properly for GRangesLists:

set.seed(10)
grl <- split(gr, sample(3, length(gr), replace=TRUE))
seqnames(grl) %in% "chr1"
## RleList of length 3
## $`1`
## logical-Rle of length 1 with 1 run
##   Lengths:     1
##   Values : FALSE
## 
## $`2`
## logical-Rle of length 2 with 2 runs
##   Lengths:     1     1
##   Values : FALSE  TRUE
## 
## $`3`
## logical-Rle of length 7 with 3 runs
##   Lengths:     2     1     4
##   Values : FALSE  TRUE FALSE

Which breaks the GRanges* abstraction that I was hoping to use. As such, I need to write GRanges and GRangesList-specific code to check whether the entries contain any intervals in my desired chromosome - not great.

However, it occurred to me that an elegant solution would be to repurpose overlapsAny(), which always returns a logical vector. To wit, the following gives me the desired result for both objects:

chr1 <- GRanges("chr1:1-1000")
overlapsAny(gr, chr1)
##  [1] FALSE FALSE FALSE FALSE  TRUE  TRUE FALSE FALSE FALSE FALSE
overlapsAny(grl, chr1)
## [1] FALSE  TRUE  TRUE

The above is not quite perfect as it still requires us to construct chr1, which requires knowledge of the range of entries on chromosome 1. A user-friendlier version of the above would allow us to just do:

overlapsAny(gr, "chr1")
overlapsAny(grl, "chr1")

To achieve the same effect. This would simply require new methods for GRanges(List),character, with the understanding that all character arguments are interpreted as seqlevels by the GenomicRanges overlap infrastructure.

Activity

  1. hpages commented on Sep 2, 2026

    @hpages
    Contributor

    Sorry for not getting to this earlier.

    Yeah, the proposal has some appeal. Seems incomplete though:

    library(GenomicRanges)
    
    gr <- GRanges(c("chr3:15-20", "chr2:1-10"), seqinfo=Seqinfo(c("chr1", "chr2", "chr3")))
    
    gr
    # GRanges object with 2 ranges and 0 metadata columns:
    #       seqnames    ranges strand
    #          <Rle> <IRanges>  <Rle>
    #   [1]     chr3     15-20      *
    #   [2]     chr2      1-10      *
    #   -------
    #   seqinfo: 3 sequences from an unspecified genome; no seqlengths
    
    grl <- GRangesList(gr, gr[1])
    
    findOverlaps(gr, seqlevels(gr))
    # Hits object with 2 hits and 0 metadata columns:
    #       queryHits subjectHits
    #       <integer>   <integer>
    #   [1]         1           3
    #   [2]         2           2
    #   -------
    #   queryLength: 2 / subjectLength: 3
    
    findOverlaps(grl, seqlevels(grl))
    # Hits object with 3 hits and 0 metadata columns:
    #            from        to
    #       <integer> <integer>
    #   [1]         1         3
    #   [2]         1         2
    #   [3]         2         3
    #   -------
    #   nLnode: 2 / nRnode: 3
    
    countOverlaps(gr, "chr2")
    # Error: unable to find an inherited method for function ‘countOverlaps’ for signature ‘query = "GRanges", subject = "character"’
    
    countOverlaps(grl, "chr2")
    # Error: unable to find an inherited method for function ‘countOverlaps’ for signature ‘query = "CompressedGRangesList", subject = "character"’
    
    overlapsAny(gr, "chr2")
    # Error: unable to find an inherited method for function ‘overlapsAny’ for signature ‘query = "GRanges", subject = "character"’
    
    overlapsAny(grl, "chr2")
    # Error: unable to find an inherited method for function ‘overlapsAny’ for signature ‘query = "CompressedGRangesList", subject = "character"’
    
    subsetByOverlaps(gr, "chr2")
    # Error: unable to find an inherited method for function ‘subsetByOverlaps’ for signature ‘x = "GRanges", ranges = "character"’
    
    subsetByOverlaps(grl, "chr2")
    # Error: unable to find an inherited method for function ‘subsetByOverlaps’ for signature ‘x = "CompressedGRangesList", ranges = "character"’

    IIRC it should be enough to make countOverlaps() work to get overlapsAny() and subsetByOverlaps() for free, but it's been a long time since I worked on findOverlaps & family so you might want to double check that.

    Note that if you just want to know whether a GRanges or GRangesList contains elements on a particular chromosome, you can simply use seqlevelsInUse():

    seqlevels(gr)
    # [1] "chr1" "chr2" "chr3"
    
    seqlevels(grl)
    # [1] "chr1" "chr2" "chr3"
    
    seqlevelsInUse(gr)
    # [1] "chr2" "chr3"
    
    seqlevelsInUse(grl)
    # [1] "chr2" "chr3"

    The following is equivalent to doing any(overlapsAny(gr, "chr2")) and any(overlapsAny(grl, "chr2")) but is going to be MUCH more efficient:

    "chr2" %in% seqlevelsInUse(gr)
    # [1] TRUE
    
    "chr2" %in% seqlevelsInUse(grl)
    # [1] TRUE
  2. LTLA commented on Sep 4, 2026

    @LTLA
    Author

    Methods added:

    library(GenomicRanges)
    
    gr <- GRanges(c("chr3:15-20", "chr2:1-10"), seqinfo=Seqinfo(c("chr1", "chr2", "chr3")))
    grl <- GRangesList(gr, gr[1])
    
    findOverlaps(gr, seqlevels(gr))
    ## Hits object with 2 hits and 0 metadata columns:
    ##       queryHits subjectHits
    ##       <integer>   <integer>
    ##   [1]         1           3
    ##   [2]         2           2
    ##   -------
    ##   queryLength: 2 / subjectLength: 3
    
    findOverlaps(grl, seqlevels(grl))
    ## Hits object with 3 hits and 0 metadata columns:
    ##            from        to
    ##       <integer> <integer>
    ##   [1]         1         3
    ##   [2]         1         2
    ##   [3]         2         3
    ##   -------
    ##   nLnode: 2 / nRnode: 3
    
    countOverlaps(gr, "chr2")
    ## [1] 0 1
    
    countOverlaps(grl, "chr2")
    ## [1] 1 0
    
    overlapsAny(gr, "chr2")
    ## [1] FALSE  TRUE
    
    overlapsAny(grl, "chr2")
    ## [1]  TRUE FALSE
    
    subsetByOverlaps(gr, "chr2")
    ## GRanges object with 1 range and 0 metadata columns:
    ##       seqnames    ranges strand
    ##          <Rle> <IRanges>  <Rle>
    ##   [1]     chr2      1-10      *
    ##   -------
    ##   seqinfo: 3 sequences from an unspecified genome; no seqlengths
    
    subsetByOverlaps(grl, "chr2")
    ## GRangesList object of length 1:
    ## [[1]]
    ## GRanges object with 2 ranges and 0 metadata columns:
    ##       seqnames    ranges strand
    ##          <Rle> <IRanges>  <Rle>
    ##   [1]     chr3     15-20      *
    ##   [2]     chr2      1-10      *
    ##   -------
    ##   seqinfo: 3 sequences from an unspecified genome; no seqlengths

    Unfortunately these weren't automatic, as the existing methods dispatch on Vector,Vector and character doesn't fit the bill. Possibly this could be relaxed to ANY,ANY in IRanges but that's beyond the scope of this PR.

    Also worth noting that I explicitly don't consider minoverlap= or certain types of type= in my PR. It could be made to work, but this would require checking the seqlengths and it becomes significantly more complicated.

    As for seqlevelsInUse(), the OSCA use case is closer to which(overlapsAny(gr, "chrM")), as we need to know which rows of the SCE correspond to mitochondrial genes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions