Skip to content
Refgenie

Exploring the Brickyard Genome Store

This tutorial shows how to connect to the brickyard genome store and browse its curated collection of ~1,952 reference genomes. You’ll look up genomes by accession, compare assemblies from different sources, and export FASTA files.

For background on what the brickyard genome collection is, see The Brickyard Genome Collection. This tutorial assumes you can already install the refget package and know the basics of RefgetStore and aliases.

Learning objectives

  • Open the brickyard genome store (local path or remote URL)
  • List available genomes and alias namespaces
  • Look up a genome by NCBI accession
  • Compare two versions of the same genome from different sources
  • Export a FASTA from the store

1. Opening the store

Section titled “1. Opening the store”

The brickyard genome store can be opened either from a remote URL or a local path. Here we connect to the remote store and use a temporary local cache.

import os
import tempfile
from refget.store import RefgetStore
# Remote URL for the brickyard genome store
# (Update this URL when the brickyard store is published to S3)
BRICKYARD_URL = "https://refgenie.s3.us-east-1.amazonaws.com/brickyard_genome_store"


# Open the remote store with a local cache directory
temp_dir = tempfile.mkdtemp(prefix="genome_store_tutorial_")
cache_path = os.path.join(temp_dir, "cache")


store = RefgetStore.open_remote(
    cache_path=cache_path,
    remote_url=BRICKYARD_URL
)


# Show store statistics
print(store.stats())
TODO: capture output after store is built
Expected format:
{'n_collections_loaded': '0', 'storage_mode': 'Encoded', 'n_sequences_loaded': '0', 'total_disk_size': '...', 'n_sequences': '...', 'n_collections': '1952'}

If you have a local copy of the store, you can open it directly:

# If you have a local copy:
# store = RefgetStore.on_disk("/path/to/brickyard_genome_store")

2. Browsing available genomes

Section titled “2. Browsing available genomes”

The store organizes genomes using alias namespaces. Let’s see what’s available.

# List alias namespaces
namespaces = store.list_collection_alias_namespaces()
print(f"Collection alias namespaces: {namespaces}")
TODO: capture output after store is built
Expected format:
Collection alias namespaces: ['accession', 'common', 'refgenie']
# List accession aliases (first 10)
accession_aliases = store.list_collection_aliases("accession")
print(f"Total accession aliases: {len(accession_aliases)}")
print(f"\nFirst 10 accessions:")
for alias in accession_aliases[:10]:
    print(f"  {alias}")
TODO: capture output after store is built
Expected format:
Total accession aliases: 1952


First 10 accessions:
  GCA_000001215.4
  GCA_000001405.15
  GCA_000001405.28
  GCA_000001405.29
  GCA_000001635.8
  GCA_000001635.9
  GCA_000002985.3
  GCA_000005005.6
  GCA_000005425.2
  GCA_000005575.1
# List common name aliases (should be a short list)
common_aliases = store.list_collection_aliases("common")
print(f"Common name aliases:")
for alias in common_aliases:
    print(f"  {alias}")
TODO: capture output after store is built
Expected format:
Common name aliases:
  hg38
  hg19
  mm39
  mm10

3. Looking up a genome by accession

Section titled “3. Looking up a genome by accession”

The most common way to find a genome is by its NCBI accession. Let’s look up the GRCh38.p14 human reference genome.

# Look up hg38 by its NCBI RefSeq accession
hg38 = store.get_collection_by_alias("accession", "GCF_000001405.40")
if hg38:
    print(f"Digest: {hg38.digest}")
    print(f"Sequences: {hg38.n_sequences}")
TODO: capture output after store is built
Expected format:
Digest: <sha512t24u digest>
Sequences: <number of sequences>
# Reverse lookup: find all aliases that point to this collection
if hg38:
    aliases = store.get_aliases_for_collection(hg38.digest)
    print(f"All aliases for this collection:")
    for namespace, alias in aliases:
        print(f"  {namespace}/{alias}")
TODO: capture output after store is built
Expected format:
All aliases for this collection:
  accession/GCF_000001405.40
  common/hg38
  refgenie/hg38

4. Comparing two genome versions

Section titled “4. Comparing two genome versions”

RefgetStore can compare two collections to show what they share and where they differ. This is useful for understanding the relationship between assemblies from different sources or different versions of the same genome.

# Look up two different assemblies to compare
hg38_ncbi = store.get_collection_by_alias("accession", "GCF_000001405.40")
hg19_ncbi = store.get_collection_by_alias("accession", "GCF_000001405.25")


if hg38_ncbi and hg19_ncbi:
    print(f"hg38 digest: {hg38_ncbi.digest}")
    print(f"hg19 digest: {hg19_ncbi.digest}")
TODO: capture output after store is built
Expected format:
hg38 digest: <sha512t24u digest>
hg19 digest: <sha512t24u digest>
# Compare the two assemblies
if hg38_ncbi and hg19_ncbi:
    comparison = store.compare(hg38_ncbi.digest, hg19_ncbi.digest)
    print(f"Shared attributes: {comparison['attributes']['a_and_b']}")
    print(f"A-only attributes: {comparison['attributes']['a_only']}")
    print(f"B-only attributes: {comparison['attributes']['b_only']}")
TODO: capture output after store is built
Expected format:
Shared attributes: ['lengths', 'name_length_pairs', 'names', 'sequences', 'sorted_name_length_pairs', 'sorted_sequences']
A-only attributes: []
B-only attributes: []

The comparison shows which seqcol attributes are shared between the two assemblies and which are unique to each. Since hg38 and hg19 are different genome builds, they will typically differ in their sequence content while sharing the same set of attribute types.

5. Exporting a FASTA

Section titled “5. Exporting a FASTA”

You can export any collection from the store as a FASTA file. This downloads the sequences (if remote) and writes them to disk.

# Export the hg38 collection to a FASTA file
if hg38:
    output_path = os.path.join(temp_dir, "hg38_export.fa")
    store.export_fasta(hg38.digest, output_path, None, None)
    print(f"Exported to: {output_path}")
TODO: capture output after store is built
Expected format:
Exported to: /tmp/genome_store_tutorial_.../hg38_export.fa
# Verify the export
if hg38:
    file_size = os.path.getsize(output_path)
    print(f"File size: {file_size:,} bytes")
    print(f"\nFirst 5 lines:")
    with open(output_path) as f:
        for i, line in enumerate(f):
            if i >= 5:
                break
            print(line.rstrip())
TODO: capture output after store is built
Expected format:
File size: <size> bytes


First 5 lines:
>chr1
NNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNN
NNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNN
NNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNN
NNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNN

Summary

  • The brickyard genome store provides ~1,952 curated reference genomes accessible by accession, common name, or digest.
  • Use open_remote() to connect to the store with automatic local caching, or on_disk() for a local copy.
  • Alias namespaces (accession, common, refgenie) let you look up genomes using familiar identifiers.
  • Collection comparison reveals what two assemblies share, helping you understand the relationship between genome versions.
  • FASTA export lets you extract any genome from the store for downstream analysis.

What’s next?

Section titled “What’s next?”
  • RefgetStore tutorial — General store operations: creating stores, retrieving sequences, extracting regions
  • Working with Aliases — Managing your own aliases: adding, resolving, bulk loading, and removing aliases
  • FHR Metadata Headers — Attaching assembly metadata (species, version, masking) to collections
# Cleanup
import shutil
shutil.rmtree(temp_dir)