Skip to main content

Proteins on genomes.jbrowse.org

2 videos in this tutorial

JBrowse v5 beta

The tutorials target the JBrowse v5 beta, and the v4.3.0 release on the download page lacks some of what they show. To install the beta of JBrowse Web, run npm install -g @jbrowse/cli@next, then jbrowse create jbrowse2 --branch v5.0.0-beta.17. Desktop beta builds are coming soon.

A missense variant changes one codon, and what it does depends on where that residue sits in the folded protein and how conserved it is across related proteins. The protein browser on genomes.jbrowse.org takes a gene symbol and opens the gene, its 3D structure and an alignment of related proteins as one JBrowse session, linked so that a residue picked in one view lights up in the other two. We'll:

  • open TP53 in the protein browser on R248, a cancer hotspot, and read the session it launches
  • change what the session opens on: a domain, a structure, a coloring
  • launch the same views from a gene's right-click menu, where you choose the structure and the species to align, on NLRP1, whose domains differ between mammals

Prerequisites

The data

Nothing to download: the protein browser and the two plugins fetch from these services, per gene, when you open a session. Adding the plugins to your own instance covers your own JBrowse.

The files
What it isFile
AlphaFold DB, the predicted structuresalphafold.ebi.ac.uk
PDBe, the experimental structurespdbe/
UniProt, the protein each gene encodes and the projected Domains, Chains, Mutations and AA Modifications trackswww.uniprot.org
InterPro, the protein browser's domain map and the Pfam seed alignmentsinterpro/
PDBe-KB, the protein browser's partner and ligand listspdbe-kb/
UniRef, the cluster a protein with no NCBI orthologs is aligned withuniref
NCBI's ortholog report, the rows of an ortholog alignmentrest-api/
NCBI's Conserved Domain Database, the alignment's domain overlaycdd.shtml

Opening TP53 in the protein browser

We'll start on TP53's R248, one of the residues most often mutated in human cancer, where the protein contacts DNA. Open the protein browser and click the TP53 chip, which focuses the page on that residue:

  • The page draws the protein end to end with its InterPro domains, marks R248 on the ruler, and shows the focus beside the launch button as Opens at Cancer hotspot R248.
  • Tick Advanced. The Structure box shows the entry the chip picked, 3KMD, the DNA-binding core of p53 bound to DNA.
  • Set Color to AlphaMissense pathogenicity, which paints each residue by how damaging AlphaMissense predicts a substitution there to be.
  • Click Open in JBrowse ↗.

Typing a gene into the search box and pressing Search opens the same card with no focus. Advanced also adds a species box, which takes any species name or NCBI taxon ID whose genome genomes.jbrowse.org hosts with NCBI gene annotation, and the chips after TP53 open other organisms on a residue each, such as rifampicin resistance in M. tuberculosis rpoB.

The protein browser on the TP53 chip with Advanced ticked: the picked structure and coloring above the launch button, and the protein map below. Open TP53 in the protein browser ↗

Reading the TP53 session

Open in JBrowse opens a new tab with one session and three views of the same transcript:

  • The gene, its coding exons back to back with the introns cut out, read 5′ to 3′, above ClinVar's variants and AlphaMissense's scores
  • The alignment, the seed alignment of the Pfam family R248 falls in, P53, opened on the columns around R248 with TP53's own row, linked to the gene, in the middle. The launch button's tooltip names the alignment before you click.
  • The structure, 3KMD in Mol*, with R248 selected

Hover a codon in the gene view and its residue lights up on the structure and its column in the alignment; hover the structure or the alignment and the codon lights up in turn. g2p_mapper maps each position through the transcript's coding sequence, so introns, UTRs and residues the structure does not cover highlight nothing.

TP53 as the protein browser launches it on R248: the coding exons over ClinVar and AlphaMissense, the P53 family alignment on R248's column, and 3KMD colored by AlphaMissense with R248 in magenta. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)

Changing what the TP53 session opens on

The page picks the session's alignment and structure from the focus beside the launch button. Click Clear to drop it, and choose another:

  • A domain: click a block on the map's Domains row. The session opens on the domain, with the seed alignment of its Pfam family.
  • A residue: type a position into the Residue box, which Advanced shows while nothing is focused. The alignment becomes the Pfam seed of the domain the residue falls in, and the structure the PDB entry in which that residue was seen touching DNA, a small molecule or another protein, else the AlphaFold model.
  • A partner or a ligand: under Advanced, click Partners… or Ligands… on the map to list the proteins and small molecules PDB entries show touching this one. Clicking one opens the complex they were seen in.
  • A truncation: under a focused residue, More about residue offers to open on the residues a stop codon there, or skipping its exon, would remove.
  • Nothing: the session opens on the whole gene, the AlphaFold model and an alignment of the gene's orthologs from NCBI, one per species, built in the browser when the session opens. NCBI lists orthologs for vertebrates and insects; any other protein gets its UniRef50 cluster instead.

