Skip to main content

Synteny from an ortholog table (grape, peach, cacao)

2 videos in this tutorial

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.8. Desktop beta builds are coming soon.

jcvi's MCScan lines up orthologous genes across more than two genomes at once, into one wide table with a column per species. We load that table directly, draw grape, peach and cacao as rows of a single synteny view, and then read one grape locus across all seven plant genomes without leaving grape's own view.

Prerequisites

On Debian/Ubuntu, apt install samtools tabix last-align gffread covers the aligner and the file tools; jcvi installs with pip install jcvi, datasets is a single-binary download, and node comes from nodejs.org.

Where the data comes from

Seven RefSeq assemblies, one per species, each fetched by accession with the datasets CLI.

Three genomes from one ortholog table

A linear synteny view stacks N genome rows with a ribbon band between each adjacent pair. This page builds a grape / peach / cacao stack from a single jcvi MCScan .blocks file, a cross-species ortholog table. An ortholog table compares annotated genes, so it spans species too divergent to align base by base; all-vs-all synteny covers genomes close enough for a PAF.

What a .blocks file is

A .blocks file is a tab-delimited table: one row per orthologous group, one column per genome, . where a genome has no member. The file names none of its columns, so blockAssemblies does, by position:

grape01	peach01	cacao01
grape02	peach02	cacao02
grape03	.	.

A real cell holds the annotation's own gene id (rna-XM_007225519.2 for NCBI). The table has no coordinates; one .bed per genome places each id.

One reference, or all against all

A table is reference-anchored when every row starts from one genome's gene, and all against all when a row is an orthogroup inferred across the genomes at once. The difference is in the pairs that leave the reference out. The adapter takes any two columns and never consults column 0, so either shape loads.

  • jcvi MCScan tables are anchored. A peach-cacao ortholog with no grape counterpart has no row, so any peach-cacao link runs through their shared grape genes. Direct vs transitive pairs measures that.
  • OrthoFinder infers each orthogroup across all genomes at once, so every pair of columns rests on the same inference. Synteny visualization (OrthoFinder orthogroups) builds a six-genome view that way.
  • MCScanX compares every pair into one .collinearity file. Converting one picks a reference, and a pair that leaves it out stays loadable as its own track.

A duplicated gene

A cell holds one gene id, and two conventions place a second copy.

mcscan writes a column per chain of synteny blocks, so a grape gene syntenic to two peach regions fills a second peach column. --iter caps the chains, and the run below pins it to one. At --iter=2:

grape01	peach01	peach01b
grape02	peach02	.
grape03	.	.

Name that column peach in blockAssemblies with peach.bed beside it, and both are drawn. A genome holding several columns is still one genome to the track, so the track's own assemblyNames names peach once.

The other convention is a copy per row, repeating the grape id:

grape01	peach01	cacao01
grape02	peach02a	cacao02
grape02	peach02b	cacao02
grape03	.	.

The grape-peach band draws a ribbon from grape02 to each copy, and the repeated cacao02 draws its ribbon twice. orthogroups_to_blocks.py writes this shape by default; the MCScanX converter keeps the best-scoring copy.

Producing the data

grape.blocks and the BEDs come from jcvi and the LAST aligner over the seven accessions. One accession supplies the genome, the annotation and (through gffread) the CDS, so the assembly and annotation are one build:

for sp in grape peach cacao; do
  gffread "$sp.gff3" -g "$sp.fa" -x "$sp.cds.fa"
  # --key=ID on both sides is what makes the two files join; --primary_only
  # keeps one transcript per gene, so a link is gene to gene
  python -m jcvi.formats.gff bed --type=mRNA --key=ID --primary_only \
    "$sp.gff3" -o "$sp.bed"
  python -m jcvi.formats.fasta format "$sp.cds.fa" "$sp.cds"
done

Both sides key on the mRNA's GFF3 ID. gffread names each CDS after it, and --key=ID writes it into BED column 4. For a key it cannot resolve, jcvi generates mrna_494685, which joins to nothing; --key=transcript_id and --key=Name produce that same unjoinable id on an NCBI annotation.

Then catalog orthologs against the reference, MCScan each pair, and join:

for sp in peach cacao; do
  # --no_strip_names keeps the ids matching the BEDs above
  python -m jcvi.compara.catalog ortholog --no_strip_names grape "$sp"
  # --iter=1 keeps one block per grape gene, which is one lane per mate
  python -m jcvi.compara.synteny mcscan grape.bed "grape.$sp.lifted.anchors" \
    --iter=1 -o "grape.$sp.i1.blocks"
done
python -m jcvi.formats.base join grape.peach.i1.blocks grape.cacao.i1.blocks \
  --noheader | cut -f1,2,4 > grape.blocks

Each per-pair table is grape then the mate, so the join emits the grape column twice and cut -f1,2,4 keeps it once, followed by one mate per lane, the order blockAssemblies and bedLocations list.

Each assembly also gets a refNameAliases file from the download's sequence report, since NCBI names sequences by accession. The adapter reads .blocks and BED files plain or gzipped.

Bringing your own ortholog table

MCScanBlocksAdapter needs two inputs, neither of them MCScan-specific:

  • a tab-delimited table, one row per orthogroup and one column per genome, each cell holding a single gene id (. or an empty cell for no ortholog)
  • one BED per column whose fourth field carries those same gene ids

Two columns is a valid table, so a reciprocal-best-hit list already works as a pairwise synteny track.

From MCScanX

mcscanx_to_anchors.py pivots a .collinearity file into a table, given the two-letter chromosome tag MCScanX uses for each genome:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/mcscanx_to_anchors.py
python3 mcscanx_to_anchors.py --gff xyz.gff --collinearity xyz.collinearity \
  --species vv=grape --species pp=peach --species tc=cacao

That writes grape.blocks and a BED per genome. The first --species is column 0, so a block between two non-reference genomes has nowhere to go and that pair is reached transitively. Where one reference gene has blocks against several genes, the best-scoring takes the cell.

