Skip to main content

Synteny from gene symbols (primates and E. coli)

JBrowse v5 beta

The tutorials target the JBrowse v5 beta, and the v4.3.0 release on the download page lacks some of what they show. To install the beta of JBrowse Web, run npm install -g @jbrowse/cli@next, then jbrowse create jbrowse2 --branch v5.0.0-beta.20. Desktop beta builds for Linux and macOS are on the releases page; the Windows build waits on code signing.

We look at one human locus across seven other primates at once. NCBI gives an orthologous gene the same symbol in every species it annotates, so an ortholog table is a join on the gene name over eight GFF3 files. Bacterial annotations name fewer genes and rename more of them, so the page closes on E. coli to see what the join does with them. We:

  • build the join, and set up each lane's assembly from its hub
  • load the table as a multi-genome ortholog track, each primate a lane under the human view in the coordinates of that primate's genome
  • read the TP53 neighbourhood and a 17q window across the lanes
  • read human chromosome 2 against the ape chromosomes it fused from
  • rebuild the join over E. coli annotations, with lanes built from chromosome lengths, and read the O-antigen cluster

Prerequisites

# Debian/Ubuntu
sudo apt install tabix
# or conda, which has every tool above
conda install -c bioconda -c conda-forge htslib ncbi-datasets-cli
# or Linux x86_64 binaries for the tools apt lacks
wget -P ~/.local/bin \
  https://ftp.ncbi.nlm.nih.gov/pub/datasets/command-line/v2/linux-amd64/datasets \
  https://ftp.ncbi.nlm.nih.gov/pub/datasets/command-line/v2/linux-amd64/dataformat
chmod +x ~/.local/bin/datasets ~/.local/bin/dataformat

The data

Eight RefSeq assemblies, each fetched by accession with the datasets CLI: the current human reference, the six NHGRI telomere-to-telomere ape assemblies (Yoo et al. 2025) and the telomere-to-telomere rhesus macaque. The E. coli section uses E. coli and Shigella assemblies anchored on K-12 MG1655, all pinned by accession in its build script.

The tracks below read local files that the build scripts write, so run them first, or run An ortholog table joined on gene names over RefSeq accessions of your own. Each script fetches the annotations and reports it needs for every genome itself.

What it isFile
Human, GRCh38.p14GCF_000001405.40_GRCh38.p14/
ChimpanzeeGCF_028858775.2_NHGRI_mPanTro3-v2.1_pri/
BonoboGCF_029289425.2_NHGRI_mPanPan1-v2.1_pri/
GorillaGCF_029281585.2_NHGRI_mGorGor1-v2.1_pri/
Sumatran orangutanGCF_028885655.2_NHGRI_mPonAbe1-v2.1_pri/
Bornean orangutanGCF_028885625.2_NHGRI_mPonPyg2-v2.1_pri/
SiamangGCF_028878055.3_NHGRI_mSymSyn1-v2.1_pri/
Rhesus macaque, T2T-MMU8v2.0GCF_049350105.2_T2T-MMU8v2.0/
E. coli K-12 MG1655GCF_000005845.2_ASM584v2/

An ortholog table joined on gene names

An ortholog table in the .blocks shape has one row per orthologous group, one column per genome and a gene id in each cell. NCBI's eukaryotic annotation pipeline names a gene after its ortholog, so human TP53 is chimpanzee TP53 and gorilla TP53, and for genomes it annotated the table is a join on the Name attribute of each GFF3.

The join needs only the annotations, so the download is a GFF3 and a sequence report per genome:

# one RefSeq accession per line; the first is the genome the rows are anchored on
datasets download genome accession --inputfile accessions.txt \
  --include gff3,seq-report --filename genomes.zip
unzip genomes.zip

symbols_to_blocks.py reads each GFF3 once, writes a BED of its protein-coding genes and the table, and prints the column order it used:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/symbols_to_blocks.py
# --anchor names the genome whose genes are the rows; every other column is
# the ortholog of that gene, or a dot
python3 symbols_to_blocks.py --anchor human -o primates.blocks \
  human=human.gff.gz chimp=chimp.gff.gz bonobo=bonobo.gff.gz gorilla=gorilla.gff.gz \
  sumatran=sumatran.gff.gz bornean=bornean.gff.gz siamang=siamang.gff.gz macaque=macaque.gff.gz

symbols_to_blocks.py joins on the case-folded symbol and handles these cases:

  • A gene named with an NCBI LOC placeholder joins nothing. RefSeq names the salivary amylase copies that way in the other primates.
  • A symbol shared by several genes in one genome gets a row per copy, because a link joins one gene to one gene. The main case is the pseudoautosomal genes, annotated on both X and Y.
  • Open reading frame genes spell differently in the apes (human C1orf35 is chimp C1H1orf35), and the helper reads that back.

The helper prints how much of each column it filled.

Setting up each lane's assembly from its hub

Each genome is also a hub on genomes.jbrowse.org. A hub's config.json holds a whole JBrowse assembly: the 2bit sequence, an alias table that resolves the NC_ names in the BEDs, and the NCBI RefSeq genes. Each lane takes its assembly entry and gene track from its hub, so the ortholog table is the one file built here:

