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:

{
  "$schema": "https://jbrowse.org/jb2/schema/v5/config.json",
  "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. Every recipe below starts from this:

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

{
  "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" }
}

volvox.sort.gff3.gz is relative to a config.json. Replace it with its URL or its path on this computer.

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.

Shorthand and longhand

The one-line { trackId, uri } track above is the whole-track shorthand. JBrowse unpacks a shorthand one layer at a time until it reaches the longhand the engine reads, and every layer is also a valid config to write yourself. A key written at any layer wins over what the layers below would fill in.

The shortest form names the file:

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

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

{
  "trackId": "genes",
  "uri": "volvox.sort.gff3.gz",
  "assemblyNames": ["volvox"]
}

volvox.sort.gff3.gz is relative to a config.json. Replace it with its URL or its path on this computer.

The first unpacking reads the extension and adds the track type, the adapter with its uri, and a name from the file name:

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

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

volvox.sort.gff3.gz is relative to a config.json. Replace it with its URL or its path on this computer.

The second unpacking is the adapter's own uri shorthand, which becomes its location slot and the .tbi index beside it:

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

{
  "type": "FeatureTrack",
  "trackId": "genes",
  "name": "volvox.sort.gff3.gz",
  "assemblyNames": ["volvox"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "gffGzLocation": {
      "uri": "volvox.sort.gff3.gz",
      "locationType": "UriLocation"
    },
    "index": {
      "location": {
        "uri": "volvox.sort.gff3.gz.tbi",
        "locationType": "UriLocation"
      },
      "indexType": "TBI"
    }
  }
}
jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "genes",
  "name": "volvox.sort.gff3.gz",
  "assemblyNames": ["volvox"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "gffGzLocation": {
      "uri": "volvox.sort.gff3.gz",
      "locationType": "UriLocation"
    },
    "index": {
      "location": {
        "uri": "volvox.sort.gff3.gz.tbi",
        "locationType": "UriLocation"
      },
      "indexType": "TBI"
    }
  }
}'

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": "volvox.sort.gff3.gz",
  "assemblyNames": ["volvox"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "gffGzLocation": {
      "uri": "volvox.sort.gff3.gz",
      "locationType": "UriLocation"
    },
    "index": {
      "location": {
        "uri": "volvox.sort.gff3.gz.tbi",
        "locationType": "UriLocation"
      },
      "indexType": "TBI"
    }
  }
}

volvox.sort.gff3.gz, volvox.sort.gff3.gz.tbi are relative to a config.json. Replace each with its URL or its path on this computer.

All three configs above describe one track. Write the shortest for a file the extension describes, the middle for a different type or a displays array, and the last for an index that does not sit beside its file. An assembly unpacks the same way, { "name": "volvox", "uri": "volvox.2bit" } becoming a sequence adapter (file types lists the extensions).

A complete config

A config.json 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.

