Reviewing a gene prediction (Tiberius)
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.
A gene finder run on a genome returns thousands of gene models, and most of them agree with the existing annotation. A person has to look at each model that disagrees, such as two genes predicted as one, a gene with different exons, or a gene where nothing was annotated. We compare the predictions of Tiberius, a deep-learning gene finder, with GENCODE on human chr22, and turn the disagreements into a review page that links each one back into JBrowse. We:
- load the predictions and GENCODE as two gene tracks over a model that merges two genes
- sort every model against GENCODE into classes with the review pipeline
- build the static review page, with a JBrowse capture and an Open in JBrowse link per model
- review the cards, and read the Disagreements track the pipeline adds under each prediction
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.6 or newer, pnpm, htslib
(
bgzip,tabix),samtools, and the JBrowse CLI
# Debian/Ubuntu
sudo apt install samtools tabix nodejs
# or conda, which has every tool above
conda install -c bioconda -c conda-forge samtools htslib nodejs
# any platform
npm install -g @jbrowse/cli@nextThe data
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. Building the review portal takes your own prediction, annotation and genome in their place.
The files
| What it is | File |
|---|---|
| Tiberius gene predictions | tiberius_grch38.gff.gz |
| GENCODE 47 comprehensive annotation | gencode.v47.chr_patch_hapl_scaff.annotation.sorted.gff3.gz |
| Hg38 reference sequence | hg38.prefix.fa.gz |
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"
}Edits config.json in the current folder, creating it if there is none. See JBrowse CLI with Desktop.
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 Browse hosted genomes and pick it. To load the files of this config instead:
In JBrowse Desktop, Open your own 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.gziJBrowse 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.
{
"trackId": "tiberius_grch38",
"name": "Tiberius gene predictions",
"uri": "https://jbrowse.org/genomes/GRCh38/tiberius_grch38.gff.gz",
"assemblyNames": ["hg38"]
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track https://jbrowse.org/genomes/GRCh38/tiberius_grch38.gff.gz \
--trackId tiberius_grch38 \
--name "Tiberius gene predictions" \
--assemblyNames hg38In 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
JBrowse reads the adapter and track type off the file name. Then fill in:
- Track name:
Tiberius gene predictions - Assembly:
hg38
Click Add.
Open this track in JBrowse Web ↗
Needs JBrowse Desktop 5.0 or newer. If nothing opens, copy the link and paste it into Desktop's Open JBrowse Web link..., on the start screen or under File → Session.
https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fucsc%2Fhg38%2Fconfig.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22trackId%22%3A%22tiberius_grch38%22%2C%22name%22%3A%22Tiberius+gene+predictions%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fgenomes%2FGRCh38%2Ftiberius_grch38.gff.gz%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%7D%5D%2C%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%22tiberius_grch38%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+Tiberius+gene+predictionsThis 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/ucsc/hg38/config.json")
app = JBrowseApp(
assemblies=config["assemblies"],
tracks=config.get("tracks", []) + [
{
"trackId": "tiberius_grch38",
"name": "Tiberius gene predictions",
"uri": "https://jbrowse.org/genomes/GRCh38/tiberius_grch38.gff.gz",
"assemblyNames": [
"hg38"
]
}
],
views=[
{
"type": "LinearGenomeView",
"assembly": "hg38",
"loc": "chr22:49,987,402-50,067,759",
"tracks": [
"tiberius_grch38"
]
}
],
)
app # display the widgetThis 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/ucsc/hg38/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 ?? []), ...[
{
"trackId": "tiberius_grch38",
"name": "Tiberius gene predictions",
"uri": "https://jbrowse.org/genomes/GRCh38/tiberius_grch38.gff.gz",
"assemblyNames": [
"hg38"
]
}
]]}
aggregateTextSearchAdapters={config.aggregateTextSearchAdapters}
configuration={config.configuration}
views={[
{
"type": "LinearGenomeView",
"assembly": "hg38",
"loc": "chr22:49,987,402-50,067,759",
"tracks": [
"tiberius_grch38"
]
}
]}
/>
)
}jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.
cat > tracks.json <<'JSON'
[
{
"trackId": "tiberius_grch38",
"name": "Tiberius gene predictions",
"uri": "https://jbrowse.org/genomes/GRCh38/tiberius_grch38.gff.gz",
"assemblyNames": [
"hg38"
]
}
]
JSON
npx @jbrowse/img --config https://jbrowse.org/ucsc/hg38/config.json \
--trackConfigs tracks.json \
--assembly hg38 --loc chr22:49,987,402-50,067,759 \
--track tiberius_grch38 \
--out figure.svgFor a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).
GENCODE's GFF3 also has region features that would draw as a bar above the
genes, so the geneLike filter keeps the genes and their transcripts:
Goes in the tracks array of config.json. See Tracks.
{
"trackId": "gencode_47",
"name": "Gencode v47",
"uri": "https://jbrowse.org/genomes/GRCh38/gencode/gencode.v47.chr_patch_hapl_scaff.annotation.sorted.gff3.gz",
"assemblyNames": ["hg38"],
"displayDefaults": { "filter": ["geneLike"] }
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track https://jbrowse.org/genomes/GRCh38/gencode/gencode.v47.chr_patch_hapl_scaff.annotation.sorted.gff3.gz \
--trackId gencode_47 \
--name "Gencode v47" \
--assemblyNames hg38 \
--displayDefaults '{"filter":["geneLike"]}'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:
{
"trackId": "gencode_47",
"name": "Gencode v47",
"uri": "https://jbrowse.org/genomes/GRCh38/gencode/gencode.v47.chr_patch_hapl_scaff.annotation.sorted.gff3.gz",
"assemblyNames": ["hg38"],
"displayDefaults": { "filter": ["geneLike"] }
}Open this track in JBrowse Web ↗
Needs JBrowse Desktop 5.0 or newer. If nothing opens, copy the link and paste it into Desktop's Open JBrowse Web link..., on the start screen or under File → Session.
https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fucsc%2Fhg38%2Fconfig.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22trackId%22%3A%22gencode_47%22%2C%22name%22%3A%22Gencode+v47%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fgenomes%2FGRCh38%2Fgencode%2Fgencode.v47.chr_patch_hapl_scaff.annotation.sorted.gff3.gz%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%2C%22displayDefaults%22%3A%7B%22filter%22%3A%5B%22geneLike%22%5D%7D%7D%5D%2C%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%22gencode_47%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+Gencode+v47This 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/ucsc/hg38/config.json")
app = JBrowseApp(
assemblies=config["assemblies"],
tracks=config.get("tracks", []) + [
{
"trackId": "gencode_47",
"name": "Gencode v47",
"uri": "https://jbrowse.org/genomes/GRCh38/gencode/gencode.v47.chr_patch_hapl_scaff.annotation.sorted.gff3.gz",
"assemblyNames": [
"hg38"
],
"displayDefaults": {
"filter": [
"geneLike"
]
}
}
],
views=[
{
"type": "LinearGenomeView",
"assembly": "hg38",
"loc": "chr22:49,987,402-50,067,759",
"tracks": [
"gencode_47"
]
}
],
)
app # display the widgetThis 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/ucsc/hg38/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 ?? []), ...[
{
"trackId": "gencode_47",
"name": "Gencode v47",
"uri": "https://jbrowse.org/genomes/GRCh38/gencode/gencode.v47.chr_patch_hapl_scaff.annotation.sorted.gff3.gz",
"assemblyNames": [
"hg38"
],
"displayDefaults": {
"filter": [
"geneLike"
]
}
}
]]}
aggregateTextSearchAdapters={config.aggregateTextSearchAdapters}
configuration={config.configuration}
views={[
{
"type": "LinearGenomeView",
"assembly": "hg38",
"loc": "chr22:49,987,402-50,067,759",
"tracks": [
"gencode_47"
]
}
]}
/>
)
}jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.
cat > tracks.json <<'JSON'
[
{
"trackId": "gencode_47",
"name": "Gencode v47",
"uri": "https://jbrowse.org/genomes/GRCh38/gencode/gencode.v47.chr_patch_hapl_scaff.annotation.sorted.gff3.gz",
"assemblyNames": [
"hg38"
],
"displayDefaults": {
"filter": [
"geneLike"
]
}
}
]
JSON
npx @jbrowse/img --config https://jbrowse.org/ucsc/hg38/config.json \
--trackConfigs tracks.json \
--assembly hg38 --loc chr22:49,987,402-50,067,759 \
--track gencode_47 \
--out figure.svgFor a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).
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.
Sorting Tiberius models into five classes against GENCODE
The merge above is one kind of disagreement. 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.
| Class | What it means | On chr22 | What an annotator does |
|---|---|---|---|
| Agrees | shares splice junctions with a reference gene | 424 | nothing |
| Merged model | one prediction covers two separate reference genes | 1 | split into two models |
| Structure conflict | covers one gene but shares none of its splice junctions | 3 | check the exon structure |
| Novel locus | predicted where the reference annotates nothing | 12 | assess, then create |
| Novel coding | predicted coding where the reference has only non-coding features | 119 | assess 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 is 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-CPT1Boverlap 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 installmake-portal.mjs reads the two annotations, classifies every model, captures a
JBrowse view at each candidate and writes the page. Each input is a local path
or a URL; for the chr22 example, pass the three URLs from the data table:
# --prediction: the gene finder's GFF3; --reference: the annotation to compare
# it with; --fasta: the genome both annotate
# --assembly: the name the page's JBrowse config gives that genome
# --region: scan one chromosome, fetching the annotations with tabix
# --max: candidates kept per class
# --with-app: bundle JBrowse, so the output needs no network
# add --aliases <file> when the annotations and the FASTA name chromosomes
# differently (chr22 against 22)
node bin/make-portal.mjs \
--prediction predictions.gff3.gz \
--reference reference.gff3.gz \
--fasta genome.fa.gz \
--assembly hg38 --region chr22 --max 3 \
--with-app --out ./portalThe 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
run against the hg38 hub's GENCODE 49, with --rnaseq 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
Open the example portal, or
npx serve ./portal for your own build. It has 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
The page keeps verdicts in your browser. Export writes them out as TSV, and
Import reads that TSV back on another browser. 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-1048g13605.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 -See also
- Tutorial: RNA-seq visualization
- Tutorial: Protein domains on gene models
- Config guide: Supported file types
- Docs: Capturing a JBrowse view from a script
Citations
- Gabriel et al. (2024). Tiberius: end-to-end deep learning with an HMM for gene prediction
- Frankish et al. (2023). GENCODE: reference annotation for the human and mouse genomes in 2023
Feedback on this tutorial is welcome: contact us.