Synteny from liftOver chains (hg38 and eight vertebrates)

TL;DR: we look at one human locus across eight other mammals at once, from alignments that already exist. UCSC publishes a liftOver chain from hg38 to every genome it hosts, and jbrowse.org keeps each of those chains as an indexed alignment file, so one track composes eight of them into a lane per genome under the human view, each lane drawing that genome's own RefSeq gene models from its UCSC hub. The primate lanes come out nearly straight; mouse, dog and cow are where the chain breaks, reverses and skips, and the page ends there.

Prerequisites

htslib (tabix), to read a hosted alignment's index without downloading it
A running JBrowse instance (the web quickstart or the desktop quickstart)

Where the data comes from

UCSC's pairwise liftOver chains from hg38 (Kent et al. 2003), each converted to an indexed PAF and rehosted beside the hub configs genomes.jbrowse.org serves, and eight UCSC genome hubs, whose assembly entry and NCBI RefSeq gene track each lane takes verbatim.

The chains

UCSC's liftOver folder for hg38, one hg38To<Genome>.over.chain.gz per genome: https://hgdownload.soe.ucsc.edu/goldenPath/hg38/liftOver/

The same chains as indexed alignments

chimpanzee, panTro6: https://jbrowse.org/ucsc/hg38/liftOver/hg38ToPanTro6.over.pif.gz
gorilla, gorGor6: https://jbrowse.org/ucsc/hg38/liftOver/hg38ToGorGor6.over.pif.gz
orangutan, ponAbe3: https://jbrowse.org/ucsc/hg38/liftOver/hg38ToPonAbe3.over.pif.gz
rhesus macaque, rheMac10: https://jbrowse.org/ucsc/hg38/liftOver/hg38ToRheMac10.over.pif.gz
marmoset, calJac4: https://jbrowse.org/ucsc/hg38/liftOver/hg38ToCalJac4.over.pif.gz
mouse, mm39: https://jbrowse.org/ucsc/hg38/liftOver/hg38ToMm39.over.pif.gz
dog, canFam6: https://jbrowse.org/ucsc/hg38/liftOver/hg38ToCanFam6.over.pif.gz
cow, bosTau9: https://jbrowse.org/ucsc/hg38/liftOver/hg38ToBosTau9.over.pif.gz

The hubs each lane's assembly and gene track come from

hg38: https://jbrowse.org/ucsc/hg38/config.json
every other genome at the same path under its own name, panTro6 for one: https://jbrowse.org/ucsc/panTro6/config.json
the finished config, the eight hub entries and the composed track together: https://jbrowse.org/demos/hg38_vertebrates/config.json

One alignment per genome

The primate page and the E. coli page fill their lanes from a gene table, joining genes across genomes by name, so a lane holds genes and nothing between them. An alignment file places sequence instead: every base of the human window that a chain reaches has a position in the other genome, gene or not, and the lanes on this page are drawn from that.

UCSC's chains are one alignment per genome, each between hg38 and that genome alone. Composed, they make a star with hg38 at the centre: hg38 against chimpanzee, hg38 against mouse, and no row anywhere that aligns chimpanzee to mouse. That is exactly the shape a lane stack anchored on hg38 reads. Each lane is placed from its own chain, and the ribbons between two adjacent mate lanes are composed through the human coordinates they share.

Each hosted file is a chain converted to PAF and indexed with jbrowse make-pif, which can write a coarse tier beside the per-base one for whole-chromosome zooms. tabix reads either question off the index without fetching the alignment: the header names the tiers the file carries, and the coarse tier's sequence names are the upper-case ones.

# the #pif header, if the file was built recently enough to carry one
tabix -H https://jbrowse.org/ucsc/hg38/liftOver/hg38ToPanTro6.over.pif.gz | awk 'NR==1'
# how many coarse-tier sequences the index holds; zero means one tier
tabix -l https://jbrowse.org/ucsc/hg38/liftOver/hg38ToPanTro6.over.pif.gz | grep -c '^[TQ]'

The composed track

One SyntenyTrack names hg38 and every genome it stacks, and its adapter is a MultiPairwiseSyntenyAdapter holding one child per chain. Each child is an ordinary PairwiseIndexedPAFAdapter with its own pair of assembly names, in the order the file states them, and the anchor is never written: it is the one assembly every child names. The list below is cut to three genomes for the page; the hosted config carries all eight. The assemblies and their gene tracks come from each genome's hub config unchanged, and a lane finds its gene models through the session, so the only thing the track adds to the hub entries is itself.

