Skip to main content

Driving JBrowse with an AI agent (two Drosophila genomes)

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

An AI agent, given four requests in plain words, aligns two fruit fly species that have no published alignment and inspects the result in JBrowse Desktop. Typed one at a time, the requests ask the agent to:

  • align the two genomes with minimap2 and open them side by side, genes and all
  • add a dotplot of the pair, restricted to the six chromosome arms
  • count alignment blocks by strand, to find where the two genomes run in opposite directions
  • navigate the view to what it found

Prerequisites

Where the data comes from

The assemblies are two GenArk genomes (D. simulans, D. mauritiana); each hub config holds the 2bit sequence, a chromAlias file, an NCBI RefSeq gene track and a Trix text index.

Nothing to download: the agent fetches both sequences itself.

The files

Ask the agent to align and open the two genomes

The first request, in one sentence:

Align D. simulans GCF_016746395.2 against D. mauritiana GCF_004382145.1 with
minimap2. Run it in the background and poll it, and when it is done index it
and open both genomes side by side, with their gene tracks and the alignment
between them.

The agent runs this aligner command:

## The largest chromosome measures 2.4% divergence (de:f), past asm10's 1%.
## --cs writes the difference string the index below carries.
minimap2 -t 8 -cx asm20 --cs mau.fa.gz sim.fa.gz > sim_vs_mau.paf

The alignment takes several minutes, so the agent runs it in the background. Indexing the PAF then lets the browser read one region without parsing the whole file:

jbrowse make-pif sim_vs_mau.paf

The agent's config merges the two genomes.jbrowse.org hub configs, keeping each gene track, and adds this alignment as a synteny track. For your own pair, swap uri for your .pif.gz (its .tbi beside it), load both assemblies, and check the order of assemblyNames on the track:

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

{
  "type": "SyntenyTrack",
  "trackId": "sim_vs_mau",
  "name": "D. simulans vs D. mauritiana",
  "assemblyNames": ["GCF_016746395.2", "GCF_004382145.1"],
  "adapter": {
    "type": "PairwiseIndexedPAFAdapter",
    "uri": "sim_vs_mau.pif.gz",
    "assemblyNames": ["GCF_016746395.2", "GCF_004382145.1"]
  }
}
jbrowse add-track sim_vs_mau.pif.gz \
  --trackId sim_vs_mau \
  --name "D. simulans vs D. mauritiana" \
  --assemblyNames GCF_016746395.2,GCF_004382145.1 \
  --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": "sim_vs_mau",
  "name": "D. simulans vs D. mauritiana",
  "assemblyNames": ["GCF_016746395.2", "GCF_004382145.1"],
  "adapter": {
    "type": "PairwiseIndexedPAFAdapter",
    "uri": "sim_vs_mau.pif.gz",
    "assemblyNames": ["GCF_016746395.2", "GCF_004382145.1"]
  }
}

sim_vs_mau.pif.gz is relative to a config.json. Replace it with its URL or its path on this computer.

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

In assemblyNames, the query (sim.fa.gz, the second minimap2 argument) comes first and the target second, the order of the PAF columns. In the other order no chromosome name resolves and the synteny band draws empty.