# a GenArk hub path is the accession cut into threes
curl -fO https://jbrowse.org/hubs/genark/GCF/028/858/775/GCF_028858775.2/config.json

The build relabels the lane and adds the short name as an alias, so a session can still say chimp:

{
  "name": "GCF_028858775.2",
  "displayName": "Chimpanzee (NHGRI_mPanTro3-v2.1)",
  "aliases": ["chimp"],
  "sequence": {
    "type": "ReferenceSequenceTrack",
    "trackId": "GCF_028858775.2-ReferenceSequenceTrack",
    "adapter": {
      "type": "TwoBitAdapter",
      "uri": "https://hgdownload.soe.ucsc.edu/hubs/GCF/028/858/775/GCF_028858775.2/GCF_028858775.2.2bit",
      "chromSizes": "https://hgdownload.soe.ucsc.edu/hubs/GCF/028/858/775/GCF_028858775.2/GCF_028858775.2.chrom.sizes.txt"
    }
  },
  "refNameAliases": {
    "adapter": {
      "type": "RefNameAliasAdapter",
      "refNameColumnHeaderName": "ucsc",
      "uri": "https://hgdownload.soe.ucsc.edu/hubs/GCF/028/858/775/GCF_028858775.2/GCF_028858775.2.chromAlias.txt"
    }
  }
}

refNameColumnHeaderName makes the UCSC names canonical, so the lane headers read chr19. Human is the exception: UCSC serves GRCh38 as hg38 with no GenArk hub, so the human lane is hg38:

Goes in the assemblies array of config.json. See Assemblies.

{
  "name": "hg38",
  "uri": "https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz",
  "refNameAliases": {
    "uri": "https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/hg38_aliases.txt"
  },
  "cytobands": "https://jbrowse.org/genomes/GRCh38/cytoBand.txt"
}
jbrowse add-assembly https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz \
  --name hg38 \
  --refNameAliases https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/hg38_aliases.txt \
  --config '{"cytobands":"https://jbrowse.org/genomes/GRCh38/cytoBand.txt"}'

hg38 is one of the genomes JBrowse Desktop hosts, with gene tracks already set up: on the start screen click Show all available genomes and pick it. To load the files of this config instead:

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:

https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz
https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz.fai
https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz.gzi

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

  • Genome name: hg38
  • refName aliases (under More options): https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/hg38_aliases.txt
  • cytobands (under More options): https://jbrowse.org/genomes/GRCh38/cytoBand.txt

Each lane draws gene models from a gene track on its assembly. For your own annotation, add one per genome from a bgzipped, tabix-indexed GFF3 (prep) that uses the assembly's refNames:

Goes in the tracks array of config.json. See Tracks.

{
  "type": "FeatureTrack",
  "trackId": "chimp_genes",
  "name": "chimp genes",
  "assemblyNames": ["GCF_028858775.2"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "chimp.sorted.gff3.gz"
  }
}
jbrowse add-track chimp.sorted.gff3.gz \
  --trackId chimp_genes \
  --name "chimp genes" \
  --assemblyNames GCF_028858775.2 \
  --load copy

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

  • Main file: chimp.sorted.gff3.gz

Click Next. JBrowse reads the adapter and track type off the file name. Then fill in:

  • Track name: chimp genes
  • Assembly: GCF_028858775.2

Click Add.

chimp.sorted.gff3.gz is relative to a config.json. Replace it with its URL or its path on this computer.

Loading the multi-genome ortholog track

One SyntenyTrack names every assembly, and blockAssemblies and bedLocations hold one entry per table column, in the order the helper printed. In grammar-of-graphics terms, the display's encoding.color is a color scale, and the cluster field maps each gene's ortholog group, named by its gene symbol, to a color:

  • A conserved gene is one color down the whole stack, and a lane missing it breaks the column.
  • A gene no group claims is grey.
  • A key naming the groups appears in the top right once the window holds few enough to list. Untick Show → Legend in the track menu to hide it.

Goes in the tracks array of config.json. See Tracks.

