Skip to main content

Cookbook

Copy-paste recipes for the settings people reach for most. Each is a whole track config, so it lands the same way in config.json, through the CLI, or pasted into a running JBrowse. They run against the volvox sample data JBrowse ships (test_data/volvox).

The smallest config

An assembly to supply the reference sequence, and a track to draw on it:

{
  "assemblies": [{ "name": "volvox", "uri": "volvox.2bit" }],
  "tracks": [{ "trackId": "genes", "uri": "volvox.sort.gff3.gz" }]
}

JBrowse reads the adapter and the track type off the file's extension, finds the index sibling, and takes name from the file name (the shortest track). The same track written out, which is where every recipe below starts:

{
  "type": "FeatureTrack",
  "trackId": "genes",
  "name": "Genes",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "Gff3TabixAdapter", "uri": "volvox.sort.gff3.gz" }
}
jbrowse add-track volvox.sort.gff3.gz \
  --trackId genes \
  --name Genes \
  --assemblyNames volvox \
  --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": "FeatureTrack",
  "trackId": "genes",
  "name": "Genes",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "Gff3TabixAdapter", "uri": "volvox.sort.gff3.gz" }
}

Display settings go in displayDefaults, which routes each one to the display that defines it. A jexl: prefix turns any slot into a per-feature callback (using jexl callbacks). About → Copy config on a track writes out what you set in the app.

A complete config

The same file with the settings people usually reach for: a track of each common type, a defaultSession to open on load, and a theme. Every recipe below changes one piece of it.

{
  "assemblies": [{ "name": "volvox", "uri": "volvox.2bit" }],
  "tracks": [
    {
      "type": "FeatureTrack",
      "trackId": "genes",
      "name": "Genes",
      "category": ["Annotation"],
      "assemblyNames": ["volvox"],
      "adapter": { "type": "Gff3TabixAdapter", "uri": "volvox.sort.gff3.gz" },
      "displayDefaults": {
        "color": "jexl:feature.strand==1?'tomato':feature.strand==-1?'cornflowerblue':'goldenrod'",
        "height": 200,
        "mouseover": "jexl:feature.name"
      }
    },
    {
      "type": "AlignmentsTrack",
      "trackId": "reads",
      "name": "Reads",
      "assemblyNames": ["volvox"],
      "adapter": { "type": "BamAdapter", "uri": "volvox-sorted.bam" },
      "displayDefaults": {
        "heightMode": "fit",
        "colorBy": { "type": "mappingQuality" },
        "filterBy": { "flagExclude": 1540, "flagInclude": 0 }
      }
    },
    {
      "type": "QuantitativeTrack",
      "trackId": "coverage",
      "name": "Coverage",
      "assemblyNames": ["volvox"],
      "adapter": { "type": "BigWigAdapter", "uri": "volvox_microarray.bw" },
      "displayDefaults": {
        "color": "#C8B414",
        "scaleType": "log",
        "minScore": 0
      }
    },
    {
      "type": "VariantTrack",
      "trackId": "variants",
      "name": "Variants",
      "assemblyNames": ["volvox"],
      "adapter": { "type": "VcfTabixAdapter", "uri": "volvox.filtered.vcf.gz" },
      "displayDefaults": {
        "color": "jexl:feature.type=='SNV'?'green':'purple'",
        "jexlFilters": ["feature.INFO.AF[0] > 0.05"]
      }
    }
  ],
  "defaultSession": {
    "name": "My session",
    "views": [
      {
        "type": "LinearGenomeView",
        "loc": "ctgA:1-50000",
        "assembly": "volvox",
        "tracks": ["genes", "reads", "coverage", "variants"]
      }
    ]
  },
  "configuration": {
    "theme": { "palette": { "primary": { "main": "#311b92" } } }
  }
}

Colors

color takes a CSS color or a jexl: expression that runs once per feature. These are the colors Color by... → Strand writes, so forward stays red everywhere in the app, synteny ribbons included:

{
  "type": "FeatureTrack",
  "trackId": "genes_by_strand",
  "name": "Genes (colored by strand)",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "Gff3TabixAdapter", "uri": "volvox.sort.gff3.gz" },
  "displayDefaults": {
    "color": "jexl:feature.strand==1?'tomato':feature.strand==-1?'cornflowerblue':'goldenrod'"
  }
}
jbrowse add-track volvox.sort.gff3.gz \
  --trackId genes_by_strand \
  --name "Genes (colored by strand)" \
  --assemblyNames volvox \
  --displayDefaults "{\"color\":\"jexl:feature.strand==1?'tomato':feature.strand==-1?'cornflowerblue':'goldenrod'\"}" \
  --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": "FeatureTrack",
  "trackId": "genes_by_strand",
  "name": "Genes (colored by strand)",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "Gff3TabixAdapter", "uri": "volvox.sort.gff3.gz" },
  "displayDefaults": {
    "color": "jexl:feature.strand==1?'tomato':feature.strand==-1?'cornflowerblue':'goldenrod'"
  }
}
NCBI RefSeq genes on hg38 with this recipe applied: forward-strand genes red, reverse-strand blue. Open this view in JBrowse ↗

The steps behind the figure above, run against your own data.

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses hg38, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add your own track: File → Open track..., then 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 analysis set (GFF3Tabix)”.
  3. Drag the bar at the bottom edge of the track to resize it.
  4. Track menu → Color by... → Strand
  5. Type your region of interest into the location box and press Enter.This figure is at chr17:7,400,000-7,700,000.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? 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%22chr17%3A7%2C400%2C000-7%2C700%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22ncbi_refseq_109_hg38%22%2C%22height%22%3A260%2C%22color%22%3A%22jexl%3Afeature.strand%3D%3D1%3F%27tomato%27%3Afeature.strand%3D%3D-1%3F%27cornflowerblue%27%3A%27goldenrod%27%22%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+cookbook_color_by_strand