--blocks-score appends the row's weakest pairing as a trailing column, which the adapter's attributeColumns names:

{
  "type": "SyntenyTrack",
  "trackId": "grape_peach_cacao_scored",
  "name": "Grape / peach / cacao (MCScanX, scored)",
  "assemblyNames": ["grape", "peach", "cacao"],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "uri": "grape.blocks",
    "blockAssemblies": ["grape", "peach", "cacao"],
    "bedLocations": [
      { "uri": "grape.bed" },
      { "uri": "peach.bed" },
      { "uri": "cacao.bed" }
    ],
    "attributeColumns": ["score"]
  }
}
jbrowse add-track-json '{
  "type": "SyntenyTrack",
  "trackId": "grape_peach_cacao_scored",
  "name": "Grape / peach / cacao (MCScanX, scored)",
  "assemblyNames": ["grape", "peach", "cacao"],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "uri": "grape.blocks",
    "blockAssemblies": ["grape", "peach", "cacao"],
    "bedLocations": [
      { "uri": "grape.bed" },
      { "uri": "peach.bed" },
      { "uri": "cacao.bed" }
    ],
    "attributeColumns": ["score"]
  }
}'

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": "grape_peach_cacao_scored",
  "name": "Grape / peach / cacao (MCScanX, scored)",
  "assemblyNames": ["grape", "peach", "cacao"],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "uri": "grape.blocks",
    "blockAssemblies": ["grape", "peach", "cacao"],
    "bedLocations": [
      { "uri": "grape.bed" },
      { "uri": "peach.bed" },
      { "uri": "cacao.bed" }
    ],
    "attributeColumns": ["score"]
  }
}

grape.blocks, grape.bed, peach.bed, cacao.bed are relative to a config.json. Replace each with its URL or its path on this computer.

Each named column becomes a feature attribute and an entry in the palette button's menu. RefName and strand handling is in the pairwise MCScan tutorial; given two --species the script writes that page's .anchors files, which draws a pair the table left out as a second track.

From OrthoFinder

Orthogroups.tsv is one row per orthogroup and one column per genome, with a header row, a leading id column and comma-separated gene lists per cell:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/orthogroups_to_blocks.py
python3 orthogroups_to_blocks.py Orthogroups.tsv -o grape.blocks \
  --bed grape=grape.bed --bed peach=peach.bed

The script prints the column order blockAssemblies needs. By default a duplicated gene becomes one row per copy. Synteny visualization (OrthoFinder orthogroups) builds a six-genome view this way.

From Ensembl Compara

Compara publishes one homology TSV per species, so the table is a download:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/compara_to_blocks.py
python3 compara_to_blocks.py Compara.116.protein_default.homologies.tsv.gz \
  --reference sorghum_bicolor=sorghum --species triticum_aestivum=wheat \
  --bed sorghum=sorghum.bed --bed wheat=wheat.bed

attributeColumns can name identity, homology_identity and goc_score the way the scored table above names score. A partner species the export lacks writes no table, with no error, so check each --species name against the file's homology_species column. Synteny visualization (a polyploid against itself) uses this route for one panel.

From reciprocal best BLAST hits

Reduce each direction of an all-vs-all blastp or DIAMOND run (-outfmt 6) to its best hit per query, then keep the pairs that agree both ways:

sort -k1,1 -k12,12gr grape_vs_peach.tsv | awk '!seen[$1]++ {print $1 "\t" $2}' > g2p
sort -k1,1 -k12,12gr peach_vs_grape.tsv | awk '!seen[$1]++ {print $1 "\t" $2}' > p2g
awk 'NR == FNR {best[$1] = $2; next} best[$2] == $1' p2g g2p > grape_peach.rbh

grape_peach.rbh is a two-column table, loadable as-is with blockAssemblies: ["grape", "peach"]. For more genomes, run the same reduction against one reference genome and outer-join the results on the reference gene:

export LC_ALL=C  # join and sort must agree on collation
join -t $'\t' -a1 -a2 -e . -o 0,1.2,2.2 \
  <(sort -k1,1 grape_peach.rbh) <(sort -k1,1 grape_cacao.rbh) > grape.blocks

The reference column is whichever genome you joined on, so direct vs transitive applies to any table built this way.

BED files

Only the first six BED fields are read. From a GFF3:

awk -F'\t' -v OFS='\t' '$3 == "gene" && match($9, /ID=[^;]+/) {
  id = substr($9, RSTART + 3, RLENGTH - 3)
  sub(/^gene:/, "", id)
  print $1, $4 - 1, $5, id, 0, $7
}' grape.gff3 > grape.bed

Ensembl namespaces its GFF3 ids (ID=gene:VIT_00000001) where its proteomes do not, hence the sub.

Column 1 must use the JBrowse assembly's sequence names. Column 4 must match the table's gene ids; the adapter's gotchas cover how ids get mangled, and jcvi dropping isoform suffixes is why --no_strip_names is passed. Column 6 is strand, and a ribbon draws inverted when the two ends disagree.

Setting up the three assemblies

Grape, peach and cacao each become an assembly (jbrowse add-assembly, in the script) whose name matches the track's assemblyNames and whose sequence names match its .bed. See the assemblies configuration guide for the JSON.

Loading the blocks file with MCScanBlocksAdapter

One track backs every band of the stack. blockAssemblies names every column in order and bedLocations gives the matching BED per column; the track can draw every genome they name, so the adapter needs no assemblyNames unless you mean to narrow it to fewer:

{
  "type": "SyntenyTrack",
  "trackId": "grape_peach_cacao_blocks",
  "name": "Grape / peach / cacao (MCScan blocks)",
  "assemblyNames": ["grape", "peach", "cacao"],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "uri": "grape.blocks.gz",
    "blockAssemblies": ["grape", "peach", "cacao"],
    "bedLocations": [
      { "uri": "grape.bed.gz" },
      { "uri": "peach.bed.gz" },
      { "uri": "cacao.bed.gz" }
    ]
  }
}
jbrowse add-track-json '{
  "type": "SyntenyTrack",
  "trackId": "grape_peach_cacao_blocks",
  "name": "Grape / peach / cacao (MCScan blocks)",
  "assemblyNames": ["grape", "peach", "cacao"],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "uri": "grape.blocks.gz",
    "blockAssemblies": ["grape", "peach", "cacao"],
    "bedLocations": [
      { "uri": "grape.bed.gz" },
      { "uri": "peach.bed.gz" },
      { "uri": "cacao.bed.gz" }
    ]
  }
}'

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": "grape_peach_cacao_blocks",
  "name": "Grape / peach / cacao (MCScan blocks)",
  "assemblyNames": ["grape", "peach", "cacao"],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "uri": "grape.blocks.gz",
    "blockAssemblies": ["grape", "peach", "cacao"],
    "bedLocations": [
      { "uri": "grape.bed.gz" },
      { "uri": "peach.bed.gz" },
      { "uri": "cacao.bed.gz" }
    ]
  }
}

grape.blocks.gz, grape.bed.gz, peach.bed.gz, cacao.bed.gz are relative to a config.json. Replace each with its URL or its path on this computer.

Stacking the three genomes

Add → Linear synteny view and pick grape_peach_cacao_blocks; each of its three assemblies becomes a row. The all-vs-all tutorial walks the dialog. The declarative equivalent, stacking peach-cacao-grape:

{
  "defaultSession": {
    "name": "Grape / Peach / Cacao multi-way synteny",
    "views": [
      {
        "type": "LinearSyntenyView",
        "displayName": "Peach - Cacao - Grape (MCScan blocks)",
        "views": [
          { "assembly": "peach" },
          { "assembly": "cacao" },
          { "assembly": "grape" }
        ],
        "tracks": [["grape_peach_cacao_blocks"], ["grape_peach_cacao_blocks"]],
        "colorBy": "reference",
        "autoDiagonalize": true
      }
    ]
  }
}
jbrowse set-default-session --session - << 'EOF'
{
  "name": "Grape / Peach / Cacao multi-way synteny",
  "views": [
    {
      "type": "LinearSyntenyView",
      "displayName": "Peach - Cacao - Grape (MCScan blocks)",
      "views": [
        { "assembly": "peach" },
        { "assembly": "cacao" },
        { "assembly": "grape" }
      ],
      "tracks": [["grape_peach_cacao_blocks"], ["grape_peach_cacao_blocks"]],
      "colorBy": "reference",
      "autoDiagonalize": true
    }
  ]
}
EOF

Open this session in JBrowse

tracks is one entry per band. autoDiagonalize reorders and flips each row's chromosomes on load so the ribbons run along the diagonal, and colorBy: "reference" anchors every band on the middle row.

Three genomes stacked peach-cacao-grape, with one MCScan .blocks file backing both synteny bands. autoDiagonalize has reordered and flipped each row's chromosomes so the ribbons run along the diagonal, and Color by → Reference anchors both bands on the shared middle row. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)

The steps behind the figure above, run against your own data.

  1. Open your genomes: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one), then File → Open genome... for each of the rest.This figure's rows, top to bottom: peach, cacao, grape.
  2. Open the view: Add → Linear synteny view, and set the rows to those assemblies in the import form.
  3. Point the import form at your own file: click the arrow between two rows, choose New track, and paste a URL or pick a local file.A synteny track the session already has is quicker: pick it under **Quick start**, which fills in the rows itself.This figure uses the “grape_peach_cacao_blocks” track for both bands.
  4. Click Launch.
  5. Synteny view header → palette button → ReferenceThe palette button's tooltip reads "Color by: ...". Reference is offered only in a stacked view of three or more genomes, where there is a shared reference to trace.
  6. Synteny view header → View options → Rows → Re-order chromosomesReorders 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.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fdemos%2Fgrape_peach_cacao%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22views%22%3A%5B%7B%22assembly%22%3A%22peach%22%7D%2C%7B%22assembly%22%3A%22cacao%22%7D%2C%7B%22assembly%22%3A%22grape%22%7D%5D%2C%22tracks%22%3A%5B%5B%22grape_peach_cacao_blocks%22%5D%2C%5B%22grape_peach_cacao_blocks%22%5D%5D%2C%22colorBy%22%3A%22reference%22%2C%22autoDiagonalize%22%3Atrue%7D%5D%7D&sessionName=JBrowse+docs%3A+multiway_synteny%2Fgrape_peach_cacao

This session spec pastes after &session=spec- on any JBrowse Web instance.

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "peach"
        },
        {
          "assembly": "cacao"
        },
        {
          "assembly": "grape"
        }
      ],
      "tracks": [
        [
          "grape_peach_cacao_blocks"
        ],
        [
          "grape_peach_cacao_blocks"
        ]
      ],
      "colorBy": "reference",
      "autoDiagonalize": true
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/grape_peach_cacao/config.json

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/grape_peach_cacao/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearSyntenyView",
            "views": [
                {
                    "assembly": "peach"
                },
                {
                    "assembly": "cacao"
                },
                {
                    "assembly": "grape"
                }
            ],
            "tracks": [
                [
                    "grape_peach_cacao_blocks"
                ],
                [
                    "grape_peach_cacao_blocks"
                ]
            ],
            "colorBy": "reference",
            "autoDiagonalize": True
        }
    ],
)
app  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "peach"
        },
        {
          "assembly": "cacao"
        },
        {
          "assembly": "grape"
        }
      ],
      "tracks": [
        [
          "grape_peach_cacao_blocks"
        ],
        [
          "grape_peach_cacao_blocks"
        ]
      ],
      "colorBy": "reference",
      "autoDiagonalize": true
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/grape_peach_cacao/config.json \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

Direct vs transitive pairs

The table is anchored on grape, so only pairs including grape are direct. A peach-cacao link had to pass through a shared grape gene, and any ortholog grape lost is absent. Put the reference in the middle (peach-grape-cacao) and every band is direct; the demo above stacks grape at the bottom.

