MAF track

TL;DR: a MafTrack (with a LinearMafDisplay) shows a multiple alignment of several species against a reference, one row per species with a coverage summary on top. JBrowse reads three formats (BigMaf, tabix MAF, bgzipped TAF). Supply the species with a samples array, an nhLocation Newick tree, or both.

A MAF track shows a multiple alignment of several species against a reference genome: one row per aligned species, with a coverage summary on top. JBrowse reads three formats, all configured as a MafTrack with a LinearMafDisplay. For what the track looks like once loaded, see the MAF track user guide.

Adapters#

Provide the aligned species as one of the following (see below):

• a samples array, in track order
• an nhLocation Newick tree, which both supplies the species and orders/labels the rows as a dendrogram
• both

Example using the tabix-indexed BED form (the UCSC ce11 26-way, ordered by its phylogenetic tree). MafTabixAdapter takes the uri shorthand, resolving the sibling .tbi, plus an nhUri for the tree:

{
  "type": "MafTrack",
  "trackId": "ce11.26way",
  "name": "UCSC 26-way multiple alignment",
  "assemblyNames": ["ce11"],
  "adapter": {
    "type": "MafTabixAdapter",
    "uri": "https://jbrowse.org/demos/ce/ce11.26way.bed.gz",
    "nhUri": "https://hgdownload.soe.ucsc.edu/goldenPath/ce11/multiz26way/ce11.26way.nh"
  }
}

jbrowse add-track-json '{
  "type": "MafTrack",
  "trackId": "ce11.26way",
  "name": "UCSC 26-way multiple alignment",
  "assemblyNames": ["ce11"],
  "adapter": {
    "type": "MafTabixAdapter",
    "uri": "https://jbrowse.org/demos/ce/ce11.26way.bed.gz",
    "nhUri": "https://hgdownload.soe.ucsc.edu/goldenPath/ce11/multiz26way/ce11.26way.nh"
  }
}'

BigMafAdapter is the one MAF adapter with no uri shorthand: it takes a bigBedLocation, as in the 470-way example below, and may also carry the two optional sub-adapters.

The samples array#

A samples entry is either a bare id string or an object. The id is the token matched against the MAF's src column, haplotype suffix included, so a hg38.chr1 row matches the sample hg38. The object form adds:

• label — the sidebar label, for an id that is not itself readable.
• color — the row's color.
• assemblyName — the assembly this species' own genome is loaded as, which makes its rows navigable: right-clicking a drag selection then offers that row's locus in the species' own coordinates. Rows of a sample that leaves it unset are not offered. It has to be written out: ids are UCSC db names in some alignments, scientific names in others (which map to several assemblies) and lab-internal ids in others still, so a name lookup can land on the wrong genome and report coordinates that are silently wrong.
• assemblyConfigLocation — the config to load assemblyName out of when the session does not already have it. Omit it when the assembly is already in the config the user opened. A site hosting many genomes keeps one config per genome, so an alignment's species usually are not present in that config; JBrowse fetches just the named assembly from here at click time, which keeps a 26-way or 470-way navigable. It is a UriLocation, so a relative uri resolves against the declaring config rather than against the page.

A tree and a samples array compose, which is how a tree-ordered alignment also gets navigable rows. With an nhLocation/nhUri the tree's leaf names are the sample set and the row order, and samples becomes an override table matched by id; a leaf with no matching entry keeps its own name as its label.

This track has one row pointing at an assembly the config already holds, one loading its assembly from a sibling config on click, and one plain row that is not navigable:

{
  "type": "MafTrack",
  "trackId": "volvox_maf_navigable",
  "name": "MAF multiple alignment (navigable rows)",
  "assemblyNames": ["volvox"],
  "adapter": {
    "type": "MafTabixAdapter",
    "uri": "volvox.maf.bed.gz",
    "samples": [
      { "id": "volvox", "label": "volvox", "assemblyName": "volvox" },
      {
        "id": "simvolvox",
        "label": "simvolvox",
        "assemblyName": "simvolvox",
        "assemblyConfigLocation": {
          "uri": "config_maf_nav_targets.json",
          "locationType": "UriLocation"
        }
      },
      { "id": "microvolvox", "label": "microvolvox" }
    ]
  }
}