Config file CLI (add-track-json) JBrowse Desktop

{
  "type": "SyntenyTrack",
  "trackId": "hg38_liftover_multiway",
  "name": "hg38 vs 8 UCSC genomes (liftOver chains)",
  "assemblyNames": ["hg38", "panTro6", "rheMac10", "mm39"],
  "adapter": {
    "type": "MultiPairwiseSyntenyAdapter",
    "adapters": [
      {
        "type": "PairwiseIndexedPAFAdapter",
        "uri": "https://jbrowse.org/ucsc/hg38/liftOver/hg38ToPanTro6.over.pif.gz",
        "csi": true,
        "assemblyNames": ["panTro6", "hg38"]
      },
      {
        "type": "PairwiseIndexedPAFAdapter",
        "uri": "https://jbrowse.org/ucsc/hg38/liftOver/hg38ToRheMac10.over.pif.gz",
        "csi": true,
        "assemblyNames": ["rheMac10", "hg38"]
      },
      {
        "type": "PairwiseIndexedPAFAdapter",
        "uri": "https://jbrowse.org/ucsc/hg38/liftOver/hg38ToMm39.over.pif.gz",
        "csi": true,
        "assemblyNames": ["mm39", "hg38"]
      }
    ]
  },
  "displays": [
    {
      "type": "MultiWaySyntenyDisplay",
      "displayId": "hg38_liftover_multiway-MultiWaySyntenyDisplay",
      "height": 600
    }
  ]
}

jbrowse add-track-json '{
  "type": "SyntenyTrack",
  "trackId": "hg38_liftover_multiway",
  "name": "hg38 vs 8 UCSC genomes (liftOver chains)",
  "assemblyNames": ["hg38", "panTro6", "rheMac10", "mm39"],
  "adapter": {
    "type": "MultiPairwiseSyntenyAdapter",
    "adapters": [
      {
        "type": "PairwiseIndexedPAFAdapter",
        "uri": "https://jbrowse.org/ucsc/hg38/liftOver/hg38ToPanTro6.over.pif.gz",
        "csi": true,
        "assemblyNames": ["panTro6", "hg38"]
      },
      {
        "type": "PairwiseIndexedPAFAdapter",
        "uri": "https://jbrowse.org/ucsc/hg38/liftOver/hg38ToRheMac10.over.pif.gz",
        "csi": true,
        "assemblyNames": ["rheMac10", "hg38"]
      },
      {
        "type": "PairwiseIndexedPAFAdapter",
        "uri": "https://jbrowse.org/ucsc/hg38/liftOver/hg38ToMm39.over.pif.gz",
        "csi": true,
        "assemblyNames": ["mm39", "hg38"]
      }
    ]
  },
  "displays": [
    {
      "type": "MultiWaySyntenyDisplay",
      "displayId": "hg38_liftover_multiway-MultiWaySyntenyDisplay",
      "height": 600
    }
  ]
}'

In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track..., choose Add track from pasted JSON, and paste:

{
  "type": "SyntenyTrack",
  "trackId": "hg38_liftover_multiway",
  "name": "hg38 vs 8 UCSC genomes (liftOver chains)",
  "assemblyNames": ["hg38", "panTro6", "rheMac10", "mm39"],
  "adapter": {
    "type": "MultiPairwiseSyntenyAdapter",
    "adapters": [
      {
        "type": "PairwiseIndexedPAFAdapter",
        "uri": "https://jbrowse.org/ucsc/hg38/liftOver/hg38ToPanTro6.over.pif.gz",
        "csi": true,
        "assemblyNames": ["panTro6", "hg38"]
      },
      {
        "type": "PairwiseIndexedPAFAdapter",
        "uri": "https://jbrowse.org/ucsc/hg38/liftOver/hg38ToRheMac10.over.pif.gz",
        "csi": true,
        "assemblyNames": ["rheMac10", "hg38"]
      },
      {
        "type": "PairwiseIndexedPAFAdapter",
        "uri": "https://jbrowse.org/ucsc/hg38/liftOver/hg38ToMm39.over.pif.gz",
        "csi": true,
        "assemblyNames": ["mm39", "hg38"]
      }
    ]
  },
  "displays": [
    {
      "type": "MultiWaySyntenyDisplay",
      "displayId": "hg38_liftover_multiway-MultiWaySyntenyDisplay",
      "height": 600
    }
  ]
}

