Customizing feature details

The track slot formatDetails takes jexl callbacks that return an object of fields to merge onto a feature: a new key adds a row, an existing key overrides it, and undefined/null hides it. formatAbout does the same for the About track dialog. For complex logic, register a jexl function in a small plugin.

{
  "trackId": "genes",
  "assemblyNames": ["volvox"],
  "name": "Genes",
  "uri": "volvox.sort.gff3.gz",
  "formatDetails": {
    "feature": "jexl:{name:'<a href=https://google.com/?q='+feature.name+'>'+feature.name+'</a>',extrafield:'Field added with custom callback:' + feature.name,phase:undefined,type:undefined}"
  }
}

jbrowse add-track-json '{
  "trackId": "genes",
  "assemblyNames": ["volvox"],
  "name": "Genes",
  "uri": "volvox.sort.gff3.gz",
  "formatDetails": {
    "feature": "jexl:{name:'\''<a href=https://google.com/?q='\''+feature.name+'\''>'\''+feature.name+'\''</a>'\'',extrafield:'\''Field added with custom callback:'\'' + feature.name,phase:undefined,type:undefined}"
  }
}'

{
  "trackId": "genes",
  "assemblyNames": ["volvox"],
  "name": "Genes",
  "uri": "volvox.sort.gff3.gz",
  "formatDetails": {
    "feature": "jexl:{name:'<a href=https://google.com/?q='+feature.name+'>'+feature.name+'</a>',extrafield:'Field added with custom callback:' + feature.name,phase:undefined,type:undefined}"
  }
}

✕

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

Copy

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A17200-23200%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22gff3tabix_genes%22%2C%22height%22%3A300%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+customized_feature_details

Or rebuild it from your own data:

Steps

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 volvox, 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 “GFF3Tabix genes”.
3. Type your region of interest into the location box and press Enter.This figure is at ctgA:17200-23200.

Spec

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

Copy

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:17200-23200",
      "tracks": [
        {
          "trackId": "gff3tabix_genes",
          "height": 300
        }
      ]
    }
  ]
}

Notebook

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

Copy

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/volvox/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "volvox",
            "loc": "ctgA:17200-23200",
            "tracks": [
                {
                    "trackId": "gff3tabix_genes",
                    "height": 300
                }
            ]
        }
    ],
)
app  # display the widget

Image

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.

Copy

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --assembly volvox --loc ctgA:17200-23200 \
  --track gff3tabix_genes '{"height":300}' \
  --width 1500 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Agent

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.

