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.11. 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

Two GenArk assemblies and their genome hubs on genomes.jbrowse.org (D. simulans, D. mauritiana). Each hub's config holds the 2bit sequence, a chromAlias file, an NCBI RefSeq gene track and a Trix text index.

What the agent is driving

Connected to JBrowse Desktop, the agent gets four tools: run_javascript, open, screenshot and docs. The requests below go through run_javascript, which runs code against the session through a jb helper library.

Set up the client as in Using JBrowse with AI agents, then run the four requests below.

A Claude Code session driving JBrowse Desktop: the agent aligns the two genomes, builds the comparison and dotplot, and navigates to what it found.

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 aligner it runs:

## 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 whole-genome alignment takes several minutes, longer than the two-minute timeout on run_javascript, so the request above runs it in the background.

Indexing the PAF lets the browser read one region of it without parsing the whole file:

jbrowse make-pif sim_vs_mau.paf

The config the agent writes merges the two hosted ones, keeping each gene track and adding the alignment as a synteny track.

Check the order of assemblyNames on the synteny track the agent wrote. Your own pair takes the same track with its uri swapped for your .pif.gz, which needs its .tbi beside it, and both assembly names loaded:

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.

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.

Thirty kilobases of chr3R on both genomes: NCBI RefSeq on each row, 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 ↗

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

Or rebuild it from your own data:

Opening in Desktop needs JBrowse Desktop 5.0+, and saves the view as a reopenable session.

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%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

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.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 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 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 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 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.

Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

With your own data, the steps behind the figure:

  1. Put your genomes in your JBrowse Web's config.json: run jbrowse add-assembly once for each.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 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 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 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 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 from https://jbrowse.org/demos/fly_agent_synteny/config.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

{
  "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 — swap an adapter uri for your own file 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 the dotplot

Add a dotplot of the same two assemblies underneath.

D. simulans and D. mauritiana each have a few hundred unplaced scaffolds, which interleave the axes if drawn. Naming the 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 ↗

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

Or rebuild it from your own data:

Opening in Desktop needs JBrowse Desktop 5.0+, and saves the view as a reopenable session.

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%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

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.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)

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

Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

With your own data, the steps behind the figure:

  1. Put your genomes in your JBrowse Web's config.json: run jbrowse add-assembly once for each.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)

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

This session spec draws the figure from https://jbrowse.org/demos/fly_agent_synteny/config.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

{
  "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 — swap an adapter uri for your own file 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 they disagree

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

A reverse-strand block a few hundred kilobases wide is a few pixels at whole-genome zoom. The same information is in the PAF as numbers: aligned bases per arm, split by strand, at 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 they 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)

The 2R region is the largest and the least tidy; the two X regions are smaller and cleaner.

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 closes both gene tracks, so the view draws the whole-genome alignment alone, and 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 ↗

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

Or rebuild it from your own data:

Opening in Desktop needs JBrowse Desktop 5.0+, and saves the view as a reopenable session.

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%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

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.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.

Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

With your own data, the steps behind the figure:

  1. Put your genomes in your JBrowse Web's config.json: run jbrowse add-assembly once for each.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 from https://jbrowse.org/demos/fly_agent_synteny/config.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

{
  "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 — swap an adapter uri for your own file 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 ↗

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

Or rebuild it from your own data:

Opening in Desktop needs JBrowse Desktop 5.0+, and saves the view as a reopenable session.

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%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

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.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.

Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

With your own data, the steps behind the figure:

  1. Put your genomes in your JBrowse Web's config.json: run jbrowse add-assembly once for each.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 from https://jbrowse.org/demos/fly_agent_synteny/config.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

{
  "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 — swap an adapter uri for your own file 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.

What the requests had to tell the agent

Three sentences, and each prevents a failure with no error message:

  • Start long work in the background, and let it finish before opening anything. Otherwise a tool call times out and the agent reports a failure that did not happen.
  • Restrict the dotplot axes to the arms. Otherwise a few hundred unplaced scaffolds interleave both axes.
  • Answer counted from the alignment file. Otherwise the agent describes the dotplot.

Two more come up unprompted: screenshot what it builds, since a wrong track id or empty region still renders as a plausible browser, and say the numbers before it navigates, so what you see is a claim you can check.

The same 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