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.21. Desktop beta builds for Linux and macOS are on the releases page; the Windows build waits on code signing.

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

# Debian/Ubuntu
sudo apt install minimap2 nodejs
# or conda, which has every tool above
conda install -c bioconda -c conda-forge minimap2 nodejs
# any platform
npm install -g @jbrowse/cli@next

The data

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.

The agent downloads both sequences and aligns them, which takes minutes and gigabytes of memory. For a pair of your own, name your two FASTA files in the first request, or swap in your .pif.gz and assemblies, as Ask the agent to align and open the two genomes shows.

The files
What it is File
D. simulans sequence, which the agent downloads to align GCF_016746395.2.fa.gz
D. mauritiana sequence, which the agent downloads to align GCF_004382145.1.fa.gz

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:

# asm20: the two species diverge past the 1% asm10 allows
# --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. The agent then indexes the PAF, so the browser can 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"]
  }
}

Edits config.json in the current folder. See JBrowse CLI with Desktop.

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, so the synteny band is empty.

chr3R on both genomes with RefSeq genes on each row and the minimap2 alignment between them, colored by strand.
Open in JBrowse Web ↗

Large dataset: slow to open.

Or rebuild it from your own data:

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

From scratch:

  1. Open your genomes: Open your own genome in JBrowse Desktop, then File → Open genome... for each of the rest, or jbrowse add-assembly for each in JBrowse Web.This figure's rows, top to bottom: 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. Add your file: click the arrow between two rows and choose New track. Needs a bgzip-indexed PAF (.pif.gz + .tbi).Or pick a synteny track you already have under Quick start, which fills in the rows.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 track: + → Add track... in this view's track selector, or check it there. Needs a BigBed file (.bb).This figure uses “NCBI RefSeq - RefSeq All”.
    2. Go to your region in the location box.This figure is at chr3R:16,090,000-16,120,000.
  11. Row 2 (GCF_004382145.1)
    1. Add the next track the same way. Needs a BigBed file (.bb).This figure uses “NCBI RefSeq - RefSeq All”.
    2. Go to your region in the location box.This figure is at chr3R:16,826,000-16,856,000.

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

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

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/demos/fly_agent_synteny/config.json
- Tracks:
  - D. simulans vs D. mauritiana (minimap2 asm20) (sim_vs_mau), SyntenyTrack, a bgzip-indexed PAF (.pif.gz + .tbi), drawn as LinearSyntenyDisplay
  - NCBI RefSeq - RefSeq All (GCF_016746395.2-ncbiRefSeq), FeatureTrack, a BigBed file (.bb), drawn as LinearBasicDisplay
  - NCBI RefSeq - RefSeq All (GCF_004382145.1-ncbiRefSeq), FeatureTrack, a BigBed file (.bb), drawn as LinearBasicDisplay

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

The session spec that draws the view:
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "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
      ],
      "mark": {
        "interpolate": "linear"
      },
      "encoding": {
        "color": "strand"
      },
      "offscreen": {
        "show": false
      }
    }
  ]
}
Redraw the figure headlessly
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
      ],
      "mark": {
        "interpolate": "linear"
      },
      "encoding": {
        "color": "strand"
      },
      "offscreen": {
        "show": 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

More: Using JBrowse with AI agents.

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

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/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
            ],
            "mark": {
                "interpolate": "linear"
            },
            "encoding": {
                "color": "strand"
            },
            "offscreen": {
                "show": False
            }
        }
    ],
)
app  # display the widget

This view in your React 19 app, with @jbrowse/react-app2 and @jbrowse/core. Add your own files to tracks.

import { use } from 'react'
import { JBrowse } from '@jbrowse/react-app2'
import '@jbrowse/react-app2/styles.css'
import { addRelativeUris } from '@jbrowse/core/util/addRelativeUris'

const configUrl = "https://jbrowse.org/demos/fly_agent_synteny/config.json"
const configPromise = fetch(configUrl)
  .then(res => res.json())
  .then(config => {
    addRelativeUris(config, new URL(configUrl))
    return config
  })