chr3R on both genomes with NCBI RefSeq genes on each row and the minimap2 alignment between them, colored red where the two run in the same direction. One block spans the window, and each gene meets its counterpart exon for exon.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%2Ffly_agent_synteny%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22views%22%3A%5B%7B%22assembly%22%3A%22GCF_016746395.2%22%2C%22loc%22%3A%22chr3R%3A16%2C090%2C000-16%2C120%2C000%22%2C%22tracks%22%3A%5B%22GCF_016746395.2-ncbiRefSeq%22%5D%7D%2C%7B%22assembly%22%3A%22GCF_004382145.1%22%2C%22loc%22%3A%22chr3R%3A16%2C826%2C000-16%2C856%2C000%22%2C%22tracks%22%3A%5B%22GCF_004382145.1-ncbiRefSeq%22%5D%7D%5D%2C%22tracks%22%3A%5B%5B%22sim_vs_mau%22%5D%5D%2C%22collapseEmptyRows%22%3Afalse%2C%22levelHeights%22%3A%5B140%5D%2C%22drawCurves%22%3Afalse%2C%22color%22%3A%7B%22field%22%3A%22strand%22%7D%2C%22showOffscreenMates%22%3Afalse%7D%5D%7D&sessionName=JBrowse+docs%3A+agent_synteny%2Fcomparison_built

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  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. For JBrowse Web, run jbrowse add-assembly once for each to put them in your config.json.This figure's rows, top to bottom: GCF_016746395.2, GCF_004382145.1.
  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 a bgzip-indexed PAF (.pif.gz + .tbi).A synteny track the session already has is quicker: pick it under Quick start, which fills in the rows itself.This figure uses “D. simulans vs D. mauritiana (minimap2 asm20)”.
  4. Add → Linear synteny view → Collapse panels to rulers (unchecked)A row the launch gave no tracks opens with its "No tracks active" block instead of its ruler alone.
  5. Click Launch.
  6. Drag the bar below a synteny level to resize it.This figure's level is 140px tall.
  7. Synteny display settings (the sliders button in the view header) → Curved lines (unchecked)
  8. Synteny view header → palette button → StrandThe palette button's tooltip reads "Color by: ...".
  9. Synteny display settings (the sliders button in the view header) → Off-screen mates (unchecked)On by default: a locus syntenic to a contig the facing panel is not showing draws no ribbon, so without the marks it looks exactly like a locus syntenic to nothing.
  10. Row 1 (GCF_016746395.2)
    1. Add a track: open this view's track selector and check one your config has, or click + and choose Add track to paste a URL or choose a local file. This one needs a BigBed file (.bb).This figure uses “NCBI RefSeq - RefSeq All”.
    2. Type your region of interest into the location box and press Enter.This figure is at chr3R:16,090,000-16,120,000.
  11. Row 2 (GCF_004382145.1)
    1. Add a track: open this view's track selector and check one your config has, or click + and choose Add track to paste a URL or choose a local file. This one needs a BigBed file (.bb).This figure uses “NCBI RefSeq - RefSeq All”.
    2. Type your region of interest into the location box and press Enter.This figure is at chr3R:16,826,000-16,856,000.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/fly_agent_synteny/config.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "GCF_016746395.2",
          "loc": "chr3R:16,090,000-16,120,000",
          "tracks": [
            "GCF_016746395.2-ncbiRefSeq"
          ]
        },
        {
          "assembly": "GCF_004382145.1",
          "loc": "chr3R:16,826,000-16,856,000",
          "tracks": [
            "GCF_004382145.1-ncbiRefSeq"
          ]
        }
      ],
      "tracks": [
        [
          "sim_vs_mau"
        ]
      ],
      "collapseEmptyRows": false,
      "levelHeights": [
        140
      ],
      "drawCurves": false,
      "color": {
        "field": "strand"
      },
      "showOffscreenMates": false
    }
  ]
}

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/fly_agent_synteny/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearSyntenyView",
            "views": [
                {
                    "assembly": "GCF_016746395.2",
                    "loc": "chr3R:16,090,000-16,120,000",
                    "tracks": [
                        "GCF_016746395.2-ncbiRefSeq"
                    ]
                },
                {
                    "assembly": "GCF_004382145.1",
                    "loc": "chr3R:16,826,000-16,856,000",
                    "tracks": [
                        "GCF_004382145.1-ncbiRefSeq"
                    ]
                }
            ],
            "tracks": [
                [
                    "sim_vs_mau"
                ]
            ],
            "collapseEmptyRows": False,
            "levelHeights": [
                140
            ],
            "drawCurves": False,
            "color": {
                "field": "strand"
            },
            "showOffscreenMates": False
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "GCF_016746395.2",
          "loc": "chr3R:16,090,000-16,120,000",
          "tracks": [
            "GCF_016746395.2-ncbiRefSeq"
          ]
        },
        {
          "assembly": "GCF_004382145.1",
          "loc": "chr3R:16,826,000-16,856,000",
          "tracks": [
            "GCF_004382145.1-ncbiRefSeq"
          ]
        }
      ],
      "tracks": [
        [
          "sim_vs_mau"
        ]
      ],
      "collapseEmptyRows": false,
      "levelHeights": [
        140
      ],
      "drawCurves": false,
      "color": {
        "field": "strand"
      },
      "showOffscreenMates": false
    }
  ]
}
JSON

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

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "GCF_016746395.2",
          "loc": "chr3R:16,090,000-16,120,000",
          "tracks": [
            "GCF_016746395.2-ncbiRefSeq"
          ]
        },
        {
          "assembly": "GCF_004382145.1",
          "loc": "chr3R:16,826,000-16,856,000",
          "tracks": [
            "GCF_004382145.1-ncbiRefSeq"
          ]
        }
      ],
      "tracks": [
        [
          "sim_vs_mau"
        ]
      ],
      "collapseEmptyRows": false,
      "levelHeights": [
        140
      ],
      "drawCurves": false,
      "color": {
        "field": "strand"
      },
      "showOffscreenMates": false
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/fly_agent_synteny/config.json \
  --width 1400 --height 604 \
  --timeout 120000 \
  --spec 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.