This session spec pastes after &session=spec- on any JBrowse Web instance.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,400,000-7,700,000",
      "tracks": [
        {
          "trackId": "ncbi_refseq_109_hg38",
          "height": 260,
          "color": "jexl:feature.strand==1?'tomato':feature.strand==-1?'cornflowerblue':'goldenrod'"
        }
      ]
    }
  ]
}

Loaded against config: test_data/config_demo.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

from jbrowse_anywidget import LinearGenomeView, fetch_hub

view = LinearGenomeView(
    assembly=fetch_hub("hg38"),
    location="chr17:7,400,000-7,700,000",
)

view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track",
    "name": "My track",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "Gff3TabixAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,400,000-7,700,000",
      "tracks": [
        {
          "trackId": "ncbi_refseq_109_hg38",
          "height": 260,
          "color": "jexl:feature.strand==1?'tomato':feature.strand==-1?'cornflowerblue':'goldenrod'"
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --session 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.

Every attribute is a plain property on feature. VCF INFO fields parse as arrays, so index them (feature.INFO.SVTYPE[0]), and on a gene track the expression runs once per exon, so a transcript's attribute is feature.parent.myattr. A color that comes out undefined paints magenta.

RecipedisplayDefaults
Solid color{ "color": "#6a3d9a" }
By feature type (lookup table){ "color": "jexl:{CDS:'#d62728',exon:'#2ca02c',gene:'#1f77b4'}[feature.type] || 'gray'" }
By a numeric threshold{ "color": "jexl:feature.score > 7.3 ? 'red' : '#0068d1'" }
Continuous gradient from a number{ "color": "jexl:`hsl(${feature.score*3},50%,50%)`" }
Auto color per category{ "color": "jexl:randomColor(feature.type)" }
BED file's own colorsleave color unset
BAM/CRAM tag (AlignmentsTrack){ "colorBy": { "type": "tag", "tag": "HP" } }

The lookup table can key on any field the track exposes, and the legend slot names what each color stands for:

{
  "type": "FeatureTrack",
  "trackId": "rmsk_hg38",
  "name": "RepeatMasker",
  "assemblyNames": ["hg38"],
  "adapter": { "type": "BedTabixAdapter", "uri": "rmsk.bed.gz" },
  "displayDefaults": {
    "color": "jexl:{SINE:'#e41a1c',LINE:'#377eb8',LTR:'#4daf4a',DNA:'#984ea3',Simple_repeat:'#ff7f00',Low_complexity:'#a65628'}[feature.repClass] || 'gray'",
    "legend": [
      { "label": "SINE", "color": "#e41a1c" },
      { "label": "LINE", "color": "#377eb8" },
      { "label": "LTR", "color": "#4daf4a" },
      { "label": "DNA", "color": "#984ea3" },
      { "label": "Simple repeat", "color": "#ff7f00" },
      { "label": "Low complexity", "color": "#a65628" },
      { "label": "other", "color": "gray" }
    ]
  }
}
jbrowse add-track rmsk.bed.gz \
  --trackId rmsk_hg38 \
  --name RepeatMasker \
  --assemblyNames hg38 \
  --displayDefaults "{\"color\":\"jexl:{SINE:'#e41a1c',LINE:'#377eb8',LTR:'#4daf4a',DNA:'#984ea3',Simple_repeat:'#ff7f00',Low_complexity:'#a65628'}[feature.repClass] || 'gray'\",\"legend\":[{\"label\":\"SINE\",\"color\":\"#e41a1c\"},{\"label\":\"LINE\",\"color\":\"#377eb8\"},{\"label\":\"LTR\",\"color\":\"#4daf4a\"},{\"label\":\"DNA\",\"color\":\"#984ea3\"},{\"label\":\"Simple repeat\",\"color\":\"#ff7f00\"},{\"label\":\"Low complexity\",\"color\":\"#a65628\"},{\"label\":\"other\",\"color\":\"gray\"}]}" \
  --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": "FeatureTrack",
  "trackId": "rmsk_hg38",
  "name": "RepeatMasker",
  "assemblyNames": ["hg38"],
  "adapter": { "type": "BedTabixAdapter", "uri": "rmsk.bed.gz" },
  "displayDefaults": {
    "color": "jexl:{SINE:'#e41a1c',LINE:'#377eb8',LTR:'#4daf4a',DNA:'#984ea3',Simple_repeat:'#ff7f00',Low_complexity:'#a65628'}[feature.repClass] || 'gray'",
    "legend": [
      { "label": "SINE", "color": "#e41a1c" },
      { "label": "LINE", "color": "#377eb8" },
      { "label": "LTR", "color": "#4daf4a" },
      { "label": "DNA", "color": "#984ea3" },
      { "label": "Simple repeat", "color": "#ff7f00" },
      { "label": "Low complexity", "color": "#a65628" },
      { "label": "other", "color": "gray" }
    ]
  }
}
UCSC RepeatMasker over a 17q21 window with the lookup table above: every repeat takes the color of its repClass, and classes not in the table fall through to gray. The key over the track is the legend slot, spelling out what each color stands for. Open this view in JBrowse ↗

The steps behind the figure above, run against your own data.

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses hg38, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “RepeatMasker”.
  3. Drag the bar at the bottom edge of the track to resize it.
  4. Type your region of interest into the location box and press Enter.This figure is at chr17:45,700,000-45,750,000.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? 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%22sessionTracks%22%3A%5B%7B%22type%22%3A%22FeatureTrack%22%2C%22trackId%22%3A%22rmsk_hg38_ucsc%22%2C%22name%22%3A%22RepeatMasker%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22BedTabixAdapter%22%2C%22bedGzLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fucsc%2Fhg38%2Frmsk.bed.gz%22%2C%22locationType%22%3A%22UriLocation%22%7D%2C%22index%22%3A%7B%22indexType%22%3A%22CSI%22%2C%22location%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fucsc%2Fhg38%2Frmsk.bed.gz.csi%22%2C%22locationType%22%3A%22UriLocation%22%7D%7D%7D%2C%22displays%22%3A%5B%7B%22type%22%3A%22LinearBasicDisplay%22%2C%22color%22%3A%22jexl%3A%7BSINE%3A%27%23e41a1c%27%2CLINE%3A%27%23377eb8%27%2CLTR%3A%27%234daf4a%27%2CDNA%3A%27%23984ea3%27%2CSimple_repeat%3A%27%23ff7f00%27%2CLow_complexity%3A%27%23a65628%27%7D%5Bget%28feature%2C%27repClass%27%29%5D+%7C%7C+%27gray%27%22%2C%22legend%22%3A%5B%7B%22label%22%3A%22SINE%22%2C%22color%22%3A%22%23e41a1c%22%7D%2C%7B%22label%22%3A%22LINE%22%2C%22color%22%3A%22%23377eb8%22%7D%2C%7B%22label%22%3A%22LTR%22%2C%22color%22%3A%22%234daf4a%22%7D%2C%7B%22label%22%3A%22DNA%22%2C%22color%22%3A%22%23984ea3%22%7D%2C%7B%22label%22%3A%22Simple+repeat%22%2C%22color%22%3A%22%23ff7f00%22%7D%2C%7B%22label%22%3A%22Low+complexity%22%2C%22color%22%3A%22%23a65628%22%7D%2C%7B%22label%22%3A%22other%22%2C%22color%22%3A%22gray%22%7D%5D%7D%5D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr17%3A45%2C700%2C000-45%2C750%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22rmsk_hg38_ucsc%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A260%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+cookbook_color_by_type

A figure adds its tracks to one session. The jbrowse CLI writes the same tracks into a config.json instead, where every session that opens it has them: add-track where flags cover the whole track, add-track-json where they do not.

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "rmsk_hg38_ucsc",
  "name": "RepeatMasker",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "BedTabixAdapter",
    "bedGzLocation": {
      "uri": "https://jbrowse.org/ucsc/hg38/rmsk.bed.gz",
      "locationType": "UriLocation"
    },
    "index": {
      "indexType": "CSI",
      "location": {
        "uri": "https://jbrowse.org/ucsc/hg38/rmsk.bed.gz.csi",
        "locationType": "UriLocation"
      }
    }
  },
  "displays": [
    {
      "type": "LinearBasicDisplay",
      "color": "jexl:{SINE:'\''#e41a1c'\'',LINE:'\''#377eb8'\'',LTR:'\''#4daf4a'\'',DNA:'\''#984ea3'\'',Simple_repeat:'\''#ff7f00'\'',Low_complexity:'\''#a65628'\''}[get(feature,'\''repClass'\'')] || '\''gray'\''",
      "legend": [
        {
          "label": "SINE",
          "color": "#e41a1c"
        },
        {
          "label": "LINE",
          "color": "#377eb8"
        },
        {
          "label": "LTR",
          "color": "#4daf4a"
        },
        {
          "label": "DNA",
          "color": "#984ea3"
        },
        {
          "label": "Simple repeat",
          "color": "#ff7f00"
        },
        {
          "label": "Low complexity",
          "color": "#a65628"
        },
        {
          "label": "other",
          "color": "gray"
        }
      ]
    }
  ]
}'

