Skip to main content

RefName aliasing

RefName aliasing lets JBrowse treat different naming conventions for the same chromosome (e.g. chr1 vs 1 vs NC_000001.11) as a single sequence. With an alias adapter configured on an assembly, JBrowse translates refNames so tracks using different conventions all line up.

Configure an alias adapter on the assembly. Use RefNameAliasAdapter for a UCSC-style tab file, NcbiSequenceReportAliasAdapter for an NCBI sequence_report.tsv. The primary refName must match your FASTA exactly.

How resolution works

Keep three distinct names in mind:

  • canonical name - what JBrowse displays and navigates by. Every alias resolves to it. Defaults to the name in your FASTA / sequence adapter.
  • sequence-adapter (FASTA) name - the name your reference file uses. Usually the same as the canonical name, but can differ (see useNameOverride below).
  • track refName - the name a track's data file uses. Each track's regions are translated from the canonical name into that track's naming scheme before querying, so a BAM using 1 and a VCF using chr1 both work against a chr1 canonical assembly.

When queried, a track adapter gets the resolved track refName as refName and the sequence-adapter name as originalRefName (used by CRAM/BAM to fetch the correct reference bases). See also configuring reference name aliasing.

Choosing an adapter

SituationRecommended adapter
UCSC genome, or any hand-maintained tab-separated fileRefNameAliasAdapter
NCBI/RefSeq genome with a sequence_report.tsvNcbiSequenceReportAliasAdapter
FASTA uses RefSeq accessions but you want chr1 shownNcbiSequenceReportAliasAdapter (default)
FASTA uses RefSeq accessions and you want them shownNcbiSequenceReportAliasAdapter, useNameOverride:false

RefNameAliasAdapter

Reads any tab-separated alias file, including the UCSC chromAlias format. Each row lists every name for one sequence:

chr1	1	NC_000001.11
chr2	2	NC_000002.12

One column is the "primary" refName that must match the names in your FASTA/sequence adapter; the other columns become aliases. The primary column is the first by default; use refNameColumn (below) to pick a different one.

{
  "name": "hg38",
  "uri": "hg38.fa.gz",
  "refNameAliases": { "uri": "aliases.txt" }
}
jbrowse add-assembly hg38.fa.gz \
  --name hg38 \
  --refNameAliases aliases.txt \
  --load copy

In JBrowse Desktop, Open new genome on the start screen (or File → Open genome... in a session), then Open from a URL and paste, one per line:

hg38.fa.gz
hg38.fa.gz.fai
hg38.fa.gz.gzi

JBrowse reads the format off the file name. Then fill in:

  • Genome name: hg38
  • refName aliases (under More options): aliases.txt

hg38.fa.gz, aliases.txt are relative to a config.json. Replace each with its URL or its path on this computer.

The bare { "uri": ... } form of refNameAliases is shorthand for the default RefNameAliasAdapter. Spell the adapter out when you need one of its options, or a different alias adapter entirely:

{
  "name": "hg38",
  "uri": "hg38.fa.gz",
  "refNameAliases": {
    "adapter": {
      "type": "RefNameAliasAdapter",
      "uri": "aliases.txt"
    }
  }
}
jbrowse add-assembly hg38.fa.gz \
  --name hg38 \
  --refNameAliases aliases.txt \
  --load copy

In JBrowse Desktop, Open new genome on the start screen (or File → Open genome... in a session), then Open from a URL and paste, one per line:

hg38.fa.gz
hg38.fa.gz.fai
hg38.fa.gz.gzi

JBrowse reads the format off the file name. Then fill in:

  • Genome name: hg38
  • refName aliases (under More options): aliases.txt

hg38.fa.gz, aliases.txt are relative to a config.json. Replace each with its URL or its path on this computer.

("uri": "..." is shorthand for "location": { "uri": "..." }.)

Options:

  • refNameColumn - zero-based index of the column matching your FASTA. Above, that's the first column (chr1/chr2).
  • refNameColumnHeaderName (string) - alternative to refNameColumn. Selects the primary column by its header name instead of by index, read from the last #-prefixed line in the file (the one immediately above the data, so a file with a comment block still resolves against the real header). The adapter throws if the named column is not in that header. It only looks when a # line exists: a file with no header row falls back to refNameColumn.
#name	alias1	alias2
chr1	1	NC_000001.11
{
  "name": "hg38",
  "uri": "hg38.fa.gz",
  "refNameAliases": {
    "adapter": {
      "type": "RefNameAliasAdapter",
      "uri": "aliases.txt",
      "refNameColumnHeaderName": "name"
    }
  }
}
jbrowse add-assembly hg38.fa.gz \
  --name hg38 \
  --refNameAliases aliases.txt \
  --load copy

In JBrowse Desktop, Open new genome on the start screen (or File → Open genome... in a session), then Open from a URL and paste, one per line:

hg38.fa.gz
hg38.fa.gz.fai
hg38.fa.gz.gzi

JBrowse reads the format off the file name. Then fill in:

  • Genome name: hg38
  • refName aliases (under More options): aliases.txt

hg38.fa.gz, aliases.txt are relative to a config.json. Replace each with its URL or its path on this computer.

NcbiSequenceReportAliasAdapter

Reads NCBI sequence_report.tsv files, which map GenBank accessions, RefSeq accessions, UCSC-style names, and sequence names all at once. Get them from the NCBI datasets page for any RefSeq assembly, or the datasets CLI.

{
  "name": "GCF_000001405.40",
  "uri": "GCF_000001405.40.fa.gz",
  "refNameAliases": {
    "adapter": {
      "type": "NcbiSequenceReportAliasAdapter",
      "uri": "sequence_report.tsv"
    }
  }
}

Three column headers are required, matched by name rather than position: GenBank seq accession, RefSeq seq accession and UCSC style name. A fourth, Sequence name, is optional. The primary refName is taken from UCSC style name, falling back to Sequence name where that column exists and the UCSC one is blank; a row with neither is skipped. Whichever of the four columns a row does fill become aliases for it.

Options:

  • useNameOverride controls which name is canonical (displayed) when your FASTA does not use UCSC names:
    • true - show UCSC-style names (chr1) even though your FASTA uses RefSeq accessions (NC_000001.11); JBrowse still fetches reference bases from the FASTA under NC_000001.11. The common case for NCBI FASTAs.
    • false - keep your FASTA's own names canonical. JBrowse displays NC_000001.11, and chr1 resolves to it as a searchable alias.

Troubleshooting

Start by looking at what actually loaded: the reference sequence track's "About track" dialog has an "Assembly" section whose "Show ref name aliases" button lists every refName in the assembly beside the names resolving to it. A row with no aliases is an alias file that did not apply to that contig; a missing row is a contig the sequence adapter never had.

  • Aliases don't resolve / tracks appear empty. The primary refName must match your FASTA exactly. For RefNameAliasAdapter, confirm refNameColumn points at the column whose values equal your FASTA's sequence names.
  • Encountered invalid refName error. A name in the alias file contains characters outside the SAM-spec refName set (e.g. stray whitespace or quoting). Clean the offending row.
  • NCBI adapter throws about the header line. The error names the missing column. The first line must carry the three required headers spelled exactly as above; a renamed column reads as an absent one. Sequence name is not required, so a file without it parses.

See also