Skip to content

Refgenie

reference genome manager

Refgenie manages storage, access, and transfer of reference genome resources. It provides command-line and Python interfaces to download pre-built reference genome "assets", like indexes used by bioinformatics tools. It can also build assets for custom genome assemblies. Refgenie provides programmatic access to a standard genome folder structure, so software can swap from one genome to another.

  1. It downloads individual resources from the command line. Think of it as GitHub for reference genomes: refgenie pull hg38/bwa_index.

  2. It's scripted. If you need resources that are not on a server, such as for a custom genome, you can build your own: refgenie build custom_genome/bowtie2_index.

  3. It finds local asset locations. When you need a path to an asset, you seek it, so your pipelines are portable across computing environments: refgenie seek hg38/bowtie2_index.

  4. It works with remote files, which is useful for cloud applications. Get the URL of an asset file on a server without downloading it: refgenie seekr hg38/fasta.

  5. It includes a Python API. Tool developers use from refgenie import Refgenie to get paths to any genome asset from Python.

  6. It checks genome compatibility. You call genomes by names like "hg38", but refgenie also gives each genome an ID computed from its sequences (a GA4GH sequence collection digest), so assets always match the genome they were built from.

  7. It scales. Refgenie keeps its records in a database. It uses a local SQLite file by default and can use PostgreSQL, including on a remote server, for multi-user and distributed setups.

Four commands install refgenie, set it up, download a small asset, and print its path:

Terminal window
pip install "refgenie>=1.0.0a3"
refgenie init
refgenie pull hg38/fasta_index
refgenie seek hg38/fasta_index.chrom_sizes
  1. Install. Version 1.0 is a pre-release, so ask PyPI for it by version: plain pip install refgenie gives you the old 0.13. See Install. Copied an old command like refgenie seek -g hg38 -a fasta? See 0.x commands in 1.0.
  2. Initialize. refgenie init creates the local database and genome folder, and subscribes to the public server at https://api.refgenie.org. See Configure for other locations and database options.
  3. Pull. hg38/fasta_index is about 12 KB: the FASTA index and chromosome sizes for hg38, without the 3 GB FASTA. Not sure which hg38 you need? See Which hg38 should I use?.
  4. Seek. refgenie seek prints the local path to a file in the asset, so your scripts work on any computer. See Retrieve paths to assets.

To see everything you can pull, run refgenie listr, or browse refgenie.org. See Download pre-built assets.

If what you need is not on a server, register your genome from its FASTA file and build assets locally. Building needs recipes from a data channel:

Terminal window
refgenie data-channel add refgenie https https://refgenie.github.io/refgenie-registry/index.yaml
refgenie data-channel sync refgenie --exists-ok
refgenie genome init --fasta mygenome.fa.gz --name mygenome
refgenie build mygenome/bwa_index

See Build assets.

Use seekr ("seek remote") to get the URL of a file on a server, here the FASTA index inside the hg38/fasta asset:

Terminal window
refgenie seekr hg38/fasta.fai

See Configure remote storage.

from refgenie import Refgenie
rgc = Refgenie()
digest = rgc.alias.resolve("hg38") # seek takes the genome's ID (digest), not its name
rgc.asset.seek(digest, "fasta_index", seek_key_name="chrom_sizes")

The Refgenie object connects to the configured database and does everything the CLI does. See the Refgenie Python object.


To read more about why refgenie exists and how it is built, continue to the overview.