Run these where the config.json is, or add --out <dir>, and point each uri at your own file. The config needs hg38 already — jbrowse add-assembly adds yours. The location and the settings the steps carry are session state rather than track config — that half is the Session spec tab, or jbrowse set-default-session.

This session spec pastes after &session=spec- on any JBrowse Web instance.

{
  "sessionTracks": [
    {
      "type": "FeatureTrack",
      "trackId": "rmsk_hg38_ucsc",
      "name": "RepeatMasker",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "BedTabixAdapter",
        "bedGzLocation": {
          "uri": "https://jbrowse.org/ucsc/hg38/rmsk.bed.gz",
          "locationType": "UriLocation"
        },
        "index": {
          "indexType": "CSI",
          "location": {
            "uri": "https://jbrowse.org/ucsc/hg38/rmsk.bed.gz.csi",
            "locationType": "UriLocation"
          }
        }
      },
      "displays": [
        {
          "type": "LinearBasicDisplay",
          "color": "jexl:{SINE:'#e41a1c',LINE:'#377eb8',LTR:'#4daf4a',DNA:'#984ea3',Simple_repeat:'#ff7f00',Low_complexity:'#a65628'}[get(feature,'repClass')] || 'gray'",
          "legend": [
            {
              "label": "SINE",
              "color": "#e41a1c"
            },
            {
              "label": "LINE",
              "color": "#377eb8"
            },
            {
              "label": "LTR",
              "color": "#4daf4a"
            },
            {
              "label": "DNA",
              "color": "#984ea3"
            },
            {
              "label": "Simple repeat",
              "color": "#ff7f00"
            },
            {
              "label": "Low complexity",
              "color": "#a65628"
            },
            {
              "label": "other",
              "color": "gray"
            }
          ]
        }
      ]
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:45,700,000-45,750,000",
      "tracks": [
        {
          "trackId": "rmsk_hg38_ucsc",
          "type": "LinearBasicDisplay",
          "height": 260
        }
      ]
    }
  ]
}

Loaded against config: test_data/config_demo.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

from jbrowse_anywidget import LinearGenomeView, fetch_hub

view = LinearGenomeView(
    assembly=fetch_hub("hg38"),
    location="chr17:45,700,000-45,750,000",
)

