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.11. 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:

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

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 its name in that header. The track below lists three marks, and the first draws a bar per copy with milliDiv as the height, below maxBpPerPx. A formula step writes the first four characters of the name into a lineage field (AluJ, AluS, AluY: oldest to youngest, and AluY is still inserting), and a categorical domain fixes the legend order and colours. The adapter's densityAdapter names a density sidecar, built in Zooming out.

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",
    "densityAdapter": {
      "type": "BigWigAdapter",
      "uri": "https://jbrowse.org/demos/gene_density/Alu.bed.density.bw"
    }
  },
  "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",
          "source": "density",
          "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",
    "densityAdapter": {
      "type": "BigWigAdapter",
      "uri": "https://jbrowse.org/demos/gene_density/Alu.bed.density.bw"
    }
  },
  "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",
          "source": "density",
          "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",
    "densityAdapter": {
      "type": "BigWigAdapter",
      "uri": "https://jbrowse.org/demos/gene_density/Alu.bed.density.bw"
    }
  },
  "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",
          "source": "density",
          "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 it on chr1:151,000,000-151,030,000, 30 kb of 1q21. Hover a bar for its values; click it to open the 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 colour. 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 ↗

Or rebuild it from your own data:

Opening in Desktop needs JBrowse Desktop 5.0+, and saves the view as a reopenable session.

Nothing happens?

Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=test_data%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

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).This figure uses hg38, loaded from a .2bit genome.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “Alu copies”.
    1. Drag the bar at the bottom edge of the track to resize it (200px here).
  3. Type your region of interest into the location box and press Enter.This figure is at chr1:151,000,000-151,030,000.

Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

With your own data, the steps behind the figure:

  1. Put your genome in your JBrowse Web's config.json: jbrowse add-assembly adds it.This figure uses hg38, loaded from a .2bit genome.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “Alu copies”.
    1. Drag the bar at the bottom edge of the track to resize it (200px here).
  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 from test_data/alu_age/config.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

{
  "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 — swap an adapter uri for your own file 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": {
      "track": "alu_age",
      "locus": "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

Past the per-copy bars' minBpPerPx, two binned counts replace them: every Alu copy in grey, and the AluY copies in red. In the config, each count is a mark that bins copies with { "type": "bin", "step": "auto" } and counts them with an aggregate; the red one adds a filter for AluY.

On a whole chromosome the track would exceed its feature budget. The grey mark has "source": "density", so past the budget it draws the bins of a density sidecar, a bigWig of feature starts per kilobase:

# 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

Density band in the track menu holds or forces the swap to density bins.

AluY share per megabase, against the genome-wide share

The red AluY count is too small to read against a total that varies several-fold 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, then run it:

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

The track below plots the young share on a symmetric pinned axis, coloured by a threshold at 0. Edit plot... in the track menu sets the same cut, colours and key names on an open 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 from the density sidecar above the AluY share per megabase, red above the genome-wide share and blue below. Under the wedge, the same two tracks 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 ↗

Or rebuild it from your own data:

Opening in Desktop needs JBrowse Desktop 5.0+, and saves the view as a reopenable session.

Nothing happens?

Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=test_data%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_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%2Fchromosome

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).This figure uses hg38, loaded from a .2bit genome.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “Alu copies”.
    1. Drag the bar at the bottom edge of the track to resize it (110px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “AluY share per Mb, against the genome”.
    1. Drag the bar at the bottom edge of the track to resize it (90px here).
  4. Type your region of interest into the location box and press Enter.This figure is at chr1.

Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

With your own data, the steps behind the figure:

  1. Put your genome in your JBrowse Web's config.json: jbrowse add-assembly adds it.This figure uses hg38, loaded from a .2bit genome.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “Alu copies”.
    1. Drag the bar at the bottom edge of the track to resize it (110px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “AluY share per Mb, against the genome”.
    1. Drag the bar at the bottom edge of the track to resize it (90px here).
  4. Type your region of interest into the location box and press Enter.This figure is at chr1.

This session spec draws the figure from test_data/alu_age/config.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr1",
      "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",
            "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 \
  --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 — swap an adapter uri for your own file 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_age",
          "type": "LinearMarkDisplay",
          "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": {
      "track": "alu_young_share",
      "locus": "chr1:191,500,000",
      "fracY": 0.3
    },
    "dx": -40,
    "dy": -95
  },
  {
    "type": "text",
    "text": "Alu dense: young share low",
    "fontSize": 18,
    "leader": true,
    "anchor": {
      "track": "alu_young_share",
      "locus": "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 ↗

Or rebuild it from your own data:

Opening in Desktop needs JBrowse Desktop 5.0+, and saves the view as a reopenable session.

Nothing happens?

Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=test_data%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

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).This figure uses hg38, loaded from a .2bit genome.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “Alu copies”.
    1. Drag the bar at the bottom edge of the track to resize it (110px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “AluY share per Mb, against the genome”.
    1. Drag the bar at the bottom edge of the track to resize it (90px here).
  4. Type your region of interest into the location box and press Enter.This figure is at chr1:184000001-212000000.

Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

With your own data, the steps behind the figure:

  1. Put your genome in your JBrowse Web's config.json: jbrowse add-assembly adds it.This figure uses hg38, loaded from a .2bit genome.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “Alu copies”.
    1. Drag the bar at the bottom edge of the track to resize it (110px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “AluY share per Mb, against the genome”.
    1. Drag the bar at the bottom edge of the track to resize it (90px here).
  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 from test_data/alu_age/config.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

{
  "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 — swap an adapter uri for your own file 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_age",
          "type": "LinearMarkDisplay",
          "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": {
      "track": "alu_young_share",
      "locus": "chr1:191,500,000",
      "fracY": 0.3
    },
    "dx": -40,
    "dy": -95
  },
  {
    "type": "text",
    "text": "Alu dense: young share low",
    "fontSize": 18,
    "leader": true,
    "anchor": {
      "track": "alu_young_share",
      "locus": "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.

Where Alu is sparse the young share runs red, and where it is dense it turns blue.

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 megabase and one blue one 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

With no arguments the script builds the tracks over UCSC's table. bash build_alu_age.sh rmsk.bed.gz genome.fa builds them over 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. ↩