Skip to main content

A grammar of graphics over a BED (RepeatMasker Alu age)

JBrowse v5 beta

The tutorials target the JBrowse v5 beta, and the v4.3.0 release on the download page lacks some of what they show. To install the beta of JBrowse Web, run npm install -g @jbrowse/cli@next, then jbrowse create jbrowse2 --branch v5.0.0-beta.13. Desktop beta builds are coming soon.

RepeatMasker annotates Alu, a primate-specific repeat family, and its milliDiv column records each copy's divergence from its subfamily consensus, in tenths of a percent. Divergence grows with time, so the column is an age. We plot it per copy, count copies per bin zoomed out, and ask where the young copies sit along chromosome 1. LinearMarkDisplay turns the columns of a feature file into plots from a JSON marks list; it is experimental, and its config shape may change.

Prerequisites

  • a JBrowse to open the figures' sessions in (Web or Desktop)
  • htslib (bgzip, tabix)
  • Node.js and the JBrowse CLI, for jbrowse make-density
  • python3, standard library only, for the per-megabase counts
  • bedGraphToBigWig from the UCSC utilities, which make-density runs

Where the data comes from

UCSC's hg38 RepeatMasker table, rehosted by genomes.jbrowse.org's hg38 with the Alu rows cut out.

The build script takes these files from their URLs, so there is nothing to download by hand.

Plotting each Alu copy's divergence at one locus

We'll load hg38, the assembly the RepeatMasker coordinates are on.

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

{
  "name": "hg38",
  "uri": "https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz",
  "refNameAliases": {
    "uri": "https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/hg38_aliases.txt"
  },
  "cytobands": "https://jbrowse.org/genomes/GRCh38/cytoBand.txt"
}
jbrowse add-assembly https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz \
  --name hg38 \
  --refNameAliases https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/hg38_aliases.txt \
  --config '{"cytobands":"https://jbrowse.org/genomes/GRCh38/cytoBand.txt"}'

hg38 is one of the genomes JBrowse Desktop hosts, with gene tracks already set up: on the start screen click Show all available genomes and pick it. To load the files of this config instead:

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

https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz
https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz.fai
https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz.gzi

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

  • Genome name: hg38
  • refName aliases (under More options): https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/hg38_aliases.txt
  • cytobands (under More options): https://jbrowse.org/genomes/GRCh38/cytoBand.txt

The track reads any BED-like file, bgzipped and tabix-indexed, with a # header line naming the columns; a mark refers to a column by name. In grammar-of-graphics terms, encoding maps columns to a mark's channels, and color is a color scale from a field through a domain to a range. The track below lists three marks:

  • Per-copy bars (below maxBpPerPx): a bar per copy with milliDiv as the height. A formula step writes the first four characters of the name into lineage (AluJ, AluS, AluY: oldest to youngest, and AluY is still inserting), and the categorical domain fixes the legend order
  • Copies per bin (past minBpPerPx): every Alu copy counted per bin, in grey
  • AluY per bin: the same count behind a filter for AluY, in red

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

