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 describe one track. Write the layer that says what you mean: the shortest for a file the extension describes, the middle for a different type or a displays array, 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": {
        "color": { "field": "strand" },
        "height": 200,
        "mouseover": "jexl:feature.name"
      }
    },
    {
      "type": "AlignmentsTrack",
      "trackId": "reads",
      "name": "Reads",
      "assemblyNames": ["volvox"],
      "adapter": { "type": "BamAdapter", "uri": "volvox-sorted.bam" },
      "displayDefaults": {
        "heightMode": "fit",
        "color": { "field": "mapq" },
        "filter": { "flagExclude": 1540, "flagInclude": 0 }
      }
    },
    {
      "type": "QuantitativeTrack",
      "trackId": "coverage",
      "name": "Coverage",
      "assemblyNames": ["volvox"],
      "adapter": { "type": "BigWigAdapter", "uri": "volvox_microarray.bw" },
      "displayDefaults": {
        "color": "#C8B414",
        "scales": { "y": { "type": "log", "domainMin": 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'",
        "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

color is a CSS color, or an object that paints each feature by one of its fields and draws a key saying what each color means. This is the object 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": {
    "color": { "field": "strand" }
  }
}
jbrowse add-track volvox.sort.gff3.gz \
  --trackId genes_by_strand \
  --name "Genes (colored by strand)" \
  --assemblyNames volvox \
  --displayDefaults '{"color":{"field":"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": {
    "color": { "field": "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 on hg38 with this recipe applied: forward-strand genes red, reverse-strand blue.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

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

https://jbrowse.org/code/jb2/main/?config=test_data%2Fconfig_demo.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%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%7B%22field%22%3A%22strand%22%7D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+cookbook_color_by_strand

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq analysis set (GFF3Tabix)”.
    1. Track menu → Color by... → Strand
  3. Type your region of interest into the location box and press Enter.This figure is at chr17:7,400,000-7,700,000.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/code/jb2/main/test_data/config_demo.json, which is what the Web button above opens.

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

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

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/config_demo.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr17:7,400,000-7,700,000",
            "tracks": [
                {
                    "trackId": "ncbi_refseq_109_hg38",
                    "height": 260,
                    "color": {
                        "field": "strand"
                    }
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

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

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

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,400,000-7,700,000",
      "tracks": [
        {
          "trackId": "ncbi_refseq_109_hg38",
          "height": 260,
          "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

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.

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.

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

score paints a gradient unless scale says otherwise, and any other field a color per value; domainMin and domainMax pin a gradient's ends, which otherwise follow the loaded features. labels names the domain values in the key and 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": {
    "color": {
      "field": "repClass",
      "domain": [
        "SINE",
        "LINE",
        "LTR",
        "DNA",
        "Simple_repeat",
        "Low_complexity"
      ],
      "range": [
        "#e41a1c",
        "#377eb8",
        "#4daf4a",
        "#984ea3",
        "#ff7f00",
        "#a65628"
      ],
      "labels": [
        "SINE",
        "LINE",
        "LTR",
        "DNA",
        "Simple repeat",
        "Low complexity"
      ]
    }
  }
}
jbrowse add-track rmsk.bed.gz \
  --trackId rmsk_hg38 \
  --name RepeatMasker \
  --assemblyNames hg38 \
  --displayDefaults '{"color":{"field":"repClass","domain":["SINE","LINE","LTR","DNA","Simple_repeat","Low_complexity"],"range":["#e41a1c","#377eb8","#4daf4a","#984ea3","#ff7f00","#a65628"],"labels":["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": {
    "color": {
      "field": "repClass",
      "domain": [
        "SINE",
        "LINE",
        "LTR",
        "DNA",
        "Simple_repeat",
        "Low_complexity"
      ],
      "range": [
        "#e41a1c",
        "#377eb8",
        "#4daf4a",
        "#984ea3",
        "#ff7f00",
        "#a65628"
      ],
      "labels": [
        "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 over a 17q21 window with this recipe: each repeat gets the color of its repClass, and every class the domain leaves out a color of its own. The key over the track comes from the same object.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

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

https://jbrowse.org/code/jb2/main/?config=test_data%2Fconfig_demo.json&session=spec-%7B%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%7B%22field%22%3A%22repClass%22%2C%22domain%22%3A%5B%22SINE%22%2C%22LINE%22%2C%22LTR%22%2C%22DNA%22%2C%22Simple_repeat%22%2C%22Low_complexity%22%5D%2C%22range%22%3A%5B%22%23e41a1c%22%2C%22%23377eb8%22%2C%22%234daf4a%22%2C%22%23984ea3%22%2C%22%23ff7f00%22%2C%22%23a65628%22%5D%2C%22labels%22%3A%5B%22SINE%22%2C%22LINE%22%2C%22LTR%22%2C%22DNA%22%2C%22Simple+repeat%22%2C%22Low+complexity%22%5D%7D%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

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

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

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

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 Spec tab, or jbrowse set-default-session.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/code/jb2/main/test_data/config_demo.json, which is what the Web button above opens.

{
  "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": {
            "field": "repClass",
            "domain": [
              "SINE",
              "LINE",
              "LTR",
              "DNA",
              "Simple_repeat",
              "Low_complexity"
            ],
            "range": [
              "#e41a1c",
              "#377eb8",
              "#4daf4a",
              "#984ea3",
              "#ff7f00",
              "#a65628"
            ],
            "labels": [
              "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",
          "type": "LinearBasicDisplay",
          "height": 260
        }
      ]
    }
  ]
}

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

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/config_demo.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []) + [
        {
            "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": {
                        "field": "repClass",
                        "domain": [
                            "SINE",
                            "LINE",
                            "LTR",
                            "DNA",
                            "Simple_repeat",
                            "Low_complexity"
                        ],
                        "range": [
                            "#e41a1c",
                            "#377eb8",
                            "#4daf4a",
                            "#984ea3",
                            "#ff7f00",
                            "#a65628"
                        ],
                        "labels": [
                            "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",
                    "type": "LinearBasicDisplay",
                    "height": 260
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

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",
        "color": {
          "field": "repClass",
          "domain": [
            "SINE",
            "LINE",
            "LTR",
            "DNA",
            "Simple_repeat",
            "Low_complexity"
          ],
          "range": [
            "#e41a1c",
            "#377eb8",
            "#4daf4a",
            "#984ea3",
            "#ff7f00",
            "#a65628"
          ],
          "labels": [
            "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 display:LinearBasicDisplay '{"height":260}' \
  --width 1200 --out figure.svg

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

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "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": {
            "field": "repClass",
            "domain": [
              "SINE",
              "LINE",
              "LTR",
              "DNA",
              "Simple_repeat",
              "Low_complexity"
            ],
            "range": [
              "#e41a1c",
              "#377eb8",
              "#4daf4a",
              "#984ea3",
              "#ff7f00",
              "#a65628"
            ],
            "labels": [
              "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",
          "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 \
  --width 1200 --height 465 \
  --spec session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

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. showLabels pins which lines are drawn at every zoom, and mouseover 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:feature.name || feature.id",
      "description": "note"
    },
    "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":"note"},"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": "note"
    },
    "showLabels": "nameAndDescription",
    "mouseover": "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,
    "color": { "field": "mapq" },
    "showSoftClipping": true,
    "facet": { "field": "tags.HP", "domain": ["2", "1"] },
    "filter": {
      "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,"color":{"field":"mapq"},"showSoftClipping":true,"facet":{"field":"tags.HP","domain":["2","1"]},"filter":{"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,
    "color": { "field": "mapq" },
    "showSoftClipping": true,
    "facet": { "field": "tags.HP", "domain": ["2", "1"] },
    "filter": {
      "flagExclude": 1540,
      "flagInclude": 0,
      "tagFilters": [{ "tag": "HP", "value": "1" }]
    }
  }
}

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

  • color's field also takes strand, pairOrientation, insertSize and tags.XX; a string is one color for every read, and domain with range recolors one level: { "field": "pairOrientation", "domain": ["RR"], "range": ["#d95f02"] }
  • baseColor draws a per-base layer over the reads, whatever color fills them with: "modifications", "bisulfite", "baseQuality" or "base"
  • facet also takes strand, firstOfPairStrand, pairOrientation, split, pairing, mapq, or any read field; domain pins which haplotype (or other value) stacks first — the same slot feature, variant, mark and multiway synteny tracks all take
  • 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

A string in 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": {
    "color": "#C8B414",
    "scales": { "y": { "type": "log", "domainMin": 0 } }
  }
}
jbrowse add-track volvox_microarray.bw \
  --trackId coverage \
  --name Coverage \
  --assemblyNames volvox \
  --displayDefaults '{"color":"#C8B414","scales":{"y":{"type":"log","domainMin":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",
    "scales": { "y": { "type": "log", "domainMin": 0 } }
  }
}

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 scales.y.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 across 1.5 Mb of chr1, one interpolated line and one color per 1000 Genomes individual 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 in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

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

https://jbrowse.org/code/jb2/main/?config=test_data%2Fconfig_demo.json&session=spec-%7B%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%22mark%22%3A%22line%22%2C%22scales%22%3A%7B%22y%22%3A%7B%22domainMin%22%3A0%2C%22domainMax%22%3A5%7D%7D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+cookbook_multiwig

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq analysis set (GFF3Tabix)”.
  3. Add the next track the same way.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. Type your region of interest into the location box and press Enter.This figure is at chr1:102,900,000-104,400,000.

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 Spec tab, or jbrowse set-default-session.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/code/jb2/main/test_data/config_demo.json, which is what the Web button above opens.

{
  "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",
          "scales": {
            "y": {
              "domainMin": 0,
              "domainMax": 5
            }
          }
        }
      ]
    }
  ]
}

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