Ask for a dotplot restricted to the chromosome arms

Add a dotplot of the same two assemblies underneath.

Naming the six chromosome arms gives one diagonal:

Restrict both dotplot axes to chr2L, chr2R, chr3L, chr3R, chr4 and chrX.

Ask the agent to quantify what restricting the axes drops. Add one more request, to color the dotplot by strand, so a reversed block draws in blue and a forward one in red.

The alignment as a dotplot, both axes cut to the six chromosome arms. One forward diagonal in red, with short reverse segments in blue where chr2R begins and partway along chrX.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%2Ffly_agent_synteny%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22DotplotView%22%2C%22displayName%22%3A%22D.+simulans+vs+D.+mauritiana%22%2C%22views%22%3A%5B%7B%22assembly%22%3A%22GCF_016746395.2%22%2C%22displayedRegionNames%22%3A%5B%22chr2L%22%2C%22chr2R%22%2C%22chr3L%22%2C%22chr3R%22%2C%22chr4%22%2C%22chrX%22%5D%7D%2C%7B%22assembly%22%3A%22GCF_004382145.1%22%2C%22displayedRegionNames%22%3A%5B%22chr2L%22%2C%22chr2R%22%2C%22chr3L%22%2C%22chr3R%22%2C%22chr4%22%2C%22chrX%22%5D%7D%5D%2C%22tracks%22%3A%5B%22sim_vs_mau%22%5D%2C%22color%22%3A%7B%22field%22%3A%22strand%22%7D%2C%22showTickLabels%22%3Afalse%2C%22height%22%3A760%7D%5D%7D&sessionName=JBrowse+docs%3A+agent_synteny%2Fdotplot_arms

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  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. For JBrowse Web, run jbrowse add-assembly once for each to put them in your config.json.This figure has GCF_016746395.2 on X and GCF_004382145.1 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 a bgzip-indexed PAF (.pif.gz + .tbi).A synteny track the session already has is quicker: pick it under Quick start, which fills in both axes itself.This figure uses “D. simulans vs D. mauritiana (minimap2 asm20)”.
  4. Click Launch.
  5. Click the view's title in its header and enter "D. simulans vs D. mauritiana"
  6. Dotplot header → palette button → StrandThe palette button's tooltip reads "Color by: ...".
  7. Dotplot display settings (the sliders button in the view header) → Tick labels (unchecked)
  8. Drag the bar at the bottom edge of the view to resize it (760px here).

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/fly_agent_synteny/config.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "DotplotView",
      "displayName": "D. simulans vs D. mauritiana",
      "views": [
        {
          "assembly": "GCF_016746395.2",
          "displayedRegionNames": [
            "chr2L",
            "chr2R",
            "chr3L",
            "chr3R",
            "chr4",
            "chrX"
          ]
        },
        {
          "assembly": "GCF_004382145.1",
          "displayedRegionNames": [
            "chr2L",
            "chr2R",
            "chr3L",
            "chr3R",
            "chr4",
            "chrX"
          ]
        }
      ],
      "tracks": [
        "sim_vs_mau"
      ],
      "color": {
        "field": "strand"
      },
      "showTickLabels": false,
      "height": 760
    }
  ]
}

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/fly_agent_synteny/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "DotplotView",
            "displayName": "D. simulans vs D. mauritiana",
            "views": [
                {
                    "assembly": "GCF_016746395.2",
                    "displayedRegionNames": [
                        "chr2L",
                        "chr2R",
                        "chr3L",
                        "chr3R",
                        "chr4",
                        "chrX"
                    ]
                },
                {
                    "assembly": "GCF_004382145.1",
                    "displayedRegionNames": [
                        "chr2L",
                        "chr2R",
                        "chr3L",
                        "chr3R",
                        "chr4",
                        "chrX"
                    ]
                }
            ],
            "tracks": [
                "sim_vs_mau"
            ],
            "color": {
                "field": "strand"
            },
            "showTickLabels": False,
            "height": 760
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "DotplotView",
      "displayName": "D. simulans vs D. mauritiana",
      "views": [
        {
          "assembly": "GCF_016746395.2",
          "displayedRegionNames": [
            "chr2L",
            "chr2R",
            "chr3L",
            "chr3R",
            "chr4",
            "chrX"
          ]
        },
        {
          "assembly": "GCF_004382145.1",
          "displayedRegionNames": [
            "chr2L",
            "chr2R",
            "chr3L",
            "chr3R",
            "chr4",
            "chrX"
          ]
        }
      ],
      "tracks": [
        "sim_vs_mau"
      ],
      "color": {
        "field": "strand"
      },
      "showTickLabels": false,
      "height": 760
    }
  ]
}
JSON