{
  "type": "SyntenyTrack",
  "trackId": "primate_orthologs",
  "name": "Primate orthologs by gene symbol (8 genomes, RefSeq)",
  "assemblyNames": [
    "hg38",
    "GCF_028858775.2",
    "GCF_029289425.2",
    "GCF_029281585.2",
    "GCF_028885655.2",
    "GCF_028885625.2",
    "GCF_028878055.3",
    "GCF_049350105.2"
  ],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "uri": "primates.blocks.gz",
    "blockAssemblies": [
      "hg38",
      "GCF_028858775.2",
      "GCF_029289425.2",
      "GCF_029281585.2",
      "GCF_028885655.2",
      "GCF_028885625.2",
      "GCF_028878055.3",
      "GCF_049350105.2"
    ],
    "bedLocations": [
      "human.bed.gz",
      "chimp.bed.gz",
      "bonobo.bed.gz",
      "gorilla.bed.gz",
      "sumatran.bed.gz",
      "bornean.bed.gz",
      "siamang.bed.gz",
      "macaque.bed.gz"
    ]
  },
  "displays": [
    {
      "type": "MultiWaySyntenyDisplay",
      "encoding": { "color": "cluster" }
    }
  ]
}
jbrowse add-track-json '{
  "type": "SyntenyTrack",
  "trackId": "primate_orthologs",
  "name": "Primate orthologs by gene symbol (8 genomes, RefSeq)",
  "assemblyNames": [
    "hg38",
    "GCF_028858775.2",
    "GCF_029289425.2",
    "GCF_029281585.2",
    "GCF_028885655.2",
    "GCF_028885625.2",
    "GCF_028878055.3",
    "GCF_049350105.2"
  ],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "uri": "primates.blocks.gz",
    "blockAssemblies": [
      "hg38",
      "GCF_028858775.2",
      "GCF_029289425.2",
      "GCF_029281585.2",
      "GCF_028885655.2",
      "GCF_028885625.2",
      "GCF_028878055.3",
      "GCF_049350105.2"
    ],
    "bedLocations": [
      "human.bed.gz",
      "chimp.bed.gz",
      "bonobo.bed.gz",
      "gorilla.bed.gz",
      "sumatran.bed.gz",
      "bornean.bed.gz",
      "siamang.bed.gz",
      "macaque.bed.gz"
    ]
  },
  "displays": [
    {
      "type": "MultiWaySyntenyDisplay",
      "encoding": { "color": "cluster" }
    }
  ]
}'

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": "primate_orthologs",
  "name": "Primate orthologs by gene symbol (8 genomes, RefSeq)",
  "assemblyNames": [
    "hg38",
    "GCF_028858775.2",
    "GCF_029289425.2",
    "GCF_029281585.2",
    "GCF_028885655.2",
    "GCF_028885625.2",
    "GCF_028878055.3",
    "GCF_049350105.2"
  ],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "uri": "primates.blocks.gz",
    "blockAssemblies": [
      "hg38",
      "GCF_028858775.2",
      "GCF_029289425.2",
      "GCF_029281585.2",
      "GCF_028885655.2",
      "GCF_028885625.2",
      "GCF_028878055.3",
      "GCF_049350105.2"
    ],
    "bedLocations": [
      "human.bed.gz",
      "chimp.bed.gz",
      "bonobo.bed.gz",
      "gorilla.bed.gz",
      "sumatran.bed.gz",
      "bornean.bed.gz",
      "siamang.bed.gz",
      "macaque.bed.gz"
    ]
  },
  "displays": [
    {
      "type": "MultiWaySyntenyDisplay",
      "encoding": { "color": "cluster" }
    }
  ]
}

primates.blocks.gz, human.bed.gz, chimp.bed.gz, bonobo.bed.gz, gorilla.bed.gz, sumatran.bed.gz, bornean.bed.gz, siamang.bed.gz, macaque.bed.gz are relative to a config.json. Replace each with its URL or its path on this computer.

That shows it in the linear view. For the synteny view, open Add → Linear synteny view, pick the track under Quick start, and click Launch.

Reading the TP53 neighbourhood across eight primates

In a linear genome view on human, the track draws a lane per primate under the human axis, each in that genome's coordinates. Each lane's header names the chromosome and span, with [rev] where the lane runs against human (lane headers). The ribbons color by strand by default (Color by → Strand, under Ribbons on the track menu): each ribbon shows whether its two lanes agree in orientation. The session below opens the TP53 neighbourhood:

Goes at the top level of config.json, replacing any defaultSession there. See Default session.

{
  "defaultSession": {
    "name": "TP53 neighbourhood across eight primates",
    "views": [
      {
        "type": "LinearGenomeView",
        "assembly": "hg38",
        "loc": "chr17:7,400,000-7,700,000",
        "tracks": [
          {
            "trackId": "primate_orthologs",
            "type": "MultiWaySyntenyDisplay",
            "ribbons": { "encoding": { "color": "strand" } },
            "height": 620
          }
        ]
      }
    ]
  }
}
jbrowse set-default-session --session - << 'EOF'
{
  "name": "TP53 neighbourhood across eight primates",
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,400,000-7,700,000",
      "tracks": [
        {
          "trackId": "primate_orthologs",
          "type": "MultiWaySyntenyDisplay",
          "ribbons": { "encoding": { "color": "strand" } },
          "height": 620
        }
      ]
    }
  ]
}
EOF

Open this session in JBrowse Web ↗

TP53 on human chr17 over seven primate lanes, each with its own RefSeq genes. The reversed siamang lane shows [rev] and draws its ribbons straight.
Open in JBrowse Web ↗

Large dataset: slow to open.

Or rebuild it from your own data:

Quickest: open the view, then File → Open track... for your files.

From scratch:

  1. Open your genome: Open new genome in JBrowse Desktop, or jbrowse add-assembly for JBrowse Web.This figure uses hg38, loaded from a .2bit genome.
  2. Add your track: File → Open track..., or check it in the track selector. Needs an MCScan .blocks file plus one BED per genome.This figure uses “Primate orthologs by gene symbol (8 genomes, RefSeq)”.
    1. Track menu → Color by → Ribbons → Strand
  3. Go to your region in the location box.This figure is at chr17:7,400,000-7,700,000.