{
  "$schema": "https://jbrowse.org/jb2/schema/v5/config.json",
  "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": {
        "encoding": { "color": "strand" },
        "height": 200,
        "tooltip": "jexl:feature.name"
      }
    },
    {
      "type": "AlignmentsTrack",
      "trackId": "reads",
      "name": "Reads",
      "assemblyNames": ["volvox"],
      "adapter": { "type": "BamAdapter", "uri": "volvox-sorted.bam" },
      "displayDefaults": {
        "heightMode": "fit",
        "encoding": { "color": "mapq" },
        "filter": [{ "field": "mapq", "gte": 20 }]
      }
    },
    {
      "type": "QuantitativeTrack",
      "trackId": "coverage",
      "name": "Coverage",
      "assemblyNames": ["volvox"],
      "adapter": { "type": "BigWigAdapter", "uri": "volvox_microarray.bw" },
      "displayDefaults": {
        "encoding": {
          "y": { "scale": { "type": "log", "domainMin": 0 } },
          "color": { "value": "#C8B414" }
        }
      }
    },
    {
      "type": "VariantTrack",
      "trackId": "variants",
      "name": "Variants",
      "assemblyNames": ["volvox"],
      "adapter": { "type": "VcfTabixAdapter", "uri": "volvox.filtered.vcf.gz" },
      "displayDefaults": {
        "encoding": {
          "color": { "value": "jexl:feature.type=='SNV'?'green':'purple'" }
        },
        "filter": ["jexl: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

encoding.color is a CSS color as { "value": … }, or a field that paints each feature by its value and draws a key saying what each color means. This is the setting Color by → Strand writes, so forward stays red everywhere in the app, synteny ribbons included:

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

{
  "type": "FeatureTrack",
  "trackId": "genes_by_strand",
  "name": "Genes (colored by strand)",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "Gff3TabixAdapter", "uri": "volvox.sort.gff3.gz" },
  "displayDefaults": {
    "encoding": { "color": "strand" }
  }
}
jbrowse add-track volvox.sort.gff3.gz \
  --trackId genes_by_strand \
  --name "Genes (colored by strand)" \
  --assemblyNames volvox \
  --displayDefaults '{"encoding":{"color":"strand"}}' \
  --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": {
    "encoding": { "color": "strand" }
  }
}

volvox.sort.gff3.gz is relative to a config.json. Replace it with its URL or its path on this computer.

NCBI RefSeq genes with this recipe: forward strand red, reverse blue.
Open in JBrowse Web ↗

Or rebuild it from your own data:

Quickest: open the view, then File → Open track... for your files.

From scratch:

  1. Open your genome: Open new genome in JBrowse Desktop, or jbrowse add-assembly for JBrowse Web.This figure uses hg38, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add your track: File → Open track..., or check it in the track selector. Needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq analysis set (GFF3Tabix)”.
    1. Track menu → Color by → Strand
  3. Go to your region in the location box.This figure is at chr17:7,400,000-7,700,000.

Paste into a coding agent, with your goal on the first line.

My goal: [write yours, e.g. this view of my own files, or these track settings in my config.json]

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/code/jb2/main/test_data/config_demo.json
- Tracks:
  - NCBI RefSeq analysis set (GFF3Tabix) (ncbi_refseq_109_hg38), FeatureTrack, a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi), drawn as LinearBasicDisplay

Docs: https://jbrowse.org/jb2/docs/agents_authoring/ (writing a config), https://jbrowse.org/jb2/docs/agents/ (driving a running JBrowse). Use the jbrowse-authoring, jbrowse-hosted-data and jbrowse-capture skills if you have them. Check any config with `npx @jbrowse/cli validate`, then render it and look: a config that loads is not yet a track that drew.

The session spec that draws the view:
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,400,000-7,700,000",
      "tracks": [
        {
          "trackId": "ncbi_refseq_109_hg38",
          "height": 260,
          "encoding": {
            "color": {
              "field": "strand"
            }
          }
        }
      ]
    }
  ]
}
Redraw the figure headlessly
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,
          "encoding": {
            "color": {
              "field": "strand"
            }
          }
        }
      ]
    }
  ]
}
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 460 \
  --spec session.json -o figure.png

More: Using JBrowse with AI agents.

Adds these tracks to your config.json, styled as in the figure. Point each uri at your file (replace YOUR_FILE).

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "ncbi_refseq_109_hg38",
  "name": "NCBI RefSeq analysis set (GFF3Tabix)",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "height": 260,
    "encoding": {
      "color": {
        "field": "strand"
      }
    }
  }
}'

Run beside config.json, or add --out <dir>. Needs hg38 in the config (jbrowse add-assembly).

