Skip to main content

Synteny from MCScan anchors (grape, peach)

TL;DR: a pairwise jcvi MCScan run writes two files that JBrowse loads as separate synteny tracks: .anchors (one orthologous gene pair per line, via MCScanAnchorsAdapter) and .anchors.simple (one synteny block per line, via MCScanSimpleAnchorsAdapter). Both pair genes by name, so each also needs a BED per genome mapping gene ids to coordinates.

Prerequisites

On Debian/Ubuntu, apt install samtools tabix wget last-align covers the aligner and the file tools; jcvi installs with pip install jcvi and node comes from nodejs.org.

Where the data comes from

Grape (Jaillon et al. 2007) and peach genomes and gene annotations, Ensembl Plants release 58.

What MCScan compares

MCScan works through gene annotations, so it finds synteny between species too divergent for minimap2 to line up base by base. An anchor is a gene pair, so there is no CIGAR and nothing to draw below a gene.

For three or more genomes from one MCScan run, see ortholog tables, which loads a .blocks table with one track backing every band.

What .anchors and .anchors.simple hold

.anchors is the gene-pair level. Each line is one orthologous pair and its alignment score, with ### separating synteny blocks:

###
VIT_201s0011g00070.1	Prupe.1G290900.1	1430
VIT_201s0011g00080.1	Prupe.1G290800.1	446
VIT_201s0011g00090.1	Prupe.1G290700.1	147

.anchors.simple is the same run reduced to one line per block: the first and last gene of the block on each side, a score, and the block's orientation:

VIT_201s0011g00070.1	VIT_201s0011g00910.1	Prupe.1G281700.1	Prupe.1G290900.1	149	-
VIT_201s0011g02000.1	VIT_201s0011g02280.2	Prupe.1G345900.1	Prupe.1G348100.1	53	-
VIT_201s0011g02300.1	VIT_201s0011g02530.1	Prupe.1G299800.1	Prupe.1G303200.1	39	+

.anchors.simple draws one ribbon per block where .anchors draws one per gene pair. Neither file carries coordinates; the BED files supply them.

A run of MCScan blocks on grape chr9 against peach Pp03. Top: .anchors alone, one ribbon per orthologous gene pair. Bottom: both files on the same band, so each block is the bundle of pairs it was reduced from. Open in JBrowse: Gene pairs ↗ · Blocks ↗

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: grape, peach.
  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. This one needs an MCScan .anchors file.A synteny track the session already has is quicker: pick it under **Quick start**, which fills in the rows itself.This figure uses “Grape peach synteny (MCScan, anchors)”.
  4. Click Launch.
  5. Synteny display settings (the sliders button in the view header) → Curved lines (unchecked)
  6. Drag the bar below a synteny level to resize it.This figure's level is 260px tall.
  7. Launch synteny view dialog → Collapse panels to rulers (checked)Checked by default. A row the launch gave no tracks opens as its ruler alone instead of a "No tracks active" block; any row expands again from its own controls afterwards.
  8. Type your region of interest into the location box and press Enter.Row 1 (grape) — This figure is at chr9:1-7,700,000.
  9. Type your region of interest into the location box and press Enter.Row 2 (peach) — This figure is at Pp03:2,100,000-6,900,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=test_data%2Fconfig_dotplot.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22tracks%22%3A%5B%5B%22grape_peach_synteny_mcscan%22%5D%5D%2C%22drawCurves%22%3Afalse%2C%22levelHeights%22%3A%5B260%5D%2C%22collapseEmptyRows%22%3Atrue%2C%22views%22%3A%5B%7B%22assembly%22%3A%22grape%22%2C%22loc%22%3A%22chr9%3A1-7%2C700%2C000%22%2C%22tracks%22%3A%5B%5D%7D%2C%7B%22assembly%22%3A%22peach%22%2C%22loc%22%3A%22Pp03%3A2%2C100%2C000-6%2C900%2C000%22%2C%22tracks%22%3A%5B%5D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+mcscan_synteny%2Fanchors

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

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "tracks": [
        [
          "grape_peach_synteny_mcscan"
        ]
      ],
      "drawCurves": false,
      "levelHeights": [
        260
      ],
      "collapseEmptyRows": true,
      "views": [
        {
          "assembly": "grape",
          "loc": "chr9:1-7,700,000",
          "tracks": []
        },
        {
          "assembly": "peach",
          "loc": "Pp03:2,100,000-6,900,000",
          "tracks": []
        }
      ]
    }
  ]
}