Paste into a coding agent, with your goal on the first line.

My goal: [write yours, e.g. this view of my own files, or these track settings in my config.json]

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/demos/primate_orthologs/config.json
- Tracks:
  - Primate orthologs by gene symbol (8 genomes, RefSeq) (primate_orthologs), SyntenyTrack, an MCScan .blocks file plus one BED per genome, drawn as MultiWaySyntenyDisplay

Docs: https://jbrowse.org/jb2/docs/agents_authoring/ (writing a config), https://jbrowse.org/jb2/docs/agents/ (driving a running JBrowse). Use the jbrowse-authoring, jbrowse-hosted-data and jbrowse-capture skills if you have them. Check any config with `npx @jbrowse/cli validate`, then render it and look: a config that loads is not yet a track that drew.

The session spec that draws the view:
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,400,000-7,700,000",
      "tracks": [
        {
          "trackId": "primate_orthologs",
          "ribbons": {
            "encoding": {
              "color": "strand"
            }
          },
          "height": 620
        }
      ]
    }
  ]
}
Redraw the figure headlessly
cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,400,000-7,700,000",
      "tracks": [
        {
          "trackId": "primate_orthologs",
          "ribbons": {
            "encoding": {
              "color": "strand"
            }
          },
          "height": 620
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/primate_orthologs/config.json \
  --width 1500 --height 833 \
  --timeout 180000 \
  --spec session.json -o figure.png

The figure's clicks close the legend's gene cluster section, which this command does not do, so its picture differs there.

More: Using JBrowse with AI agents.

Adds these tracks to your config.json, styled as in the figure. Point each uri at your file (replace YOUR_FILE).

jbrowse add-track-json '{
  "type": "SyntenyTrack",
  "trackId": "primate_orthologs",
  "name": "Primate orthologs by gene symbol (8 genomes, RefSeq)",
  "assemblyNames": [
    "hg38",
    "GCF_028858775.2",
    "GCF_029289425.2",
    "GCF_029281585.2",
    "GCF_028885655.2",
    "GCF_028885625.2",
    "GCF_028878055.3",
    "GCF_049350105.2"
  ],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "ribbons": {
      "encoding": {
        "color": "strand"
      }
    },
    "height": 620
  }
}'

Run beside config.json, or add --out <dir>. Needs hg38, GCF_028858775.2, GCF_029289425.2, GCF_029281585.2, GCF_028885655.2, GCF_028885625.2, GCF_028878055.3, GCF_049350105.2 in the config (jbrowse add-assembly).

This view in a notebook, with jbrowse-anywidget. Swap a track's uri for your file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/primate_orthologs/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr17:7,400,000-7,700,000",
            "tracks": [
                {
                    "trackId": "primate_orthologs",
                    "ribbons": {
                        "encoding": {
                            "color": "strand"
                        }
                    },
                    "height": 620
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.

npx @jbrowse/img --config https://jbrowse.org/demos/primate_orthologs/config.json \
  --assembly hg38 --loc chr17:7,400,000-7,700,000 \
  --track primate_orthologs '{"ribbons":{"encoding":{"color":"strand"}},"height":620}' \
  --width 1500 --out figure.svg

For a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).

The session spec behind the figure, over this config.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,400,000-7,700,000",
      "tracks": [
        {
          "trackId": "primate_orthologs",
          "ribbons": {
            "encoding": {
              "color": "strand"
            }
          },
          "height": 620
        }
      ]
    }
  ]
}

Navigate to chr17:34,000,000-38,000,000 on 17q, where the strand color separates forward blocks from reversed ones.

17q over the seven primate lanes, ribbons colored by strand. Blue marks a block read backwards from the lane above.
Open in JBrowse Web ↗

Large dataset: slow to open.

Or rebuild it from your own data:

Quickest: open the view, then File → Open track... for your files.

From scratch:

  1. Open your genome: Open new genome in JBrowse Desktop, or jbrowse add-assembly for JBrowse Web.This figure uses hg38, loaded from a .2bit genome.
  2. Add your track: File → Open track..., or check it in the track selector. Needs an MCScan .blocks file plus one BED per genome.This figure uses “Primate orthologs by gene symbol (8 genomes, RefSeq)”.
    1. Track menu → Color by → Ribbons → Strand
  3. Go to your region in the location box.This figure is at chr17:34,000,000-38,000,000.

Paste into a coding agent, with your goal on the first line.

My goal: [write yours, e.g. this view of my own files, or these track settings in my config.json]

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/demos/primate_orthologs/config.json
- Tracks:
  - Primate orthologs by gene symbol (8 genomes, RefSeq) (primate_orthologs), SyntenyTrack, an MCScan .blocks file plus one BED per genome, drawn as MultiWaySyntenyDisplay