{
  "type": "FeatureTrack",
  "trackId": "alu_age",
  "name": "Alu copies",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "BedTabixAdapter",
    "uri": "https://jbrowse.org/demos/gene_density/Alu.bed.gz"
  },
  "displays": [
    {
      "type": "LinearMarkDisplay",
      "marks": [
        {
          "mark": "bar",
          "transform": [
            {
              "type": "formula",
              "expr": "jexl:substring(feature.name, 0, 4)",
              "as": "lineage"
            }
          ],
          "encoding": {
            "y": "milliDiv",
            "color": {
              "field": "lineage",
              "scale": "categorical",
              "domain": ["AluJ", "AluS", "AluY", "FLAM", "FRAM"],
              "range": ["#4575b4", "#fdae61", "#d73027", "#8c8c8c", "#8c8c8c"],
              "title": "Alu lineage"
            }
          },
          "maxBpPerPx": 100
        },
        {
          "mark": "bar",
          "transform": [
            { "type": "bin", "step": "auto" },
            {
              "type": "aggregate",
              "groupby": ["start", "end"],
              "ops": [{ "op": "count" }]
            }
          ],
          "encoding": { "color": { "value": "#c0c0c0" } },
          "minBpPerPx": 100
        },
        {
          "mark": "bar",
          "transform": [
            {
              "type": "filter",
              "expr": "jexl:startsWith(feature.name, 'AluY')"
            },
            { "type": "bin", "step": "auto" },
            {
              "type": "aggregate",
              "groupby": ["start", "end"],
              "ops": [{ "op": "count" }]
            }
          ],
          "encoding": { "color": { "value": "#d73027" } },
          "minBpPerPx": 100
        }
      ]
    }
  ]
}
jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "alu_age",
  "name": "Alu copies",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "BedTabixAdapter",
    "uri": "https://jbrowse.org/demos/gene_density/Alu.bed.gz"
  },
  "displays": [
    {
      "type": "LinearMarkDisplay",
      "marks": [
        {
          "mark": "bar",
          "transform": [
            {
              "type": "formula",
              "expr": "jexl:substring(feature.name, 0, 4)",
              "as": "lineage"
            }
          ],
          "encoding": {
            "y": "milliDiv",
            "color": {
              "field": "lineage",
              "scale": "categorical",
              "domain": ["AluJ", "AluS", "AluY", "FLAM", "FRAM"],
              "range": ["#4575b4", "#fdae61", "#d73027", "#8c8c8c", "#8c8c8c"],
              "title": "Alu lineage"
            }
          },
          "maxBpPerPx": 100
        },
        {
          "mark": "bar",
          "transform": [
            { "type": "bin", "step": "auto" },
            {
              "type": "aggregate",
              "groupby": ["start", "end"],
              "ops": [{ "op": "count" }]
            }
          ],
          "encoding": { "color": { "value": "#c0c0c0" } },
          "minBpPerPx": 100
        },
        {
          "mark": "bar",
          "transform": [
            {
              "type": "filter",
              "expr": "jexl:startsWith(feature.name, '\''AluY'\'')"
            },
            { "type": "bin", "step": "auto" },
            {
              "type": "aggregate",
              "groupby": ["start", "end"],
              "ops": [{ "op": "count" }]
            }
          ],
          "encoding": { "color": { "value": "#d73027" } },
          "minBpPerPx": 100
        }
      ]
    }
  ]
}'

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": "alu_age",
  "name": "Alu copies",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "BedTabixAdapter",
    "uri": "https://jbrowse.org/demos/gene_density/Alu.bed.gz"
  },
  "displays": [
    {
      "type": "LinearMarkDisplay",
      "marks": [
        {
          "mark": "bar",
          "transform": [
            {
              "type": "formula",
              "expr": "jexl:substring(feature.name, 0, 4)",
              "as": "lineage"
            }
          ],
          "encoding": {
            "y": "milliDiv",
            "color": {
              "field": "lineage",
              "scale": "categorical",
              "domain": ["AluJ", "AluS", "AluY", "FLAM", "FRAM"],
              "range": ["#4575b4", "#fdae61", "#d73027", "#8c8c8c", "#8c8c8c"],
              "title": "Alu lineage"
            }
          },
          "maxBpPerPx": 100
        },
        {
          "mark": "bar",
          "transform": [
            { "type": "bin", "step": "auto" },
            {
              "type": "aggregate",
              "groupby": ["start", "end"],
              "ops": [{ "op": "count" }]
            }
          ],
          "encoding": { "color": { "value": "#c0c0c0" } },
          "minBpPerPx": 100
        },
        {
          "mark": "bar",
          "transform": [
            {
              "type": "filter",
              "expr": "jexl:startsWith(feature.name, 'AluY')"
            },
            { "type": "bin", "step": "auto" },
            {
              "type": "aggregate",
              "groupby": ["start", "end"],
              "ops": [{ "op": "count" }]
            }
          ],
          "encoding": { "color": { "value": "#d73027" } },
          "minBpPerPx": 100
        }
      ]
    }
  ]
}