This 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/code/jb2/main/test_data/config_demo.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr17:7,400,000-7,700,000",
            "tracks": [
                {
                    "trackId": "ncbi_refseq_109_hg38",
                    "height": 260,
                    "encoding": {
                        "color": {
                            "field": "strand"
                        }
                    }
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --assembly hg38 --loc chr17:7,400,000-7,700,000 \
  --track ncbi_refseq_109_hg38 '{"height":260,"encoding":{"color":{"field":"strand"}}}' \
  --width 1500 --out figure.svg

For a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).

The session spec behind the figure, over this config.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,400,000-7,700,000",
      "tracks": [
        {
          "trackId": "ncbi_refseq_109_hg38",
          "height": 260,
          "encoding": {
            "color": {
              "field": "strand"
            }
          }
        }
      ]
    }
  ]
}

field names any attribute the track has. On a gene track a transcript's parts paint in the transcript's value, or the gene's where the transcript has none.

Recipeencoding.color
Solid color{ "value": "#6a3d9a" }
A color per value"type"
Chosen colors for some values{ "field": "type", "scale": { "domain": ["CDS", "exon"], "range": ["#d62728", "#2ca02c"] } }
Bins of a number{ "field": "score", "scale": { "type": "threshold", "domain": [7.3], "range": ["#0068d1", "red"] } }
A gradient along a number{ "field": "score", "scale": { "scheme": "viridis" } }
BED file's own colorsleave encoding.color unset
Anything elsea value holding a jexl: expression over feature returning a color

score paints a gradient unless scale.type is set, and any other field a color per value; scale.domainMin and scale.domainMax pin a gradient's ends, which otherwise follow the loaded features. scale.names names the scale.domain values in the key and legend.title heads it:

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

{
  "type": "FeatureTrack",
  "trackId": "rmsk_hg38",
  "name": "RepeatMasker",
  "assemblyNames": ["hg38"],
  "adapter": { "type": "BedTabixAdapter", "uri": "rmsk.bed.gz" },
  "displayDefaults": {
    "encoding": {
      "color": {
        "field": "repClass",
        "scale": {
          "domain": [
            "SINE",
            "LINE",
            "LTR",
            "DNA",
            "Simple_repeat",
            "Low_complexity"
          ],
          "range": [
            "#e41a1c",
            "#377eb8",
            "#4daf4a",
            "#984ea3",
            "#ff7f00",
            "#a65628"
          ],
          "names": [
            "SINE",
            "LINE",
            "LTR",
            "DNA",
            "Simple repeat",
            "Low complexity"
          ]
        }
      }
    }
  }
}
jbrowse add-track rmsk.bed.gz \
  --trackId rmsk_hg38 \
  --name RepeatMasker \
  --assemblyNames hg38 \
  --displayDefaults '{"encoding":{"color":{"field":"repClass","scale":{"domain":["SINE","LINE","LTR","DNA","Simple_repeat","Low_complexity"],"range":["#e41a1c","#377eb8","#4daf4a","#984ea3","#ff7f00","#a65628"],"names":["SINE","LINE","LTR","DNA","Simple repeat","Low complexity"]}}}}' \
  --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": {
    "encoding": {
      "color": {
        "field": "repClass",
        "scale": {
          "domain": [
            "SINE",
            "LINE",
            "LTR",
            "DNA",
            "Simple_repeat",
            "Low_complexity"
          ],
          "range": [
            "#e41a1c",
            "#377eb8",
            "#4daf4a",
            "#984ea3",
            "#ff7f00",
            "#a65628"
          ],
          "names": [
            "SINE",
            "LINE",
            "LTR",
            "DNA",
            "Simple repeat",
            "Low complexity"
          ]
        }
      }
    }
  }
}

rmsk.bed.gz is relative to a config.json. Replace it with its URL or its path on this computer.

UCSC RepeatMasker with this recipe, each repeat colored by its repClass. The key over the track comes from the same object.
Open in JBrowse Web ↗

Or rebuild it from your own data:

Quickest: open the view, then File → Open track... for your files.

From scratch:

  1. Open your genome: Open new genome in JBrowse Desktop, or jbrowse add-assembly for JBrowse Web.This figure uses hg38, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add your track: File → Open track..., or check it in the track selector. Needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “RepeatMasker”.
  3. Go to your region in the location box.This figure is at chr17:45,700,000-45,750,000.

