Skip to main content

Reviewing a gene prediction (Tiberius)

JBrowse v5 beta

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

We compare gene predictions from Tiberius, a deep-learning gene finder, on human chr22 with the GENCODE annotation, and:

  • sort the models that disagree into four classes
  • build a static review page with one card per model, each linking back into JBrowse

The pipeline is cmdcolin/gene-review-portal, and its README documents every option.

Prerequisites

  • an existing annotation of the genome, to compare the predictions against
  • to build a portal over your own genome: Node 23+, pnpm, htslib for tabix, and the JBrowse CLI

Where the data comes from

Tiberius predictions over GRCh38 (Gabriel et al. 2024), read against GENCODE 47 and the hg38 reference.

Nothing to download: the track configs and commands below read these files by URL.

The files

A Tiberius model that merges IL17REL and TTLL8

We'll load the GRCh38 sequence the predictions were made on, then the two annotations. Each annotation is a GFF3 that is bgzipped, sorted and tabix-indexed with its .tbi beside it (prep), and uses the assembly's refNames.

Goes in the assemblies array of config.json. See Assemblies.

{
  "name": "hg38",
  "uri": "https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz",
  "refNameAliases": {
    "uri": "https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/hg38_aliases.txt"
  },
  "cytobands": "https://jbrowse.org/genomes/GRCh38/cytoBand.txt"
}
jbrowse add-assembly https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz \
  --name hg38 \
  --refNameAliases https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/hg38_aliases.txt \
  --config '{"cytobands":"https://jbrowse.org/genomes/GRCh38/cytoBand.txt"}'

hg38 is one of the genomes JBrowse Desktop hosts, with gene tracks already set up: on the start screen click Show all available genomes and pick it. To load the files of this config instead:

In JBrowse Desktop, Open new genome on the start screen (or File → Open genome... in a session), then Open from a URL and paste, one per line:

https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz
https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz.fai
https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz.gzi

JBrowse reads the format off the file name. Then fill in:

  • Genome name: hg38
  • refName aliases (under More options): https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/hg38_aliases.txt
  • cytobands (under More options): https://jbrowse.org/genomes/GRCh38/cytoBand.txt

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

{
  "type": "FeatureTrack",
  "trackId": "tiberius",
  "name": "Tiberius predictions",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "https://jbrowse.org/genomes/GRCh38/tiberius_grch38.gff.gz"
  }
}
jbrowse add-track https://jbrowse.org/genomes/GRCh38/tiberius_grch38.gff.gz \
  --trackId tiberius \
  --name "Tiberius predictions" \
  --assemblyNames hg38

In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track... and, in Add a track from file or URL, enter:

  • Main file: https://jbrowse.org/genomes/GRCh38/tiberius_grch38.gff.gz

Click Next. JBrowse reads the adapter and track type off the file name. Then fill in:

  • Track name: Tiberius predictions
  • Assembly: hg38

Click Add.

Open this track in JBrowse Web ↗

Open this track in JBrowse Desktop ↗ (JBrowse Desktop 5.0+)

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

{
  "type": "FeatureTrack",
  "trackId": "gencode_v47",
  "name": "GENCODE 47",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "https://jbrowse.org/genomes/GRCh38/gencode/gencode.v47.chr_patch_hapl_scaff.annotation.sorted.gff3.gz"
  }
}
jbrowse add-track https://jbrowse.org/genomes/GRCh38/gencode/gencode.v47.chr_patch_hapl_scaff.annotation.sorted.gff3.gz \
  --trackId gencode_v47 \
  --name "GENCODE 47" \
  --assemblyNames hg38

In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track... and, in Add a track from file or URL, enter:

  • Main file: https://jbrowse.org/genomes/GRCh38/gencode/gencode.v47.chr_patch_hapl_scaff.annotation.sorted.gff3.gz

Click Next. JBrowse reads the adapter and track type off the file name. Then fill in:

  • Track name: GENCODE 47
  • Assembly: hg38

Click Add.

Open this track in JBrowse Web ↗

Open this track in JBrowse Desktop ↗ (JBrowse Desktop 5.0+)

Open the two annotations together at chr22:49,987,402-50,067,759. Tiberius draws one model, g14001.t1, across most of the window, where GENCODE has two genes with a gap between them. GENCODE's gene features have gene_name and no Name, so the track labels them by accession, ENSG00000188263 for IL17REL and ENSG00000138892 for TTLL8.

