Skip to content

Forge a BSgenome package from refgenie

Many Bioconductor tools take a reference genome as a BSgenome object, which comes from an installable data package such as BSgenome.Hsapiens.UCSC.hg38. Refgenie manages reference genomes and keeps the sequences of each one in a RefgetStore. BiocRefgetStore reads a refgenie genome from that store, and forgeBSgenome() builds a BSgenome data package from it. The package records the genome's refgenie digest, so you can always tell which genome it holds.

You need BiocRefgetStore and gtars (see the Getting started vignette) and BSgenomeForge:

BiocManager::install("BSgenomeForge")

RefgetGenome.from_refgenie() opens a genome that a refgenie server lists, by name. It asks the server (by default https://api.refgenie.org) for the genome's digest and for the public RefgetStore that holds it, then opens the genome from that store. This step downloads only metadata. To find a genome's name, browse refgenie.org; this example uses the yeast genome R64-1-1.

library(BiocRefgetStore)
genome <- RefgetGenome.from_refgenie("R64-1-1")
genome

Store data is cached under tools::R_user_dir("BiocRefgetStore", "cache"), in one folder per store. Pass cache_path to use another folder.

Now forge the package. Its name follows the BSgenome convention BSgenome.<organism>.<provider>.<build>, and each part may hold only letters and numbers, so R64-1-1 becomes R6411. List the circular sequences in circ_seqs; check seqnames(genome) for their names (Mito in this yeast genome, chrM in hg38).

pkg <- forgeBSgenome(genome, "BSgenome.Scerevisiae.refgenie.R6411",
organism = "Saccharomyces cerevisiae",
circ_seqs = "Mito", dest = tempdir())

Install and load it like any other source package:

install.packages(pkg, repos = NULL, type = "source")
library(BSgenome.Scerevisiae.refgenie.R6411)

The package exports a BSgenome object named after the second part of the package name:

Scerevisiae
getSeq(Scerevisiae, "Mito", 1, 60)

Refgenie keeps the sequences of the genomes it manages in <genome_folder>/.refget_store, and stores genome names there under the alias namespace "refgenie". The genome folder is ~/.refgenie/genomes unless you set REFGENIE_GENOME_FOLDER (see Configure refgenie).

genome <- RefgetGenome.from_directory("~/.refgenie/genomes/.refget_store",
namespace = "refgenie", alias = "R64-1-1")
pkg <- forgeBSgenome(genome, "BSgenome.Scerevisiae.refgenie.R6411",
organism = "Saccharomyces cerevisiae",
circ_seqs = "Mito", dest = tempdir())

This reads sequences from your disk. It works for a genome whose sequences refgenie loaded into the store, such as one initialized from a FASTA file with refgenie genome init --fasta. A genome registered from a server with refgenie genome init --server ... --no-build has only its metadata (names, lengths and digests) in the local store, so reading its sequences stops with an error saying the bases could not be loaded. Open that genome with RefgetGenome.from_refgenie() and the same name instead.

Refgenie identifies each genome by a digest computed from its sequences: its GA4GH sequence collection digest. collection_digest() returns it, and forgeBSgenome() records it as the package's genome field:

collection_digest(genome)
GenomeInfoDb::genome(Scerevisiae)[[1]]

Loading the package back into a RefgetStore recomputes the digest from the sequences themselves, and gives the same value:

collection_digest(RefgetGenome.from_bsgenome(Scerevisiae))

So the genome field of any forged package leads back to its refgenie genome. It is the digest that refgenie genome list shows, and the server describes the genome at https://api.refgenie.org/v4/genomes/<digest>; for this yeast genome, see refgenie.org/genomes/ia9g4Myony-xxLsSc7eQOC_NdClGgPGu.

Opening a genome downloads only metadata (about 40 KB for yeast). Forging downloads each sequence once and keeps it in the cache folder, writes the sequences to temporary FASTA files, and packs them into the package's .2bit file. Installing is a standard R CMD INSTALL.

GenomeSequencesBasesDownloadOpenForgeInstall
Yeast R64-1-1, measured1712.2 Mbp3.1 MB2.5 s6.2 s12.7 s
Human hg38, estimated1953.1 Gbp1.4 GB

The yeast numbers come from one run on one workstation with an empty cache. The hg38 row is an estimate, not a measurement: its download is the total size of its 195 sequence files in the public store, and its temporary FASTA files need about 3.1 GB of disk while forging. Its times were not measured.