Copy

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:17200-23200",
      "tracks": [
        {
          "trackId": "gff3tabix_genes",
          "height": 300
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --width 1500 --height 680 \
  --spec session.json -o figure.png

The figure was taken after clicks this command does not make, so its picture can differ.

It leaves out 2 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.

The <a> markup is needed only because the link text differs from the URL; a value that is nothing but a URL is linked for you. The slots (feature, subfeatures, depth, maxDepth) are on the formatDetails config docs.

How the returned object is applied#

The callback's object is shallow-merged onto the feature, and the result drives the panel:

• A new key adds a row.
• An existing key replaces that row's value, core fields included: {type: undefined} removes the Type row, {name: ...} rewrites the Name row. length counts as one even though the panel computes it from start/end.
• undefined or null hides the row.
• subfeatures can be hidden but not replaced. Reshape each subfeature with the subfeatures callback instead; returning a new list is an error.
• A non-object return is an error. "jexl:feature.name" where "jexl:{name:feature.name}" was meant replaces the panel with a message naming the track, or the session configuration, whose callback failed.

The panel's rows and a plugin's extra panels read the merged feature; an extra panel also gets the original as unformatted. The sequence panel reads only the original, so a rewritten name or type never reaches its FASTA header, transcript picker or sequence. A saved session keeps the raw feature and re-runs the callbacks on load, so editing a track's formatDetails reshapes an open panel in place.

What a callback can see#

• feature is the clicked feature, or in subfeatures the subfeature being formatted.
• track is the track's config, so one session-wide callback can link out per assembly: "jexl:{ncbi:'https://www.ncbi.nlm.nih.gov/gene/?term='+feature.name+'+'+track.assemblyNames[0]}".
• In subfeatures, parent is the feature this one sits in and depth how far down, 1 for a gene's transcript and 2 for the transcript's exon, so a transcript row can hold its gene's name: "jexl:{gene:parent.name}".

Values are HTML, and bare URLs become links#

Every value passes through an HTML sanitizer, so <b>, <a> and <table> render as markup, and a value that is not recognizable HTML is escaped (a VCF <TRA> allele still reads as <TRA>). A value that is just a URL becomes a link on its own; the cookbook's details recipe links a gene to NCBI that way.

Static fields, depth and maxDepth#

Only a string starting with jexl: is evaluated, so a field that is the same on every feature is written as a plain object. A GFF3 gene nests three levels deep (gene, mRNA, then exon and CDS), and two slots bound how far the panel goes:

• depth bounds the subfeatures callback. At 1 it reformats only the transcript rows.
• maxDepth bounds the panel. At 1 it shows the transcript cards but not the exon and CDS cards inside them, formatted or not.

{
  "trackId": "genes_transcripts_only",
  "name": "Genes",
  "uri": "volvox.sort.gff3.gz",
  "assemblyNames": ["volvox"],
  "formatDetails": {
    "feature": {
      "Source": "GENCODE v44",
      "Contact": "helpdesk@example.org",
      "phase": null
    },
    "subfeatures": "jexl:{Transcript:feature.name, phase:undefined}",
    "depth": 1,
    "maxDepth": 1
  }
}

jbrowse add-track-json '{
  "trackId": "genes_transcripts_only",
  "name": "Genes",
  "uri": "volvox.sort.gff3.gz",
  "assemblyNames": ["volvox"],
  "formatDetails": {
    "feature": {
      "Source": "GENCODE v44",
      "Contact": "helpdesk@example.org",
      "phase": null
    },
    "subfeatures": "jexl:{Transcript:feature.name, phase:undefined}",
    "depth": 1,
    "maxDepth": 1
  }
}'

{
  "trackId": "genes_transcripts_only",
  "name": "Genes",
  "uri": "volvox.sort.gff3.gz",
  "assemblyNames": ["volvox"],
  "formatDetails": {
    "feature": {
      "Source": "GENCODE v44",
      "Contact": "helpdesk@example.org",
      "phase": null
    },
    "subfeatures": "jexl:{Transcript:feature.name, phase:undefined}",
    "depth": 1,
    "maxDepth": 1
  }
}

Session-wide formatDetails#

The feature, subfeatures, depth and maxDepth slots also exist under configuration.formatDetails, applied to every track:

{
  "configuration": {
    "formatDetails": {
      "feature": "jexl:{Assembly:'hg19', score:undefined}",
      "subfeatures": "jexl:{Assembly:'hg19'}",
      "maxDepth": 2
    }
  }
}

Where a track sets the same slot, feature and subfeatures objects are merged (the track's keys over the session's) and depth/maxDepth override (the track's value wins).

Complex logic goes in a jexl function#

Register a function from a small plugin, as the no-build plugin tutorial shows, and call it from the slot: "feature": "jexl:{name:formatName(feature)}". The function can return a whole object (many attributes relabeled at once) or one value (a dbxref turned into a link).

The feature a formatDetails callback receives is a plain object read from the serialized session, so use property access (feature.start); feature.get('start') fails here. See property access vs get().

The About track dialog#

formatAbout reshapes the "About track" dialog the same way, on the track or session-wide as configuration.formatAbout. The callback's variable is config, the track's own configuration:

{
  "trackId": "genes",
  "name": "Genes",
  "uri": "volvox.sort.gff3.gz",
  "assemblyNames": ["volvox"],
  "formatAbout": {
    "hideUris": true,
    "config": "jexl:{Source:'GENCODE v44',adapter:undefined}"
  }
}

jbrowse add-track-json '{
  "trackId": "genes",
  "name": "Genes",
  "uri": "volvox.sort.gff3.gz",
  "assemblyNames": ["volvox"],
  "formatAbout": {
    "hideUris": true,
    "config": "jexl:{Source:'\''GENCODE v44'\'',adapter:undefined}"
  }
}'

{
  "trackId": "genes",
  "name": "Genes",
  "uri": "volvox.sort.gff3.gz",
  "assemblyNames": ["volvox"],
  "formatAbout": {
    "hideUris": true,
    "config": "jexl:{Source:'GENCODE v44',adapter:undefined}"
  }
}

• hideUris drops every file location from the dialog only; config.json still has them. A session-wide true cannot be turned back on by a track.
• config merges over the config shown, exactly as formatDetails.feature does.

Adding a panel or replacing the widget#

To add a section of your own or replace the widget wholesale, a plugin uses two extension points:

• Core-extraFeaturePanel appends a React component below the built-in sections
• Core-replaceWidget wraps or replaces the whole feature-details widget

See also#

• Config guide: Using jexl callbacks
• Config guide: Customizing feature colors
• Developer guide: Extension points