jbrowse add-track-json '{
  "type": "MafTrack",
  "trackId": "volvox_maf_navigable",
  "name": "MAF multiple alignment (navigable rows)",
  "assemblyNames": ["volvox"],
  "adapter": {
    "type": "MafTabixAdapter",
    "uri": "volvox.maf.bed.gz",
    "samples": [
      { "id": "volvox", "label": "volvox", "assemblyName": "volvox" },
      {
        "id": "simvolvox",
        "label": "simvolvox",
        "assemblyName": "simvolvox",
        "assemblyConfigLocation": {
          "uri": "config_maf_nav_targets.json",
          "locationType": "UriLocation"
        }
      },
      { "id": "microvolvox", "label": "microvolvox" }
    ]
  }
}'

The hosted config_maf_navigation.json is the runnable version of that config, also reachable from the no-config screen.

Producing the tabix BED from a MAF#

MafTabixAdapter reads a BED whose sixth column packs every row of an alignment block as comma-separated src:start:size:strand:srcSize:seq, with the first three columns giving that block's interval on the reference. maf2bed writes it. It takes the assembly to use as the reference, so a hg38.chr1 row becomes a chr1 line and every other species rides in column 6:

cargo install maf2bed

export LC_ALL=C  # sort and tabix have to agree on collation
maf2bed hg38 < file.maf | sort -k1,1 -k2,2n | bgzip > file.bed.gz
tabix -p bed file.bed.gz

It streams, so a whole-genome MAF costs no more memory than a small one, and it reads from a pipe (pigz -dc file.maf.gz | maf2bed hg38 | ...). Without a Rust toolchain, maf2bed.pl is the same conversion in Perl and its output is interchangeable.

Every block has to be rooted on the assembly you name, which a MAF from hal2maf --refGenome <name> or from UCSC already is. A MAF whose blocks are rooted on different genomes, as pggb -M produces, needs re-rooting first; see Pangenome (pggb).

Sub-adapters: summary and CDS frames#

Two optional sub-adapters hang off the MAF adapter, alongside the main location:

• summaryAdapter: the zoom-out tier, described in its own section below. Either a UCSC bigMafSummary (a BigBedAdapter over bigMafSummary.bb) or a BedTabixAdapter over the summary maf2bed writes.
• annotationAdapter: a UCSC mafFrames file (a BigBedAdapter over multiz<N>wayFrames.bb) carrying each gene's CDS reading frame projected through the alignment, one record per (species, region), keyed by src species. It enables the "Show CDS frames" overlay and the "Codon changes (amino acids)" row coloring, neither on by default. When the file carries a record for the reference src, the reference row shows its own gene structure too.

The zoom-out tier#

Every MAF format packs each block's species sequences together, so a zoomed-out query downloads them all: on a deep alignment a single screen can be tens of megabytes. JBrowse blocks that with a "requested too much data" prompt, which means a track with no summaryAdapter has no zoom-out view — only the prompt.

The summaryAdapter slot points at a second, much smaller file holding one row per species per aligned region, with a score but no sequence. Where it is configured, zooming out past the force-load threshold swaps the per-base rows for per-species presence bars read from that file instead of blocking.

For a BigMaf track, UCSC ships one alongside the alignment:

"summaryAdapter": {
  "type": "BigBedAdapter",
  "bigBedLocation": { "uri": "https://example.com/multiz470waySummary.bb" }
}

For the other three, maf2bed --summary writes one in the same pass that converts the alignment, so it costs no extra scan of the MAF:

export LC_ALL=C

maf2bed hg38 --summary summary.bed < file.maf \
  | sort -k1,1 -k2,2n | bgzip > file.bed.gz
tabix -p bed file.bed.gz