view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track",
    "name": "My track",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "BedTabixAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "sessionTracks": [
    {
      "type": "FeatureTrack",
      "trackId": "rmsk_hg38_ucsc",
      "name": "RepeatMasker",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "BedTabixAdapter",
        "bedGzLocation": {
          "uri": "https://jbrowse.org/ucsc/hg38/rmsk.bed.gz",
          "locationType": "UriLocation"
        },
        "index": {
          "indexType": "CSI",
          "location": {
            "uri": "https://jbrowse.org/ucsc/hg38/rmsk.bed.gz.csi",
            "locationType": "UriLocation"
          }
        }
      },
      "displays": [
        {
          "type": "LinearBasicDisplay",
          "color": "jexl:{SINE:'#e41a1c',LINE:'#377eb8',LTR:'#4daf4a',DNA:'#984ea3',Simple_repeat:'#ff7f00',Low_complexity:'#a65628'}[get(feature,'repClass')] || 'gray'",
          "legend": [
            {
              "label": "SINE",
              "color": "#e41a1c"
            },
            {
              "label": "LINE",
              "color": "#377eb8"
            },
            {
              "label": "LTR",
              "color": "#4daf4a"
            },
            {
              "label": "DNA",
              "color": "#984ea3"
            },
            {
              "label": "Simple repeat",
              "color": "#ff7f00"
            },
            {
              "label": "Low complexity",
              "color": "#a65628"
            },
            {
              "label": "other",
              "color": "gray"
            }
          ]
        }
      ]
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:45,700,000-45,750,000",
      "tracks": [
        {
          "trackId": "rmsk_hg38_ucsc",
          "type": "LinearBasicDisplay",
          "height": 260
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --session 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.

Customizing feature colors covers reading the type list off the file and moving an outgrown callback into a plugin.

Labels, tooltips & details

showLabels pins which text is drawn at every zoom, and mouseover is rendered as HTML:

{
  "type": "FeatureTrack",
  "trackId": "genes_labeled",
  "name": "Genes",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "Gff3TabixAdapter", "uri": "volvox.sort.gff3.gz" },
  "displayDefaults": {
    "labels": {
      "name": "jexl:feature.name || feature.id",
      "description": "jexl:feature.note || feature.description || ''"
    },
    "showLabels": "nameAndDescription",
    "mouseover": "jexl:`${feature.name} [${feature.type}] ${feature.start}-${feature.end}`"
  }
}
jbrowse add-track volvox.sort.gff3.gz \
  --trackId genes_labeled \
  --name Genes \
  --assemblyNames volvox \
  --displayDefaults "{\"labels\":{\"name\":\"jexl:feature.name || feature.id\",\"description\":\"jexl:feature.note || feature.description || ''\"},\"showLabels\":\"nameAndDescription\",\"mouseover\":\"jexl:\`\${feature.name} [\${feature.type}] \${feature.start}-\${feature.end}\`\"}" \
  --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": "FeatureTrack",
  "trackId": "genes_labeled",
  "name": "Genes",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "Gff3TabixAdapter", "uri": "volvox.sort.gff3.gz" },
  "displayDefaults": {
    "labels": {
      "name": "jexl:feature.name || feature.id",
      "description": "jexl:feature.note || feature.description || ''"
    },
    "showLabels": "nameAndDescription",
    "mouseover": "jexl:`${feature.name} [${feature.type}] ${feature.start}-${feature.end}`"
  }
}

formatDetails reshapes the click-details panel: the returned object merges into what is shown, a field set to undefined is hidden, and a bare URL becomes a link:

{
  "type": "FeatureTrack",
  "trackId": "genes_linked_details",
  "name": "Genes",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "Gff3TabixAdapter", "uri": "volvox.sort.gff3.gz" },
  "formatDetails": {
    "feature": "jexl:{NCBI:'https://www.ncbi.nlm.nih.gov/gene/?term='+feature.name, type:undefined}"
  }
}
jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "genes_linked_details",
  "name": "Genes",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "Gff3TabixAdapter", "uri": "volvox.sort.gff3.gz" },
  "formatDetails": {
    "feature": "jexl:{NCBI:'\''https://www.ncbi.nlm.nih.gov/gene/?term='\''+feature.name, type:undefined}"
  }
}'

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": "FeatureTrack",
  "trackId": "genes_linked_details",
  "name": "Genes",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "Gff3TabixAdapter", "uri": "volvox.sort.gff3.gz" },
  "formatDetails": {
    "feature": "jexl:{NCBI:'https://www.ncbi.nlm.nih.gov/gene/?term='+feature.name, type:undefined}"
  }
}

Customizing feature details covers subfeatures, the session-wide form, and the About dialog.

Feature tracks

heightMode fit shrinks the features so the whole stack fits the height, which is what gets a dense track into a screenshot without a scrollbar. jexlFilters draws only the features that pass every expression, on variant and alignments tracks too:

{
  "type": "FeatureTrack",
  "trackId": "genes_fit",
  "name": "Long genes only",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "Gff3TabixAdapter", "uri": "volvox.sort.gff3.gz" },
  "displayDefaults": {
    "height": 200,
    "heightMode": "fit",
    "jexlFilters": [
      "feature.end - feature.start > 1000",
      "feature.type == 'gene'"
    ]
  }
}
jbrowse add-track volvox.sort.gff3.gz \
  --trackId genes_fit \
  --name "Long genes only" \
  --assemblyNames volvox \
  --displayDefaults "{\"height\":200,\"heightMode\":\"fit\",\"jexlFilters\":[\"feature.end - feature.start > 1000\",\"feature.type == 'gene'\"]}" \
  --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": "FeatureTrack",
  "trackId": "genes_fit",
  "name": "Long genes only",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "Gff3TabixAdapter", "uri": "volvox.sort.gff3.gz" },
  "displayDefaults": {
    "height": 200,
    "heightMode": "fit",
    "jexlFilters": [
      "feature.end - feature.start > 1000",
      "feature.type == 'gene'"
    ]
  }
}

Alignments tracks