Paste into a coding agent, with your goal on the first line.

My goal: [write yours, e.g. this view of my own files, or these track settings in my config.json]

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/code/jb2/main/test_data/config_demo.json
- Tracks:
  - RepeatMasker (rmsk_hg38_ucsc), FeatureTrack, a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi), drawn as LinearBasicDisplay

Docs: https://jbrowse.org/jb2/docs/agents_authoring/ (writing a config), https://jbrowse.org/jb2/docs/agents/ (driving a running JBrowse). Use the jbrowse-authoring, jbrowse-hosted-data and jbrowse-capture skills if you have them. Check any config with `npx @jbrowse/cli validate`, then render it and look: a config that loads is not yet a track that drew.

The session spec that draws the view:
{
  "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",
          "encoding": {
            "color": {
              "field": "repClass",
              "scale": {
                "domain": [
                  "SINE",
                  "LINE",
                  "LTR",
                  "DNA",
                  "Simple_repeat",
                  "Low_complexity"
                ],
                "range": [
                  "#e41a1c",
                  "#377eb8",
                  "#4daf4a",
                  "#984ea3",
                  "#ff7f00",
                  "#a65628"
                ],
                "names": [
                  "SINE",
                  "LINE",
                  "LTR",
                  "DNA",
                  "Simple repeat",
                  "Low complexity"
                ]
              }
            }
          }
        }
      ]
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:45,700,000-45,750,000",
      "tracks": [
        {
          "trackId": "rmsk_hg38_ucsc",
          "height": 260
        }
      ]
    }
  ]
}
Redraw the figure headlessly
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",
          "encoding": {
            "color": {
              "field": "repClass",
              "scale": {
                "domain": [
                  "SINE",
                  "LINE",
                  "LTR",
                  "DNA",
                  "Simple_repeat",
                  "Low_complexity"
                ],
                "range": [
                  "#e41a1c",
                  "#377eb8",
                  "#4daf4a",
                  "#984ea3",
                  "#ff7f00",
                  "#a65628"
                ],
                "names": [
                  "SINE",
                  "LINE",
                  "LTR",
                  "DNA",
                  "Simple repeat",
                  "Low complexity"
                ]
              }
            }
          }
        }
      ]
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:45,700,000-45,750,000",
      "tracks": [
        {
          "trackId": "rmsk_hg38_ucsc",
          "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 \
  --width 1200 --height 465 \
  --spec session.json -o figure.png

More: Using JBrowse with AI agents.

Adds these tracks to your config.json, styled as in the figure. Point each uri at your file.

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",
      "encoding": {
        "color": {
          "field": "repClass",
          "scale": {
            "domain": [
              "SINE",
              "LINE",
              "LTR",
              "DNA",
              "Simple_repeat",
              "Low_complexity"
            ],
            "range": [
              "#e41a1c",
              "#377eb8",
              "#4daf4a",
              "#984ea3",
              "#ff7f00",
              "#a65628"
            ],
            "names": [
              "SINE",
              "LINE",
              "LTR",
              "DNA",
              "Simple repeat",
              "Low complexity"
            ]
          }
        }
      },
      "height": 260
    }
  ]
}'

Run beside config.json, or add --out <dir>. Needs hg38 in the config (jbrowse add-assembly).