Structure under Advanced overrides the pick with any AlphaFold or PDB entry, and Color also offers ClinVar pathogenic variants and, on an AlphaFold model, AlphaFold confidence (pLDDT). The page URL holds the gene, the focus and the structure, so ?gene=TP53&ref=9606&residue=248&structure=3kmd reopens this launch.

Launching from the gene's right-click menu

The protein browser picks the structure and the alignment for you. A gene's right-click menu, in any JBrowse with the protein3d and msaview plugins, lets you pick both, and starts from a gene already on screen.

Open hg38 on genomes.jbrowse.org, type TP53 into the location box, and right-click the gene. The menu has Launch protein view from protein3d and Launch MSA view from msaview. Choose Launch protein view.

The dialog opens on its AlphaFoldDB search tab:

  • Look up from the feature's identifiers (selected) maps the transcript's accession to UniProt entries and picks the reviewed one.
  • Choose transcript isoform opens on the isoform you right-clicked, picks which transcript becomes the query, and tags the isoforms whose translation matches the structure's residues.
  • Launch renders the structure.
TP53's right-click launcher, the dialog resolving a UniProt entry and an isoform, and the structure Launch renders. Hovering a coding position picks out its residue.

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

  1. Right-click TP53 and launch its protein structure
  2. Hover a coding position: the structure lights its residue
  3. An intron maps to no residue
  4. Each coding base of the genome maps to one residue of the structure
Open this view in JBrowse Web ↗ ·

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 genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a .2bit genome.
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq Curated”.
    1. Track menu → Gene glyph → Representative transcript
  3. Add the next track the same way. This one needs a BigBed file (.bb).This figure uses “ClinVar Variants - ClinVar SNVs”.
  4. Type your region of interest into the location box and press Enter.This figure is at chr17:7,674,400-7,676,600.

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,674,400-7,676,600",
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "geneGlyphMode": "longestCoding",
          "height": 60
        },
        {
          "trackId": "hg38-clinvarMain",
          "height": 90
        }
      ]
    }
  ]
}

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/ucsc/hg38/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr17:7,674,400-7,676,600",
            "tracks": [
                {
                    "trackId": "hg38-ncbiRefSeqCurated",
                    "geneGlyphMode": "longestCoding",
                    "height": 60
                },
                {
                    "trackId": "hg38-clinvarMain",
                    "height": 90
                }
            ]
        }
    ],
)
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: a data file opens as the track its name says.