Loaded against config: test_data/config_dotplot.json

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",
      "tracks": [
        [
          "grape_peach_synteny_mcscan"
        ]
      ],
      "drawCurves": false,
      "levelHeights": [
        260
      ],
      "collapseEmptyRows": true,
      "views": [
        {
          "assembly": "grape",
          "loc": "chr9:1-7,700,000",
          "tracks": []
        },
        {
          "assembly": "peach",
          "loc": "Pp03:2,100,000-6,900,000",
          "tracks": []
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_dotplot.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 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: grape, peach.
  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. This one needs an MCScan .anchors.simple file.A synteny track the session already has is quicker: pick it under **Quick start**, which fills in the rows itself.This figure uses “Grape peach synteny (MCScan, simple anchors)”.
  4. 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. This one needs an MCScan .anchors file.This figure uses “Grape peach synteny (MCScan, anchors)”.
  5. Click Launch.
  6. Synteny display settings (the sliders button in the view header) → Curved lines (unchecked)
  7. Drag the bar below a synteny level to resize it.This figure's level is 260px tall.
  8. Launch synteny view dialog → Collapse panels to rulers (checked)Checked by default. A row the launch gave no tracks opens as its ruler alone instead of a "No tracks active" block; any row expands again from its own controls afterwards.
  9. Type your region of interest into the location box and press Enter.Row 1 (grape) — This figure is at chr9:1-7,700,000.
  10. Type your region of interest into the location box and press Enter.Row 2 (peach) — This figure is at Pp03:2,100,000-6,900,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=test_data%2Fconfig_dotplot.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22tracks%22%3A%5B%5B%22grape_peach_synteny_mcscan_simple%22%2C%22grape_peach_synteny_mcscan%22%5D%5D%2C%22drawCurves%22%3Afalse%2C%22levelHeights%22%3A%5B260%5D%2C%22collapseEmptyRows%22%3Atrue%2C%22views%22%3A%5B%7B%22assembly%22%3A%22grape%22%2C%22loc%22%3A%22chr9%3A1-7%2C700%2C000%22%2C%22tracks%22%3A%5B%5D%7D%2C%7B%22assembly%22%3A%22peach%22%2C%22loc%22%3A%22Pp03%3A2%2C100%2C000-6%2C900%2C000%22%2C%22tracks%22%3A%5B%5D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+mcscan_synteny%2Fanchors_simple

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

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "tracks": [
        [
          "grape_peach_synteny_mcscan_simple",
          "grape_peach_synteny_mcscan"
        ]
      ],
      "drawCurves": false,
      "levelHeights": [
        260
      ],
      "collapseEmptyRows": true,
      "views": [
        {
          "assembly": "grape",
          "loc": "chr9:1-7,700,000",
          "tracks": []
        },
        {
          "assembly": "peach",
          "loc": "Pp03:2,100,000-6,900,000",
          "tracks": []
        }
      ]
    }
  ]
}