npx @jbrowse/img dotplot --config https://jbrowse.org/demos/fly_agent_synteny/config.json \
  --spec session.json \
  --width 1000 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "DotplotView",
      "displayName": "D. simulans vs D. mauritiana",
      "views": [
        {
          "assembly": "GCF_016746395.2",
          "displayedRegionNames": [
            "chr2L",
            "chr2R",
            "chr3L",
            "chr3R",
            "chr4",
            "chrX"
          ]
        },
        {
          "assembly": "GCF_004382145.1",
          "displayedRegionNames": [
            "chr2L",
            "chr2R",
            "chr3L",
            "chr3R",
            "chr4",
            "chrX"
          ]
        }
      ],
      "tracks": [
        "sim_vs_mau"
      ],
      "color": {
        "field": "strand"
      },
      "showTickLabels": false,
      "height": 760
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/fly_agent_synteny/config.json \
  --width 1000 --height 900 \
  --timeout 120000 \
  --spec 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.

Ask where the two genomes run in opposite directions

Where do the two genomes run in opposite directions? Answer from the
alignment file, not from the dotplot, and show me the numbers.

At whole-genome zoom a reverse-strand block a few hundred kilobases wide is a few pixels, so the request asks for numbers from the PAF: aligned bases per arm, split by strand, at mapping quality (MAPQ) 30 or better:

awk -F'\t' '
BEGIN {
  ## the arm each RefSeq accession is, from the chromAlias files
  split("NC_052520.2 2L NC_052521.2 2R NC_052522.2 3L NC_052523.2 3R NC_052524.2 4 NC_052525.2 X", a, " ")
  split("NC_046667.1 2L NC_046668.1 2R NC_046669.1 3L NC_046670.1 3R NC_046671.1 4 NC_046672.1 X", b, " ")
  for (i = 1; i in a; i += 2) q[a[i]] = a[i+1]
  for (i = 1; i in b; i += 2) t[b[i]] = b[i+1]
}
## $12 is MAPQ, $5 the strand, $4-$3 the aligned length on the query
$12 >= 30 && ($1 in q) && ($6 in t) && q[$1] == t[$6] {
  aligned[q[$1]] += $4 - $3
  if ($5 == "-") reverse[q[$1]] += $4 - $3
}
END {
  for (k in aligned)
    printf "%-3s %6.2f Mb aligned, %5.2f%% reverse\n", k, aligned[k]/1e6, 100*reverse[k]/aligned[k]
}' sim_vs_mau.paf | sort
2L   22.15 Mb aligned,  0.28% reverse
2R   20.56 Mb aligned,  5.02% reverse
3L   22.56 Mb aligned,  0.03% reverse
3R   27.03 Mb aligned,  0.01% reverse
4     1.10 Mb aligned,  0.00% reverse
X    21.04 Mb aligned,  4.44% reverse