This 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/code/jb2/main/test_data/config_demo.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []) + [
        {
            "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",
                    "encoding": {
                        "color": {
                            "field": "repClass",
                            "scale": {
                                "domain": [
                                    "SINE",
                                    "LINE",
                                    "LTR",
                                    "DNA",
                                    "Simple_repeat",
                                    "Low_complexity"
                                ],
                                "range": [
                                    "#e41a1c",
                                    "#377eb8",
                                    "#4daf4a",
                                    "#984ea3",
                                    "#ff7f00",
                                    "#a65628"
                                ],
                                "names": [
                                    "SINE",
                                    "LINE",
                                    "LTR",
                                    "DNA",
                                    "Simple repeat",
                                    "Low complexity"
                                ]
                            }
                        }
                    }
                }
            ]
        }
    ],
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr17:45,700,000-45,750,000",
            "tracks": [
                {
                    "trackId": "rmsk_hg38_ucsc",
                    "height": 260
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.

cat > tracks.json <<'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",
        "encoding": {
          "color": {
            "field": "repClass",
            "scale": {
              "domain": [
                "SINE",
                "LINE",
                "LTR",
                "DNA",
                "Simple_repeat",
                "Low_complexity"
              ],
              "range": [
                "#e41a1c",
                "#377eb8",
                "#4daf4a",
                "#984ea3",
                "#ff7f00",
                "#a65628"
              ],
              "names": [
                "SINE",
                "LINE",
                "LTR",
                "DNA",
                "Simple repeat",
                "Low complexity"
              ]
            }
          }
        }
      }
    ]
  }
]
JSON

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --tracks tracks.json \
  --assembly hg38 --loc chr17:45,700,000-45,750,000 \
  --track rmsk_hg38_ucsc '{"height":260}' \
  --width 1200 --out figure.svg

For a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).

The session spec behind the figure, over this config.

{
  "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",
          "encoding": {
            "color": {
              "field": "repClass",
              "scale": {
                "domain": [
                  "SINE",
                  "LINE",
                  "LTR",
                  "DNA",
                  "Simple_repeat",
                  "Low_complexity"
                ],
                "range": [
                  "#e41a1c",
                  "#377eb8",
                  "#4daf4a",
                  "#984ea3",
                  "#ff7f00",
                  "#a65628"
                ],
                "names": [
                  "SINE",
                  "LINE",
                  "LTR",
                  "DNA",
                  "Simple repeat",
                  "Low complexity"
                ]
              }
            }
          }
        }
      ]
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:45,700,000-45,750,000",
      "tracks": [
        {
          "trackId": "rmsk_hg38_ucsc",
          "height": 260
        }
      ]
    }
  ]
}

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

Labels, tooltips & details

labels.name and labels.description each name the feature field a label line reads, such as "note", or take a jexl: expression where the label wants a fallback or combines fields; { "show": false } turns a line off (FeatureNameLabel). join skips a field the feature lacks, along with its separator, and && adds an optional part only when it is present: below, the name reads Protein:HGA (hga) or plain EDEN, and the description gene · protein kinase or plain match_part. The tooltip is rendered as HTML:

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

{
  "type": "FeatureTrack",
  "trackId": "genes_labeled",
  "name": "Genes",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "Gff3TabixAdapter", "uri": "volvox.sort.gff3.gz" },
  "displayDefaults": {
    "labels": {
      "name": "jexl:join(' ', feature.name || feature.id, feature.alias && `(${feature.alias})`)",
      "description": "jexl:join(' · ', feature.type, feature.note)"
    },
    "tooltip": "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:join(' ', feature.name || feature.id, feature.alias && \`(\${feature.alias})\`)\",\"description\":\"jexl:join(' · ', feature.type, feature.note)\"},\"tooltip\":\"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:join(' ', feature.name || feature.id, feature.alias && `(${feature.alias})`)",
      "description": "jexl:join(' · ', feature.type, feature.note)"
    },
    "tooltip": "jexl:`${feature.name} [${feature.type}] ${feature.start}-${feature.end}`"
  }
}

volvox.sort.gff3.gz is relative to a config.json. Replace it with its URL or its path on this computer.

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:

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

{
  "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}"
  }
}

volvox.sort.gff3.gz is relative to a config.json. Replace it with its URL or its path on this computer.

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

Feature tracks

A feature track fits its height by default: a crowded window drops labels and then squeezes the rows rather than scrolling. heightMode fixed keeps every label and scrolls instead. filter draws only the features that pass every jexl: expression, on variant tracks too:

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

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