Loaded against config: test_data/config_dotplot.json

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",
      "tracks": [
        [
          "grape_peach_synteny_mcscan_simple",
          "grape_peach_synteny_mcscan"
        ]
      ],
      "drawCurves": false,
      "levelHeights": [
        260
      ],
      "collapseEmptyRows": true,
      "views": [
        {
          "assembly": "grape",
          "loc": "chr9:1-7,700,000",
          "tracks": []
        },
        {
          "assembly": "peach",
          "loc": "Pp03:2,100,000-6,900,000",
          "tracks": []
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_dotplot.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.

BED files

One BED per genome, prepared from its GFF3 before the ortholog run. Only the first six columns are read, and column 4 must match the anchor gene ids byte for byte:

chr1	12836	26777	VIT_201s0011g00010.1	0	+
chr1	33170	35791	VIT_201s0011g00030.1	0	+

Column 1 must use the same reference sequence names as the JBrowse assembly.

Which mismatches are loud and which are silent is in the synteny track guide. The one that bites here is jcvi stripping isoform suffixes unless run with --no_strip_names, which the script passes.

Producing the data

One jcvi command writes both anchor files and the BEDs are prepared from each GFF3 beforehand:

python -m jcvi.formats.gff bed --type=mRNA --key=transcript_id \
  --primary_only grape.gff3.gz -o grape.bed
python -m jcvi.formats.gff bed --type=mRNA --key=transcript_id \
  --primary_only peach.gff3.gz -o peach.bed
python -m jcvi.formats.fasta format grape.cds.fa.gz grape.cds
python -m jcvi.formats.fasta format peach.cds.fa.gz peach.cds

python -m jcvi.compara.catalog ortholog --no_strip_names grape peach

That leaves grape.peach.anchors and grape.peach.anchors.simple in the working directory. The adapters read anchors and BED files plain or gzipped.

Loading both tracks

Each adapter takes the anchor file plus the two BEDs, and assemblyNames lists the genomes in the order the anchor columns are in (column 1's genome first):

{
  "type": "SyntenyTrack",
  "trackId": "grape_peach_anchors",
  "name": "Grape peach synteny (MCScan, anchors)",
  "assemblyNames": ["grape", "peach"],
  "adapter": {
    "type": "MCScanAnchorsAdapter",
    "uri": "grape.peach.anchors.gz",
    "bed1": "grape.bed.gz",
    "bed2": "peach.bed.gz",
    "assemblyNames": ["grape", "peach"]
  }
}
jbrowse add-track grape.peach.anchors.gz \
  --trackId grape_peach_anchors \
  --name "Grape peach synteny (MCScan, anchors)" \
  --assemblyNames grape,peach \
  --bed1 grape.bed.gz \
  --bed2 peach.bed.gz \
  --load copy

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_anchors",
  "name": "Grape peach synteny (MCScan, anchors)",
  "assemblyNames": ["grape", "peach"],
  "adapter": {
    "type": "MCScanAnchorsAdapter",
    "uri": "grape.peach.anchors.gz",
    "bed1": "grape.bed.gz",
    "bed2": "peach.bed.gz",
    "assemblyNames": ["grape", "peach"]
  }
}

The simple-anchors track is the same shape with the adapter type and file swapped:

{
  "type": "SyntenyTrack",
  "trackId": "grape_peach_anchors_simple",
  "name": "Grape peach synteny (MCScan, simple anchors)",
  "assemblyNames": ["grape", "peach"],
  "adapter": {
    "type": "MCScanSimpleAnchorsAdapter",
    "uri": "grape.peach.anchors.simple.gz",
    "bed1": "grape.bed.gz",
    "bed2": "peach.bed.gz",
    "assemblyNames": ["grape", "peach"]
  }
}
jbrowse add-track grape.peach.anchors.simple.gz \
  --trackId grape_peach_anchors_simple \
  --name "Grape peach synteny (MCScan, simple anchors)" \
  --assemblyNames grape,peach \
  --bed1 grape.bed.gz \
  --bed2 peach.bed.gz \
  --load copy

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_anchors_simple",
  "name": "Grape peach synteny (MCScan, simple anchors)",
  "assemblyNames": ["grape", "peach"],
  "adapter": {
    "type": "MCScanSimpleAnchorsAdapter",
    "uri": "grape.peach.anchors.simple.gz",
    "bed1": "grape.bed.gz",
    "bed2": "peach.bed.gz",
    "assemblyNames": ["grape", "peach"]
  }
}

bed1 and bed2 supply the coordinates, one per genome in assemblyNames order. Both adapters read the whole file into memory, which suits MCScan's scale; there is no MCScan equivalent of PIF.

Both tracks in one synteny view

Add → Linear synteny view, pick peach and grape, and turn on both tracks.

Peach and grape with both MCScan tracks loaded. The ribbons between the panels are the per-gene .anchors pairs; the strand-colored bars inside each panel are the .anchors.simple blocks. The marks along the top of the band are anchors whose grape gene is on a chromosome this panel is not showing. Most of this peach chromosome has counterparts elsewhere in grape. Open this view in JBrowse ↗

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.
  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. This one needs an MCScan .anchors file.A synteny track the session already has is quicker: pick it under **Quick start**, which fills in the rows itself.This figure uses “Grape peach synteny (MCScan, anchors)”.
  4. 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. This one needs an MCScan .anchors.simple file.This figure uses “Grape peach synteny (MCScan, simple anchors)”.
  5. Click Launch.
  6. Synteny display settings (the sliders button in the view header) → Curved lines (checked)
  7. Drag the bar below a synteny level to resize it.This figure's level is 236px tall.
  8. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file. This one needs an MCScan .anchors.simple file.Row 1 (peach) — This figure uses “Grape peach synteny (MCScan, simple anchors)”.
  9. Drag the bar at the bottom edge of the track to resize it.Row 1 (peach).
  10. Type your region of interest into the location box and press Enter.Row 1 (peach) — This figure is at Pp05:7,380,181-14,148,567.
  11. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file. This one needs an MCScan .anchors.simple file.Row 2 (grape) — This figure uses “Grape peach synteny (MCScan, simple anchors)”.
  12. Drag the bar at the bottom edge of the track to resize it.Row 2 (grape).
  13. Type your region of interest into the location box and press Enter.Row 2 (grape) — This figure is at chr2:1-7,112,179.

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=test_data%2Fconfig_dotplot.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22drawCurves%22%3Atrue%2C%22tracks%22%3A%5B%5B%22grape_peach_synteny_mcscan%22%2C%22grape_peach_synteny_mcscan_simple%22%5D%5D%2C%22levelHeights%22%3A%5B236%5D%2C%22views%22%3A%5B%7B%22assembly%22%3A%22peach%22%2C%22loc%22%3A%22Pp05%3A7%2C380%2C181-14%2C148%2C567%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22grape_peach_synteny_mcscan_simple%22%2C%22type%22%3A%22LGVSyntenyDisplay%22%2C%22height%22%3A60%7D%5D%7D%2C%7B%22assembly%22%3A%22grape%22%2C%22loc%22%3A%22chr2%3A1-7%2C112%2C179%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22grape_peach_synteny_mcscan_simple%22%2C%22type%22%3A%22LGVSyntenyDisplay%22%2C%22height%22%3A60%7D%5D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+mcscan_anchors

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

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "drawCurves": true,
      "tracks": [
        [
          "grape_peach_synteny_mcscan",
          "grape_peach_synteny_mcscan_simple"
        ]
      ],
      "levelHeights": [
        236
      ],
      "views": [
        {
          "assembly": "peach",
          "loc": "Pp05:7,380,181-14,148,567",
          "tracks": [
            {
              "trackId": "grape_peach_synteny_mcscan_simple",
              "type": "LGVSyntenyDisplay",
              "height": 60
            }
          ]
        },
        {
          "assembly": "grape",
          "loc": "chr2:1-7,112,179",
          "tracks": [
            {
              "trackId": "grape_peach_synteny_mcscan_simple",
              "type": "LGVSyntenyDisplay",
              "height": 60
            }
          ]
        }
      ]
    }
  ]
}