sort -k1,1 -k2,2n summary.bed | bgzip > summary.bed.gz
tabix -p bed summary.bed.gz

--summary needs maf2bed v0.6.0 or newer. Versions before that read only the first argument and ignore the rest, so the command above exits 0 and writes only the alignment BED; check that summary.bed exists before wiring the slot.

Its # header names the columns, so the sub-adapter needs no columnNames:

{
  "type": "MafTrack",
  "trackId": "multiz_with_summary",
  "name": "Multiz alignment (with zoom-out tier)",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "MafTabixAdapter",
    "uri": "https://example.com/multiz.bed.gz",
    "samples": ["hg38", "panTro6", "mm39"],
    "summaryAdapter": {
      "type": "BedTabixAdapter",
      "bedGzLocation": { "uri": "https://example.com/multiz.summary.bed.gz" },
      "index": {
        "location": { "uri": "https://example.com/multiz.summary.bed.gz.tbi" }
      }
    }
  }
}

jbrowse add-track-json '{
  "type": "MafTrack",
  "trackId": "multiz_with_summary",
  "name": "Multiz alignment (with zoom-out tier)",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "MafTabixAdapter",
    "uri": "https://example.com/multiz.bed.gz",
    "samples": ["hg38", "panTro6", "mm39"],
    "summaryAdapter": {
      "type": "BedTabixAdapter",
      "bedGzLocation": { "uri": "https://example.com/multiz.summary.bed.gz" },
      "index": {
        "location": { "uri": "https://example.com/multiz.summary.bed.gz.tbi" }
      }
    }
  }
}'

The bars are shaded by the summary's score, and hovering one reports it as a number alongside the species and the aligned block. The two producers put different metrics there — UCSC a normalized alignment score, maf2bed percent identity to the reference — but both are 0..1 and both shade the same way, so the tooltip labels it as the file's score rather than as either. Both are distinct from the conservation band, which is computed from the alignment itself and needs no file.

BgzipMafAdapter and BgzipTaffyAdapter take the same slot, and the same maf2bed --summary BED serves them. Their .tai index seeks within an alignment, so a read costs what is on screen rather than what the blocks happen to span. That bounds the span a read covers, not the number of rows, and a read costs both. On a deep alignment an index moves the zoom-out ceiling; the summary file removes it. Each slot doc quotes the bytes per base measured for that format on HPRC's published alignment: BgzipMafAdapter, BgzipTaffyAdapter.

Display options#

The conservation band, the identity plots (heatmap / X-Y plot), source-chromosome coloring, and the inversion (strand-flip) overlay are all derived from the alignment with no extra configuration, picked from the track menu. The user guide covers what each one shows.

A larger example: the human 470-way#

These features work at genome scale. The UCSC hg38 470-way multiz (the Zoonomia mammals and more) is a BigMafAdapter over multiz470way.bigMaf, with its multiz470waySummary.bb (zoom-out) and multiz470wayFrames.bb (CDS frames / codon view): the same three pieces as the smaller examples, pointed at the UCSC downloads.

{
  "type": "MafTrack",
  "trackId": "multiz470way",
  "name": "Multiz 470-way",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "BigMafAdapter",
    "bigBedLocation": {
      "uri": "https://hgdownload.soe.ucsc.edu/goldenPath/hg38/multiz470way/multiz470way.bigMaf"
    },
    "summaryAdapter": {
      "type": "BigBedAdapter",
      "bigBedLocation": {
        "uri": "https://hgdownload.soe.ucsc.edu/goldenPath/hg38/multiz470way/multiz470waySummary.bb"
      }
    },
    "annotationAdapter": {
      "type": "BigBedAdapter",
      "bigBedLocation": {
        "uri": "https://hgdownload.soe.ucsc.edu/goldenPath/hg38/multiz470way/multiz470wayFrames.bb"
      }
    }
  }
}

A subtree filter (from the track menu) narrows the hundreds of species to a focused set for detailed reading; see the user guide for how the large alignment renders.

See also#

• MAF track
• Synteny track config
• Supported file types