Four arms have essentially no reverse-strand alignment and are the control: 2R and X sit an order of magnitude above them.

Grouping the reverse-strand blocks of 5 kb or more, and cutting a group wherever half a megabase passes with none, gives three regions:

2R  sim    59,995 - 2,256,808  <->  mau   628,956 - 3,646,198   (2.20 Mb, 75 blocks)
X   sim 8,303,553 - 8,752,357  <->  mau 8,530,265 - 8,980,862   (0.45 Mb,  2 blocks)
X   sim 21,441,285 - 22,026,996 <->  mau 21,459,277 - 22,872,816 (0.59 Mb, 12 blocks)

Ask the agent to open the 2R and X regions

Close the gene tracks and take the synteny view to the 2R region.

The agent opens the simulans row at chr2R:1-2,400,000 and the mauritiana row at chr2R:500,000-3,800,000.

The 2R region, the alignment alone between the two rows. Reverse-strand blocks in blue cross the band, short and many, because the sequence at this end of the arm is repeat-rich.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%2Ffly_agent_synteny%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22views%22%3A%5B%7B%22assembly%22%3A%22GCF_016746395.2%22%2C%22loc%22%3A%22chr2R%3A1-2%2C400%2C000%22%7D%2C%7B%22assembly%22%3A%22GCF_004382145.1%22%2C%22loc%22%3A%22chr2R%3A500%2C000-3%2C800%2C000%22%7D%5D%2C%22tracks%22%3A%5B%5B%22sim_vs_mau%22%5D%5D%2C%22collapseEmptyRows%22%3Atrue%2C%22levelHeights%22%3A%5B360%5D%2C%22drawCurves%22%3Afalse%2C%22color%22%3A%7B%22field%22%3A%22strand%22%7D%2C%22showOffscreenMates%22%3Afalse%2C%22minAlignmentLength%22%3A5000%7D%5D%7D&sessionName=JBrowse+docs%3A+agent_synteny%2Finversion_2r

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  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. For JBrowse Web, run jbrowse add-assembly once for each to put them in your config.json.This figure's rows, top to bottom: GCF_016746395.2, GCF_004382145.1.
  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 a bgzip-indexed PAF (.pif.gz + .tbi).A synteny track the session already has is quicker: pick it under Quick start, which fills in the rows itself.This figure uses “D. simulans vs D. mauritiana (minimap2 asm20)”.
  4. Click Launch.
  5. Drag the bar below a synteny level to resize it.This figure's level is 360px tall.
  6. Synteny display settings (the sliders button in the view header) → Curved lines (unchecked)
  7. Synteny view header → palette button → StrandThe palette button's tooltip reads "Color by: ...".
  8. Synteny display settings (the sliders button in the view header) → Off-screen mates (unchecked)On by default: a locus syntenic to a contig the facing panel is not showing draws no ribbon, so without the marks it looks exactly like a locus syntenic to nothing.
  9. Synteny display settings (the sliders button in the view header) → Min length → drag to 5,000bpHides alignments shorter than this, which is what clears the hairball of short spurious chains at whole-genome zoom.
  10. Row 1 (GCF_016746395.2)
    1. Type your region of interest into the location box and press Enter.This figure is at chr2R:1-2,400,000.
  11. Row 2 (GCF_004382145.1)
    1. Type your region of interest into the location box and press Enter.This figure is at chr2R:500,000-3,800,000.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/fly_agent_synteny/config.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "GCF_016746395.2",
          "loc": "chr2R:1-2,400,000"
        },
        {
          "assembly": "GCF_004382145.1",
          "loc": "chr2R:500,000-3,800,000"
        }
      ],
      "tracks": [
        [
          "sim_vs_mau"
        ]
      ],
      "collapseEmptyRows": true,
      "levelHeights": [
        360
      ],
      "drawCurves": false,
      "color": {
        "field": "strand"
      },
      "showOffscreenMates": false,
      "minAlignmentLength": 5000
    }
  ]
}

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/fly_agent_synteny/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearSyntenyView",
            "views": [
                {
                    "assembly": "GCF_016746395.2",
                    "loc": "chr2R:1-2,400,000"
                },
                {
                    "assembly": "GCF_004382145.1",
                    "loc": "chr2R:500,000-3,800,000"
                }
            ],
            "tracks": [
                [
                    "sim_vs_mau"
                ]
            ],
            "collapseEmptyRows": True,
            "levelHeights": [
                360
            ],
            "drawCurves": False,
            "color": {
                "field": "strand"
            },
            "showOffscreenMates": False,
            "minAlignmentLength": 5000
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "GCF_016746395.2",
          "loc": "chr2R:1-2,400,000"
        },
        {
          "assembly": "GCF_004382145.1",
          "loc": "chr2R:500,000-3,800,000"
        }
      ],
      "tracks": [
        [
          "sim_vs_mau"
        ]
      ],
      "collapseEmptyRows": true,
      "levelHeights": [
        360
      ],
      "drawCurves": false,
      "color": {
        "field": "strand"
      },
      "showOffscreenMates": false,
      "minAlignmentLength": 5000
    }
  ]
}
JSON

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

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "GCF_016746395.2",
          "loc": "chr2R:1-2,400,000"
        },
        {
          "assembly": "GCF_004382145.1",
          "loc": "chr2R:500,000-3,800,000"
        }
      ],
      "tracks": [
        [
          "sim_vs_mau"
        ]
      ],
      "collapseEmptyRows": true,
      "levelHeights": [
        360
      ],
      "drawCurves": false,
      "color": {
        "field": "strand"
      },
      "showOffscreenMates": false,
      "minAlignmentLength": 5000
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/fly_agent_synteny/config.json \
  --width 1400 --height 560 \
  --timeout 120000 \
  --spec 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.