export default function Figure() {
  const config = use(configPromise)
  return (
    <JBrowse
      assemblies={config.assemblies}
      tracks={config.tracks}
      aggregateTextSearchAdapters={config.aggregateTextSearchAdapters}
      configuration={config.configuration}
      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
          ],
          "mark": {
            "interpolate": "linear"
          },
          "encoding": {
            "color": "strand"
          },
          "offscreen": {
            "show": false
          }
        }
      ]}
    />
  )
}

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

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "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
      ],
      "mark": {
        "interpolate": "linear"
      },
      "encoding": {
        "color": "strand"
      },
      "offscreen": {
        "show": false
      }
    }
  ]
}
JSON

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

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

The session spec behind the figure, over this config.

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "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
      ],
      "mark": {
        "interpolate": "linear"
      },
      "encoding": {
        "color": "strand"
      },
      "offscreen": {
        "show": false
      }
    }
  ]
}

Ask for a dotplot restricted to the chromosome arms

Add a dotplot of the same two assemblies underneath.

With the axes restricted to the chromosome arms, the plot shows one diagonal:

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

Add one more request to color the dotplot by strand, so a reversed block is drawn blue and a forward one red.

The alignment as a dotplot cut to the chromosome arms, colored by strand.
Open in JBrowse Web ↗

Large dataset: slow to open.

Or rebuild it from your own data:

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

From scratch:

  1. Open your genomes: Open your own genome in JBrowse Desktop, then File → Open genome... for each of the rest, or jbrowse add-assembly for each in JBrowse Web.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. Add your file: use the track panel under the two axis selectors and choose New track. Needs a bgzip-indexed PAF (.pif.gz + .tbi).Or pick a synteny track you already have under Quick start, which fills in both axes.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).

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

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

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/demos/fly_agent_synteny/config.json
- Tracks:
  - D. simulans vs D. mauritiana (minimap2 asm20) (sim_vs_mau), SyntenyTrack, a bgzip-indexed PAF (.pif.gz + .tbi), drawn as DotplotDisplay

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

The session spec that draws the view:
{
  "views": [
    {
      "type": "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"
      ],
      "encoding": {
        "color": "strand"
      },
      "axis": {
        "labels": false
      },
      "height": 760
    }
  ]
}
Redraw the figure headlessly
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"
      ],
      "encoding": {
        "color": "strand"
      },
      "axis": {
        "labels": 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

More: Using JBrowse with AI agents.

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

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/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"
            ],
            "encoding": {
                "color": "strand"
            },
            "axis": {
                "labels": False
            },
            "height": 760
        }
    ],
)
app  # display the widget

This view in your React 19 app, with @jbrowse/react-app2 and @jbrowse/core. Add your own files to tracks.

import { use } from 'react'
import { JBrowse } from '@jbrowse/react-app2'
import '@jbrowse/react-app2/styles.css'
import { addRelativeUris } from '@jbrowse/core/util/addRelativeUris'

const configUrl = "https://jbrowse.org/demos/fly_agent_synteny/config.json"
const configPromise = fetch(configUrl)
  .then(res => res.json())
  .then(config => {
    addRelativeUris(config, new URL(configUrl))
    return config
  })

export default function Figure() {
  const config = use(configPromise)
  return (
    <JBrowse
      assemblies={config.assemblies}
      tracks={config.tracks}
      aggregateTextSearchAdapters={config.aggregateTextSearchAdapters}
      configuration={config.configuration}
      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"
          ],
          "encoding": {
            "color": "strand"
          },
          "axis": {
            "labels": false
          },
          "height": 760
        }
      ]}
    />
  )
}

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

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "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"
      ],
      "encoding": {
        "color": "strand"
      },
      "axis": {
        "labels": 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

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

The session spec behind the figure, over this config.

{
  "views": [
    {
      "type": "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"
      ],
      "encoding": {
        "color": "strand"
      },
      "axis": {
        "labels": false
      },
      "height": 760
    }
  ]
}

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

The agent reports 2R and X with far more reverse-strand alignment than the other four arms, which are the control. Asked to group the reverse-strand blocks of 5 kb or more, cutting a group wherever half a megabase passes with none, it names one region on 2R and two on X.

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. Reverse-strand blocks are drawn blue and cross the band.
Open in JBrowse Web ↗

Large dataset: slow to open.