Docs: https://jbrowse.org/jb2/docs/agents_authoring/ (writing a config), https://jbrowse.org/jb2/docs/agents/ (driving a running JBrowse). Use the jbrowse-authoring, jbrowse-hosted-data and jbrowse-capture skills if you have them. Check any config with `npx @jbrowse/cli validate`, then render it and look: a config that loads is not yet a track that drew.

The session spec that draws the view:
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:34,000,000-38,000,000",
      "tracks": [
        {
          "trackId": "primate_orthologs",
          "ribbons": {
            "encoding": {
              "color": "strand"
            }
          },
          "height": 620
        }
      ]
    }
  ]
}
Redraw the figure headlessly
cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:34,000,000-38,000,000",
      "tracks": [
        {
          "trackId": "primate_orthologs",
          "ribbons": {
            "encoding": {
              "color": "strand"
            }
          },
          "height": 620
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/primate_orthologs/config.json \
  --width 1500 --height 860 \
  --timeout 180000 \
  --spec session.json -o figure.png

More: Using JBrowse with AI agents.

Adds these tracks to your config.json, styled as in the figure. Point each uri at your file (replace YOUR_FILE).

jbrowse add-track-json '{
  "type": "SyntenyTrack",
  "trackId": "primate_orthologs",
  "name": "Primate orthologs by gene symbol (8 genomes, RefSeq)",
  "assemblyNames": [
    "hg38",
    "GCF_028858775.2",
    "GCF_029289425.2",
    "GCF_029281585.2",
    "GCF_028885655.2",
    "GCF_028885625.2",
    "GCF_028878055.3",
    "GCF_049350105.2"
  ],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "ribbons": {
      "encoding": {
        "color": "strand"
      }
    },
    "height": 620
  }
}'

Run beside config.json, or add --out <dir>. Needs hg38, GCF_028858775.2, GCF_029289425.2, GCF_029281585.2, GCF_028885655.2, GCF_028885625.2, GCF_028878055.3, GCF_049350105.2 in the config (jbrowse add-assembly).

This view in a notebook, with jbrowse-anywidget. Swap a track's uri for your file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/primate_orthologs/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr17:34,000,000-38,000,000",
            "tracks": [
                {
                    "trackId": "primate_orthologs",
                    "ribbons": {
                        "encoding": {
                            "color": "strand"
                        }
                    },
                    "height": 620
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.

npx @jbrowse/img --config https://jbrowse.org/demos/primate_orthologs/config.json \
  --assembly hg38 --loc chr17:34,000,000-38,000,000 \
  --track primate_orthologs '{"ribbons":{"encoding":{"color":"strand"}},"height":620}' \
  --width 1500 --out figure.svg

For a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).

The session spec behind the figure, over this config.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:34,000,000-38,000,000",
      "tracks": [
        {
          "trackId": "primate_orthologs",
          "ribbons": {
            "encoding": {
              "color": "strand"
            }
          },
          "height": 620
        }
      ]
    }
  ]
}

Human chromosome 2 as two fused ape chromosomes

Human chromosome 2 is two ape chromosomes joined end to end. To see the join:

  • Open human over chimpanzee from Add → Linear synteny view, with primate_orthologs between them
  • Navigate the human row to chr2 and the chimpanzee row to chr12 and chr13, the two chromosomes that hold its halves
  • Pick Target in the palette button menu, which paints each ribbon by the chimpanzee chromosome it maps to
Human chr2 over chimpanzee chr12 and chr13, ribbons colored by chimpanzee chromosome.
Open in JBrowse Web ↗

Large dataset: slow to open.

Or rebuild it from your own data:

Quickest: open the view, then File → Open track... for your files.

From scratch:

  1. Open your genomes: Open new genome in JBrowse Desktop, then File → Open genome... for each of the rest, or jbrowse add-assembly for each in JBrowse Web.This figure's rows, top to bottom: hg38, GCF_028858775.2.
  2. Open the view: Add → Linear synteny view, and set the rows to those assemblies in the import form.
  3. Add your file: click the arrow between two rows and choose New track. Needs an MCScan .blocks file plus one BED per genome.Or pick a synteny track you already have under Quick start, which fills in the rows.This figure uses “Primate orthologs by gene symbol (8 genomes, RefSeq)”.
  4. Click Launch.
  5. Synteny view header → palette button → TargetThe palette button's tooltip reads "Color by: ...".
  6. Synteny display settings (the sliders button in the view header) → Opacity → drag to 1Lower values let dense overlapping ribbons show through each other.
  7. Synteny view header → View options → Rows → Re-order chromosomes...Reorders and flips each row so the best-hit blocks line up on a diagonal. The spec runs it once as the view opens; the menu item is the same thing on demand.
  8. Drag the bar below a synteny level to resize it.This figure's level is 300px tall.
  9. Row 1 (hg38)
    1. Go to your region in the location box.This figure is at chr2.
    2. View menu → Show → No tracks active button (unchecked)
  10. Row 2 (GCF_028858775.2)
    1. View menu → Show → No tracks active button (unchecked)

Paste into a coding agent, with your goal on the first line.