Loaded against config: test_data/config_dotplot.json

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",
      "drawCurves": true,
      "tracks": [
        [
          "grape_peach_synteny_mcscan",
          "grape_peach_synteny_mcscan_simple"
        ]
      ],
      "levelHeights": [
        236
      ],
      "views": [
        {
          "assembly": "peach",
          "loc": "Pp05:7,380,181-14,148,567",
          "tracks": [
            {
              "trackId": "grape_peach_synteny_mcscan_simple",
              "type": "LGVSyntenyDisplay",
              "height": 60
            }
          ]
        },
        {
          "assembly": "grape",
          "loc": "chr2:1-7,112,179",
          "tracks": [
            {
              "trackId": "grape_peach_synteny_mcscan_simple",
              "type": "LGVSyntenyDisplay",
              "height": 60
            }
          ]
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_dotplot.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 block track is drawn here as an LGVSyntenyDisplay, a synteny track drawn as features in an ordinary linear genome view row. Naming a display type takes the full displays array:

{
  "type": "SyntenyTrack",
  "trackId": "grape_peach_anchors_simple",
  "name": "Grape peach synteny (MCScan, simple anchors)",
  "assemblyNames": ["grape", "peach"],
  "adapter": {
    "type": "MCScanSimpleAnchorsAdapter",
    "uri": "grape.peach.anchors.simple.gz",
    "bed1": "grape.bed.gz",
    "bed2": "peach.bed.gz",
    "assemblyNames": ["grape", "peach"]
  },
  "displays": [
    {
      "type": "LGVSyntenyDisplay",
      "displayId": "grape_peach_anchors_simple-LGVSyntenyDisplay",
      "height": 60
    }
  ]
}
jbrowse add-track-json '{
  "type": "SyntenyTrack",
  "trackId": "grape_peach_anchors_simple",
  "name": "Grape peach synteny (MCScan, simple anchors)",
  "assemblyNames": ["grape", "peach"],
  "adapter": {
    "type": "MCScanSimpleAnchorsAdapter",
    "uri": "grape.peach.anchors.simple.gz",
    "bed1": "grape.bed.gz",
    "bed2": "peach.bed.gz",
    "assemblyNames": ["grape", "peach"]
  },
  "displays": [
    {
      "type": "LGVSyntenyDisplay",
      "displayId": "grape_peach_anchors_simple-LGVSyntenyDisplay",
      "height": 60
    }
  ]
}'

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_anchors_simple",
  "name": "Grape peach synteny (MCScan, simple anchors)",
  "assemblyNames": ["grape", "peach"],
  "adapter": {
    "type": "MCScanSimpleAnchorsAdapter",
    "uri": "grape.peach.anchors.simple.gz",
    "bed1": "grape.bed.gz",
    "bed2": "peach.bed.gz",
    "assemblyNames": ["grape", "peach"]
  },
  "displays": [
    {
      "type": "LGVSyntenyDisplay",
      "displayId": "grape_peach_anchors_simple-LGVSyntenyDisplay",
      "height": 60
    }
  ]
}