volvox.sort.gff3.gz is relative to a config.json. Replace it with its URL or its path on this computer.

Alignments tracks

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

{
  "type": "AlignmentsTrack",
  "trackId": "my_bam",
  "name": "Haplotype 1 reads",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "BamAdapter", "uri": "volvox-sorted.bam" },
  "displayDefaults": {
    "height": 400,
    "encoding": { "color": "mapq" },
    "pileup": { "softClips": { "show": true } },
    "facet": { "field": "tags.HP", "sort": ["2", "1"] },
    "filter": [{ "field": "tags.HP", "equal": "1" }]
  }
}
jbrowse add-track volvox-sorted.bam \
  --trackId my_bam \
  --name "Haplotype 1 reads" \
  --assemblyNames volvox \
  --displayDefaults '{"height":400,"encoding":{"color":"mapq"},"pileup":{"softClips":{"show":true}},"facet":{"field":"tags.HP","sort":["2","1"]},"filter":[{"field":"tags.HP","equal":"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,
    "encoding": { "color": "mapq" },
    "pileup": { "softClips": { "show": true } },
    "facet": { "field": "tags.HP", "sort": ["2", "1"] },
    "filter": [{ "field": "tags.HP", "equal": "1" }]
  }
}

volvox-sorted.bam is relative to a config.json. Replace it with its URL or its path on this computer.

  • encoding.color's field also takes strand, insertSizeAndOrientation and tags.XX; a value is one color for every read, and scale.domain with scale.range recolors one level: { "field": "insertSizeAndOrientation", "scale": { "domain": ["RR"], "range": ["#d95f02"] } }; normalInsertSize: { "min": 150, "max": 600 } pins the insert sizes that count as normal, where each region otherwise samples its own
  • pileup.bases draws a per-base layer over the reads, whatever encoding.color fills them with; its own encoding.color names "modifications", "bisulfite", "baseQuality" or "base"
  • facet also takes strand, firstOfPairStrand, pairOrientation, split, pairing, mapq, or any read field; sort pins which haplotype (or other value) stacks first — the same slot feature, variant, mark and multiway synteny tracks all take
  • filter lists the tests a read must pass, each written over the defaults on its own field: { "field": "flags.SECONDARY", "equal": false } also hides secondary alignments, and { "field": "flags.DUP" } brings duplicates back (flag explainer)
  • CRAM uses CramAdapter in place of BamAdapter

Quantitative (wiggle) tracks

A value in encoding.color paints every bar; left alone, a wiggle cuts at its origin and paints the two sides apart. mark picks bar, line, point, or span.

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

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

volvox_microarray.bw is relative to a config.json. Replace it with its URL or its path on this computer.

Multiple signals on one track, each its own color

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

{
  "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": { "mark": "line", "rows": "" }
}
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": { "mark": "line", "rows": "" }
}'

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": { "mark": "line", "rows": "" }
}

v1.bw, v2.bw are relative to a config.json. Replace each with its URL or its path on this computer.

rows decides the layout: "source" stacks one row per signal, and "", above, draws every signal in one shared plot box. Pin encoding.y.scale.domainMin/domainMax 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, one interpolated line and color per individual on a shared scale.
Open in JBrowse Web ↗

Or rebuild it from your own data:

Quickest: open the view, then File → Open track... for your files.

From scratch:

  1. Open your genome: Open new genome in JBrowse Desktop, or jbrowse add-assembly for JBrowse Web.This figure uses hg38, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add your track: File → Open track..., or check it in the track selector. Needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq analysis set (GFF3Tabix)”.
  3. Add the next track the same way. Needs one BigWig file (.bw) per row.This figure uses “PUR copy number (8 samples)”.
    1. Track menu → Plot type → Line (step)
    2. Track menu → Y axis... → RangePins the axis: Min 0 and Max 5. A field left empty follows the data in view.
  4. Go to your region in the location box.This figure is at chr1:102,900,000-104,400,000.