The script counts, per column pair, the rows where both cells resolve. Every row has a grape gene, so a grape pair draws every row its mate fills, and peach-cacao falls short by whatever grape lost.

Zooming to a conserved block

Zoom to one block with grape in the middle, and turn on each genome's gene track with Show only genes.

Gene-level view of the same block, peach over grape over cacao with each genome's gene track on. The orthologs step across all three in the same order until the ribbons fan, where three grape copies meet one peach and one cacao ortholog. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)

The steps behind the figure above, run against your own data.

  1. Open your genomes: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one), then File → Open genome... for each of the rest.This figure's rows, top to bottom: peach, grape, cacao.
  2. Open the view: Add → Linear synteny view, and set the rows to those assemblies in the import form.
  3. Point the import form at your own file: click the arrow between two rows, choose New track, and paste a URL or pick a local file.A synteny track the session already has is quicker: pick it under **Quick start**, which fills in the rows itself.This figure uses the “grape_peach_cacao_blocks” track for both bands.
  4. Click Launch.
  5. Synteny display settings (the sliders button in the view header) → Curved lines (checked)
  6. Synteny view header → palette button → ReferenceThe palette button's tooltip reads "Color by: ...". Reference is offered only in a stacked view of three or more genomes, where there is a shared reference to trace.
  7. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Row 1 (peach) — This figure uses the “peach_genes” track.
  8. Track menu → Show only genes (checked)Row 1 (peach).
  9. Track menu → Set feature height → CompactRow 1 (peach).
  10. Track menu → Show... → Labels → AutoRow 1 (peach).
  11. Type your region of interest into the location box and press Enter.Row 1 (peach) — This figure is at G7:18,555,000-18,653,000.
  12. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Row 2 (grape) — This figure uses the “grape_genes” track.
  13. Track menu → Show only genes (checked)Row 2 (grape).
  14. Track menu → Set feature height → CompactRow 2 (grape).
  15. Track menu → Show... → Labels → AutoRow 2 (grape).
  16. Type your region of interest into the location box and press Enter.Row 2 (grape) — This figure is at 11:778,000-866,000.
  17. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Row 3 (cacao) — This figure uses the “cacao_genes” track.
  18. Track menu → Show only genes (checked)Row 3 (cacao).
  19. Track menu → Set feature height → CompactRow 3 (cacao).
  20. Track menu → Show... → Labels → AutoRow 3 (cacao).
  21. Type your region of interest into the location box and press Enter.Row 3 (cacao) — This figure is at 9:3,890,000-3,960,000.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fdemos%2Fgrape_peach_cacao%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22views%22%3A%5B%7B%22assembly%22%3A%22peach%22%2C%22loc%22%3A%22G7%3A18%2C555%2C000-18%2C653%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22peach_genes%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%2C%22displayMode%22%3A%22compact%22%2C%22showLabels%22%3A%22auto%22%7D%5D%7D%2C%7B%22assembly%22%3A%22grape%22%2C%22loc%22%3A%2211%3A778%2C000-866%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22grape_genes%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%2C%22displayMode%22%3A%22compact%22%2C%22showLabels%22%3A%22auto%22%7D%5D%7D%2C%7B%22assembly%22%3A%22cacao%22%2C%22loc%22%3A%229%3A3%2C890%2C000-3%2C960%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22cacao_genes%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%2C%22displayMode%22%3A%22compact%22%2C%22showLabels%22%3A%22auto%22%7D%5D%7D%5D%2C%22tracks%22%3A%5B%5B%22grape_peach_cacao_blocks%22%5D%2C%5B%22grape_peach_cacao_blocks%22%5D%5D%2C%22drawCurves%22%3Atrue%2C%22colorBy%22%3A%22reference%22%7D%5D%7D&sessionName=JBrowse+docs%3A+multiway_synteny%2Fgrape_peach_cacao_gene_orthologs

This session spec pastes after &session=spec- on any JBrowse Web instance.

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "peach",
          "loc": "G7:18,555,000-18,653,000",
          "tracks": [
            {
              "trackId": "peach_genes",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true,
              "displayMode": "compact",
              "showLabels": "auto"
            }
          ]
        },
        {
          "assembly": "grape",
          "loc": "11:778,000-866,000",
          "tracks": [
            {
              "trackId": "grape_genes",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true,
              "displayMode": "compact",
              "showLabels": "auto"
            }
          ]
        },
        {
          "assembly": "cacao",
          "loc": "9:3,890,000-3,960,000",
          "tracks": [
            {
              "trackId": "cacao_genes",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true,
              "displayMode": "compact",
              "showLabels": "auto"
            }
          ]
        }
      ],
      "tracks": [
        [
          "grape_peach_cacao_blocks"
        ],
        [
          "grape_peach_cacao_blocks"
        ]
      ],
      "drawCurves": true,
      "colorBy": "reference"
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/grape_peach_cacao/config.json

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/grape_peach_cacao/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearSyntenyView",
            "views": [
                {
                    "assembly": "peach",
                    "loc": "G7:18,555,000-18,653,000",
                    "tracks": [
                        {
                            "trackId": "peach_genes",
                            "type": "LinearBasicDisplay",
                            "showOnlyGenes": True,
                            "displayMode": "compact",
                            "showLabels": "auto"
                        }
                    ]
                },
                {
                    "assembly": "grape",
                    "loc": "11:778,000-866,000",
                    "tracks": [
                        {
                            "trackId": "grape_genes",
                            "type": "LinearBasicDisplay",
                            "showOnlyGenes": True,
                            "displayMode": "compact",
                            "showLabels": "auto"
                        }
                    ]
                },
                {
                    "assembly": "cacao",
                    "loc": "9:3,890,000-3,960,000",
                    "tracks": [
                        {
                            "trackId": "cacao_genes",
                            "type": "LinearBasicDisplay",
                            "showOnlyGenes": True,
                            "displayMode": "compact",
                            "showLabels": "auto"
                        }
                    ]
                }
            ],
            "tracks": [
                [
                    "grape_peach_cacao_blocks"
                ],
                [
                    "grape_peach_cacao_blocks"
                ]
            ],
            "drawCurves": True,
            "colorBy": "reference"
        }
    ],
)
app  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "peach",
          "loc": "G7:18,555,000-18,653,000",
          "tracks": [
            {
              "trackId": "peach_genes",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true,
              "displayMode": "compact",
              "showLabels": "auto"
            }
          ]
        },
        {
          "assembly": "grape",
          "loc": "11:778,000-866,000",
          "tracks": [
            {
              "trackId": "grape_genes",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true,
              "displayMode": "compact",
              "showLabels": "auto"
            }
          ]
        },
        {
          "assembly": "cacao",
          "loc": "9:3,890,000-3,960,000",
          "tracks": [
            {
              "trackId": "cacao_genes",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true,
              "displayMode": "compact",
              "showLabels": "auto"
            }
          ]
        }
      ],
      "tracks": [
        [
          "grape_peach_cacao_blocks"
        ],
        [
          "grape_peach_cacao_blocks"
        ]
      ],
      "drawCurves": true,
      "colorBy": "reference"
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/grape_peach_cacao/config.json \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

