Genome Interval Arithmetic in R

Read and manipulate genome intervals and signals. Provides functionality similar to command-line tool suites within R, enabling interactive analysis and visualization of genome-scale data.

BuildStatus AppVeyor BuildStatus CoverageStatus DOI

The valr package provides tools to read and manipulate genome intervals and signals, similar to the BEDtools suite. valr enables analysis in the R/RStudio environment, leveraging modern R tools in the tidyverse for a terse, expressive syntax. Compute-intensive algorithms are implemented in Rcpp/C++, and many methods take advantage of the speed and grouping capability provided by dplyr. See vignette(valr) for more details.


The latest stable version can be installed from CRAN:


The latest development version can be installed from github:

# install.packages("devtools")

valr Example

Functions in valr have similar names to their BEDtools counterparts, and so will be familiar to users coming from the BEDtools suite. Unlike other tools that wrap BEDtools and write temporary files to disk, valr tools run natively in memory. Similar to pybedtools, valr has a terse syntax:

snps <- read_bed(valr_example('hg19.snps147.chr22.bed.gz'), n_fields = 6)
genes <- read_bed(valr_example('genes.hg19.chr22.bed.gz'), n_fields = 6)
# find snps in intergenic regions
intergenic <- bed_subtract(snps, genes)
# find distance from intergenic snps to nearest gene
nearby <- bed_closest(intergenic, genes)
nearby %>%
  select(starts_with('name'), .overlap, .dist) %>%
  filter(abs(.dist) < 5000)
#> # A tibble: 1,047 x 4
#>    name.x      name.y   .overlap .dist
#>    <chr>       <chr>       <int> <int>
#>  1 rs530458610 P704P           0  2579
#>  2 rs2261631   P704P           0  -268
#>  3 rs570770556 POTEH           0  -913
#>  4 rs538163832 POTEH           0  -953
#>  5 rs190224195 POTEH           0 -1399
#>  6 rs2379966   DQ571479        0  4750
#>  7 rs142687051 DQ571479        0  3558
#>  8 rs528403095 DQ571479        0  3309
#>  9 rs555126291 DQ571479        0  2745
#> 10 rs5747567   DQ571479        0 -1778
#> # ... with 1,037 more rows


valr 0.5.0

Major changes

  • Internal Rcpp functions have been reorganized to remove all dependencies on dplyr C++ functions.

Minor changes

  • Due to internal refactoring of Rcpp functions, only data.frames containing Numeric, Logical, Integer, Character, and List column types are supported. Columns containing Raw, Complex, or other R classes are not supported and will issue an error.

  • Factors are now disallowed from grouping variables in multiset operations to avoid sort order discrepancies, and compatibility with factor handling in dplyr v.0.8.0. Factors will now be internally type-converted to character and a warning is issued.

valr 0.4.2

Bug fixes

  • Changed the behavior of as.tbl_interval() to call as_tibble() only on non-tibble input, which prevents groups from being stripped from tibble() input (#338).

valr 0.4.1

  • Added new function, bed_partition(), which is similar to bed_merge() but collapses intervals to elemental intervals rather than the maximal overlapping region. bed_partition() also can compute summaries of data from overlapping intervals. See examples in bed_partition() and timings in vignette('benchmarks') @kriemo.

  • Several explicit comparisons to the Bioconductor GenomicRanges library are included for users considering using valr. See examples in as.tbl_interval() and timings in vignette('benchmarks').

valr 0.4.0

Minor changes

  • All relevant tests from bedtool2 were ported into valr. Bugs identified in corner cases by new tests were fixed (#328 @raysinesis)

  • bed_jaccard() now works with grouped inputs (#216)

  • Update dplyr header files to v0.7

  • bed_intersect() and internal intersect_impl were refactored to enable return of non-intersecting intervals.

  • The genome argument to bed_makewindows() was deprecated and will produce a warning if used. Also error handling was added to check and warn if there are intervals smaller than the requested window size in makewindows_impl() (#312 @kriemo)

Bug fixes

  • Fixed off by one error in reported distances from bed_closest(). Distances reported now are the same as bedtools closest behavior (#311).

  • bed_glyph() accepts trbl_intervals named other than x and y (#318).

  • bed_makewindows() now returns the number of windows specified by num_win when the input intervals are not evenly divisble into num_win, consistent with bedtools behavior.

  • The output of findOverlaps() is now sorted in subtract_impl() to prevent reporting intervals that should have been dropped when calling bed_subtract() (#316 @kriemo)

valr 0.3.1


  • A manuscript describing valr has been published in F1000Research.

  • New S3 generic as.tbl_interval() converts GenomicRanges::GRanges objects to tbl_interval.

  • New create_tss() for creating transcription start sites.

  • Improve documentation of interval statistics with more complex examples.

Minor changes

  • bed_sort() has been de-deprecated to reduce arrange calls in library code.

Bug fixes

  • bed_merge() now reports start/end columns if spec is provided (#288)

valr 0.3.0


  • New create_introns(), create_utrs5() and create_utrs3() functions for generating features from BED12 files.

  • Speed-ups in bed_makewindows() (~50x), bed_merge() (~4x), and bed_flank() (~4x) (thanks to @kriemo and @sheridar). Thanks to the sponsors of the Biofrontiers Hackathon for the caffeine underlying these improvements.

Bug fixes

  • intervals from bed_random() are now sorted properly.

valr 0.2.0

Major changes

  • Package dplyr v0.5.0 headers with valr to remove dplyr LinkingTo dependency.

  • bed_intersect() now accepts multiple tbls for intersection (#220 @kriemo).

  • new tbl_interval() and tbl_genome() that wrap tibbles and enforce strict column naming. trbl_interval() and trbl_genome() are constructors that take tibble::tribble() formatting and is.tbl_interval() and is.tbl_genome() are used to check for valid classes.

Minor changes

  • intervals returned from bed_random() are sorted by chrom and start by default.

Bug fixes

  • Merge intervals in bed_jaccard() and use numeric values for calculation (fixes #204).

valr 0.1.2

Major changes

  • Deprecate bed_sort() in favor of using dplyr::arrange() explicitly (fixes #134).

Minor changes

  • add src/init.c that calls R_registerRoutines and R_useDynamicSymbols to address NOTE in r-devel

  • Deprecate dist parameter in bed_closest() in favor of using user supplied functions (#182 @kriemo)

  • Make .id values sequential across chroms in bed_cluster() output (#171)

  • Transfer repository to, update links and docs.

  • Move shiny app to new repo (

  • Add Kent Riemondy to LICENSE file.

Bug fixes

  • bed_merge() now merges contained intervals (#177)

valr 0.1.1

Minor changes

  • test / vignette guards for Suggested RMySQL

  • fixed memory leak in absdist.cpp

  • fixed vignette entry names

valr 0.1.0

Major changes

  • initial release on CRAN

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


0.5.0 by Jay Hesselberth, a year ago,

Report a bug at

Browse source code at

Authors: Jay Hesselberth [aut, cre] , Kent Riemondy [aut]

Documentation:   PDF Manual  

MIT + file LICENSE license

Imports dplyr, rlang, readr, stringr, tibble, broom, ggplot2

Suggests knitr, rmarkdown, testthat, microbenchmark, covr, curl, RMySQL, purrr, tidyr, devtools, DT, cowplot, dbplyr, GenomicRanges, IRanges, S4Vectors

Linking to Rcpp

System requirements: C++11

See at CRAN