Getting Started with SuperIntervals

Introduction

SuperIntervals provides fast interval intersection queries. This is particularly useful for genomic analysis, time series data, and any application requiring efficient range-based lookups.

Coordinates include both endpoints. Constructors require whole numbers in the R integer range, excluding missing values. Search indices refer to internal start-sorted order; hit order is unspecified. Maps mutate by reference and cannot be restored from serialized external pointers. Query functions assume valid inputs and a current index, without checking those conditions on each call.

Basic Usage

library(superintervalsr)

Creating and Building an IntervalMap

# Create a new IntervalMap
imap <- IntervalMap(c(10, 15, 30),
                        ends = c(20, 25, 40),
                        values = c("Gene A", "Gene B", "Gene C"))

Alternatively data can be added sequentially, followed by calling build():

# Create a new IntervalMap
imap <- IntervalMap()

# Add some intervals with associated values
add(imap, 10, 20, "Gene A")
add(imap, 15, 25, "Gene B")
add(imap, 30, 40, "Gene C")

# Build the index (required before queries)
build(imap)

Searching for Overlaps

# Find all values that overlap with range 12-18
values <- search_values(imap, 12, 18)
print(values)
#> [[1]]
#> [1] "Gene B"
#> 
#> [[2]]
#> [1] "Gene A"

# Get the intervals (start, end) that overlap
keys <- search_keys(imap, 12, 18)
print(keys)
#> $start
#> [1] 15 10
#> 
#> $end
#> [1] 25 20

# Get complete information (start, end, value)
items <- search_items(imap, 12, 18)
print(items)
#> $start
#> [1] 15 10
#> 
#> $end
#> [1] 25 20
#> 
#> $value
#> $value[[1]]
#> [1] "Gene B"
#> 
#> $value[[2]]
#> [1] "Gene A"

# Find all indices that overlap with range 12-18
indices <- search_idxs(imap, 12, 18)
print(indices)
#> [1] 2 1

Query Statistics

# Check if any intervals overlap a range
has_overlaps(imap, 5, 12)
#> [1] TRUE
has_overlaps(imap, 50, 60)
#> [1] FALSE

# Count overlapping intervals
count(imap, 12, 18)
#> [1] 2

# Sum inclusive intersection widths (overlaps counted independently)
coverage(imap, 10, 40)
#> $count
#> [1] 3
#> 
#> $total_coverage
#> [1] 33

Accessing Individual Intervals

# Get interval at specific index
at(imap, 1)
#> $start
#> [1] 10
#> 
#> $end
#> [1] 20
#> 
#> $value
#> [1] "Gene A"

# Get just the start position
starts_at(imap, 1)
#> [1] 10

# Get just the end position
ends_at(imap, 1)
#> [1] 20

# Get just the value
data_at(imap, 1)
#> [1] "Gene A"

Set operations

All map-producing operations return already indexed maps:

merged <- merge_overlaps(imap)
search_keys(merged, 1, 50)
#> $start
#> [1] 30 10
#> 
#> $end
#> [1] 40 25
gaps(merged, 1, 50)
#> IntervalMap with 3 intervals
#>   [1] 1-9
#>   [2] 26-29
#>   [3] 41-50
expand(imap, 2, 2)
#> IntervalMap with 3 intervals
#>   [1] 8-22 -> Gene A
#>   [2] 13-27 -> Gene B
#>   [3] 28-42 -> Gene C
flank(imap, 2, 2)
#> IntervalMap with 6 intervals
#>   [1] 8-9 -> Gene A
#>   [2] 13-14 -> Gene B
#>   [3] 21-22 -> Gene A
#>   [4] 26-27 -> Gene B
#>   [5] 28-29 -> Gene C
#>   [6] 41-42 -> Gene C
unique_intervals(imap)
#> IntervalMap with 3 intervals
#>   [1] 10-20 -> Gene A
#>   [2] 15-25 -> Gene B
#>   [3] 30-40 -> Gene C
span(imap)
#> $start
#> [1] 10
#> 
#> $end
#> [1] 40

Adjacent intervals without an overlap remain separate when merging. Intersection and difference retain left-side values; merge and union select one representative value per merged region. Metadata ties are unspecified.

Performance Tips

Call build() after adding all intervals and before performing queries
Use reserve() if you know the number of intervals in advance
The IntervalMap is optimized for many queries on the same set of intervals

Use Cases

SuperIntervals is ideal for:

Genomics: Finding genes/features overlapping genomic regions
Time series: Querying events within time ranges
Spatial analysis: Range-based spatial queries
Data analysis: Any scenario requiring fast interval overlap detection

Session Information

sessionInfo()
#> R version 4.6.1 (2026-06-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.04.1 LTS
#> 
#> Matrix products: default
#> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so;  LAPACK version 3.12.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> time zone: Etc/UTC
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] superintervalsr_0.99.7 rmarkdown_2.32        
#> 
#> loaded via a namespace (and not attached):
#>  [1] cli_3.6.6            knitr_1.52           rlang_1.3.0         
#>  [4] xfun_0.61            otel_0.2.0           generics_0.1.4      
#>  [7] jsonlite_2.0.0       S4Vectors_0.51.10    buildtools_1.0.0    
#> [10] htmltools_0.5.9      maketools_1.3.2      sys_3.4.3           
#> [13] sass_0.4.10          stats4_4.6.1         Seqinfo_1.3.2       
#> [16] evaluate_1.0.5       jquerylib_0.1.4      fastmap_1.2.0       
#> [19] yaml_2.3.12          IRanges_2.47.5       lifecycle_1.0.5     
#> [22] compiler_4.6.1       Rcpp_1.1.2           digest_0.6.39       
#> [25] R6_2.6.1             GenomicRanges_1.65.4 bslib_0.12.0        
#> [28] tools_4.6.1          BiocGenerics_0.59.12 cachem_1.1.0