from jbrowse_anywidget import JBrowseApp, fetch_hub

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

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

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","scales":{"y":{"domainMin":0,"domainMax":5}}}' \
  --width 1500 --out figure.svg

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

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "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",
          "scales": {
            "y": {
              "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

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 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 its own 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": {
    "color": { "field": "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 '{"color":{"field":"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": {
    "color": { "field": "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

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.

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 (a color per value, the sections of a facet, the rows) domain lists the values that lead, in order, and the rest follow after them; a color's range gives the listed values their colors, as ggplot2's breaks with named values would. A threshold color reads domain as its cut points, one fewer than the colors in range, and a gradient pins its ends with domainMin and domainMax.

SettingWhat it doesTrack types
colora CSS color, or { "field", "domain", "range" } painting by a field, with a key (Colors)feature, variant, alignments, quantitative, synteny, mark display (encoding.color)
facetone labelled section per value of a field; domain stacks the listed values firstfeature, variant, alignments, synteny, mark display
rowsone row per source or sample; domain puts the listed rows firstquantitative, multi-row feature, multi-sample variant, MAF, mark display
scales.ythe value axis: type, domainMin/domainMax, domainQuantile, autoscaleGroup, and the guides rules, grid, title, minimalTicksquantitative, alignments coverage, synteny, mark display, GWAS

The same scales.y object works on each of those track types. This one 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": {
    "scales": {
      "y": {
        "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 '{"scales":{"y":{"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": {
    "scales": {
      "y": {
        "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