{
  "type": "AlignmentsTrack",
  "trackId": "my_bam",
  "name": "Haplotype 1 reads",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "BamAdapter", "uri": "volvox-sorted.bam" },
  "displayDefaults": {
    "height": 400,
    "colorBy": { "type": "mappingQuality" },
    "showSoftClipping": true,
    "groupBy": { "type": "tag", "tag": "HP" },
    "filterBy": {
      "flagExclude": 1540,
      "flagInclude": 0,
      "tagFilters": [{ "tag": "HP", "value": "1" }]
    }
  }
}
jbrowse add-track volvox-sorted.bam \
  --trackId my_bam \
  --name "Haplotype 1 reads" \
  --assemblyNames volvox \
  --displayDefaults '{"height":400,"colorBy":{"type":"mappingQuality"},"showSoftClipping":true,"groupBy":{"type":"tag","tag":"HP"},"filterBy":{"flagExclude":1540,"flagInclude":0,"tagFilters":[{"tag":"HP","value":"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": "AlignmentsTrack",
  "trackId": "my_bam",
  "name": "Haplotype 1 reads",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "BamAdapter", "uri": "volvox-sorted.bam" },
  "displayDefaults": {
    "height": 400,
    "colorBy": { "type": "mappingQuality" },
    "showSoftClipping": true,
    "groupBy": { "type": "tag", "tag": "HP" },
    "filterBy": {
      "flagExclude": 1540,
      "flagInclude": 0,
      "tagFilters": [{ "tag": "HP", "value": "1" }]
    }
  }
}
  • colorBy also takes strand, pairOrientation, insertSize, tag, and modifications
  • groupBy also takes strand, firstOfPairStrand, pairOrientation, supplementary, and mapq
  • flagExclude 1540 hides unmapped, vendor-failed, and duplicate reads; 3844 also hides secondary and supplementary (flag explainer)
  • CRAM uses CramAdapter in place of BamAdapter

Quantitative (wiggle) tracks

Setting color puts the track in single-color mode; left alone, a wiggle draws posColor above bicolorPivot and negColor below it. defaultRendering picks xyplot, line, scatter, or density.

{
  "type": "QuantitativeTrack",
  "trackId": "coverage",
  "name": "Coverage",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "BigWigAdapter", "uri": "volvox_microarray.bw" },
  "displayDefaults": { "color": "#C8B414", "scaleType": "log", "minScore": 0 }
}
jbrowse add-track volvox_microarray.bw \
  --trackId coverage \
  --name Coverage \
  --assemblyNames volvox \
  --displayDefaults '{"color":"#C8B414","scaleType":"log","minScore":0}' \
  --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": "QuantitativeTrack",
  "trackId": "coverage",
  "name": "Coverage",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "BigWigAdapter", "uri": "volvox_microarray.bw" },
  "displayDefaults": { "color": "#C8B414", "scaleType": "log", "minScore": 0 }
}

Multiple signals on one track, each its own color

{
  "type": "MultiQuantitativeTrack",
  "trackId": "multiwig",
  "name": "Grains",
  "assemblyNames": ["volvox"],
  "adapter": {
    "type": "MultiWiggleAdapter",
    "subadapters": [
      {
        "type": "BigWigAdapter",
        "name": "Grain1",
        "uri": "v1.bw",
        "color": "#f00"
      },
      {
        "type": "BigWigAdapter",
        "name": "Grain2",
        "uri": "v2.bw",
        "color": "#f60"
      }
    ]
  },
  "displayDefaults": { "defaultRendering": "multiline" }
}
jbrowse add-track-json '{
  "type": "MultiQuantitativeTrack",
  "trackId": "multiwig",
  "name": "Grains",
  "assemblyNames": ["volvox"],
  "adapter": {
    "type": "MultiWiggleAdapter",
    "subadapters": [
      {
        "type": "BigWigAdapter",
        "name": "Grain1",
        "uri": "v1.bw",
        "color": "#f00"
      },
      {
        "type": "BigWigAdapter",
        "name": "Grain2",
        "uri": "v2.bw",
        "color": "#f60"
      }
    ]
  },
  "displayDefaults": { "defaultRendering": "multiline" }
}'

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": "MultiQuantitativeTrack",
  "trackId": "multiwig",
  "name": "Grains",
  "assemblyNames": ["volvox"],
  "adapter": {
    "type": "MultiWiggleAdapter",
    "subadapters": [
      {
        "type": "BigWigAdapter",
        "name": "Grain1",
        "uri": "v1.bw",
        "color": "#f00"
      },
      {
        "type": "BigWigAdapter",
        "name": "Grain2",
        "uri": "v2.bw",
        "color": "#f60"
      }
    ]
  },
  "displayDefaults": { "defaultRendering": "multiline" }
}

A multirow* rendering stacks one row per signal; a multi* one overlays them. Pin minScore/maxScore when the quantity has an absolute meaning, or per-row autoscale draws a flat sample at the same height as an amplified one. Past a handful of samples, generate subadapters from your samplesheet (multi-quantitative tracks).

An eight-sample MultiQuantitativeTrack across 1.5 Mb of chr1 (multirowline), each 1000 Genomes individual its own color on a shared 0 to 5 copy-number scale. Every row sits at two copies through the flanks; only the amylase cluster in the middle separates them, from one copy to four. Open this view in JBrowse ↗

