% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/read.r
\name{read_bigwig}
\alias{read_bigwig}
\title{Read data from bigWig files.}
\usage{
read_bigwig(
  bwfile,
  chrom = NULL,
  start = NULL,
  end = NULL,
  as = NULL,
  fill = 0
)
}
\arguments{
\item{bwfile}{path or URL for a bigWig file. Remote files
(\verb{http://}, \verb{https://}, \verb{ftp://}) are supported when the package was
installed with libcurl available.}

\item{chrom}{chromosome(s) to read. Either a character vector of
chromosome names, or a \link[GenomicRanges:GRanges]{GenomicRanges::GRanges} of query regions (in
which case \code{start}/\code{end} are ignored; see Details).}

\item{start}{start position(s) for data. May be a vector, recycled
against \code{chrom}/\code{end} to describe several ranges.}

\item{end}{end position(s) for data. May be a vector, recycled
against \code{chrom}/\code{start} to describe several ranges.}

\item{as}{return data as a specific type. One of \code{"tbl"} (the default
tibble), \code{"GRanges"}, or \code{"Rle"}. \code{"Rle"} returns a per-base
run-length-encoded vector spanning the requested range (see Details).}

\item{fill}{value used for bases with no data when \code{as = "Rle"}.
Defaults to \code{0} (the convention for coverage); use \code{NA} to mark
uncovered bases as missing. Ignored for other \code{as} values.}
}
\value{
A \code{tibble}, \code{GRanges}, or \code{Rle}/\code{RleList} depending on \code{as}.
}
\description{
Read data from bigWig files.
}
\details{
Multiple ranges can be queried in one call by passing equal-length
(or length-1, recycled) \code{chrom}, \code{start}, and \code{end} vectors, where
range \code{i} is \verb{(chrom[i], start[i], end[i])}. Alternatively, pass a
\link[GenomicRanges:GRanges]{GenomicRanges::GRanges} as \code{chrom}; its regions are used directly.
Because \code{GRanges} is 1-based and inclusive while bigWig is 0-based and
half-open, a region is converted as \code{start(gr) - 1} to \code{end(gr)}.

When \code{as = "Rle"}, the result is an \link[S4Vectors:Rle]{S4Vectors::Rle} whose expanded
length equals the queried range, i.e. \code{end - start} when both are
supplied, otherwise the extent of the returned data for each
chromosome. Bases with no data in the file are set to \code{fill}. bigWig
coordinates are 0-based and half-open, so element \code{i} corresponds to
genomic position \code{start + i - 1}. A single-range query returns a bare
\code{Rle}; a multi-range (or multi-chromosome) query returns a named
\link[IRanges:RleList]{IRanges::RleList} with one element per range.
}
\examples{
bw <- system.file("extdata", "test.bw", package = "cpp11bigwig")

read_bigwig(bw)

read_bigwig(bw, chrom = "10")

read_bigwig(bw, chrom = "1", start = 100, end = 130)

read_bigwig(bw, as = "GRanges")

read_bigwig(bw, chrom = "1", start = 100, end = 130, as = "Rle")

# query several ranges in one call with equal-length vectors
read_bigwig(bw, chrom = c("1", "10"), start = c(0, 0), end = c(50, 50))

# multiple windows on the same chromosome (chrom recycles)
read_bigwig(bw, chrom = "1", start = c(0, 100), end = c(50, 130))

# a multi-range "Rle" query returns a named RleList, one element per range
read_bigwig(bw, chrom = "1", start = c(0, 100), end = c(50, 130), as = "Rle")

# pass a GRanges of regions; 1-based coords are converted automatically
gr <- GenomicRanges::GRanges(
  c("1", "10"),
  IRanges::IRanges(start = c(1, 1), end = c(50, 50))
)
read_bigwig(bw, chrom = gr)

}
\seealso{
\url{https://github.com/dpryan79/libBigWig}

\url{https://github.com/brentp/bw-python}
}