Or rebuild it from your own data:

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

From scratch:

  1. Open your genomes: Open your own genome in JBrowse Desktop, then File → Open genome... for each of the rest, or jbrowse add-assembly for each in JBrowse Web.This figure's rows, top to bottom: 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. Add your file: click the arrow between two rows and choose New track. Needs a bgzip-indexed PAF (.pif.gz + .tbi).Or pick a synteny track you already have under Quick start, which fills in the rows.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. Synteny display settings (the sliders button in the view header) → CIGAR indels → Off - don't draw CIGAR indelsThe row appears only when the alignments actually carry CIGAR ops — a coarse-tier PIF or a CIGAR-less PAF has none to draw.
  11. Row 1 (GCF_016746395.2)
    1. Go to your region in the location box.This figure is at chr2R:1-2,400,000.
  12. Row 2 (GCF_004382145.1)
    1. Go to your region in the location box.This figure is at chr2R:500,000-3,800,000.

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

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

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/demos/fly_agent_synteny/config.json
- Tracks:
  - D. simulans vs D. mauritiana (minimap2 asm20) (sim_vs_mau), SyntenyTrack, a bgzip-indexed PAF (.pif.gz + .tbi), drawn as LinearSyntenyDisplay

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

The session spec that draws the view:
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "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
      ],
      "mark": {
        "interpolate": "linear"
      },
      "encoding": {
        "color": "strand"
      },
      "offscreen": {
        "show": false
      },
      "filter": [
        {
          "field": "length",
          "gte": 5000
        }
      ],
      "indels": {
        "show": false
      }
    }
  ]
}
Redraw the figure headlessly
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
      ],
      "mark": {
        "interpolate": "linear"
      },
      "encoding": {
        "color": "strand"
      },
      "offscreen": {
        "show": false
      },
      "filter": [
        {
          "field": "length",
          "gte": 5000
        }
      ],
      "indels": {
        "show": 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

More: Using JBrowse with AI agents.

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

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/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
            ],
            "mark": {
                "interpolate": "linear"
            },
            "encoding": {
                "color": "strand"
            },
            "offscreen": {
                "show": False
            },
            "filter": [
                {
                    "field": "length",
                    "gte": 5000
                }
            ],
            "indels": {
                "show": False
            }
        }
    ],
)
app  # display the widget

This view in your React 19 app, with @jbrowse/react-app2 and @jbrowse/core. Add your own files to tracks.

import { use } from 'react'
import { JBrowse } from '@jbrowse/react-app2'
import '@jbrowse/react-app2/styles.css'
import { addRelativeUris } from '@jbrowse/core/util/addRelativeUris'

const configUrl = "https://jbrowse.org/demos/fly_agent_synteny/config.json"
const configPromise = fetch(configUrl)
  .then(res => res.json())
  .then(config => {
    addRelativeUris(config, new URL(configUrl))
    return config
  })

export default function Figure() {
  const config = use(configPromise)
  return (
    <JBrowse
      assemblies={config.assemblies}
      tracks={config.tracks}
      aggregateTextSearchAdapters={config.aggregateTextSearchAdapters}
      configuration={config.configuration}
      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
          ],
          "mark": {
            "interpolate": "linear"
          },
          "encoding": {
            "color": "strand"
          },
          "offscreen": {
            "show": false
          },
          "filter": [
            {
              "field": "length",
              "gte": 5000
            }
          ],
          "indels": {
            "show": false
          }
        }
      ]}
    />
  )
}

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

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "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
      ],
      "mark": {
        "interpolate": "linear"
      },
      "encoding": {
        "color": "strand"
      },
      "offscreen": {
        "show": false
      },
      "filter": [
        {
          "field": "length",
          "gte": 5000
        }
      ],
      "indels": {
        "show": false
      }
    }
  ]
}
JSON

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

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

The session spec behind the figure, over this config.

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "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
      ],
      "mark": {
        "interpolate": "linear"
      },
      "encoding": {
        "color": "strand"
      },
      "offscreen": {
        "show": false
      },
      "filter": [
        {
          "field": "length",
          "gte": 5000
        }
      ],
      "indels": {
        "show": false
      }
    }
  ]
}

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. Two reverse blocks cross in the middle.
Open in JBrowse Web ↗

