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.17. 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 each copy's milliDiv as a bar at one locus
  • bin and count copies when zoomed out
  • plot the AluY share per megabase against the genome-wide share
  • plot that share against Alu density across chromosome 1

The plots come from LinearMarkDisplay, which 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
# Debian/Ubuntu
sudo apt install tabix nodejs
# or conda, which has every tool above
conda install -c bioconda -c conda-forge htslib nodejs ucsc-bedgraphtobigwig
# or Linux x86_64 binaries for the tools apt lacks
wget -P ~/.local/bin \
  https://hgdownload.soe.ucsc.edu/admin/exe/linux.x86_64/bedGraphToBigWig
chmod +x ~/.local/bin/bedGraphToBigWig
# any platform
npm install -g @jbrowse/cli

The data

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

You don't need these files to follow the page: the track configs below read the hosted results. The build script fetches them to rebuild those results. Your own RepeatMasker BED and genome FASTA go through the same steps: the build script takes them as arguments.

What it isFile
RepeatMasker, UCSC's rmsk table as BED with a column headerrmsk.bed.gz
Reference lengths, for the bigWig headerhg38.chrom.sizes

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 scale.domain to scale.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 ordinal scale.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": {
                "type": "ordinal",
                "domain": ["AluJ", "AluS", "AluY", "FLAM", "FRAM"],
                "range": ["#4575b4", "#fdae61", "#d73027", "#8c8c8c", "#8c8c8c"]
              },
              "legend": { "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": {
                "type": "ordinal",
                "domain": ["AluJ", "AluS", "AluY", "FLAM", "FRAM"],
                "range": ["#4575b4", "#fdae61", "#d73027", "#8c8c8c", "#8c8c8c"]
              },
              "legend": { "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": {
                "type": "ordinal",
                "domain": ["AluJ", "AluS", "AluY", "FLAM", "FRAM"],
                "range": ["#4575b4", "#fdae61", "#d73027", "#8c8c8c", "#8c8c8c"]
              },
              "legend": { "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 chr1:151,000,000-151,030,000, 30 kb of 1q21, and click a bar to open its row.

Alu copies over 1q21: bar height is divergence from consensus, color is lineage.
Open in JBrowse Web ↗

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",
          "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",
                    "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: a data file opens as the track its name says.

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 '{"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",
          "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 ↗

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",
      "encoding": {
        "y": {
          "scale": { "domainMin": -1.5, "domainMax": 1.5 },
          "axis": { "title": "AluY share, log2" }
        }
      },
      "marks": [
        {
          "mark": "bar",
          "encoding": {
            "y": "youngLog2",
            "color": {
              "field": "youngLog2",
              "scale": {
                "type": "threshold",
                "domain": [0],
                "range": ["#4575b4", "#d73027"],
                "names": ["below the genome-wide share", "above it"]
              },
              "legend": { "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",
      "encoding": {
        "y": {
          "scale": { "domainMin": -1.5, "domainMax": 1.5 },
          "axis": { "title": "AluY share, log2" }
        }
      },
      "marks": [
        {
          "mark": "bar",
          "encoding": {
            "y": "youngLog2",
            "color": {
              "field": "youngLog2",
              "scale": {
                "type": "threshold",
                "domain": [0],
                "range": ["#4575b4", "#d73027"],
                "names": ["below the genome-wide share", "above it"]
              },
              "legend": { "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",
      "encoding": {
        "y": {
          "scale": { "domainMin": -1.5, "domainMax": 1.5 },
          "axis": { "title": "AluY share, log2" }
        }
      },
      "marks": [
        {
          "mark": "bar",
          "encoding": {
            "y": "youngLog2",
            "color": {
              "field": "youngLog2",
              "scale": {
                "type": "threshold",
                "domain": [0],
                "range": ["#4575b4", "#d73027"],
                "names": ["below the genome-wide share", "above it"]
              },
              "legend": { "title": "AluY share" }
            }
          }
        }
      ]
    }
  ]
}
Top: chromosome 1, Alu copies per kilobase above the AluY share per megabase. Below: the copies track over the same AluY share, copies per bin in grey and AluY in red.
Open in JBrowse Web ↗

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",
          "height": 110
        },
        {
          "trackId": "alu_young_share",
          "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",
                    "height": 110
                },
                {
                    "trackId": "alu_young_share",
                    "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: a data file opens as the track its name says.

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/alu_age/config.json \
  --assembly hg38 --loc chr1 \
  --track alu_per_kb '{"height":110}' \
  --track alu_young_share '{"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",
          "height": 110
        },
        {
          "trackId": "alu_young_share",
          "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",
          "height": 110
        },
        {
          "trackId": "alu_young_share",
          "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 ↗

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",
          "height": 110
        },
        {
          "trackId": "alu_young_share",
          "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",
                    "height": 110
                },
                {
                    "trackId": "alu_young_share",
                    "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: a data file opens as the track its name says.

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 '{"height":110}' \
  --track alu_young_share '{"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",
          "height": 110
        },
        {
          "trackId": "alu_young_share",
          "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",
          "height": 110
        },
        {
          "trackId": "alu_young_share",
          "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

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. ↩