Then ask for the first of the two X regions, chrX:8,100,000-8,950,000 over chrX:8,330,000-9,180,000, where the reverse blocks are fewer and longer:

The X region, the alignment alone between the two rows. Two reverse blocks cross in the middle of the band, with forward alignment in red on both sides of them.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%2Ffly_agent_synteny%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22views%22%3A%5B%7B%22assembly%22%3A%22GCF_016746395.2%22%2C%22loc%22%3A%22chrX%3A8%2C100%2C000-8%2C950%2C000%22%7D%2C%7B%22assembly%22%3A%22GCF_004382145.1%22%2C%22loc%22%3A%22chrX%3A8%2C330%2C000-9%2C180%2C000%22%7D%5D%2C%22tracks%22%3A%5B%5B%22sim_vs_mau%22%5D%5D%2C%22collapseEmptyRows%22%3Atrue%2C%22levelHeights%22%3A%5B360%5D%2C%22drawCurves%22%3Afalse%2C%22color%22%3A%7B%22field%22%3A%22strand%22%7D%2C%22showOffscreenMates%22%3Afalse%7D%5D%7D&sessionName=JBrowse+docs%3A+agent_synteny%2Finversion_x

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  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. For JBrowse Web, run jbrowse add-assembly once for each to put them in your config.json.This figure's rows, top to bottom: GCF_016746395.2, GCF_004382145.1.
  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 a bgzip-indexed PAF (.pif.gz + .tbi).A synteny track the session already has is quicker: pick it under Quick start, which fills in the rows itself.This figure uses “D. simulans vs D. mauritiana (minimap2 asm20)”.
  4. Click Launch.
  5. Drag the bar below a synteny level to resize it.This figure's level is 360px tall.
  6. Synteny display settings (the sliders button in the view header) → Curved lines (unchecked)
  7. Synteny view header → palette button → StrandThe palette button's tooltip reads "Color by: ...".
  8. Synteny display settings (the sliders button in the view header) → Off-screen mates (unchecked)On by default: a locus syntenic to a contig the facing panel is not showing draws no ribbon, so without the marks it looks exactly like a locus syntenic to nothing.
  9. Row 1 (GCF_016746395.2)
    1. Type your region of interest into the location box and press Enter.This figure is at chrX:8,100,000-8,950,000.
  10. Row 2 (GCF_004382145.1)
    1. Type your region of interest into the location box and press Enter.This figure is at chrX:8,330,000-9,180,000.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/fly_agent_synteny/config.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "GCF_016746395.2",
          "loc": "chrX:8,100,000-8,950,000"
        },
        {
          "assembly": "GCF_004382145.1",
          "loc": "chrX:8,330,000-9,180,000"
        }
      ],
      "tracks": [
        [
          "sim_vs_mau"
        ]
      ],
      "collapseEmptyRows": true,
      "levelHeights": [
        360
      ],
      "drawCurves": false,
      "color": {
        "field": "strand"
      },
      "showOffscreenMates": false
    }
  ]
}

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/fly_agent_synteny/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearSyntenyView",
            "views": [
                {
                    "assembly": "GCF_016746395.2",
                    "loc": "chrX:8,100,000-8,950,000"
                },
                {
                    "assembly": "GCF_004382145.1",
                    "loc": "chrX:8,330,000-9,180,000"
                }
            ],
            "tracks": [
                [
                    "sim_vs_mau"
                ]
            ],
            "collapseEmptyRows": True,
            "levelHeights": [
                360
            ],
            "drawCurves": False,
            "color": {
                "field": "strand"
            },
            "showOffscreenMates": False
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "GCF_016746395.2",
          "loc": "chrX:8,100,000-8,950,000"
        },
        {
          "assembly": "GCF_004382145.1",
          "loc": "chrX:8,330,000-9,180,000"
        }
      ],
      "tracks": [
        [
          "sim_vs_mau"
        ]
      ],
      "collapseEmptyRows": true,
      "levelHeights": [
        360
      ],
      "drawCurves": false,
      "color": {
        "field": "strand"
      },
      "showOffscreenMates": false
    }
  ]
}
JSON

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

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "GCF_016746395.2",
          "loc": "chrX:8,100,000-8,950,000"
        },
        {
          "assembly": "GCF_004382145.1",
          "loc": "chrX:8,330,000-9,180,000"
        }
      ],
      "tracks": [
        [
          "sim_vs_mau"
        ]
      ],
      "collapseEmptyRows": true,
      "levelHeights": [
        360
      ],
      "drawCurves": false,
      "color": {
        "field": "strand"
      },
      "showOffscreenMates": false
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/fly_agent_synteny/config.json \
  --width 1400 --height 560 \
  --timeout 120000 \
  --spec 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.

Three instructions to include when prompting the agent

Three instructions each prevent a failure that raises no error:

  • Start long work in the background, and let it finish before opening anything. Otherwise a tool call times out, after two minutes for run_javascript, and the agent reports a failure that did not happen.
  • Restrict the dotplot axes to the arms. Otherwise a few hundred unplaced scaffolds (not assigned to a chromosome) interleave both axes.
  • Ask for answers counted from the alignment file. Otherwise the agent describes the dotplot.

Two more are worth asking for:

  • Screenshot what you build and read the image back. A wrong track id or an empty region still renders as a plausible browser.
  • Ask for the numbers before navigating. The view you then see is a claim you can check.

Running the whole pipeline as a script

curl -O https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_fly_agent_synteny.sh
bash build_fly_agent_synteny.sh fly_agent_synteny_build

The script downloads both genomes, runs the alignment, indexes it, and writes config.json to open in Desktop. It needs the tools in Prerequisites, plus jq and curl.

See also

Citations