Genome Aliases

Introduction

Genome aliases provide human-readable names for reference genomes, mapping them to their underlying cryptographic digests. Instead of referring to genomes by their unique digest strings (e.g., a5b35a4c5b27c7f3e8e2f4c3a1b2d9e7), you can use memorable names like hg38, mm10, or GRCh38.

Learning objectives

• What are genome aliases and why use them?
• How to list existing aliases
• How to set aliases for a genome
• How to remove aliases

Why use aliases?

Refgenie identifies genomes by their content-derived digest - a unique hash computed from the genome’s sequences. While digests guarantee uniqueness and enable compatibility checking, they are difficult to remember and type. Aliases solve this problem by providing:

• Human-readable names: Use familiar names like hg38 or mm10 instead of digest strings
• Multiple aliases per genome: A single genome can have multiple aliases (e.g., hg38, GRCh38, human)
• Consistent references: Once set, aliases work throughout refgenie commands

Digest vs Alias

A digest is the unique, content-derived identifier for a genome (computed from sequences). An alias is a human-friendly name that maps to a digest. You can use either in most refgenie commands.

Listing aliases

To see all configured aliases, use the alias get command:

refgenie alias get

This displays a table showing all aliases and their corresponding genome digests:

┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Alias     ┃ Genome Digest                    ┃
┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ hg38      │ a5b35a4c5b27c7f3e8e2f4c3a1b2d9e7 │
│ GRCh38    │ a5b35a4c5b27c7f3e8e2f4c3a1b2d9e7 │
│ mm10      │ c3d45e6f7a8b9c0d1e2f3a4b5c6d7e8f │
└───────────┴──────────────────────────────────┘

Filtering by alias

To look up the digest for specific aliases:

refgenie alias get -a hg38 GRCh38

Filtering by digest

To find all aliases for a specific genome digest:

refgenie alias get -g a5b35a4c5b27c7f3e8e2f4c3a1b2d9e7

Mutually exclusive options

The -a/--aliases and -g/--genome-digests options are mutually exclusive. Use one or the other to filter results.

Setting aliases

To assign an alias to a genome, use the alias set command with the -a (alias) and -d (digest) options:

refgenie alias set -a hg38 -d a5b35a4c5b27c7f3e8e2f4c3a1b2d9e7

Setting multiple aliases at once

You can set multiple aliases for the same genome in a single command:

refgenie alias set -a hg38 GRCh38 human -d a5b35a4c5b27c7f3e8e2f4c3a1b2d9e7

Replacing existing aliases

The --reset flag removes all existing aliases for a genome before setting new ones:

refgenie alias set -a hg38_v2 -d a5b35a4c5b27c7f3e8e2f4c3a1b2d9e7 --reset

This is useful when you want to rename a genome or consolidate aliases. Without --reset, new aliases are added to any existing ones.

Genome must exist

You can only set aliases for genomes that already exist in your refgenie database. If you try to set an alias for a non-existent digest, you will see an error:

Genome with digest abc123... does not exist. You must initialize it first by building/pulling an asset for that genome.

Removing aliases

To remove aliases, use the alias remove command:

refgenie alias remove -a hg38

Removing multiple aliases

You can remove multiple aliases at once:

refgenie alias remove -a hg38 GRCh38

Aliases vs Genome

Removing an alias does not delete the genome or its assets. It only removes the name mapping. The genome remains accessible by its digest or any remaining aliases.

Using aliases in commands

Once set, aliases can be used anywhere a genome identifier is expected:

# Pull an asset using an alias
refgenie pull hg38/fasta

# List assets for an aliased genome
refgenie list -g hg38

# Get sequence using an alias
refgenie getseq -g hg38 -l chr1:1-100

# Compare genomes using aliases
refgenie compare hg38 mm10

Command reference

alias get

List aliases with optional filtering.

refgenie alias get [-a ALIASES...] [-g DIGESTS...]

Option	Description
-a, --aliases	Filter by specific alias names
-g, --genome-digests	Filter by specific genome digests

alias set

Set one or more aliases for a genome digest.

refgenie alias set -a ALIASES... -d DIGEST [--reset]

Option	Description
-a, --aliases	One or more alias names to set (required)
-d, --digest	Genome digest to associate with the aliases
-r, --reset	Remove all existing aliases before setting new ones
-f, --force	Force the action if genome does not exist

alias remove

Remove one or more aliases.

refgenie alias remove -a ALIASES...

Option	Description
-a, --aliases	One or more alias names to remove (required)