npx @jbrowse/img --config https://jbrowse.org/ucsc/hg38/config.json \
  --assembly hg38 --loc chr17:7,674,400-7,676,600 \
  --track hg38-ncbiRefSeqCurated '{"geneGlyphMode":"longestCoding","height":60}' \
  --track hg38-clinvarMain '{"height":90}' \
  --width 1920 --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": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,674,400-7,676,600",
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "geneGlyphMode": "longestCoding",
          "height": 60
        },
        {
          "trackId": "hg38-clinvarMain",
          "height": 90
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/latest/ \
  --config https://jbrowse.org/ucsc/hg38/config.json \
  --width 1920 --height 1400 \
  --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.

The structure opens under the genome view, linked the same way as the protein browser's. Where its sequence differs from the transcript's translation, the Pairwise alignment panel shows each residue the structure lacks as a gap, and Import manual alignment... in the view menu takes a pairwise alignment of your own in Clustal format instead. The lookup needs a gene feature with a recognizable protein or transcript ID, which the RefSeq gene tracks on the hosted configs have.

The protein view also has per-residue tracks for pLDDT, domains, helices and hydrophobicity. Open side by side, at the foot of the list the arrow beside the dialog's Launch button opens, puts the protein view beside the genome view. Click the nuclear export signal on the alignment panel's Motif row to select its residues and band their codons on the gene.

A connected session on TP53, NCBI RefSeq above the AlphaFold structure. A motif clicked on the protein's feature track selects its residues and bands their codons.
Open in JBrowse Web ↗

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:

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

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

    {
  "views": [
    {
      "type": "ProteinView",
      "uniprotId": "P04637",
      "transcriptId": "NM_000546.6",
      "height": 340,
      "sideBySide": true,
      "zoomToBaseLevel": false,
      "connectedView": {
        "assembly": "hg38",
        "loc": "chr17:7,668,000-7,688,000",
        "tracks": [
          {
            "trackId": "hg38-ncbiRefSeq",
            "geneGlyphMode": "longestCoding",
            "height": 70
          }
        ]
      }
    }
  ]
}

    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": "ProteinView",
      "uniprotId": "P04637",
      "transcriptId": "NM_000546.6",
      "height": 340,
      "sideBySide": true,
      "zoomToBaseLevel": false,
      "connectedView": {
        "assembly": "hg38",
        "loc": "chr17:7,668,000-7,688,000",
        "tracks": [
          {
            "trackId": "hg38-ncbiRefSeq",
            "geneGlyphMode": "longestCoding",
            "height": 70
          }
        ]
      }
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/protein3d_config.json \
  --width 2000 --height 632 \
  --timeout 90000 \
  --spec session.json -o figure.png

    The figure's clicks select the nuclear export signal, banding its codons on the gene and its residues on the structure, which this command does not do, so its picture differs there.

    It leaves out 3 callouts anchored to what the clicks bring up.

    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.

    Other structure sources and views in the Launch dialog

    The dialog's other tabs take a structure from elsewhere:

    • PDB search lists the experimental structures PDBe maps to the protein's UniProt entry
    • Foldseek search finds structures similar to the protein's
    • File or URL takes a PDB or mmCIF file of yours

    Click the arrow beside Launch to list everything the dialog can build. Launch 1D protein annotation view opens a linear genome view whose genome is the protein. The plugin registers the UniProt accession as a temporary assembly with the amino-acid sequence as its reference, so coordinates are residues. The view opens with these tracks on:

    • UniProt features, a section per feature type
    • Antigen
    • AlphaFold confidence (pLDDT) and AlphaMissense scores
    • ClinVar, the transcript's missense variants
    TP53 above the 1D protein view its gene menu launched, with its tracks in residue coordinates.
    Open in JBrowse Web ↗

    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 genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a .2bit genome.
    2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq Curated”.
      1. Track menu → Gene glyph → Representative transcript
    3. Type your region of interest into the location box and press Enter.This figure is at chr17:7,668,000-7,688,000.

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

    {
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,668,000-7,688,000",
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "geneGlyphMode": "longestCoding",
          "height": 60
        }
      ]
    }
  ]
}

    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/ucsc/hg38/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr17:7,668,000-7,688,000",
            "tracks": [
                {
                    "trackId": "hg38-ncbiRefSeqCurated",
                    "geneGlyphMode": "longestCoding",
                    "height": 60
                }
            ]
        }
    ],
)
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: a data file opens as the track its name says.

    npx @jbrowse/img --config https://jbrowse.org/ucsc/hg38/config.json \
  --assembly hg38 --loc chr17:7,668,000-7,688,000 \
  --track hg38-ncbiRefSeqCurated '{"geneGlyphMode":"longestCoding","height":60}' \
  --width 1500 --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": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,668,000-7,688,000",
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "geneGlyphMode": "longestCoding",
          "height": 60
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/ucsc/hg38/config.json \
  --width 1500 --height 1500 \
  --timeout 120000 \
  --spec session.json -o figure.png

    The figure's clicks launch the 1D protein annotation view, which this command does not do, so its picture differs there.

    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.

    TP53's launch dialog opened on the arrow beside Launch, then the 1D annotation view.

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

    1. Open a view whose genome is the protein itself
    2. The arrow beside Launch holds the 1D annotation view
    3. A section per UniProt feature type, then AlphaFold scores, residue by residue
    Open this view in JBrowse Web ↗ ·

    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 genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a .2bit genome.
    2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq Curated”.
      1. Track menu → Gene glyph → Representative transcript
    3. Type your region of interest into the location box and press Enter.This figure is at chr17:7,668,000-7,688,000.

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

    {
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,668,000-7,688,000",
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "geneGlyphMode": "longestCoding",
          "height": 60
        }
      ]
    }
  ]
}

    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/ucsc/hg38/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr17:7,668,000-7,688,000",
            "tracks": [
                {
                    "trackId": "hg38-ncbiRefSeqCurated",
                    "geneGlyphMode": "longestCoding",
                    "height": 60
                }
            ]
        }
    ],
)
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: a data file opens as the track its name says.

    npx @jbrowse/img --config https://jbrowse.org/ucsc/hg38/config.json \
  --assembly hg38 --loc chr17:7,668,000-7,688,000 \
  --track hg38-ncbiRefSeqCurated '{"geneGlyphMode":"longestCoding","height":60}' \
  --width 1920 --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": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,668,000-7,688,000",
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "geneGlyphMode": "longestCoding",
          "height": 60
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/ucsc/hg38/config.json \
  --width 1920 --height 1170 \
  --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.

    Launch an alignment from the same right-click menu too, and each panel's menu has Arrange all views → Side by side, which puts the genome, alignment and structure in three columns.

    TP53's gene menu launching an alignment and a structure, then Arrange all views → Side by side. One hover in the genome moves the highlight in both.

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

    1. Align TP53 with 15 of its orthologs from the gene's menu
    2. Then launch its AlphaFold structure the same way
    3. Tile the three views side by side
    4. Hover a coding position: the alignment and structure follow
    5. One genome position: one alignment column, one residue on the structure
    Open this view in JBrowse Web ↗ ·

    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 genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a .2bit genome.
    2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq Curated”.
      1. Track menu → Gene glyph → Representative transcript
    3. Add the next track the same way. This one needs a BigBed file (.bb).This figure uses “ClinVar Variants - ClinVar SNVs”.
    4. Type your region of interest into the location box and press Enter.This figure is at chr17:7,674,400-7,676,600.

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

    {
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,674,400-7,676,600",
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "geneGlyphMode": "longestCoding",
          "height": 60
        },
        {
          "trackId": "hg38-clinvarMain",
          "height": 90
        }
      ]
    }
  ]
}

    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/ucsc/hg38/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr17:7,674,400-7,676,600",
            "tracks": [
                {
                    "trackId": "hg38-ncbiRefSeqCurated",
                    "geneGlyphMode": "longestCoding",
                    "height": 60
                },
                {
                    "trackId": "hg38-clinvarMain",
                    "height": 90
                }
            ]
        }
    ],
)
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: a data file opens as the track its name says.

    npx @jbrowse/img --config https://jbrowse.org/ucsc/hg38/config.json \
  --assembly hg38 --loc chr17:7,674,400-7,676,600 \
  --track hg38-ncbiRefSeqCurated '{"geneGlyphMode":"longestCoding","height":60}' \
  --track hg38-clinvarMain '{"height":90}' \
  --width 1920 --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": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,674,400-7,676,600",
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "geneGlyphMode": "longestCoding",
          "height": 60
        },
        {
          "trackId": "hg38-clinvarMain",
          "height": 90
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/ucsc/hg38/config.json \
  --width 1920 --height 1060 \
  --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.

    Choosing the species to align for NLRP1

    Launch MSA view builds an alignment from the orthologs NCBI publishes for most annotated genes, one per species, with the rows and the aligner yours to choose. We'll use NLRP1, an inflammasome sensor whose domain architecture varies between mammals. Type NLRP1 into the location box, right-click the gene and choose Launch MSA view. The dialog opens on its Orthologs tab:

    • Query species is the species the gene came from, free text resolved against NCBI's taxonomy: a scientific name, a common name or a taxon id
    • Rows to align is how many species to build. NCBI orders its ortholog report from the reference organisms outward, so this takes the closest N
    • Choose isoform picks which transcript becomes the query row, the one the genome view stays linked to
    • MSA Algorithm sets which aligner EBI runs, Clustal Omega by default
    • BLAST query, a separate tab, takes a gene with no resolvable symbol

    Press Submit. The alignment opens below the genome view, with a tree on the left and NCBI's conserved domains drawn over the residues once NCBI returns them. It opens at residue zoom on the N terminus; View → Zoom → Fit width (View is the eye icon in the alignment's toolbar) puts the whole alignment on screen, which is the zoom the domain blocks read at.

    NLRP1's right-click menu, the Launch MSA view dialog on its Orthologs tab, and the alignment Submit builds.
    Open in JBrowse Web ↗

    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 genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a .2bit genome.
    2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq Curated”.
      1. Track menu → Gene glyph → Representative transcript
    3. Type your region of interest into the location box and press Enter.This figure is at chr17:5,495,000-5,591,000.

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

    {
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:5,495,000-5,591,000",
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "geneGlyphMode": "longestCoding",
          "height": 60
        }
      ]
    }
  ]
}

    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/ucsc/hg38/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr17:5,495,000-5,591,000",
            "tracks": [
                {
                    "trackId": "hg38-ncbiRefSeqCurated",
                    "geneGlyphMode": "longestCoding",
                    "height": 60
                }
            ]
        }
    ],
)
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: a data file opens as the track its name says.

    npx @jbrowse/img --config https://jbrowse.org/ucsc/hg38/config.json \
  --assembly hg38 --loc chr17:5,495,000-5,591,000 \
  --track hg38-ncbiRefSeqCurated '{"geneGlyphMode":"longestCoding","height":60}' \
  --width 1500 --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": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:5,495,000-5,591,000",
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "geneGlyphMode": "longestCoding",
          "height": 60
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/ucsc/hg38/config.json \
  --width 1500 --height 900 \
  --timeout 120000 \
  --spec session.json -o figure.png

    The figure stacks 3 frames of a click-through; this command draws the view it starts from.

    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.

    Reading NLRP1's conserved-domain overlay on the MSA

    Each colored block is an NCBI conserved domain, drawn in alignment columns. The pyrin (PYD) domain sits at the N terminus of human NLRP1 and is absent from mouse Nlrp1a. NACHT, the winged helix, HD2, FIIND and CARD run across nearly every row and are the control; the whale rows have only the C-terminal end.

    The domain calls come from NCBI's protein records. For a protein NCBI has no calls for:

    • react-msaview-cli interproscan scans the sequences into a domain file.
    • File → Open annotation file... reads that file in. The dialog's How to make one link opens a walkthrough that also covers interpro, the instant path when the rows are UniProt accessions.

    UniProt domains in genome coordinates for NLRP1

    UCSC projects UniProt's annotations onto the genome, so the hosted config holds them as tracks. Turn on UniProt - Domains (under Genes and Gene Predictions) in the linear view you launched from, then narrow it to one record:

    • Filter by... in the track menu applies the row uniProtId is Q9C000, the gene's reviewed UniProt entry. Without it, the track draws a domain once per isoform, and isoforms sharing exons overlap.
    • UniProt - Chains, Mutations and AA Modifications project the rest of the record.
    NLRP1 with NCBI RefSeq above UniProt - Domains, filtered to the gene's reviewed UniProt entry.
    Open in JBrowse Web ↗

    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 genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a .2bit genome.
    2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq Curated”.
      1. Track menu → Gene glyph → Representative transcript
    3. Add the next track the same way. This one needs a BigBed file (.bb).This figure uses “UniProt - Domains”.
      1. Track menu → Filter by... → add the expressionThis figure filters on get(feature,'uniProtId')=='Q9C000'.
    4. Type your region of interest into the location box and press Enter.This figure is at chr17:5,495,000-5,591,000.

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

    {
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:5,495,000-5,591,000",
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "geneGlyphMode": "longestCoding",
          "height": 60
        },
        {
          "trackId": "hg38-unipDomain",
          "filter": [
            "jexl:get(feature,'uniProtId')=='Q9C000'"
          ],
          "height": 90
        }
      ]
    }
  ]
}

    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/ucsc/hg38/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr17:5,495,000-5,591,000",
            "tracks": [
                {
                    "trackId": "hg38-ncbiRefSeqCurated",
                    "geneGlyphMode": "longestCoding",
                    "height": 60
                },
                {
                    "trackId": "hg38-unipDomain",
                    "filter": [
                        "jexl:get(feature,'uniProtId')=='Q9C000'"
                    ],
                    "height": 90
                }
            ]
        }
    ],
)
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: a data file opens as the track its name says.

    npx @jbrowse/img --config https://jbrowse.org/ucsc/hg38/config.json \
  --assembly hg38 --loc chr17:5,495,000-5,591,000 \
  --track hg38-ncbiRefSeqCurated '{"geneGlyphMode":"longestCoding","height":60}' \
  --track hg38-unipDomain '{"filter":["jexl:get(feature,'\''uniProtId'\'')=='\''Q9C000'\''"],"height":90}' \
  --width 1500 --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": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:5,495,000-5,591,000",
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "geneGlyphMode": "longestCoding",
          "height": 60
        },
        {
          "trackId": "hg38-unipDomain",
          "filter": [
            "jexl:get(feature,'uniProtId')=='Q9C000'"
          ],
          "height": 90
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/ucsc/hg38/config.json \
  --width 1500 --height 390 \
  --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.

    More protein browser sessions

    A protein browser session takes any other JBrowse track beside the codon, and a second protein view beside the first. Each figure's live link opens its session.1

    Open a figure's live link and hover the highlighted codon in the genome view; each protein view then lights the residue it codes for.

    BRCA1 at codon 1775 with the saturation genome editing score of every missense change and the AlphaMissense score of every possible base change, above 1T15 twice: colored by the scan's residue mean on the left and by AlphaMissense on the right. The M1775R highlight names the residue in both structures. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)
    TP53 at codon 248 with the Funk 2025 CRISPR scan and AlphaMissense, above the p53 dimer on DNA (3KMD) colored by the scan's mean per codon on the left and by AlphaMissense on the right. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)
    TP53 with every missense change of a CRISPR scan around codon 220, above the p53 surface at residue 220 in wild type (2XWR), Y220C (2J1X) and Y220C bound to rezatapopt (9S9O), all from one camera. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)
    BRCA1 with saturation genome editing scores and ClinVar records at codon 1775, above 1T15 with the BACH1 peptide and 1N5O, the M1775R crystal, with that peptide superposed from 1T15. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)
    SNCA codons 46 and 80 above one layer of the wild-type rod polymorph (6CU7) and the E46K (6UFR) α-synuclein fibrils, turned so Lys80 sits at the same place in both, with the distance between residues 46 and 80 drawn in the mutant. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)
    TP53 with a saturation genome editing score track, the alignment's domains and two protein views: 5MG7 and 7B49, both bound to DNA. R273H is labelled in every view. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)
    KRAS at codon 12 with its single-base missense changes, above the KRAS surface at residue 12 in wild type (4OBE), G12C (4LDJ) and G12C bound to sotorasib (6OIM), all from one camera, with switch II colored. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)
    CCR5 with the 1000 Genomes 30x reads of a Δ32/Δ32, a Δ32/+ and a +/+ sample over the 32-base deletion, above the codons the shifted frame reads, then CCR5 bound by HIV gp120, drawn green (6MEO), beside CCR5 alone, drawn only to the last residue the frameshift spares. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)
    CCR5 on hg38 above the Δ32 allele as its own assembly, with the deletion drawn as the pinch between the two alignment blocks and the Δ32 coding sequence ending at its premature stop. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)
    The same locus in one session: the three samples' reads over the deletion, CCR5 on hg38 above the Δ32 allele as its own assembly, and the receptor drawn whole beside the part the frameshift spares. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)
    APOE under a Manhattan plot of FinnGen Alzheimer's disease statistics, above the ortholog alignment and two protein views: the 1B68 crystal structure and its AlphaFold model colored by pLDDT. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)
    F5 under a Manhattan plot of FinnGen venous thromboembolism statistics, with the alignment and two protein views: factor Va alone (7KXY) and bound to activated protein C (9MOV). Open this view in JBrowse ↗ (large dataset — this session takes a while to load)
    BRAF with the activation loop and the ATP binding site as domain colors in the genome view, the alignment and 4MNF. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)
    CFTR with its ortholog alignment and 5UAK colored by ClinVar pathogenic variant count. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)
    HBB with the GWAS Catalog records at the codon and two protein views, 2HHB and 2HBS, colored by hydrophobicity. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)

    Adding the plugins to your own instance

    The plugin store lists the two plugins as Protein3d and MSAView, and Installing plugins covers each way to install them.

    The protein3d and msaview plugins add view types launched from a gene's right-click menu in JBrowse Web and Desktop. The single-view embedded components host only a linear genome view, so neither view type appears there. JBrowseR's JBrowseRApp takes both runtime plugins and a views list, while anywidget's JBrowseApp has no plugin loading yet.2

    The approach is described in Proteins in the Genome Browser (Journal of Molecular Biology, 2026).

    See also

    Citations

    Notes

    1. Some of these crystals carry engineered mutations. In the TP53 figure, 2J1X and 9S9O carry the stabilizing M133L, V203A, N239Y and N268D, none of them in the pocket. In the KRAS figure, 6OIM carries C51S, C80L and C118S, which remove the construct's other cysteines a covalent drug could react with. ↩

    2. A ProteinView entry in a session-spec URL opens a connected view for demo links and embedded apps. The short form takes uniprotId, transcriptId and a connectedView with the assembly, loc and tracks to look the transcript up in; the plugin derives the AlphaFold structure and translates the transcript's CDS. The explicit form takes a structure url, feature and protein sequence, for a transcript no loaded track serves. A ProteinView with only a url opens as a standalone structure. The protein3d launching guide has both forms. ↩