Large dataset: slow to open.

Or rebuild it from your own data:

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

From scratch:

  1. Open your genomes: Open your own genome in JBrowse Desktop, then File → Open genome... for each of the rest, or jbrowse add-assembly for each in JBrowse Web.This figure's rows, top to bottom: 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. Add your file: click the arrow between two rows and choose New track. Needs a bgzip-indexed PAF (.pif.gz + .tbi).Or pick a synteny track you already have under Quick start, which fills in the rows.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) → CIGAR indels → Off - don't draw CIGAR indelsThe row appears only when the alignments actually carry CIGAR ops — a coarse-tier PIF or a CIGAR-less PAF has none to draw.
  10. Row 1 (GCF_016746395.2)
    1. Go to your region in the location box.This figure is at chrX:8,100,000-8,950,000.
  11. Row 2 (GCF_004382145.1)
    1. Go to your region in the location box.This figure is at chrX:8,330,000-9,180,000.

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

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

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/demos/fly_agent_synteny/config.json
- Tracks:
  - D. simulans vs D. mauritiana (minimap2 asm20) (sim_vs_mau), SyntenyTrack, a bgzip-indexed PAF (.pif.gz + .tbi), drawn as LinearSyntenyDisplay

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

The session spec that draws the view:
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "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
      ],
      "mark": {
        "interpolate": "linear"
      },
      "encoding": {
        "color": "strand"
      },
      "offscreen": {
        "show": false
      },
      "indels": {
        "show": false
      }
    }
  ]
}
Redraw the figure headlessly
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
      ],
      "mark": {
        "interpolate": "linear"
      },
      "encoding": {
        "color": "strand"
      },
      "offscreen": {
        "show": false
      },
      "indels": {
        "show": 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

More: Using JBrowse with AI agents.

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

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/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
            ],
            "mark": {
                "interpolate": "linear"
            },
            "encoding": {
                "color": "strand"
            },
            "offscreen": {
                "show": False
            },
            "indels": {
                "show": False
            }
        }
    ],
)
app  # display the widget

This view in your React 19 app, with @jbrowse/react-app2 and @jbrowse/core. Add your own files to tracks.

import { use } from 'react'
import { JBrowse } from '@jbrowse/react-app2'
import '@jbrowse/react-app2/styles.css'
import { addRelativeUris } from '@jbrowse/core/util/addRelativeUris'

const configUrl = "https://jbrowse.org/demos/fly_agent_synteny/config.json"
const configPromise = fetch(configUrl)
  .then(res => res.json())
  .then(config => {
    addRelativeUris(config, new URL(configUrl))
    return config
  })

export default function Figure() {
  const config = use(configPromise)
  return (
    <JBrowse
      assemblies={config.assemblies}
      tracks={config.tracks}
      aggregateTextSearchAdapters={config.aggregateTextSearchAdapters}
      configuration={config.configuration}
      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
          ],
          "mark": {
            "interpolate": "linear"
          },
          "encoding": {
            "color": "strand"
          },
          "offscreen": {
            "show": false
          },
          "indels": {
            "show": false
          }
        }
      ]}
    />
  )
}

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

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "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
      ],
      "mark": {
        "interpolate": "linear"
      },
      "encoding": {
        "color": "strand"
      },
      "offscreen": {
        "show": false
      },
      "indels": {
        "show": false
      }
    }
  ]
}
JSON

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

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

The session spec behind the figure, over this config.

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "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
      ],
      "mark": {
        "interpolate": "linear"
      },
      "encoding": {
        "color": "strand"
      },
      "offscreen": {
        "show": false
      },
      "indels": {
        "show": false
      }
    }
  ]
}

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. You can then check the view against those numbers.

Running the whole pipeline as a script

build_fly_agent_synteny.sh runs the pipeline without the agent. It needs the tools in Prerequisites, plus jq and curl. The script:

  1. Downloads both genomes from their hosted GenArk configs.
  2. Aligns simulans against mauritiana with minimap2.
  3. Indexes the PAF as PIF.
  4. Merges the two hosted configs and the synteny track into one config.json to open in Desktop.
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

See also

Citations