One locus against all seven genomes

grape.blocks carries seven columns, and a plain linear genome view on grape draws every mate at once:

  • Navigate to 11:778,000-866,000 and turn on the grape gene track.
  • Turn on Grape vs peach, cacao, arabidopsis, poplar, tomato, citrus (MCScan blocks), which renders as an LGVSyntenyDisplay: every mate in one pileup.
  • Pick Group by... → Mate assembly for a lane per genome.
One grape locus against six other plants, the same MCScan blocks track grouped by mate assembly. Each lane is one genome, so the lanes read as presence and absence down a column: peach, cacao, poplar and citrus keep most of the block, while arabidopsis and tomato, the one asterid, keep a scattered few. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)

The steps behind the figure above, run against your own data.

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses grape.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “grape_genes” track.
  3. Track menu → Show only genes (checked)“grape_genes”.
  4. Track menu → Set feature height → Compact“grape_genes”.
  5. Track menu → Show... → Labels → Auto“grape_genes”.
  6. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “grape_peach_cacao_blocks” track.
  7. Track menu → Group by... → Mate assemblySynteny tracks only: one section per assembly on the other side of the alignment.“grape_peach_cacao_blocks”.
  8. Track menu → Feature height → Custom... → 14px“grape_peach_cacao_blocks”.
  9. Drag the bar at the bottom edge of the track to resize it.“grape_peach_cacao_blocks”.
  10. Type your region of interest into the location box and press Enter.This figure is at 11:778,000-866,000.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fdemos%2Fgrape_peach_cacao%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22grape%22%2C%22loc%22%3A%2211%3A778%2C000-866%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22grape_genes%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%2C%22displayMode%22%3A%22compact%22%2C%22showLabels%22%3A%22auto%22%7D%2C%7B%22trackId%22%3A%22grape_peach_cacao_blocks%22%2C%22type%22%3A%22LGVSyntenyDisplay%22%2C%22groupBy%22%3A%7B%22type%22%3A%22mateAssembly%22%7D%2C%22featureHeight%22%3A14%2C%22height%22%3A140%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+multiway_synteny%2Fblocks_one_vs_all

This session spec pastes after &session=spec- on any JBrowse Web instance.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "grape",
      "loc": "11:778,000-866,000",
      "tracks": [
        {
          "trackId": "grape_genes",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact",
          "showLabels": "auto"
        },
        {
          "trackId": "grape_peach_cacao_blocks",
          "type": "LGVSyntenyDisplay",
          "groupBy": {
            "type": "mateAssembly"
          },
          "featureHeight": 14,
          "height": 140
        }
      ]
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/grape_peach_cacao/config.json

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/grape_peach_cacao/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "grape",
            "loc": "11:778,000-866,000",
            "tracks": [
                {
                    "trackId": "grape_genes",
                    "type": "LinearBasicDisplay",
                    "showOnlyGenes": True,
                    "displayMode": "compact",
                    "showLabels": "auto"
                },
                {
                    "trackId": "grape_peach_cacao_blocks",
                    "type": "LGVSyntenyDisplay",
                    "groupBy": {
                        "type": "mateAssembly"
                    },
                    "featureHeight": 14,
                    "height": 140
                }
            ]
        }
    ],
)
app  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "grape",
      "loc": "11:778,000-866,000",
      "tracks": [
        {
          "trackId": "grape_genes",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact",
          "showLabels": "auto"
        },
        {
          "trackId": "grape_peach_cacao_blocks",
          "type": "LGVSyntenyDisplay",
          "groupBy": {
            "type": "mateAssembly"
          },
          "featureHeight": 14,
          "height": 140
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/grape_peach_cacao/config.json \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

Each genome in its own coordinates

On grape's axis a lane reads as presence and absence and does not show where in peach those genes sit. Display types → Multi-way synteny display redraws the lanes in each genome's own coordinates:

  • each lane is fitted to its own genome over the orthologs the window brings in
  • one grey ribbon per ortholog group joins adjacent lanes, bridging past a lane that places nothing
  • any track whose features carry a mate per assembly feeds the same lanes, including an OrthoFinder table or an all-vs-all PAF

The same thing as a defaultSession:

{
  "defaultSession": {
    "name": "Grape multi-way synteny track",
    "views": [
      {
        "type": "LinearGenomeView",
        "assembly": "grape",
        "loc": "11:778,000-866,000",
        "tracks": [
          {
            "trackId": "grape_genes",
            "type": "LinearBasicDisplay",
            "showOnlyGenes": true,
            "displayMode": "compact"
          },
          {
            "trackId": "grape_peach_cacao_blocks",
            "type": "MultiWaySyntenyDisplay",
            "domain": [
              "peach",
              "cacao",
              "poplar",
              "citrus",
              "arabidopsis",
              "tomato"
            ],
            "height": 340
          }
        ]
      }
    ]
  }
}
jbrowse set-default-session --session - << 'EOF'
{
  "name": "Grape multi-way synteny track",
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "grape",
      "loc": "11:778,000-866,000",
      "tracks": [
        {
          "trackId": "grape_genes",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact"
        },
        {
          "trackId": "grape_peach_cacao_blocks",
          "type": "MultiWaySyntenyDisplay",
          "domain": [
            "peach",
            "cacao",
            "poplar",
            "citrus",
            "arabidopsis",
            "tomato"
          ],
          "height": 340
        }
      ]
    }
  ]
}
EOF

