Written and maintained by CASRAI Editorial Board
Published · Last updated
On this page
bsseq is a Bioconductor package for R that stores, smooths, tests and plots whole-genome DNA methylation data from sequencing. The Bioconductor page describes it as “A collection of tools for analyzing and visualizing whole-genome methylation data from sequencing. This includes whole-genome bisulfite sequencing and Oxford nanopore data.” This page is for lab and computational biology researchers who already have per-CpG methylated and total read counts (for example from a Bismark run) and need to get from those counts to a table of differentially methylated regions (DMRs). Facts below were read from the package’s Bioconductor page and vignettes on 2026-11-08 (release 1.48.0, Bioconductor 3.23).
What bsseq is used for in research
bsseq does not align reads. The User’s Guide states that the package contains no alignment software; you align bisulfite reads elsewhere, then load per-locus counts into a BSseq object. From there it supports three jobs, all concerned with epigenetic methylation marks:
- Managing methylation data: a
BSseqobject holds width-1 loci as aGRanges, with a methylated-read matrixMand a total-coverage matrixCov(rows are loci, columns are samples) and sample metadata inpData(). - Smoothing and testing:
BSmooth()smooths methylation along the genome;BSmooth.tstat()computes a t-statistic between two groups;dmrFinder()turns the statistic into candidate DMRs. - Visualising:
plotRegion()andplotManyRegions()draw smoothed methylation around regions of interest.
The smoother is the BSmooth method from Hansen, Langmead and Irizarry (2012, Genome Biology), which the package’s vignette asks users to cite.
When bsseq fits, and when it does not
| Situation | What the documentation says |
|---|---|
| Whole-genome bisulfite sequencing (WGBS) | The use case BSmooth was designed for. |
| Standard capture bisulfite experiment | The User’s Guide warns that BSmooth is designed for whole-genome data and may not be useful here. |
| Raw FASTQ files | Not supported: the package has no aligner, so align first. |
| Oxford Nanopore methylation data | Listed on the Bioconductor page as supported data; see also the CASRAI guide to Oxford Nanopore sequencing. |
How to install or access it
bsseq is distributed through Bioconductor under the Artistic-2.0 license. Kasper Daniel Hansen is author and maintainer, with Peter Hickey as author. The release page lists R (>= 4.0) as a dependency and a C++17 system requirement. Install with:
if (!require("BiocManager", quietly = TRUE))
install.packages("BiocManager")
BiocManager::install("bsseq")
Bioconductor releases are tied to R versions, so check the R version that the release page names for your Bioconductor release. The package depends on methods, BiocGenerics, GenomicRanges and SummarizedExperiment, and imports packages including limma, DelayedArray, DelayedMatrixStats, BiocParallel, HDF5Array, rhdf5 and data.table. To open the documentation after installing, run browseVignettes("bsseq"). The two vignettes are “Analyzing WGBS data with bsseq” and “bsseq User’s Guide”.
Step-by-step: from counts to differentially methylated regions
This sequence follows the package’s own worked example, which uses the bsseqData companion package (three cancer and three normal samples, chromosomes 21 and 22). In your own project, replace the example object with data you load yourself (step 1).
- Load your data into a BSseq object. For Bismark output use
read.bismark(bismarkfiles, BACKEND="HDF5Array", BPPARAM=MulticoreParam(workers=10)). The guide notes that HDF5-backed construction from Bismark input is supported and that using more workers than input files gives no benefit. Other readers includeread.bsmooth()(BSmooth alignment suite output, base-quality cutoff 20) and the legacyread.umtab()andread.umtab2(). If you already hold per-locus counts, build the object directly:BSseq(chr=c("chr1","chrX","chr1"), pos=1:3, M=M, Cov=Cov, sampleNames=c("A1","A2","B")), or pass aGRangesasgr=instead ofchrandpos. - Add sample metadata. Group labels live in
pData(); the example uses aTypecolumn with values “cancer” and “normal”. - Smooth.
BSmooth(BSseq, BPPARAM=MulticoreParam(workers=10)). The run prints its parameters, for exampleBSmooth (ns = 70, h = 1000, maxGap = 100000000). Parallelism can be set by sample or by chromosome (parallelBy). The worked example loads a precomputed result withdata(BS.cancer.ex.fit). - Filter low-coverage loci. The example keeps loci with coverage of at least 2 in at least 2 samples of each group:
BS.cov <- getCoverage(BS.cancer.ex.fit) keepLoci.ex <- which(rowSums(BS.cov[, BS.cancer.ex$Type=="cancer"] >= 2) >= 2 & rowSums(BS.cov[, BS.cancer.ex$Type=="normal"] >= 2) >= 2) BS.cancer.ex.fit <- BS.cancer.ex.fit[keepLoci.ex,]This leaves 597,371 loci in the example data.
- Compute the t-statistic.
BS.cancer.ex.tstat <- BSmooth.tstat(BS.cancer.ex.fit, group1=c("C1","C2","C3"), group2=c("N1","N2","N3"), estimate.var="group2", local.correct=TRUE, verbose=TRUE)The statistic is group1 minus group2. The vignette sets
estimate.var="group2"because cancer samples are more variable than normal ones, andlocal.correct=TRUEapplies a large-scale mean correction. - Find DMRs.
dmrs0 <- dmrFinder(BS.cancer.ex.tstat, cutoff=c(-4.6, 4.6)), thendmrs <- subset(dmrs0, n >= 3 & abs(meanDiff) >= 0.1). The example cutoff of ±4.6 was chosen from quantiles of the genome-wide t-statistics, and the filtered result has 362 DMRs. - Plot and inspect. Colour samples by group, then draw the top region with its neighbourhood:
pData(BS.cancer.ex.fit)$col <- rep(c("red","blue"), each=3) plotRegion(BS.cancer.ex.fit, dmrs[1,], extend=5000, addRegions=dmrs)The vignette stresses that DMRs should always be inspected visually.
- Save large objects. HDF5-backed objects are saved with
saveHDF5SummarizedExperiment(), which writesassays.h5andse.rds, and reloaded withloadHDF5SummarizedExperiment().
Output and how to read it
dmrFinder() returns a table with one row per candidate region. The worked example lists these columns: chr, start, end, idxStart, idxEnd, cluster, n, width, invdensity, areaStat, maxStat, meanDiff, group1.mean, group2.mean, tstat.sd and direction.
| Column | How the vignette uses it |
|---|---|
n |
Number of CpGs in the region; the example keeps regions with n >= 3. |
areaStat |
Sum of the t-statistics across the region; used to rank DMRs. |
meanDiff |
Methylation difference between the groups; the example keeps abs(meanDiff) >= 0.1. |
group1.mean, group2.mean |
Mean methylation in each group. |
direction |
Hyper or hypo, as relative to group1 minus group2. |
Two filters shape the result: the coverage filter in step 4 decides which loci can contribute, and the n >= 3 and abs(meanDiff) >= 0.1 subset in step 6 decides which candidate regions are kept. Both are choices the vignette makes for its example data, so record your own thresholds in your methods section. Rank by areaStat, then look at the plots before reporting a region. For a targeted, single-locus methylation assay rather than genome-wide profiling, see the CASRAI guide to pyrosequencing.
Troubleshooting
| Problem | What the documentation supports |
|---|---|
| Memory pressure on large WGBS projects | Build the object with an HDF5 backend (BACKEND="HDF5Array" in read.bismark()) so assays are disk-backed. |
| Slow smoothing or loading | Use BPPARAM=MulticoreParam(workers=...); for read.bismark(), workers beyond the number of files do not help. |
BSmooth.tstat() does not find your groups |
In the example, group1 and group2 are given as sample names such as “C1” and “N1”; use the names stored in your object. |
| Stored object from an older release behaves oddly | The worked example calls updateObject() on a stored object before use. |
| Poor results on capture data | See the vignette warning above: BSmooth targets whole-genome data. |
Free alternatives
These are other Bioconductor packages for bisulfite-sequencing analysis. The descriptions are each package’s own tagline on its Bioconductor page, read 2026-11-08. Compare each package’s vignette against your design; this page does not rank them.
| Package | Bioconductor description |
|---|---|
| dmrseq | Detection and inference of differentially methylated regions from Whole Genome Bisulfite Sequencing. |
| methylKit | DNA methylation analysis from high-throughput bisulfite sequencing results. |
| DSS | Dispersion shrinkage for sequencing data. |
FAQ
What does bsseq do?
It is the Bioconductor package for analysing bisulfite-sequencing methylation data in R: it manages per-CpG counts, smooths them, tests two groups and plots regions.
Does bsseq align reads?
No. The documentation states the package contains no alignment software. Align first, then import counts with read.bismark() or another reader.
Can it handle large genomes?
The User’s Guide describes HDF5-backed objects (via HDF5Array) for Bismark input, which keeps data on disk rather than in memory.
Which statistic ranks the DMRs?
The worked example ranks by areaStat, the sum of t-statistics across the region.
How do I cite it?
The vignette asks users to cite Hansen KD, Langmead B, Irizarry RA, the BSmooth paper in Genome Biology (2012). Also report the Bioconductor release and package version you used.
Sources
- Bioconductor, bsseq package page (version 1.48.0, Bioconductor 3.23), read 2026-11-08.
- Bioconductor, bsseq User’s Guide, read 2026-11-08.
- Bioconductor, Analyzing WGBS data with bsseq, read 2026-11-08.
- Bioconductor package pages for dmrseq, methylKit and DSS, read 2026-11-08.