Open this track in JBrowse Web ↗

Open this track in JBrowse Desktop ↗ (JBrowse Desktop 5.0+)

Open chr1:151,000,000-151,030,000, 30 kb of 1q21, and click a bar to open its row.

Alu copies over a window of 1q21, one bar per copy with its divergence from its consensus as the height and its lineage as the color. The AluY bars are among the shortest in the window and the AluJ bars the tallest, with AluS between; FLAM, the older free left Alu monomer, is as tall as AluJ.
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%2Falu_age%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr1%3A151%2C000%2C000-151%2C030%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22alu_age%22%2C%22type%22%3A%22LinearMarkDisplay%22%2C%22height%22%3A200%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+alu_age%2Flocus

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 .2bit genome.
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “Alu copies”.
  3. Type your region of interest into the location box and press Enter.This figure is at chr1:151,000,000-151,030,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/alu_age/config.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr1:151,000,000-151,030,000",
      "tracks": [
        {
          "trackId": "alu_age",
          "type": "LinearMarkDisplay",
          "height": 200
        }
      ]
    }
  ]
}

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/alu_age/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr1:151,000,000-151,030,000",
            "tracks": [
                {
                    "trackId": "alu_age",
                    "type": "LinearMarkDisplay",
                    "height": 200
                }
            ]
        }
    ],
)
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/alu_age/config.json \
  --assembly hg38 --loc chr1:151,000,000-151,030,000 \
  --track alu_age display:LinearMarkDisplay '{"height":200}' \
  --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": "chr1:151,000,000-151,030,000",
      "tracks": [
        {
          "trackId": "alu_age",
          "type": "LinearMarkDisplay",
          "height": 200
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "Bar height: divergence from consensus. Older copies are taller",
    "fontSize": 18,
    "maxWidth": 400,
    "anchor": {
      "trackId": "alu_age",
      "loc": "chr1:151,010,600",
      "fracY": 0.05
    }
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/alu_age/config.json \
  --width 1500 --height 410 \
  --timeout 90000 \
  --spec session.json --annotations callouts.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.

Counting Alu copies per bin when zoomed out

On a whole chromosome the track exceeds its fetch budget and shows a "region too large" message. A bigWig of copies per kilobase, counted once from the BED, covers that width:

# writes Alu.bed.density.bw beside the input, in 1 kb bins
# --chrom-sizes takes a two-column name and length table;
#   --assembly genome.fa reads the lengths off the FASTA's .fai instead
jbrowse make-density Alu.bed.gz --chrom-sizes hg38.chrom.sizes

Add the bigWig as a track:

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

{
  "trackId": "alu_per_kb",
  "name": "Alu copies per kb",
  "assemblyNames": ["hg38"],
  "uri": "https://jbrowse.org/demos/gene_density/Alu.bed.density.bw",
  "displayDefaults": { "extent": "none" }
}
jbrowse add-track https://jbrowse.org/demos/gene_density/Alu.bed.density.bw \
  --trackId alu_per_kb \
  --name "Alu copies per kb" \
  --assemblyNames hg38 \
  --displayDefaults '{"extent":"none"}'

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": "alu_per_kb",
  "name": "Alu copies per kb",
  "assemblyNames": ["hg38"],
  "uri": "https://jbrowse.org/demos/gene_density/Alu.bed.density.bw",
  "displayDefaults": { "extent": "none" }
}

Open this track in JBrowse Web ↗

Open this track in JBrowse Desktop ↗ (JBrowse Desktop 5.0+)

AluY share per megabase, against the genome-wide share

The red AluY count is too small to read against a total that varies between bins. A script instead writes a BED with two log2 columns, the AluY share per megabase against the genome-wide share and the plus-strand share against one half as the control.

Fetch the script:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/alu_young_share.py
# columns: copies, young, plus, youngShare, youngLog2, strandLog2, one row per
# 1 Mb bin holding at least 50 copies; prints the rank correlation of each share
# against copies per bin
python3 alu_young_share.py Alu.bed.gz Alu.young_share.bed AluY
bgzip -f Alu.young_share.bed
tabix -f -p bed Alu.young_share.bed.gz

Advanced → Edit plot... in the track menu applies edits to the cut, colors and key names live. The config below sets them in the track:

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

{
  "type": "FeatureTrack",
  "trackId": "alu_young_share",
  "name": "AluY share per Mb, against the genome",
  "uri": "https://jbrowse.org/code/jb2/main/test_data/alu_age/Alu.young_share.bed.gz",
  "assemblyNames": ["hg38"],
  "displays": [
    {
      "type": "LinearMarkDisplay",
      "scales": {
        "y": {
          "domainMin": -1.5,
          "domainMax": 1.5,
          "title": "AluY share, log2"
        }
      },
      "marks": [
        {
          "mark": "bar",
          "encoding": {
            "y": "youngLog2",
            "color": {
              "field": "youngLog2",
              "scale": "threshold",
              "domain": [0],
              "range": ["#4575b4", "#d73027"],
              "labels": ["below the genome-wide share", "above it"],
              "title": "AluY share"
            }
          }
        }
      ]
    }
  ]
}
jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "alu_young_share",
  "name": "AluY share per Mb, against the genome",
  "uri": "https://jbrowse.org/code/jb2/main/test_data/alu_age/Alu.young_share.bed.gz",
  "assemblyNames": ["hg38"],
  "displays": [
    {
      "type": "LinearMarkDisplay",
      "scales": {
        "y": {
          "domainMin": -1.5,
          "domainMax": 1.5,
          "title": "AluY share, log2"
        }
      },
      "marks": [
        {
          "mark": "bar",
          "encoding": {
            "y": "youngLog2",
            "color": {
              "field": "youngLog2",
              "scale": "threshold",
              "domain": [0],
              "range": ["#4575b4", "#d73027"],
              "labels": ["below the genome-wide share", "above it"],
              "title": "AluY share"
            }
          }
        }
      ]
    }
  ]
}'

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": "alu_young_share",
  "name": "AluY share per Mb, against the genome",
  "uri": "https://jbrowse.org/code/jb2/main/test_data/alu_age/Alu.young_share.bed.gz",
  "assemblyNames": ["hg38"],
  "displays": [
    {
      "type": "LinearMarkDisplay",
      "scales": {
        "y": {
          "domainMin": -1.5,
          "domainMax": 1.5,
          "title": "AluY share, log2"
        }
      },
      "marks": [
        {
          "mark": "bar",
          "encoding": {
            "y": "youngLog2",
            "color": {
              "field": "youngLog2",
              "scale": "threshold",
              "domain": [0],
              "range": ["#4575b4", "#d73027"],
              "labels": ["below the genome-wide share", "above it"],
              "title": "AluY share"
            }
          }
        }
      ]
    }
  ]
}
Top, chromosome 1 end to end: Alu copies per kilobase above the AluY share per megabase, red above the genome-wide share and blue below. Under the wedge, the Alu copies track above the same AluY share, over a stretch where Alu-sparse megabases meet Alu-dense ones, with copies counted per bin in grey and AluY in red.
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%2Falu_age%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr1%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22alu_per_kb%22%2C%22type%22%3A%22LinearWiggleDisplay%22%2C%22height%22%3A110%7D%2C%7B%22trackId%22%3A%22alu_young_share%22%2C%22type%22%3A%22LinearMarkDisplay%22%2C%22height%22%3A90%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+alu_age%2Fchromosome

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 .2bit genome.
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a BigWig file (.bw).This figure uses “Alu copies per kb”.
  3. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “AluY share per Mb, against the genome”.
  4. Type your region of interest into the location box and press Enter.This figure is at chr1.

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr1",
      "tracks": [
        {
          "trackId": "alu_per_kb",
          "type": "LinearWiggleDisplay",
          "height": 110
        },
        {
          "trackId": "alu_young_share",
          "type": "LinearMarkDisplay",
          "height": 90
        }
      ]
    }
  ]
}

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/alu_age/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr1",
            "tracks": [
                {
                    "trackId": "alu_per_kb",
                    "type": "LinearWiggleDisplay",
                    "height": 110
                },
                {
                    "trackId": "alu_young_share",
                    "type": "LinearMarkDisplay",
                    "height": 90
                }
            ]
        }
    ],
)
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/alu_age/config.json \
  --assembly hg38 --loc chr1 \
  --track alu_per_kb display:LinearWiggleDisplay '{"height":110}' \
  --track alu_young_share display:LinearMarkDisplay '{"height":90}' \
  --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.