My goal: [write yours, e.g. this view of my own files, or these track settings in my config.json]

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/demos/primate_orthologs/config.json
- Tracks:
  - Primate orthologs by gene symbol (8 genomes, RefSeq) (primate_orthologs), SyntenyTrack, an MCScan .blocks file plus one BED per genome, drawn as LinearSyntenyDisplay

Docs: https://jbrowse.org/jb2/docs/agents_authoring/ (writing a config), https://jbrowse.org/jb2/docs/agents/ (driving a running JBrowse). Use the jbrowse-authoring, jbrowse-hosted-data and jbrowse-capture skills if you have them. Check any config with `npx @jbrowse/cli validate`, then render it and look: a config that loads is not yet a track that drew.

The session spec that draws the view:
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "hg38",
          "loc": "chr2",
          "hideNoTracksActive": true
        },
        {
          "assembly": "GCF_028858775.2",
          "displayedRegionNames": [
            "chr12",
            "chr13"
          ],
          "hideNoTracksActive": true
        }
      ],
      "tracks": [
        [
          "primate_orthologs"
        ]
      ],
      "encoding": {
        "color": "target",
        "opacity": 1
      },
      "autoDiagonalize": true,
      "levelHeights": [
        300
      ]
    }
  ]
}
Redraw the figure headlessly
cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "hg38",
          "loc": "chr2",
          "hideNoTracksActive": true
        },
        {
          "assembly": "GCF_028858775.2",
          "displayedRegionNames": [
            "chr12",
            "chr13"
          ],
          "hideNoTracksActive": true
        }
      ],
      "tracks": [
        [
          "primate_orthologs"
        ]
      ],
      "encoding": {
        "color": "target",
        "opacity": 1
      },
      "autoDiagonalize": true,
      "levelHeights": [
        300
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "fusion site",
    "leader": true,
    "anchor": {
      "view": [
        0,
        0
      ],
      "loc": "chr2:113,600,000",
      "fracY": 1
    },
    "dx": 0,
    "dy": 110
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/primate_orthologs/config.json \
  --width 1500 --height 600 \
  --timeout 120000 \
  --spec session.json --annotations callouts.json -o figure.png

More: Using JBrowse with AI agents.

This view in a notebook, with jbrowse-anywidget. Swap a track's uri for your file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/primate_orthologs/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearSyntenyView",
            "views": [
                {
                    "assembly": "hg38",
                    "loc": "chr2",
                    "hideNoTracksActive": True
                },
                {
                    "assembly": "GCF_028858775.2",
                    "displayedRegionNames": [
                        "chr12",
                        "chr13"
                    ],
                    "hideNoTracksActive": True
                }
            ],
            "tracks": [
                [
                    "primate_orthologs"
                ]
            ],
            "encoding": {
                "color": "target",
                "opacity": 1
            },
            "autoDiagonalize": True,
            "levelHeights": [
                300
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "hg38",
          "loc": "chr2",
          "hideNoTracksActive": true
        },
        {
          "assembly": "GCF_028858775.2",
          "displayedRegionNames": [
            "chr12",
            "chr13"
          ],
          "hideNoTracksActive": true
        }
      ],
      "tracks": [
        [
          "primate_orthologs"
        ]
      ],
      "encoding": {
        "color": "target",
        "opacity": 1
      },
      "autoDiagonalize": true,
      "levelHeights": [
        300
      ]
    }
  ]
}
JSON

npx @jbrowse/img synteny --config https://jbrowse.org/demos/primate_orthologs/config.json \
  --spec session.json \
  --width 1500 --out figure.svg

For a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).

The session spec behind the figure, over this config.

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "hg38",
          "loc": "chr2",
          "hideNoTracksActive": true
        },
        {
          "assembly": "GCF_028858775.2",
          "displayedRegionNames": [
            "chr12",
            "chr13"
          ],
          "hideNoTracksActive": true
        }
      ],
      "tracks": [
        [
          "primate_orthologs"
        ]
      ],
      "encoding": {
        "color": "target",
        "opacity": 1
      },
      "autoDiagonalize": true,
      "levelHeights": [
        300
      ]
    }
  ]
}

In the multi-lane view, a lane whose genome holds the window's genes on two contigs shows the contig with more of them and names the other in its header. Show ⟨contig⟩ in this lane on the header menu swaps the lane onto it.

Joining bacterial annotations (E. coli)

Genes NCBI left unnamed, the LOC genes above, are common in a bacterial annotation: RefSeq's Prokaryotic Genome Annotation Pipeline (PGAP) writes a gene's locus tag into its Name when it has no symbol, and renames genes between releases. Older PGAP runs gave every gene a locus tag and no symbol, so counting the named genes in an annotation shows whether a genome will join before anything is built:

gzip -dc strain.gff.gz | awk -F'\t' '$3 == "gene" && $9 ~ /;gene=/' | wc -l

The join is the same command with three flags for PGAP:

