Gem Version test dics DOI

Ruby bindings to lib2bit / py2bit.


gem install bio-twobit

Linux and macOS are supported. Windows is currently not supported.


Downlaod BSgenome.Hsapiens.UCSC.hg38


Quick Start

require 'bio/twobit'

hg38 ="hg38.2bit")

# "hg38.2bit"
# {"file_size"=>818064875,
# "nChroms"=>640,
# "sequence_length"=>3272116950,
# "hard_masked_length"=>161368694,
# "soft_masked_length"=>0}

# [["chr1", 248956422],
# ["chr2", 242193529],
# ["chr3", 198295559],
# ["chr4", 190214555],
# ["chr5", 181538259]]

Fetch a sequence

hg38.sequence("chr1", 50000, 50050)
  • The first number is the (0-based) position on the chromosome/contig where the sequence should begin.
  • The second number is the (1-based) position on the chromosome where the sequence should end.
hg38.bases("chr1", 10000, 10100)
# {"A"=>0.34, "C"=>0.49, "T"=>0.17, "G"=>0.0}

hg38.bases("chr1", 10000, 10100, fraction: false)
# {"A"=>34, "C"=>49, "T"=>17, "G"=>0}

# {"A"=>0.26940569141052323,
# "C"=>0.19302592242428676,
# "T"=>0.2701041550155312,
# "G"=>0.19325280952182064}

hg38.hard_masked_blocks("chr1", 0, 1000000)
# [[0, 10000], [207666, 257666], [297968, 347968], [535988, 585988]]

The 2-bit file must be closed explicitly. Alternatively, you can use a block. Even if it is not closed, it will probably be closed by GC and there will be no problem. But this is not guaranteed.

# Explicitly close the file.
tb ="test/fixtures/foo.2bit")

# You can also use blocks."test/fixtures/foo.2bit") do |t|
tb.closed? # true / false

If you would like to include information about soft-masked bases, you need to specify masked: true

tb ="test/fixtures/foo.2bit")
tb.sequence("chr1", 60, 72)

tb ="test/fixtures/foo.2bit", masked: true)
tb.sequence("chr1", 60, 72)
# => "GTagctagctGA"
# => [[62, 70]]
tb.masked? # true / false

hg19, hg38, hs1...

Some reference genomes are provided as classes in advance. These classes automatically download 2bit files from the UCSC site into a cache directory upon first use.

hg19 =
hg38 =
hs1  =

Adding a new reference genome is easy. Add here the id of the genome you want to use.

git clone
vi lib/bio/twobit/references/template.erb # Add your id to ids list.
ruby lib/bio/twobit/references/template.erb
rake install

If you want to use 2-bit files from locations other than UCSC, create your own classes here.

Pull requests are welcome.


Bug reports and pull requests are welcome on GitHub at

Do you need commit rights to my repository?
Do you want to get admin rights and take over the project?
If so, please feel free to contact us @kojix2.


The gem is available as open source under the terms of the MIT License.

Code from Red Datasets is used for automatic file download and caching. (The MIT license)