A bar says a block is there and which way round it runs; the ribbons say whether the genes inside hold their order.

What an anchor looks like up close

Zoom to one block with both gene tracks on and set to Show only genes.

One MCScan block on grape chr19 against peach Pp04, both gene tracks set to Show only genes. Each ribbon is one .anchors line drawn across each gene's own extent; the genes between them have no anchor in this run. Open this view in JBrowse ↗

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: grape, peach.
  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. This one needs an MCScan .anchors file.A synteny track the session already has is quicker: pick it under **Quick start**, which fills in the rows itself.This figure uses “Grape peach synteny (MCScan, anchors)”.
  4. Click Launch.
  5. Synteny display settings (the sliders button in the view header) → Curved lines (unchecked)
  6. Drag the bar below a synteny level to resize it.This figure's level is 220px tall.
  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. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).Row 1 (grape) — This figure uses “Vvinifera_457_v2.1.gene.sorted.gff”.
  8. Track menu → Show only genes (checked)Row 1 (grape).
  9. Track menu → Set feature height → CompactRow 1 (grape).
  10. Track menu → Show... → Labels → AutoRow 1 (grape).
  11. Drag the bar at the bottom edge of the track to resize it.Row 1 (grape).
  12. Type your region of interest into the location box and press Enter.Row 1 (grape) — This figure is at chr19:4,950,000-5,100,000.
  13. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).Row 2 (peach) — This figure uses “Ppersica_298_v2.1.gene.sorted.gff3”.
  14. Track menu → Show only genes (checked)Row 2 (peach).
  15. Track menu → Set feature height → CompactRow 2 (peach).
  16. Track menu → Show... → Labels → AutoRow 2 (peach).
  17. Drag the bar at the bottom edge of the track to resize it.Row 2 (peach).
  18. Type your region of interest into the location box and press Enter.Row 2 (peach) — This figure is at Pp04:11,975,000-12,125,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=test_data%2Fconfig_dotplot.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22views%22%3A%5B%7B%22assembly%22%3A%22grape%22%2C%22loc%22%3A%22chr19%3A4%2C950%2C000-5%2C100%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%2C%22height%22%3A70%7D%5D%7D%2C%7B%22assembly%22%3A%22peach%22%2C%22loc%22%3A%22Pp04%3A11%2C975%2C000-12%2C125%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%2C%22height%22%3A70%7D%5D%7D%5D%2C%22tracks%22%3A%5B%5B%22grape_peach_synteny_mcscan%22%5D%5D%2C%22drawCurves%22%3Afalse%2C%22levelHeights%22%3A%5B220%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+mcscan_synteny%2Fgene_level

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

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "grape",
          "loc": "chr19:4,950,000-5,100,000",
          "tracks": [
            {
              "trackId": "grape_genes",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true,
              "displayMode": "compact",
              "showLabels": "auto",
              "height": 70
            }
          ]
        },
        {
          "assembly": "peach",
          "loc": "Pp04:11,975,000-12,125,000",
          "tracks": [
            {
              "trackId": "peach_genes",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true,
              "displayMode": "compact",
              "showLabels": "auto",
              "height": 70
            }
          ]
        }
      ],
      "tracks": [
        [
          "grape_peach_synteny_mcscan"
        ]
      ],
      "drawCurves": false,
      "levelHeights": [
        220
      ]
    }
  ]
}