# --unnamed swaps the LOC pattern for the locus-tag shape PGAP falls back to,
# so a hypothetical protein joins nothing; --merge-cited joins a gene PGAP
# renamed to the gene it was annotated from; --pseudogenes keeps a gene NCBI
# writes as a pseudogene feature, such as K-12's wbbL
python3 symbols_to_blocks.py --anchor MG1655 -o ecoli.blocks --unnamed '_RS[0-9]+$' --merge-cited --pseudogenes \
  MG1655=MG1655.gff.gz Sakai=Sakai.gff.gz CFT073=CFT073.gff.gz Sflexneri_301=Sflexneri_301.gff.gz

PGAP writes on each CDS the protein it annotated the gene from (similar to AA sequence:RefSeq:NP_416533.1, the K-12 gnd protein), and --merge-cited reads that note to join K-12's gnd to the gndA most strains carry.

A lane draws its genes from the BED and the gene track, so a strain's assembly is its chromosome's name and length. The build writes <strain>.chrom.sizes, one tab-separated line, and loads it as a ChromSizesAdapter:

Goes in the assemblies array of config.json. See Assemblies.

{ "name": "MG1655", "uri": "MG1655.chrom.sizes" }
jbrowse add-assembly MG1655.chrom.sizes \
  --name MG1655 \
  --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:

MG1655.chrom.sizes

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

  • Genome name: MG1655

MG1655.chrom.sizes is relative to a config.json. Replace it with its URL or its path on this computer.

Each strain then takes a gene track like the chimpanzee one above, and the SyntenyTrack lists strains where the primate track lists primates. The O-antigen cluster between galF and gnd holds the genes that build a strain's surface sugar chain, a different set in each serotype. The session opens it on the hosted config, which has every strain, with height set to fit the stack:

Goes at the top level of config.json, replacing any defaultSession there. See Default session.

{
  "defaultSession": {
    "name": "The O-antigen cluster across 44 genomes",
    "views": [
      {
        "type": "LinearGenomeView",
        "assembly": "MG1655",
        "loc": "NC_000913.3:2,095,000-2,115,000",
        "tracks": [
          {
            "trackId": "ecoli_orthologs",
            "type": "MultiWaySyntenyDisplay",
            "height": 1500
          }
        ]
      }
    ]
  }
}
jbrowse set-default-session --session - << 'EOF'
{
  "name": "The O-antigen cluster across 44 genomes",
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "MG1655",
      "loc": "NC_000913.3:2,095,000-2,115,000",
      "tracks": [
        {
          "trackId": "ecoli_orthologs",
          "type": "MultiWaySyntenyDisplay",
          "height": 1500
        }
      ]
    }
  ]
}
EOF

Open this session in JBrowse Web ↗

The O-antigen cluster on K-12 over the E. coli and Shigella lanes, each with its own RefSeq genes.
Open in JBrowse Web ↗

Large dataset: slow to open.

Or rebuild it from your own data:

Quickest: open the view, then File → Open track... for your files.

From scratch:

  1. Open your genome: Open new genome in JBrowse Desktop, or jbrowse add-assembly for JBrowse Web.This figure uses MG1655, loaded from a .chrom.sizes file.
  2. Add your track: File → Open track..., or check it in the track selector. Needs an MCScan .blocks file plus one BED per genome.This figure uses “E. coli orthologs by gene symbol (44 genomes, RefSeq)”.
    1. Track menu → Color by → Ribbons → Solid color...
  3. Go to your region in the location box.This figure is at NC_000913.3:2,095,000-2,115,000.

Paste into a coding agent, with your goal on the first line.

My goal: [write yours, e.g. this view of my own files, or these track settings in my config.json]

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/demos/ecoli_orthologs/config.json
- Tracks:
  - E. coli orthologs by gene symbol (44 genomes, RefSeq) (ecoli_orthologs), SyntenyTrack, an MCScan .blocks file plus one BED per genome, drawn as MultiWaySyntenyDisplay

Docs: https://jbrowse.org/jb2/docs/agents_authoring/ (writing a config), https://jbrowse.org/jb2/docs/agents/ (driving a running JBrowse). Use the jbrowse-authoring, jbrowse-hosted-data and jbrowse-capture skills if you have them. Check any config with `npx @jbrowse/cli validate`, then render it and look: a config that loads is not yet a track that drew.