The track menu is the one a pairwise synteny track has. Its Level of detail entry, which picks the stored tier a zoom reads, is offered once every child carries a coarse tier, and the tabix -l line above is how to tell whether a file does.

One locus, nine genomes

Opened on hg38 around TP53, the track draws a lane per genome under the human axis, each fitted to wherever its chain places the window. A lane's header names its chromosome and where it is looking, with [rev] where that chromosome runs the other way relative to hg38, and the lanes stack densest first, so the genomes placing the most of the window sit at the top.

Config file CLI (set-default-session) URL

{
  "defaultSession": {
    "name": "TP53 neighbourhood across nine vertebrates",
    "views": [
      {
        "type": "LinearGenomeView",
        "assembly": "hg38",
        "loc": "chr17:7,400,000-7,700,000",
        "tracks": [
          "hg38-ncbiRefSeq",
          {
            "trackId": "hg38_liftover_multiway",
            "type": "MultiWaySyntenyDisplay",
            "height": 600
          }
        ]
      }
    ]
  }
}

jbrowse set-default-session --session - << 'EOF'
{
  "name": "TP53 neighbourhood across nine vertebrates",
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,400,000-7,700,000",
      "tracks": [
        "hg38-ncbiRefSeq",
        {
          "trackId": "hg38_liftover_multiway",
          "type": "MultiWaySyntenyDisplay",
          "height": 600
        }
      ]
    }
  ]
}
EOF

Open this session in JBrowse

Around TP53 every lane reads as the human axis drawn again: one chain block across the window, the same genes in the same order, ribbons running straight down through all eight. The header of each lane says which chromosome that is in the genome and how far the lane's frame reaches, and the lanes stack densest first, so a genome that placed less of the window would sit lower. Here none does; this is a neighbourhood conserved across the mammals, and the picture says so by having nothing to point at.

The TP53 neighbourhood on hg38 over eight UCSC genome lanes from one composed liftOver track, each lane drawing its own RefSeq gene models on its own chromosome. Every lane places the window as one straight block. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)

Eight megabases toward the centromere the same stack looks different. The mouse, dog and cow chains change orientation partway across the window, so those lanes carry [rev] in their headers and the ribbons reaching them cross, while the primate lanes still run straight. Two of the ape lanes name a second contig in their headers, a random or unplaced scaffold that also places part of this window: the region is a segmental-duplication hotspot, and the header is how a lane says the frame it drew is not the whole story. Show … in this lane on that lane's header menu pins it onto the other contig.

hg38 chr17 near the PMP22 segmental duplications over the same eight lanes. The primate lanes run straight through; the mouse, dog and cow lanes reverse partway across, with crossed ribbons and a reversed marker in their headers, and two ape lanes name a second contig that also places the window. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)

Color ribbons by → Strand on the track menu paints a ribbon that crosses, which is a block running the other way relative to the lane above it, so a lane's [rev] and the ribbons reaching it agree.

Reading the stack

Each lane is one genome in its own coordinates, fitted to wherever its alignment places the anchor window, so the number at a lane's right edge is the span that lane shows and the multiple after it is how much wider than the anchor window that is. A lane that has to show twice the anchor's span to cover the same genes is telling you the alignment there is stretched or broken. Ribbons join a lane to the lane directly above it, and where a source holds no alignment between two mates, as this star does not, the ribbon between them is composed through the anchor. Hovering a ribbon lights the same alignment in every lane it reaches; dragging a lane's label reorders the stack; the header menu on a lane re-anchors the view on that genome or opens it in a view of its own.

Reproduce it end to end

The script assembles the config and nothing else: it probes which of the listed genomes have a hub config and an indexed chain, reports each file's tiers, and writes the hub entries and the composed track into one config. GENOMES picks a different set; see Prerequisites.

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_hg38_liftover_multiway.sh
bash build_hg38_liftover_multiway.sh

References

Kent WJ, Baertsch R, Hinrichs A, Miller W, Haussler D. Evolution's cauldron: duplication, deletion, and rearrangement in the mouse and human genomes. Proc Natl Acad Sci USA (2003). https://doi.org/10.1073/pnas.1932072100
UCSC Genome Browser downloads: https://hgdownload.soe.ucsc.edu/downloads.html

Feedback on this tutorial is welcome: contact us.

Synteny from liftOver chains (hg38 and eight vertebrates)

Prerequisites#

Where the data comes from#

One alignment per genome#

The composed track#

One locus, nine genomes#

Reading the stack#

Reproduce it end to end#

See also#

References#