The figure stacks 2 frames: one command draws each, and ImageMagick stacks them.

Frame 1: Chromosome 1

cat > session-1.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr1",
      "tracks": [
        {
          "trackId": "alu_per_kb",
          "type": "LinearWiggleDisplay",
          "height": 110
        },
        {
          "trackId": "alu_young_share",
          "type": "LinearMarkDisplay",
          "height": 90
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/alu_age/config.json \
  --width 1500 --height 465 \
  --timeout 90000 \
  --spec session-1.json -o frame-1.png

Frame 2: The stretch under the wedge

cat > session-2.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr1:184000001-212000000",
      "tracks": [
        {
          "trackId": "alu_age",
          "type": "LinearMarkDisplay",
          "height": 110
        },
        {
          "trackId": "alu_young_share",
          "type": "LinearMarkDisplay",
          "height": 90
        }
      ]
    }
  ]
}
JSON

cat > callouts-2.json <<'JSON'
[
  {
    "type": "text",
    "text": "Alu sparse: young share high",
    "fontSize": 18,
    "leader": true,
    "anchor": {
      "trackId": "alu_young_share",
      "loc": "chr1:191,500,000",
      "fracY": 0.3
    },
    "dx": -40,
    "dy": -95
  },
  {
    "type": "text",
    "text": "Alu dense: young share low",
    "fontSize": 18,
    "leader": true,
    "anchor": {
      "trackId": "alu_young_share",
      "loc": "chr1:203,500,000",
      "fracY": 0.75
    },
    "dx": 80,
    "dy": -177
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/alu_age/config.json \
  --width 1500 --height 465 \
  --timeout 90000 \
  --spec session-2.json --annotations callouts-2.json -o frame-2.png
magick frame-1.png frame-2.png -background white -smush 70 figure.png

The figure's callouts across its frames are drawn over the stacked image, which these commands leave out.

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.

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%2Falu_age%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr1%3A184000001-212000000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22alu_age%22%2C%22type%22%3A%22LinearMarkDisplay%22%2C%22height%22%3A110%7D%2C%7B%22trackId%22%3A%22alu_young_share%22%2C%22type%22%3A%22LinearMarkDisplay%22%2C%22height%22%3A90%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+alu_age%2Fbinned

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 .2bit genome.
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “Alu copies”.
  3. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “AluY share per Mb, against the genome”.
  4. Type your region of interest into the location box and press Enter.This figure is at chr1:184000001-212000000.

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr1:184000001-212000000",
      "tracks": [
        {
          "trackId": "alu_age",
          "type": "LinearMarkDisplay",
          "height": 110
        },
        {
          "trackId": "alu_young_share",
          "type": "LinearMarkDisplay",
          "height": 90
        }
      ]
    }
  ]
}

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/alu_age/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr1:184000001-212000000",
            "tracks": [
                {
                    "trackId": "alu_age",
                    "type": "LinearMarkDisplay",
                    "height": 110
                },
                {
                    "trackId": "alu_young_share",
                    "type": "LinearMarkDisplay",
                    "height": 90
                }
            ]
        }
    ],
)
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/alu_age/config.json \
  --assembly hg38 --loc chr1:184000001-212000000 \
  --track alu_age display:LinearMarkDisplay '{"height":110}' \
  --track alu_young_share display:LinearMarkDisplay '{"height":90}' \
  --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.