Loaded against config: test_data/config_dotplot.json

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": "grape",
          "loc": "chr19:4,950,000-5,100,000",
          "tracks": [
            {
              "trackId": "grape_genes",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true,
              "displayMode": "compact",
              "showLabels": "auto",
              "height": 70
            }
          ]
        },
        {
          "assembly": "peach",
          "loc": "Pp04:11,975,000-12,125,000",
          "tracks": [
            {
              "trackId": "peach_genes",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true,
              "displayMode": "compact",
              "showLabels": "auto",
              "height": 70
            }
          ]
        }
      ],
      "tracks": [
        [
          "grape_peach_synteny_mcscan"
        ]
      ],
      "drawCurves": false,
      "levelHeights": [
        220
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_dotplot.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.

Most genes carry no ribbon, since MCScan anchors only the pairs it could call confidently. Zooming further widens the ribbons, since the file says only which gene pairs with which.

The same anchors as a dotplot

Either track also loads in a dotplot (Add → Dotplot view), where a gene pair is one point and a block a run of them. The axes start in index order; Re-order chromosomes sorts the vertical axis to follow the horizontal one.

The axes as they open, in each assembly's own index order, and then re-sorted: the reorder is a dialog off the dotplot header's overflow menu, and it reports how many grape chromosomes it moved and how many it flipped. Open the session this video starts in ↗
Grape against peach after Re-order chromosomes, every point one orthologous gene pair from the .anchors file. Each run of points is one MCScan block. Open this view in JBrowse ↗

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 has peach on X and grape on Y.
  2. Open the view: Add → Dotplot view, and set both axes to those assemblies in the import form.
  3. Point the import form at your own file: use the track panel under the two axis selectors, choose New track, and paste a URL or pick a local file. This one needs an MCScan .anchors file.A synteny track the session already has is quicker: pick it under **Quick start**, which fills in both axes itself.This figure uses “Grape peach synteny (MCScan, anchors)”.
  4. Click Launch.
  5. Dotplot header → the ⋮ menu → 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=test_data%2Fconfig_dotplot.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22DotplotView%22%2C%22views%22%3A%5B%7B%22assembly%22%3A%22peach%22%7D%2C%7B%22assembly%22%3A%22grape%22%7D%5D%2C%22tracks%22%3A%5B%22grape_peach_synteny_mcscan%22%5D%2C%22autoDiagonalize%22%3Atrue%7D%5D%7D&sessionName=JBrowse+docs%3A+mcscan_synteny%2Fdotplot

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

{
  "views": [
    {
      "type": "DotplotView",
      "views": [
        {
          "assembly": "peach"
        },
        {
          "assembly": "grape"
        }
      ],
      "tracks": [
        "grape_peach_synteny_mcscan"
      ],
      "autoDiagonalize": true
    }
  ]
}

Loaded against config: test_data/config_dotplot.json

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": "DotplotView",
      "views": [
        {
          "assembly": "peach"
        },
        {
          "assembly": "grape"
        }
      ],
      "tracks": [
        "grape_peach_synteny_mcscan"
      ],
      "autoDiagonalize": true
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_dotplot.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.

Reordering puts each peach chromosome's strongest grape partner on the diagonal, and its other partners stay off it. The script prints the same pairings off .anchors.simple. Both genomes descend from the ancestral eudicot hexaploidy (Jaillon et al.) and have rearranged differently since.

Coming from MCScanX

MCScanX is a different program from jcvi's MCScan. It writes one .collinearity holding every block, self-synteny and cross-species together, telling genomes apart by a two-letter tag on each chromosome name. mcscanx_to_anchors.py splits a run into the four files jcvi writes, in place of the jcvi step:

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 --strand-gff3 peach=peach.gff3.gz

The track configs above load the result unchanged. --species order is the anchors column order, so it has to match the track's assemblyNames. Two options decide whether the result draws:

  • --chr-prefix peach=Pp0 prepends to the refNames, and --keep-chr-tag keeps MCScanX's tag, stripped by default (vv1 becomes 1)
  • --strand-gff3 peach=peach.gff3.gz recovers strand from the annotation, which is what draws an .anchors pair as inverted

--fai peach=peach.fa.fai checks the refNames against the assembly; an unknown name draws empty. An anchors score becomes -log10 of MCScanX's e-value.

Naming a third --species writes an ortholog table instead, since one .collinearity covers every pair. See ortholog tables.

A genome against itself

Name a single --species and the script keeps a genome's own duplicated blocks:

python3 mcscanx_to_anchors.py --gff grape.gff --collinearity grape.collinearity \
  --species vv=grape --strand-gff3 grape=grape.gff3.gz

The anchor files name grape on both sides, so the track lists the assembly twice:

{
  "type": "SyntenyTrack",
  "trackId": "grape_self_anchors",
  "name": "Grape duplicated blocks (MCScanX)",
  "assemblyNames": ["grape", "grape"],
  "adapter": {
    "type": "MCScanAnchorsAdapter",
    "uri": "grape.grape.anchors",
    "bed1": "grape.bed",
    "bed2": "grape.bed",
    "assemblyNames": ["grape", "grape"]
  }
}
jbrowse add-track grape.grape.anchors \
  --trackId grape_self_anchors \
  --name "Grape duplicated blocks (MCScanX)" \
  --assemblyNames grape,grape \
  --bed1 grape.bed \
  --bed2 grape.bed \
  --load copy

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_self_anchors",
  "name": "Grape duplicated blocks (MCScanX)",
  "assemblyNames": ["grape", "grape"],
  "adapter": {
    "type": "MCScanAnchorsAdapter",
    "uri": "grape.grape.anchors",
    "bed1": "grape.bed",
    "bed2": "grape.bed",
    "assemblyNames": ["grape", "grape"]
  }
}

A dotplot of the track puts the genome on both axes, each duplicated block a run of points off the diagonal, with no diagonal itself since a gene is not its own anchor.

Reproduce it end to end

build_grape_peach_anchors.sh runs everything above and writes a config.json with both assemblies, gene tracks, both MCScan tracks and a default session opening them together.

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

Its gene ids differ from the samples above, which come from a Phytozome annotation of the same genomes.

See also

References