Open this session in JBrowse

The grape gene track over the same locus as a multi-way lane stack, one lane per genome from a single MCScan blocks track. The peach and cacao lanes draw the gene models from those genomes' gene tracks, the lanes without one draw the table's gene spans as boxes, and a chain bridges past a lane that places nothing to end at the last lane that does. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)

The steps behind the figure above, run against your own data.

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses grape.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “grape_genes” track.
  3. Track menu → Show only genes (checked)“grape_genes”.
  4. Track menu → Set feature height → Compact“grape_genes”.
  5. Track menu → Show... → Labels → Auto“grape_genes”.
  6. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “grape_peach_cacao_blocks” track.
  7. Drag the bar at the bottom edge of the track to resize it.“grape_peach_cacao_blocks”.
  8. Type your region of interest into the location box and press Enter.This figure is at 11:778,000-866,000.

Some settings have no written step yet — see the Session spec tab.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fdemos%2Fgrape_peach_cacao%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22grape%22%2C%22loc%22%3A%2211%3A778%2C000-866%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22grape_genes%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%2C%22displayMode%22%3A%22compact%22%2C%22showLabels%22%3A%22auto%22%7D%2C%7B%22trackId%22%3A%22grape_peach_cacao_blocks%22%2C%22type%22%3A%22MultiWaySyntenyDisplay%22%2C%22domain%22%3A%5B%22peach%22%2C%22cacao%22%2C%22poplar%22%2C%22citrus%22%2C%22arabidopsis%22%2C%22tomato%22%5D%2C%22height%22%3A340%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+multiway_synteny%2Flgv_track_lanes