One Tiberius model spans IL17REL (ENSG00000188263) and TTLL8 (ENSG00000138892), which GENCODE annotates as separate genes. MLC1 on the right gets a separate prediction.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=test_data%2Fconfig_demo.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr22%3A49%2C987%2C402-50%2C067%2C759%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22tiberius_grch38%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A110%7D%2C%7B%22trackId%22%3A%22gencode_47%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%2C%22height%22%3A170%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+gene_prediction_merge

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 bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  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 “Tiberius gene predictions”.
  3. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “Gencode v47”.
    1. Track menu → Show only genes (checked)
  4. Type your region of interest into the location box and press Enter.This figure is at chr22:49,987,402-50,067,759.

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/config_demo.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr22:49,987,402-50,067,759",
      "tracks": [
        {
          "trackId": "tiberius_grch38",
          "type": "LinearBasicDisplay",
          "height": 110
        },
        {
          "trackId": "gencode_47",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "height": 170
        }
      ]
    }
  ]
}

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/code/jb2/main/test_data/config_demo.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr22:49,987,402-50,067,759",
            "tracks": [
                {
                    "trackId": "tiberius_grch38",
                    "type": "LinearBasicDisplay",
                    "height": 110
                },
                {
                    "trackId": "gencode_47",
                    "type": "LinearBasicDisplay",
                    "showOnlyGenes": True,
                    "height": 170
                }
            ]
        }
    ],
)
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.

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --assembly hg38 --loc chr22:49,987,402-50,067,759 \
  --track tiberius_grch38 display:LinearBasicDisplay '{"height":110}' \
  --track gencode_47 display:LinearBasicDisplay '{"showOnlyGenes":true,"height":170}' \
  --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": "chr22:49,987,402-50,067,759",
      "tracks": [
        {
          "trackId": "tiberius_grch38",
          "type": "LinearBasicDisplay",
          "height": 110
        },
        {
          "trackId": "gencode_47",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "height": 170
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --width 1500 --height 500 \
  --timeout 90000 \
  --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.

Sorting Tiberius models into five classes against GENCODE

The portal compares each Tiberius model on chr22 with GENCODE and puts it in one of five classes: Agrees and four classes of disagreement. Only the four disagreement classes get a card.

ClassWhat it meansOn chr22What an annotator does
Agreesshares splice junctions with a reference gene424nothing
Merged modelone prediction covers two separate reference genes1split into two models
Structure conflictcovers one gene but shares none of its splice junctions3check the exon structure
Novel locuspredicted where the reference annotates nothing12assess, then create
Novel codingpredicted coding where the reference has only non-coding features119assess coding potential

The portal applies these rules, and the PI4KA control exercises them:

  • A shared junction is an intron of one of the gene's transcripts.
  • Exons are compared with genes on the same strand.
  • A merge counts only when the genes it joins do not overlap each other. PI4KA spans 152 kb on the minus strand with SERPIND1 inside one of its introns on the plus strand; Tiberius predicts PI4KA correctly, and the portal leaves it off the list.
  • GENCODE readthrough genes (one transcript spanning two neighbours) such as CHKB-CPT1B overlap the genes they join, so the portal skips them.

Building the review portal with make-portal.mjs

Clone the pipeline and install it:

git clone https://github.com/cmdcolin/gene-review-portal
cd gene-review-portal
pnpm install

make-portal.mjs reads the two annotations, classifies every model, captures a JBrowse view at each candidate and writes the page:

# --region: scan one chromosome, fetching the annotations with tabix
# --max: candidates kept per class
# --with-app: bundle JBrowse, so the output needs no network
node bin/make-portal.mjs \
  --prediction https://jbrowse.org/genomes/GRCh38/tiberius_grch38.gff.gz \
  --reference https://jbrowse.org/genomes/GRCh38/gencode/gencode.v47.chr_patch_hapl_scaff.annotation.sorted.gff3.gz \
  --fasta https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz \
  --assembly hg38 --region chr22 --max 3 \
  --with-app --out ./portal

The output directory holds the page, a JBrowse config, one PNG per candidate and, with --with-app, a copy of JBrowse. Copy it to any web server to publish.

--rnaseq reads.bam adds an alignment track under every model, in the captures and in the links; repeat it for more BAMs, and label each with --rnaseq-name. Reads across the exons of a novel locus support it as a gene.

The example portal is this build with --rnaseq run on Human Brain Reference and Universal Human Reference BAMs from the Griffith lab's RNA-seq course data.

Using the review page: cards, filters and verdicts

The example portal covers chr22, with one card per model:

  • Card shows the class, the reference genes, the locus and a capture of the two annotations
  • Filter chips narrow the list to one class
  • Verdict buttons record what you decide
  • Open in JBrowse opens the same view live

Verdicts stay in your browser, and Export decisions writes them out as TSV. Building with --apollo <url> adds a second link to every card that opens the same window in Apollo, the annotation editor, and an apollo_url column to the exported TSV.

The Disagreements track: junctions that differ from GENCODE

Every capture and live link has a Disagreements track under the prediction, with one box per junction that differs from the reference, labelled with what moved:

g13605.t1:donor-1048

g13605.t1 covers CCDC116 with two exons. Its acceptor matches GENCODE, and its donor is 1,048 bp from any CCDC116 donor.

The track reads data/conflicts.bed, plain BED6 that bedtools also reads. The file also lists junction edits in models filed as Agrees (a model sharing four of its five junctions, say), which get no card.

chr22  21636314  21636431  g13605.t1:donor-1048     0  +
chr22  23977067  23977386  g13682.t1:donor+3025     0  -
chr22  50012765  50018574  g14001.t1:split          0  -

Checking the IL17REL and TTLL8 merge against GENCODE

Query GENCODE for the two genes the Tiberius model merges:

tabix https://jbrowse.org/genomes/GRCh38/gencode/gencode.v47.chr_patch_hapl_scaff.annotation.sorted.gff3.gz \
  chr22:49,987,402-50,067,759 |
  awk -F'\t' '$3=="gene"' |
  grep -E 'IL17REL|TTLL8' |
  cut -f1,4,5,7

IL17REL ends at 50,012,765 and TTLL8 starts at 50,018,575, both on the minus strand, and the Tiberius model runs through the gap between them. The same query at PI4KA returns two genes on opposite strands.

See also

Citations