The figure stacks 2 frames: one command draws each, and ImageMagick stacks them.

Frame 1: Chromosome 1

cat > session-1.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr1",
      "tracks": [
        {
          "trackId": "alu_per_kb",
          "type": "LinearWiggleDisplay",
          "height": 110
        },
        {
          "trackId": "alu_young_share",
          "type": "LinearMarkDisplay",
          "height": 90
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/alu_age/config.json \
  --width 1500 --height 465 \
  --timeout 90000 \
  --spec session-1.json -o frame-1.png

Frame 2: The stretch under the wedge

cat > session-2.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr1:184000001-212000000",
      "tracks": [
        {
          "trackId": "alu_age",
          "type": "LinearMarkDisplay",
          "height": 110
        },
        {
          "trackId": "alu_young_share",
          "type": "LinearMarkDisplay",
          "height": 90
        }
      ]
    }
  ]
}
JSON

cat > callouts-2.json <<'JSON'
[
  {
    "type": "text",
    "text": "Alu sparse: young share high",
    "fontSize": 18,
    "leader": true,
    "anchor": {
      "trackId": "alu_young_share",
      "loc": "chr1:191,500,000",
      "fracY": 0.3
    },
    "dx": -40,
    "dy": -95
  },
  {
    "type": "text",
    "text": "Alu dense: young share low",
    "fontSize": 18,
    "leader": true,
    "anchor": {
      "trackId": "alu_young_share",
      "loc": "chr1:203,500,000",
      "fracY": 0.75
    },
    "dx": 80,
    "dy": -177
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/alu_age/config.json \
  --width 1500 --height 465 \
  --timeout 90000 \
  --spec session-2.json --annotations callouts-2.json -o frame-2.png
magick frame-1.png frame-2.png -background white -smush 70 figure.png

The figure's callouts across its frames are drawn over the stacked image, which these commands leave out.

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.

Correlating AluY share with Alu density across the genome

alu_young_share.py prints the Spearman rank correlation of each share against copies per megabase:

share, per megabasebinsSpearman rhop
AluY share2873-0.688< 1e-300
plus-strand share28730.0030.87

The young share falls as the copies rise, and the plus-strand control shows no trend.1

Checking the bars against the BED file

Read chr1:151,000,000-151,030,000 out of the BED, one line per lineage:

tabix https://jbrowse.org/demos/gene_density/Alu.bed.gz chr1:151,000,000-151,030,000 |
  awk -F'\t' '{ l = substr($4, 1, 4); n[l]++; s[l] += $12 }
    END { for (l in n) printf "%s\t%d copies\tmean milliDiv %.0f\n", l, n[l], s[l] / n[l] }'
lineagecopiesmean milliDiv
AluY357
AluS30100
FLAM4140
AluJ12150

Count the copies in one red and one blue megabase of the share track:

tabix https://jbrowse.org/demos/gene_density/Alu.bed.gz chr1:191,000,001-192,000,000 |
  awk -F'\t' '$2 >= 191000000 && $4 ~ /^Alu[JSY]/ { n++; y += ($4 ~ /^AluY/) }
    END { print n " copies, " y " AluY" }'
megabase, chr1Alu copiesAluY
191 to 192 Mb16155
203 to 204 Mb69047

The AluY count barely moves between the two megabases, and the older copies pile up in the dense one, so the young share is lower there and its bar is blue.

Reproduce it end to end

build_alu_age.sh runs every step above:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_alu_age.sh
bash build_alu_age.sh                     # builds ./alu_age_build/jbrowse2
npx --yes serve alu_age_build/jbrowse2    # then open the printed URL

By default the script builds the tracks over UCSC's table. bash build_alu_age.sh rmsk.bed.gz genome.fa uses your own RepeatMasker BED, and FAMILY and YOUNG pick another family and its youngest lineage.

See also

Citations

Notes

  1. Insertions cluster, so the copies per megabase scatter several times more widely than independent copies would. A per-megabase test that assumed independence would flag most of the genome, so the page reports the genome-wide correlation. ↩