The steps behind the figure above, run against your own data.

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses hg38, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add your own track: File → Open track..., then 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 analysis set (GFF3Tabix)”.
  3. Drag the bar at the bottom edge of the track to resize it.“NCBI RefSeq analysis set (GFF3Tabix)”.
  4. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “PUR copy number (8 samples)”.
  5. Drag the bar at the bottom edge of the track to resize it.“PUR copy number (8 samples)”.
  6. Track menu → Plot type → Multi-row → Line (step)“PUR copy number (8 samples)”.
  7. Track menu → Score → Set min/max score...Sets the score-axis minimum (0 here).“PUR copy number (8 samples)”.
  8. Track menu → Score → Set min/max score...Sets the score-axis maximum (5 here).“PUR copy number (8 samples)”.
  9. Type your region of interest into the location box and press Enter.This figure is at chr1:102,900,000-104,400,000.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? 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%22sessionTracks%22%3A%5B%7B%22type%22%3A%22MultiQuantitativeTrack%22%2C%22trackId%22%3A%22cookbook_multiwig%22%2C%22name%22%3A%22PUR+copy+number+%288+samples%29%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22MultiWiggleAdapter%22%2C%22subadapters%22%3A%5B%7B%22type%22%3A%22BigWigAdapter%22%2C%22name%22%3A%22HG01080%22%2C%22color%22%3A%22%230072B2%22%2C%22bigWigLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fgenomes%2FGRCh38%2F1000g%2Fkidd_lab_cnv%2FPUR%2FHG01080.qm2.CN.1k.bw%22%2C%22locationType%22%3A%22UriLocation%22%7D%7D%2C%7B%22type%22%3A%22BigWigAdapter%22%2C%22name%22%3A%22HG01054%22%2C%22color%22%3A%22%23D55E00%22%2C%22bigWigLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fgenomes%2FGRCh38%2F1000g%2Fkidd_lab_cnv%2FPUR%2FHG01054.qm2.CN.1k.bw%22%2C%22locationType%22%3A%22UriLocation%22%7D%7D%2C%7B%22type%22%3A%22BigWigAdapter%22%2C%22name%22%3A%22HG00739%22%2C%22color%22%3A%22%23009E73%22%2C%22bigWigLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fgenomes%2FGRCh38%2F1000g%2Fkidd_lab_cnv%2FPUR%2FHG00739.qm2.CN.1k.bw%22%2C%22locationType%22%3A%22UriLocation%22%7D%7D%2C%7B%22type%22%3A%22BigWigAdapter%22%2C%22name%22%3A%22HG00553%22%2C%22color%22%3A%22%23CC79A7%22%2C%22bigWigLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fgenomes%2FGRCh38%2F1000g%2Fkidd_lab_cnv%2FPUR%2FHG00553.qm2.CN.1k.bw%22%2C%22locationType%22%3A%22UriLocation%22%7D%7D%2C%7B%22type%22%3A%22BigWigAdapter%22%2C%22name%22%3A%22HG01070%22%2C%22color%22%3A%22%23E69F00%22%2C%22bigWigLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fgenomes%2FGRCh38%2F1000g%2Fkidd_lab_cnv%2FPUR%2FHG01070.qm2.CN.1k.bw%22%2C%22locationType%22%3A%22UriLocation%22%7D%7D%2C%7B%22type%22%3A%22BigWigAdapter%22%2C%22name%22%3A%22HG00554%22%2C%22color%22%3A%22%2356B4E9%22%2C%22bigWigLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fgenomes%2FGRCh38%2F1000g%2Fkidd_lab_cnv%2FPUR%2FHG00554.qm2.CN.1k.bw%22%2C%22locationType%22%3A%22UriLocation%22%7D%7D%2C%7B%22type%22%3A%22BigWigAdapter%22%2C%22name%22%3A%22HG00551%22%2C%22color%22%3A%22%238B008B%22%2C%22bigWigLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fgenomes%2FGRCh38%2F1000g%2Fkidd_lab_cnv%2FPUR%2FHG00551.qm2.CN.1k.bw%22%2C%22locationType%22%3A%22UriLocation%22%7D%7D%2C%7B%22type%22%3A%22BigWigAdapter%22%2C%22name%22%3A%22HG01083%22%2C%22color%22%3A%22%23666666%22%2C%22bigWigLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fgenomes%2FGRCh38%2F1000g%2Fkidd_lab_cnv%2FPUR%2FHG01083.qm2.CN.1k.bw%22%2C%22locationType%22%3A%22UriLocation%22%7D%7D%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%22chr1%3A102%2C900%2C000-104%2C400%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22ncbi_refseq_109_hg38%22%2C%22height%22%3A130%7D%2C%7B%22trackId%22%3A%22cookbook_multiwig%22%2C%22height%22%3A480%2C%22defaultRendering%22%3A%22multirowline%22%2C%22minScore%22%3A0%2C%22maxScore%22%3A5%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+cookbook_multiwig

A figure adds its tracks to one session. The jbrowse CLI writes the same tracks into a config.json instead, where every session that opens it has them: add-track where flags cover the whole track, add-track-json where they do not.

jbrowse add-track-json '{
  "type": "MultiQuantitativeTrack",
  "trackId": "cookbook_multiwig",
  "name": "PUR copy number (8 samples)",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "MultiWiggleAdapter",
    "subadapters": [
      {
        "type": "BigWigAdapter",
        "name": "HG01080",
        "color": "#0072B2",
        "bigWigLocation": {
          "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG01080.qm2.CN.1k.bw",
          "locationType": "UriLocation"
        }
      },
      {
        "type": "BigWigAdapter",
        "name": "HG01054",
        "color": "#D55E00",
        "bigWigLocation": {
          "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG01054.qm2.CN.1k.bw",
          "locationType": "UriLocation"
        }
      },
      {
        "type": "BigWigAdapter",
        "name": "HG00739",
        "color": "#009E73",
        "bigWigLocation": {
          "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG00739.qm2.CN.1k.bw",
          "locationType": "UriLocation"
        }
      },
      {
        "type": "BigWigAdapter",
        "name": "HG00553",
        "color": "#CC79A7",
        "bigWigLocation": {
          "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG00553.qm2.CN.1k.bw",
          "locationType": "UriLocation"
        }
      },
      {
        "type": "BigWigAdapter",
        "name": "HG01070",
        "color": "#E69F00",
        "bigWigLocation": {
          "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG01070.qm2.CN.1k.bw",
          "locationType": "UriLocation"
        }
      },
      {
        "type": "BigWigAdapter",
        "name": "HG00554",
        "color": "#56B4E9",
        "bigWigLocation": {
          "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG00554.qm2.CN.1k.bw",
          "locationType": "UriLocation"
        }
      },
      {
        "type": "BigWigAdapter",
        "name": "HG00551",
        "color": "#8B008B",
        "bigWigLocation": {
          "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG00551.qm2.CN.1k.bw",
          "locationType": "UriLocation"
        }
      },
      {
        "type": "BigWigAdapter",
        "name": "HG01083",
        "color": "#666666",
        "bigWigLocation": {
          "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG01083.qm2.CN.1k.bw",
          "locationType": "UriLocation"
        }
      }
    ]
  }
}'