Paste into a coding agent, with your goal on the first line.

My goal: [write yours, e.g. this view of my own files, or these track settings in my config.json]

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/code/jb2/main/test_data/config_demo.json
- Tracks:
  - NCBI RefSeq analysis set (GFF3Tabix) (ncbi_refseq_109_hg38), FeatureTrack, a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi), drawn as LinearBasicDisplay
  - PUR copy number (8 samples) (cookbook_multiwig), MultiQuantitativeTrack, one BigWig file (.bw) per row, drawn as LinearWiggleDisplay

Docs: https://jbrowse.org/jb2/docs/agents_authoring/ (writing a config), https://jbrowse.org/jb2/docs/agents/ (driving a running JBrowse). Use the jbrowse-authoring, jbrowse-hosted-data and jbrowse-capture skills if you have them. Check any config with `npx @jbrowse/cli validate`, then render it and look: a config that loads is not yet a track that drew.

The session spec that draws the view:
{
  "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,
          "mark": "line",
          "encoding": {
            "y": {
              "scale": {
                "domainMin": 0,
                "domainMax": 5
              }
            }
          }
        }
      ]
    }
  ]
}
Redraw the figure headlessly
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,
          "mark": "line",
          "encoding": {
            "y": {
              "scale": {
                "domainMin": 0,
                "domainMax": 5
              }
            }
          }
        }
      ]
    }
  ]
}
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 860 \
  --spec session.json -o figure.png

More: Using JBrowse with AI agents.

Adds these tracks to your config.json, styled as in the figure. Point each uri at your file (replace YOUR_FILE).

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"
        }
      }
    ]
  },
  "displayDefaults": {
    "height": 480,
    "mark": "line",
    "encoding": {
      "y": {
        "scale": {
          "domainMin": 0,
          "domainMax": 5
        }
      }
    }
  }
}'

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "ncbi_refseq_109_hg38",
  "name": "NCBI RefSeq analysis set (GFF3Tabix)",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "height": 130
  }
}'

Run beside config.json, or add --out <dir>. Needs hg38 in the config (jbrowse add-assembly).

This 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/code/jb2/main/test_data/config_demo.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []) + [
        {
            "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,
                    "mark": "line",
                    "encoding": {
                        "y": {
                            "scale": {
                                "domainMin": 0,
                                "domainMax": 5
                            }
                        }
                    }
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.

cat > tracks.json <<'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"
          }
        }
      ]
    }
  }
]
JSON

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --tracks tracks.json \
  --assembly hg38 --loc chr1:102,900,000-104,400,000 \
  --track ncbi_refseq_109_hg38 '{"height":130}' \
  --track cookbook_multiwig '{"height":480,"mark":"line","encoding":{"y":{"scale":{"domainMin":0,"domainMax":5}}}}' \
  --width 1500 --out figure.svg

For a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).

The session spec behind the figure, over this config.

{
  "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,
          "mark": "line",
          "encoding": {
            "y": {
              "scale": {
                "domainMin": 0,
                "domainMax": 5
              }
            }
          }
        }
      ]
    }
  ]
}

Variant tracks

encoding.color and filter work as on a feature track, and VCF INFO fields are the usual thing to branch on. The svType field reads a record's structural-variant class off its symbolic ALT or INFO/SVTYPE, and paints each class a separate color under a key:

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

{
  "type": "VariantTrack",
  "trackId": "svs_by_type",
  "name": "SVs by type",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "VcfTabixAdapter", "uri": "volvox.dup.vcf.gz" },
  "displayDefaults": {
    "encoding": { "color": "svType" },
    "filter": ["jexl:feature.INFO.AF[0] > 0.05"]
  }
}
jbrowse add-track volvox.dup.vcf.gz \
  --trackId svs_by_type \
  --name "SVs by type" \
  --assemblyNames volvox \
  --displayDefaults '{"encoding":{"color":"svType"},"filter":["jexl: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": {
    "encoding": { "color": "svType" },
    "filter": ["jexl:feature.INFO.AF[0] > 0.05"]
  }
}