This session spec pastes after &session=spec- on any JBrowse Web instance.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "grape",
      "loc": "11:778,000-866,000",
      "tracks": [
        {
          "trackId": "grape_genes",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact",
          "showLabels": "auto"
        },
        {
          "trackId": "grape_peach_cacao_blocks",
          "type": "MultiWaySyntenyDisplay",
          "domain": [
            "peach",
            "cacao",
            "poplar",
            "citrus",
            "arabidopsis",
            "tomato"
          ],
          "height": 340
        }
      ]
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/grape_peach_cacao/config.json

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/grape_peach_cacao/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "grape",
            "loc": "11:778,000-866,000",
            "tracks": [
                {
                    "trackId": "grape_genes",
                    "type": "LinearBasicDisplay",
                    "showOnlyGenes": True,
                    "displayMode": "compact",
                    "showLabels": "auto"
                },
                {
                    "trackId": "grape_peach_cacao_blocks",
                    "type": "MultiWaySyntenyDisplay",
                    "domain": [
                        "peach",
                        "cacao",
                        "poplar",
                        "citrus",
                        "arabidopsis",
                        "tomato"
                    ],
                    "height": 340
                }
            ]
        }
    ],
)
app  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "grape",
      "loc": "11:778,000-866,000",
      "tracks": [
        {
          "trackId": "grape_genes",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact",
          "showLabels": "auto"
        },
        {
          "trackId": "grape_peach_cacao_blocks",
          "type": "MultiWaySyntenyDisplay",
          "domain": [
            "peach",
            "cacao",
            "poplar",
            "citrus",
            "arabidopsis",
            "tomato"
          ],
          "height": 340
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/grape_peach_cacao/config.json \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

What a lane header shows

Each lane has its own scale, and its header shows it:

  • Left: where the lane starts, with [rev] where its gene order runs against grape's
  • Right: the lane's span, and its multiple of grape's span where that is not one. Spans snap to one of a few fixed multiples, so a pan rarely moves a lane's content
  • Ticks fall at one interval shared by every mate lane. A lane zoomed too far out for ticks draws none
  • The view's gridlines stop at the grape lane, the only lane they are true for
  • A lane with no gene track the session can read (GFF3, GTF, BigBed or BED) outlines the table's gene spans and labels them no annotation, which is the four BLOCKS_ONLY_SPECIES lanes here

Ordering the lanes

  • domain pins the lanes it names to the top; the rest follow densest-first over the whole fetched table, so the order holds across a pan
  • with Bridge lanes that place nothing off, a sparse lane mid-stack cuts every chain running through it, which densest-first guards against

Zooming to genes

Cut the window to a few genes and each ribbon connects one gene to one ortholog. A copy-number difference fans one gene into several, and a lone ortholog draws at gene size, centered in its lane. Hovering a ribbon highlights its ortholog group down every lane; clicking one opens the pair's details and keeps the group's ribbons outlined after the pointer leaves, until a click on empty canvas lets them go.

The same lanes cut to a few genes, with one ribbon clicked. Each ribbon links one gene to its ortholog in the lane below; the clicked group carries an outline down the lanes that chain it, and the details panel opens on the pair the click landed on. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)

The steps behind the figure above, run against your own data.

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses grape.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “grape_genes” track.
  3. Track menu → Show only genes (checked)“grape_genes”.
  4. Track menu → Set feature height → Compact“grape_genes”.
  5. Track menu → Show... → Labels → Auto“grape_genes”.
  6. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “grape_peach_cacao_blocks” track.
  7. Drag the bar at the bottom edge of the track to resize it.“grape_peach_cacao_blocks”.
  8. Type your region of interest into the location box and press Enter.This figure is at 11:828,000-866,000.

Some settings have no written step yet — see the Session spec tab.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fdemos%2Fgrape_peach_cacao%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22grape%22%2C%22loc%22%3A%2211%3A828%2C000-866%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22grape_genes%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%2C%22displayMode%22%3A%22compact%22%2C%22showLabels%22%3A%22auto%22%7D%2C%7B%22trackId%22%3A%22grape_peach_cacao_blocks%22%2C%22type%22%3A%22MultiWaySyntenyDisplay%22%2C%22domain%22%3A%5B%22peach%22%2C%22cacao%22%2C%22poplar%22%2C%22citrus%22%2C%22arabidopsis%22%2C%22tomato%22%5D%2C%22height%22%3A340%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+multiway_synteny%2Flgv_track_clicked

This session spec pastes after &session=spec- on any JBrowse Web instance.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "grape",
      "loc": "11:828,000-866,000",
      "tracks": [
        {
          "trackId": "grape_genes",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact",
          "showLabels": "auto"
        },
        {
          "trackId": "grape_peach_cacao_blocks",
          "type": "MultiWaySyntenyDisplay",
          "domain": [
            "peach",
            "cacao",
            "poplar",
            "citrus",
            "arabidopsis",
            "tomato"
          ],
          "height": 340
        }
      ]
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/grape_peach_cacao/config.json

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/grape_peach_cacao/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "grape",
            "loc": "11:828,000-866,000",
            "tracks": [
                {
                    "trackId": "grape_genes",
                    "type": "LinearBasicDisplay",
                    "showOnlyGenes": True,
                    "displayMode": "compact",
                    "showLabels": "auto"
                },
                {
                    "trackId": "grape_peach_cacao_blocks",
                    "type": "MultiWaySyntenyDisplay",
                    "domain": [
                        "peach",
                        "cacao",
                        "poplar",
                        "citrus",
                        "arabidopsis",
                        "tomato"
                    ],
                    "height": 340
                }
            ]
        }
    ],
)
app  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "grape",
      "loc": "11:828,000-866,000",
      "tracks": [
        {
          "trackId": "grape_genes",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact",
          "showLabels": "auto"
        },
        {
          "trackId": "grape_peach_cacao_blocks",
          "type": "MultiWaySyntenyDisplay",
          "domain": [
            "peach",
            "cacao",
            "poplar",
            "citrus",
            "arabidopsis",
            "tomato"
          ],
          "height": 340
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/grape_peach_cacao/config.json \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

The grape lanes from gene scale back out to the block: a hovered ribbon reads one ortholog group down the stack, and each zoom-out re-fits every lane's own frame to the anchor's widening window. Open the session this video starts in ↗

Open the session the video starts in ↗, then take the steps it shows:

  1. Hover a ribbon
  2. Zoom out

The steps behind the figure above, run against your own data.

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses grape.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “grape_genes” track.
  3. Track menu → Show only genes (checked)“grape_genes”.
  4. Track menu → Set feature height → Compact“grape_genes”.
  5. Track menu → Show... → Labels → Auto“grape_genes”.
  6. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “grape_peach_cacao_blocks” track.
  7. Drag the bar at the bottom edge of the track to resize it.“grape_peach_cacao_blocks”.
  8. Type your region of interest into the location box and press Enter.This figure is at 11:828,000-866,000.

Some settings have no written step yet — see the Session spec tab.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fdemos%2Fgrape_peach_cacao%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22grape%22%2C%22loc%22%3A%2211%3A828%2C000-866%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22grape_genes%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%2C%22displayMode%22%3A%22compact%22%2C%22showLabels%22%3A%22auto%22%7D%2C%7B%22trackId%22%3A%22grape_peach_cacao_blocks%22%2C%22type%22%3A%22MultiWaySyntenyDisplay%22%2C%22domain%22%3A%5B%22peach%22%2C%22cacao%22%2C%22poplar%22%2C%22citrus%22%2C%22arabidopsis%22%2C%22tomato%22%5D%2C%22height%22%3A340%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+synteny%2Fmultiway_zoom_out

This session spec pastes after &session=spec- on any JBrowse Web instance.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "grape",
      "loc": "11:828,000-866,000",
      "tracks": [
        {
          "trackId": "grape_genes",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact",
          "showLabels": "auto"
        },
        {
          "trackId": "grape_peach_cacao_blocks",
          "type": "MultiWaySyntenyDisplay",
          "domain": [
            "peach",
            "cacao",
            "poplar",
            "citrus",
            "arabidopsis",
            "tomato"
          ],
          "height": 340
        }
      ]
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/grape_peach_cacao/config.json

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/grape_peach_cacao/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "grape",
            "loc": "11:828,000-866,000",
            "tracks": [
                {
                    "trackId": "grape_genes",
                    "type": "LinearBasicDisplay",
                    "showOnlyGenes": True,
                    "displayMode": "compact",
                    "showLabels": "auto"
                },
                {
                    "trackId": "grape_peach_cacao_blocks",
                    "type": "MultiWaySyntenyDisplay",
                    "domain": [
                        "peach",
                        "cacao",
                        "poplar",
                        "citrus",
                        "arabidopsis",
                        "tomato"
                    ],
                    "height": 340
                }
            ]
        }
    ],
)
app  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "grape",
      "loc": "11:828,000-866,000",
      "tracks": [
        {
          "trackId": "grape_genes",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact",
          "showLabels": "auto"
        },
        {
          "trackId": "grape_peach_cacao_blocks",
          "type": "MultiWaySyntenyDisplay",
          "domain": [
            "peach",
            "cacao",
            "poplar",
            "citrus",
            "arabidopsis",
            "tomato"
          ],
          "height": 340
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/grape_peach_cacao/config.json \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

Restacking around a locus

Two routes reach the stacked view from the lanes:

  • From the lane track, Launch → Linear synteny view (visible region) in its track menu offers a row to every genome aligning in the window
  • From the scale bar, drag-select a locus and pick Launch → Linear synteny view. The dialog opens a row per genome with arrows to order them; moving grape between peach and cacao is the reference-in-the-middle layout from Direct vs transitive pairs
  • From a lane's header, click the ⋮ beside the lane's name or right-click the name: Re-anchor on peach turns the whole track around on that genome, and Open peach at the matching region opens it on its own with its gene track
A lane header's menu: reorder or hide the lane, open peach on its own at the span the lane is drawing, or re-anchor the whole track on it. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)

The steps behind the figure above, run against your own data.

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses grape.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “grape_peach_cacao_blocks” track.
  3. Drag the bar at the bottom edge of the track to resize it.
  4. Type your region of interest into the location box and press Enter.This figure is at 11:778,000-866,000.

Some settings have no written step yet — see the Session spec tab.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fdemos%2Fgrape_peach_cacao%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22grape%22%2C%22loc%22%3A%2211%3A778%2C000-866%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22grape_peach_cacao_blocks%22%2C%22type%22%3A%22MultiWaySyntenyDisplay%22%2C%22domain%22%3A%5B%22peach%22%2C%22cacao%22%2C%22poplar%22%5D%2C%22height%22%3A260%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+multiway_synteny%2Flane_header_menu

This session spec pastes after &session=spec- on any JBrowse Web instance.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "grape",
      "loc": "11:778,000-866,000",
      "tracks": [
        {
          "trackId": "grape_peach_cacao_blocks",
          "type": "MultiWaySyntenyDisplay",
          "domain": [
            "peach",
            "cacao",
            "poplar"
          ],
          "height": 260
        }
      ]
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/grape_peach_cacao/config.json

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/grape_peach_cacao/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "grape",
            "loc": "11:778,000-866,000",
            "tracks": [
                {
                    "trackId": "grape_peach_cacao_blocks",
                    "type": "MultiWaySyntenyDisplay",
                    "domain": [
                        "peach",
                        "cacao",
                        "poplar"
                    ],
                    "height": 260
                }
            ]
        }
    ],
)
app  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "grape",
      "loc": "11:778,000-866,000",
      "tracks": [
        {
          "trackId": "grape_peach_cacao_blocks",
          "type": "MultiWaySyntenyDisplay",
          "domain": [
            "peach",
            "cacao",
            "poplar"
          ],
          "height": 260
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/grape_peach_cacao/config.json \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

Restacking around one grape locus, from the lane reading above: a scale-bar selection raises Launch, the dialog lists a panel per genome and names the mates it can draw a lane for but not a panel, and one arrow moves the reference into the middle of the launched stack. Open the session this video starts in ↗

Open the session the video starts in ↗, then take the steps it shows:

  1. Drag across the scale bar
  2. Linear synteny view
  3. The reference opens on top
  4. Move grape between peach and cacao

The steps behind the figure above, run against your own data.

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses grape.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “grape_genes” track.
  3. Track menu → Show only genes (checked)“grape_genes”.
  4. Track menu → Set feature height → Compact“grape_genes”.
  5. Track menu → Show... → Labels → Auto“grape_genes”.
  6. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “grape_peach_cacao_blocks” track.
  7. Track menu → Group by... → Mate assemblySynteny tracks only: one section per assembly on the other side of the alignment.“grape_peach_cacao_blocks”.
  8. Track menu → Feature height → Custom... → 14px“grape_peach_cacao_blocks”.
  9. Drag the bar at the bottom edge of the track to resize it.“grape_peach_cacao_blocks”.
  10. Type your region of interest into the location box and press Enter.This figure is at 11:778,000-866,000.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fdemos%2Fgrape_peach_cacao%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22grape%22%2C%22loc%22%3A%2211%3A778%2C000-866%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22grape_genes%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%2C%22displayMode%22%3A%22compact%22%2C%22showLabels%22%3A%22auto%22%7D%2C%7B%22trackId%22%3A%22grape_peach_cacao_blocks%22%2C%22type%22%3A%22LGVSyntenyDisplay%22%2C%22groupBy%22%3A%7B%22type%22%3A%22mateAssembly%22%7D%2C%22featureHeight%22%3A14%2C%22height%22%3A140%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+synteny%2Frestack_around_locus

This session spec pastes after &session=spec- on any JBrowse Web instance.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "grape",
      "loc": "11:778,000-866,000",
      "tracks": [
        {
          "trackId": "grape_genes",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact",
          "showLabels": "auto"
        },
        {
          "trackId": "grape_peach_cacao_blocks",
          "type": "LGVSyntenyDisplay",
          "groupBy": {
            "type": "mateAssembly"
          },
          "featureHeight": 14,
          "height": 140
        }
      ]
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/grape_peach_cacao/config.json

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/grape_peach_cacao/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "grape",
            "loc": "11:778,000-866,000",
            "tracks": [
                {
                    "trackId": "grape_genes",
                    "type": "LinearBasicDisplay",
                    "showOnlyGenes": True,
                    "displayMode": "compact",
                    "showLabels": "auto"
                },
                {
                    "trackId": "grape_peach_cacao_blocks",
                    "type": "LGVSyntenyDisplay",
                    "groupBy": {
                        "type": "mateAssembly"
                    },
                    "featureHeight": 14,
                    "height": 140
                }
            ]
        }
    ],
)
app  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "grape",
      "loc": "11:778,000-866,000",
      "tracks": [
        {
          "trackId": "grape_genes",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact",
          "showLabels": "auto"
        },
        {
          "trackId": "grape_peach_cacao_blocks",
          "type": "LGVSyntenyDisplay",
          "groupBy": {
            "type": "mateAssembly"
          },
          "featureHeight": 14,
          "height": 140
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/grape_peach_cacao/config.json \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

Reproduce it end to end

build_grape_peach_cacao_synteny.sh runs everything above and writes a config.json with the assemblies, gene tracks, the synteny track and the stacked default session. Its BLOCKS_ONLY_SPECIES list is where the extra lanes come from; a genome added there needs only CDS and GFF3.

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_grape_peach_cacao_synteny.sh
bash build_grape_peach_cacao_synteny.sh
npx --yes serve grape_peach_cacao_build/jbrowse2  # then open the printed URL

The script needs the tools under Prerequisites.

See also