Run these where the config.json is, or add --out <dir>, and point each uri at your own file. The config needs hg38 already — jbrowse add-assembly adds yours. The location and the settings the steps carry are session state rather than track config — that half is the Session spec tab, or jbrowse set-default-session.

This session spec pastes after &session=spec- on any JBrowse Web instance.

{
  "sessionTracks": [
    {
      "type": "MultiQuantitativeTrack",
      "trackId": "cookbook_multiwig",
      "name": "PUR copy number (8 samples)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "MultiWiggleAdapter",
        "subadapters": [
          {
            "type": "BigWigAdapter",
            "name": "HG01080",
            "color": "#0072B2",
            "bigWigLocation": {
              "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG01080.qm2.CN.1k.bw",
              "locationType": "UriLocation"
            }
          },
          {
            "type": "BigWigAdapter",
            "name": "HG01054",
            "color": "#D55E00",
            "bigWigLocation": {
              "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG01054.qm2.CN.1k.bw",
              "locationType": "UriLocation"
            }
          },
          {
            "type": "BigWigAdapter",
            "name": "HG00739",
            "color": "#009E73",
            "bigWigLocation": {
              "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG00739.qm2.CN.1k.bw",
              "locationType": "UriLocation"
            }
          },
          {
            "type": "BigWigAdapter",
            "name": "HG00553",
            "color": "#CC79A7",
            "bigWigLocation": {
              "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG00553.qm2.CN.1k.bw",
              "locationType": "UriLocation"
            }
          },
          {
            "type": "BigWigAdapter",
            "name": "HG01070",
            "color": "#E69F00",
            "bigWigLocation": {
              "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG01070.qm2.CN.1k.bw",
              "locationType": "UriLocation"
            }
          },
          {
            "type": "BigWigAdapter",
            "name": "HG00554",
            "color": "#56B4E9",
            "bigWigLocation": {
              "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG00554.qm2.CN.1k.bw",
              "locationType": "UriLocation"
            }
          },
          {
            "type": "BigWigAdapter",
            "name": "HG00551",
            "color": "#8B008B",
            "bigWigLocation": {
              "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG00551.qm2.CN.1k.bw",
              "locationType": "UriLocation"
            }
          },
          {
            "type": "BigWigAdapter",
            "name": "HG01083",
            "color": "#666666",
            "bigWigLocation": {
              "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG01083.qm2.CN.1k.bw",
              "locationType": "UriLocation"
            }
          }
        ]
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr1:102,900,000-104,400,000",
      "tracks": [
        {
          "trackId": "ncbi_refseq_109_hg38",
          "height": 130
        },
        {
          "trackId": "cookbook_multiwig",
          "height": 480,
          "defaultRendering": "multirowline",
          "minScore": 0,
          "maxScore": 5
        }
      ]
    }
  ]
}

Loaded against config: test_data/config_demo.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

from jbrowse_anywidget import LinearGenomeView, fetch_hub

view = LinearGenomeView(
    assembly=fetch_hub("hg38"),
    location="chr1:102,900,000-104,400,000",
)