volvox.dup.vcf.gz is relative to a config.json. Replace it with its URL or its path on this computer.

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

Synteny and dotplot tracks

Swapped assemblies are a 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.

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

{
  "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"
  }
}

out.paf is relative to a config.json. Replace it with its URL or its path on this computer.

That shows it in the linear view. For the synteny view, open Add → Linear synteny view, pick the track under Quick start, and click Launch.

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. Three or more genomes as one lane apiece, rather than every assembly anchored against one reference, is MultiWaySyntenyDisplay (grouping and lane order has a worked config).

Settings every track type shares

A handful of setting names recur across track types. field names a feature field. Over a field's categories, facet.sort, rows.sort and a color's scale.domain list the values that lead, in order, and the rest follow after them; a color's scale.range gives the listed values their colors, as ggplot2's breaks with named values would. A threshold color reads scale.domain as its cut points, one fewer than the colors in scale.range, and a gradient pins its ends with scale.domainMin and scale.domainMax.

SettingWhat it doesTrack types
encoding.colora CSS color as { "value" }, or { "field", "scale": { "domain", "range" } } painting by a field, with a key (Colors)feature, variant, alignments, quantitative, synteny, mark display (per mark)
facetone labelled section per value of a field; sort stacks the listed values firstfeature, variant, alignments, synteny, mark display
rowsone row per source or sample; sort puts the listed rows firstquantitative, multi-row feature, multi-sample variant, MAF, mark display
encoding.ythe value axis: scale (type, domainMin/domainMax, fenceQuantile, group), axis (title, grid) and rules, beside field on a quantitative trackquantitative, mark display, GWAS
coverage.encoding.ythe coverage band's depth axis: scale (type, domainMin/domainMax, fenceQuantile, group), axis (title, grid) and rulesalignments, synteny, MAF

A coverage.encoding.y channel captions an alignments track's coverage band, rules it at every tick and draws a labelled line at 20x:

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

{
  "type": "AlignmentsTrack",
  "trackId": "reads_depth_guides",
  "name": "Reads, with depth guides",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "BamAdapter", "uri": "volvox-sorted.bam" },
  "displayDefaults": {
    "coverage": {
      "encoding": {
        "y": {
          "axis": { "title": "depth", "grid": true },
          "rules": [{ "value": 20, "color": "#d62728", "label": "20x" }]
        }
      }
    }
  }
}
jbrowse add-track volvox-sorted.bam \
  --trackId reads_depth_guides \
  --name "Reads, with depth guides" \
  --assemblyNames volvox \
  --displayDefaults '{"coverage":{"encoding":{"y":{"axis":{"title":"depth","grid":true},"rules":[{"value":20,"color":"#d62728","label":"20x"}]}}}}' \
  --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": "reads_depth_guides",
  "name": "Reads, with depth guides",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "BamAdapter", "uri": "volvox-sorted.bam" },
  "displayDefaults": {
    "coverage": {
      "encoding": {
        "y": {
          "axis": { "title": "depth", "grid": true },
          "rules": [{ "value": 20, "color": "#d62728", "label": "20x" }]
        }
      }
    }
  }
}

volvox-sorted.bam is relative to a config.json. Replace it with its URL or its path on this computer.

For a picture no built-in display draws, such as bars from a BED score, points colored by a category or a histogram of feature lengths, the mark display builds it from marks, encoding and transform. Its examples are copy-paste recipes like the ones on this page.

Instance-wide settings

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

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

{
  "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>"
  }
}

volvox-sorted.bam is relative to a config.json. Replace it with its URL or its path on this computer.

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

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

{
  "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

volvox.2bit, volvox.chromAliases.txt are relative to a config.json. Replace each with its URL or its path on this computer.

  • 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