The session spec that draws the view:
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "MG1655",
      "loc": "NC_000913.3:2,095,000-2,115,000",
      "tracks": [
        {
          "trackId": "ecoli_orthologs",
          "height": 1500,
          "ribbons": {
            "encoding": {
              "color": {
                "value": "rgb(130,130,130)"
              }
            }
          }
        }
      ]
    }
  ]
}
Redraw the figure headlessly
cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "MG1655",
      "loc": "NC_000913.3:2,095,000-2,115,000",
      "tracks": [
        {
          "trackId": "ecoli_orthologs",
          "height": 1500,
          "ribbons": {
            "encoding": {
              "color": {
                "value": "rgb(130,130,130)"
              }
            }
          }
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/ecoli_orthologs/config.json \
  --width 1500 --height 1740 \
  --timeout 240000 \
  --spec session.json -o figure.png

More: Using JBrowse with AI agents.

Adds these tracks to your config.json, styled as in the figure. Point each uri at your file (replace YOUR_FILE).

jbrowse add-track-json '{
  "type": "SyntenyTrack",
  "trackId": "ecoli_orthologs",
  "name": "E. coli orthologs by gene symbol (44 genomes, RefSeq)",
  "assemblyNames": [
    "MG1655",
    "DH10B",
    "Sakai",
    "EDL933",
    "CFT073",
    "UTI89",
    "S88",
    "UMN026",
    "IAI39",
    "IAI1",
    "55989",
    "ED1a",
    "2011C-3493",
    "E24377A",
    "HS",
    "SE11",
    "ATCC_8739",
    "SMS-3-5",
    "BL21_DE3",
    "APEC_O1",
    "Nissle_1917",
    "NCTC86",
    "Sflexneri_301",
    "Sdysenteriae_Sd197",
    "Sboydii_Sb227",
    "Ssonnei_53G",
    "ST540",
    "ST2747",
    "BL21_TaKaRa",
    "HMS174",
    "MG1655_TMP32XR1",
    "2009C-3133",
    "SaT040",
    "SRCC_1675",
    "644-PT8",
    "M19",
    "S30",
    "S56",
    "tolC",
    "WCHEC050613",
    "MGY",
    "C43_DE3",
    "C3026",
    "G749"
  ],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "height": 1500,
    "ribbons": {
      "encoding": {
        "color": {
          "value": "rgb(130,130,130)"
        }
      }
    }
  }
}'

Run beside config.json, or add --out <dir>. Needs MG1655, DH10B, Sakai, EDL933, CFT073, UTI89, S88, UMN026, IAI39, IAI1, 55989, ED1a, 2011C-3493, E24377A, HS, SE11, ATCC_8739, SMS-3-5, BL21_DE3, APEC_O1, Nissle_1917, NCTC86, Sflexneri_301, Sdysenteriae_Sd197, Sboydii_Sb227, Ssonnei_53G, ST540, ST2747, BL21_TaKaRa, HMS174, MG1655_TMP32XR1, 2009C-3133, SaT040, SRCC_1675, 644-PT8, M19, S30, S56, tolC, WCHEC050613, MGY, C43_DE3, C3026, G749 in the config (jbrowse add-assembly).

This view in a notebook, with jbrowse-anywidget. Swap a track's uri for your file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/ecoli_orthologs/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "MG1655",
            "loc": "NC_000913.3:2,095,000-2,115,000",
            "tracks": [
                {
                    "trackId": "ecoli_orthologs",
                    "height": 1500,
                    "ribbons": {
                        "encoding": {
                            "color": {
                                "value": "rgb(130,130,130)"
                            }
                        }
                    }
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.

npx @jbrowse/img --config https://jbrowse.org/demos/ecoli_orthologs/config.json \
  --assembly MG1655 --loc NC_000913.3:2,095,000-2,115,000 \
  --track ecoli_orthologs '{"height":1500,"ribbons":{"encoding":{"color":{"value":"rgb(130,130,130)"}}}}' \
  --width 1500 --out figure.svg

For a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).

The session spec behind the figure, over this config.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "MG1655",
      "loc": "NC_000913.3:2,095,000-2,115,000",
      "tracks": [
        {
          "trackId": "ecoli_orthologs",
          "height": 1500,
          "ribbons": {
            "encoding": {
              "color": {
                "value": "rgb(130,130,130)"
              }
            }
          }
        }
      ]
    }
  ]
}

Read the lanes from the top:

  • The K-12 derivatives sort to the top, since lanes stack by how many of the window's genes they place on one contig, and have the cluster gene for gene.
  • Below them the flanks chain down every lane: galF on one side, gnd (gndA in most lanes), ugd and wzzB on the other.
  • The interior is grey, except the rfb genes, wzx and wzy, which join wherever a strain has them.

symbols_to_blocks.py gives a symbol K-12 lacks a row of its own, so vioB is one color down IAI39 and the BL21 lanes. A gene PGAP left under its locus tag, such as ECOLC_RS24020 in the ATCC_8739 lane, has no row. Most of the grey is each serotype's sugar genes, which have no K-12 counterpart to join by name; OrthoFinder groups genes by protein sequence, which joins the ones the annotations named differently.

Reproduce it end to end

The primate script needs the tools under Prerequisites and works in three steps:

  1. Download the eight annotations and sequence reports, and keep the genes on the assembled chromosomes each report names, so no lane has a gene on an unplaced scaffold.
  2. Join the annotations on gene symbol into one table anchored on human.
  3. Write the config from each genome's hub entry and gene track, plus the ortholog track.
curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_primate_orthologs.sh
bash build_primate_orthologs.sh

The E. coli script also needs htslib, and works in three steps:

  1. Download each genome's annotation, sequence report and assembly report, name each lane after the report's strain field, and drop a genome the report calls neither E. coli nor Shigella.
  2. Keep each genome's longest sequence as its chromosome, so a lane follows one contig and no plasmid, and sort and index the GFF3 as in the web quickstart.
  3. Join the annotations on gene symbol with the PGAP flags, and write the config.
curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_ecoli_orthologs.sh
bash build_ecoli_orthologs.sh

See also

Citations