view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track_1",
    "name": "My track 1",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "Gff3TabixAdapter", "uri": "https://your-server/your-file"},
})
view.add_track({
    "type": "MultiQuantitativeTrack",
    "trackId": "my_track_2",
    "name": "My track 2",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "MultiWiggleAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "sessionTracks": [
    {
      "type": "MultiQuantitativeTrack",
      "trackId": "cookbook_multiwig",
      "name": "PUR copy number (8 samples)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "MultiWiggleAdapter",
        "subadapters": [
          {
            "type": "BigWigAdapter",
            "name": "HG01080",
            "color": "#0072B2",
            "bigWigLocation": {
              "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG01080.qm2.CN.1k.bw",
              "locationType": "UriLocation"
            }
          },
          {
            "type": "BigWigAdapter",
            "name": "HG01054",
            "color": "#D55E00",
            "bigWigLocation": {
              "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG01054.qm2.CN.1k.bw",
              "locationType": "UriLocation"
            }
          },
          {
            "type": "BigWigAdapter",
            "name": "HG00739",
            "color": "#009E73",
            "bigWigLocation": {
              "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG00739.qm2.CN.1k.bw",
              "locationType": "UriLocation"
            }
          },
          {
            "type": "BigWigAdapter",
            "name": "HG00553",
            "color": "#CC79A7",
            "bigWigLocation": {
              "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG00553.qm2.CN.1k.bw",
              "locationType": "UriLocation"
            }
          },
          {
            "type": "BigWigAdapter",
            "name": "HG01070",
            "color": "#E69F00",
            "bigWigLocation": {
              "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG01070.qm2.CN.1k.bw",
              "locationType": "UriLocation"
            }
          },
          {
            "type": "BigWigAdapter",
            "name": "HG00554",
            "color": "#56B4E9",
            "bigWigLocation": {
              "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG00554.qm2.CN.1k.bw",
              "locationType": "UriLocation"
            }
          },
          {
            "type": "BigWigAdapter",
            "name": "HG00551",
            "color": "#8B008B",
            "bigWigLocation": {
              "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG00551.qm2.CN.1k.bw",
              "locationType": "UriLocation"
            }
          },
          {
            "type": "BigWigAdapter",
            "name": "HG01083",
            "color": "#666666",
            "bigWigLocation": {
              "uri": "https://jbrowse.org/genomes/GRCh38/1000g/kidd_lab_cnv/PUR/HG01083.qm2.CN.1k.bw",
              "locationType": "UriLocation"
            }
          }
        ]
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr1:102,900,000-104,400,000",
      "tracks": [
        {
          "trackId": "ncbi_refseq_109_hg38",
          "height": 130
        },
        {
          "trackId": "cookbook_multiwig",
          "height": 480,
          "defaultRendering": "multirowline",
          "minScore": 0,
          "maxScore": 5
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --session 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.

Variant tracks

color and jexlFilters work as on a feature track, and VCF INFO fields are the usual thing to branch on:

{
  "type": "VariantTrack",
  "trackId": "svs_by_type",
  "name": "SVs by type",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "VcfTabixAdapter", "uri": "volvox.dup.vcf.gz" },
  "displayDefaults": {
    "color": "jexl:{DEL:'red',INS:'blue',DUP:'green',INV:'orange'}[feature.INFO.SVTYPE[0]] || 'gray'",
    "jexlFilters": ["feature.INFO.AF[0] > 0.05"]
  }
}
jbrowse add-track volvox.dup.vcf.gz \
  --trackId svs_by_type \
  --name "SVs by type" \
  --assemblyNames volvox \
  --displayDefaults "{\"color\":\"jexl:{DEL:'red',INS:'blue',DUP:'green',INV:'orange'}[feature.INFO.SVTYPE[0]] || 'gray'\",\"jexlFilters\":[\"feature.INFO.AF[0] > 0.05\"]}" \
  --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": "VariantTrack",
  "trackId": "svs_by_type",
  "name": "SVs by type",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "VcfTabixAdapter", "uri": "volvox.dup.vcf.gz" },
  "displayDefaults": {
    "color": "jexl:{DEL:'red',INS:'blue',DUP:'green',INV:'orange'}[feature.INFO.SVTYPE[0]] || 'gray'",
    "jexlFilters": ["feature.INFO.AF[0] > 0.05"]
  }
}

For a multi-sample VCF as a genotype grid, see variant tracks.

Synteny and dotplot tracks

Getting the two assemblies backwards is the most common mistake here. minimap2 takes its inputs target first (minimap2 grape.fa peach.fa makes grape the target), so name them explicitly. The query draws on the dotplot's horizontal axis and the top row in linear synteny; if the track loads blank, flip the two.

{
  "type": "SyntenyTrack",
  "trackId": "grape_peach_synteny",
  "name": "Grape vs Peach",
  "assemblyNames": ["peach", "grape"],
  "adapter": {
    "type": "PAFAdapter",
    "uri": "out.paf",
    "queryAssembly": "peach",
    "targetAssembly": "grape"
  }
}
jbrowse add-track-json '{
  "type": "SyntenyTrack",
  "trackId": "grape_peach_synteny",
  "name": "Grape vs Peach",
  "assemblyNames": ["peach", "grape"],
  "adapter": {
    "type": "PAFAdapter",
    "uri": "out.paf",
    "queryAssembly": "peach",
    "targetAssembly": "grape"
  }
}'

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": "grape_peach_synteny",
  "name": "Grape vs Peach",
  "assemblyNames": ["peach", "grape"],
  "adapter": {
    "type": "PAFAdapter",
    "uri": "out.paf",
    "queryAssembly": "peach",
    "targetAssembly": "grape"
  }
}

Large alignments

Every synteny adapter reads the whole file into memory, except the indexed (PIF) ones. Index a big PAF once, then use the same track with "type": "PairwiseIndexedPAFAdapter" and the .pif.gz as its uri:

jbrowse make-pif alignments.paf   # -> alignments.pif.gz (+ .tbi)

The synteny track guide has every adapter, and all-vs-all synteny stacks more than two genomes from one PAF.

Instance-wide settings

A nested category makes nested folders in the track selector, and metadata shows in the track details:

{
  "type": "AlignmentsTrack",
  "trackId": "brain_rnaseq",
  "name": "Brain RNA-seq",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "BamAdapter", "uri": "volvox-sorted.bam" },
  "category": ["RNA-seq", "Brain"],
  "metadata": {
    "description": "150bp paired-end reads",
    "source": "See <a href='https://example.com'>the paper</a>"
  }
}
jbrowse add-track-json '{
  "type": "AlignmentsTrack",
  "trackId": "brain_rnaseq",
  "name": "Brain RNA-seq",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "BamAdapter", "uri": "volvox-sorted.bam" },
  "category": ["RNA-seq", "Brain"],
  "metadata": {
    "description": "150bp paired-end reads",
    "source": "See <a href='\''https://example.com'\''>the paper</a>"
  }
}'

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": "AlignmentsTrack",
  "trackId": "brain_rnaseq",
  "name": "Brain RNA-seq",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "BamAdapter", "uri": "volvox-sorted.bam" },
  "category": ["RNA-seq", "Brain"],
  "metadata": {
    "description": "150bp paired-end reads",
    "source": "See <a href='https://example.com'>the paper</a>"
  }
}

refNameAliases lines up tracks that name the same chromosome differently (chr1 vs 1 vs NC_000001):

{
  "name": "volvox",
  "uri": "volvox.2bit",
  "refNameAliases": { "uri": "volvox.chromAliases.txt" }
}
jbrowse add-assembly volvox.2bit \
  --name volvox \
  --refNameAliases volvox.chromAliases.txt \
  --load copy

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

volvox.2bit

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

  • Genome name: volvox
  • refName aliases (under More options): volvox.chromAliases.txt
  • Text searching: jbrowse text-index builds the index and writes it into your config (text searching)
  • Theme: configuration.theme, as in the complete config above (theming)
  • Plugins: "plugins": [{ "name": "MyPlugin", "esmLoc": { "uri": "myplugin.js" } }] (plugins)

From config to a URL

https://host/jbrowse2/?config=config.json&assembly=volvox&loc=ctgA:1-50000&tracks=genes,coverage

assembly is the name of an entry in assemblies, loc is a region or a gene name once you have run jbrowse text-index, and tracks is a list of trackIds. A link like this ignores any defaultSession; add &extendSession=true to keep the session and change only the location. See URL query parameter API for display settings in the link, multi-view layouts, and share links.

Where to go next