Skip to main content

Structural variants (1000 Genomes)

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.

Take the deletion of RHD, the RhD blood group gene, out of the 1000 Genomes ensemble SV callset, sort the cohort's genotypes at it, then open three of those samples' reads and watch the coverage go to zero, halve, and stay flat. The page ends on a complex call from the same cohort whose coverage does none of that.

Prerequisites

  • a JBrowse instance to add tracks to (see the web quickstart or the desktop quickstart)
  • a multi-sample SV VCF, bgzip-compressed and tabix-indexed, with a .tbi or .csi beside it
  • CRAMs aligned to the same assembly, each with its .crai beside it

Where the data comes from

The page reads the 1000 Genomes 2022 high-coverage ensemble SV callset (Byrska-Bishop et al., 2022) against CRAMs from three of the cohort's samples and QuicK-mer2 copy number for the whole cohort.

Nothing to download: the track configs below read these files by URL.

The files

The RHD deletion in the 1000 Genomes SV callset

HGSV_1821 is a deletion on chr1 spanning the whole of RHD, so samples called homozygous have no copy of that gene. Deleting RHD is the most common cause of the RhD-negative blood type. The call is PASS and common enough to fill all three genotype classes, which read depth separates into two copies of the gene, one, or none.

Loading the callset, the reads and the copy-number store

The CRAMs decode against the assembly's sequence, so it must be the GRCh38 sequence the reads were aligned to, with the chromosome names the VCF uses.

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

We'll add the callset as a variant track. Swap uri for your own VCF, which needs per-sample genotype columns and an index beside it:

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

{
  "type": "VariantTrack",
  "trackId": "kgp_ensemble_sv",
  "name": "1KGP ensemble SV calls, 3202 samples",
  "assemblyNames": ["hg38"],
  "uri": "https://jbrowse.org/demos/1000g/1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz"
}
jbrowse add-track https://jbrowse.org/demos/1000g/1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz \
  --trackId kgp_ensemble_sv \
  --name "1KGP ensemble SV calls, 3202 samples" \
  --assemblyNames hg38

In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track... and, in Add a track from file or URL, enter:

  • Main file: https://jbrowse.org/demos/1000g/1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz

Click Next. JBrowse reads the adapter and track type off the file name. Then fill in:

  • Track name: 1KGP ensemble SV calls, 3202 samples
  • Assembly: hg38

Click Add.

Open this track in JBrowse Web ↗

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

One alignments track per sample comes next, here HG00113, the homozygous alt. Swap uri for your own CRAM, with its .crai beside it. The other two samples differ only in the file:

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

{
  "type": "AlignmentsTrack",
  "trackId": "hg00113_cram",
  "name": "HG00113 high coverage",
  "assemblyNames": ["hg38"],
  "uri": "https://1000genomes.s3.amazonaws.com/1000G_2504_high_coverage/data/ERR3240129/HG00113.final.cram"
}
jbrowse add-track https://1000genomes.s3.amazonaws.com/1000G_2504_high_coverage/data/ERR3240129/HG00113.final.cram \
  --trackId hg00113_cram \
  --name "HG00113 high coverage" \
  --assemblyNames hg38

In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track... and, in Add a track from file or URL, enter:

  • Main file: https://1000genomes.s3.amazonaws.com/1000G_2504_high_coverage/data/ERR3240129/HG00113.final.cram

Click Next. JBrowse reads the adapter and track type off the file name. Then fill in:

  • Track name: HG00113 high coverage
  • Assembly: hg38

Click Add.

Open this track in JBrowse Web ↗

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

The copy-number track reads the Zarr store through jbrowse-plugin-zarr, which is not yet in the plugin store. Add its hosted bundle to the config's plugins:

{
  "plugins": [
    {
      "name": "Zarr",
      "url": "https://jbrowse.org/demos/zarr/jbrowse-plugin-zarr.umd.production.min.js"
    }
  ]
}

The track below reads the store; the copy-number tutorial builds one from your own BigWigs:

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

{
  "type": "MultiQuantitativeTrack",
  "trackId": "cnv_1000g_zarr",
  "name": "1000 Genomes copy number, 2504 individuals",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "MultiWiggleZarrAdapter",
    "uri": "https://jbrowse.org/demos/1000g/qm2_cn_1kb.zarr"
  },
  "displayDefaults": {
    "mark": "span",
    "origin": 2,
    "scales": { "y": { "domainMin": 0, "domainMax": 4 } },
    "color": {
      "field": "score",
      "scale": "threshold",
      "range": ["#2166ac", "#b2182b"],
      "title": "Copy number"
    }
  }
}
jbrowse add-track-json '{
  "type": "MultiQuantitativeTrack",
  "trackId": "cnv_1000g_zarr",
  "name": "1000 Genomes copy number, 2504 individuals",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "MultiWiggleZarrAdapter",
    "uri": "https://jbrowse.org/demos/1000g/qm2_cn_1kb.zarr"
  },
  "displayDefaults": {
    "mark": "span",
    "origin": 2,
    "scales": { "y": { "domainMin": 0, "domainMax": 4 } },
    "color": {
      "field": "score",
      "scale": "threshold",
      "range": ["#2166ac", "#b2182b"],
      "title": "Copy number"
    }
  }
}'

In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track..., choose Add track from pasted JSON, and paste:

{
  "type": "MultiQuantitativeTrack",
  "trackId": "cnv_1000g_zarr",
  "name": "1000 Genomes copy number, 2504 individuals",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "MultiWiggleZarrAdapter",
    "uri": "https://jbrowse.org/demos/1000g/qm2_cn_1kb.zarr"
  },
  "displayDefaults": {
    "mark": "span",
    "origin": 2,
    "scales": { "y": { "domainMin": 0, "domainMax": 4 } },
    "color": {
      "field": "score",
      "scale": "threshold",
      "range": ["#2166ac", "#b2182b"],
      "title": "Copy number"
    }
  }
}

Navigate to chr1:25,200,000-25,400,000, the genotype figure's window. In grammar-of-graphics terms, the copy-number track's mark is the shape drawn, scales.y its y scale and color a color scale on score.

Sorting the cohort by genotype at the RHD deletion

Switch the callset track to Display types → Multi-sample variant display from the track menu. Each sample becomes a row drawn at the variant's genomic span, so the deletion is a wide block. Clicking it opens the feature details panel, whose SAMPLES section lists every sample's genotype, read depth and other fields.

Rows start in the callset's order. Right-click the deletion and pick Sort by genotype to order rows by genotype at that call, then by how far each keeps matching its neighbours. Clustering → Cluster rows by genotype... in the track menu instead clusters rows by genotypes across the whole window, with a dendrogram.

In the matrix, dark blue is no copy of RHD, light blue one and grey two. The olive stripe is HGSV_1823, a small copy-number record nested inside the deletion. The callset gives most of the cohort a no-call there (no genotype reported), but QuicK-mer2 measures copy number per bin from the reads, so the olive no-call column is a red gain in the copy-number track.

A matrix cell marks some call at that column. To see which call, load the same VCF again in the ordinary variant display, which draws each record on a separate row with its id, class and size, or color cells by SV type, as the multi-variant track guide shows.

The figure below has three tracks over NCBI RefSeq genes:

  • the callset as a genotype matrix, one row per sample, sorted by genotype at the RHD deletion
  • QuicK-mer2 copy number for 2504 individuals, one row each and clustered on this window, where blue is a copy lost against the diploid white and red a copy gained
  • the same records in the ordinary variant display, each labelled with its id
The 1KGP ensemble SV callset over the RHD locus on chr1, with the panel's copy-number calls under it. The deletion draws as a wide block, splitting the cohort into three bands in the matrix and three levels of copy number.
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%2F1000g_cnv%2Fconfig.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22type%22%3A%22VariantTrack%22%2C%22trackId%22%3A%22kgp_sv_matrix%22%2C%22name%22%3A%221KGP+ensemble+SV+calls%2C+3202+samples%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22VcfTabixAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2F1000g%2F1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz%22%7D%7D%2C%7B%22type%22%3A%22VariantTrack%22%2C%22trackId%22%3A%22kgp_sv_records%22%2C%22name%22%3A%221KGP+ensemble+SV+calls%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22VcfTabixAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2F1000g%2F1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz%22%7D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%221%3A25%2C200%2C000-25%2C400%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22kgp_sv_matrix%22%2C%22type%22%3A%22LinearMultiSampleVariantDisplay%22%2C%22showVariantLane%22%3Atrue%2C%22forceLoad%22%3Atrue%2C%22height%22%3A290%7D%2C%7B%22trackId%22%3A%22cnv_1000g_zarr%22%2C%22type%22%3A%22LinearWiggleDisplay%22%2C%22mark%22%3A%22span%22%2C%22origin%22%3A2%2C%22scales%22%3A%7B%22y%22%3A%7B%22domainMin%22%3A0%2C%22domainMax%22%3A4%7D%7D%2C%22color%22%3A%7B%22field%22%3A%22score%22%2C%22scale%22%3A%22threshold%22%2C%22range%22%3A%5B%22%232166ac%22%2C%22%23b2182b%22%5D%2C%22title%22%3A%22Copy+number%22%7D%2C%22height%22%3A330%2C%22runClustering%22%3Atrue%2C%22showTree%22%3Afalse%7D%2C%7B%22trackId%22%3A%22kgp_sv_records%22%2C%22type%22%3A%22LinearVariantDisplay%22%2C%22forceLoad%22%3Atrue%2C%22height%22%3A170%2C%22color%22%3A%22%234a5568%22%7D%2C%7B%22trackId%22%3A%22ncbi_refseq_hg38%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A120%2C%22showLabels%22%3A%22name%22%2C%22showOnlyGenes%22%3Atrue%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+multisv_rhd

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

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

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

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “1KGP ensemble SV calls, 3202 samples”.
    1. Track menu → Show... → Show variant lane (checked)Draws the variants at their genomic positions in a lane above the genotype rows. Offered only while "Show as genotype matrix" is unchecked.
    2. Click Force load in the track's "Zoom in to see features or force load" message.Loads the region even past the byte-size limit, which can be slow.
  3. Add the next track the same way.This figure uses “1000 Genomes copy number, 2504 individuals (Zarr)”.
    1. Track menu → Plot type → Density
    2. Track menu → Settings → originThe value the bars grow from, which a threshold color with no domain of its own also cuts at. No menu row writes it.
    3. Track menu → Y axis... → RangePins the axis: Min 0 and Max 4. A field left empty follows the data in view.
    4. Track menu → Edit colors/arrangement... → the plot color swatchesThe two colors the plot is drawn in, above and below the baseline; both the same paints a flat plot.
    5. Track menu → Clustering → Cluster rows by similarityOrders the rows by how alike they are across the region in view, and draws the tree it built beside them. It clusters over what is displayed, so the same menu item somewhere else gives a different order.
    6. Track menu → Show... → Show tree (unchecked)On by default. The item is disabled until there is a tree to show, and drops out entirely under an Overlapping plot, which collapses every source onto one row for a dendrogram to align to.
  4. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “1KGP ensemble SV calls”.
    1. Click Force load in the track's "Zoom in to see features or force load" message.Loads the region even past the byte-size limit, which can be slow.
    2. Track menu → Color by... → Solid color... → #4a5568
  5. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes”.
    1. Track menu → Show... → Labels → Name only
    2. Track menu → Show only genes (checked)
  6. Type your region of interest into the location box and press Enter.This figure is at 1:25,200,000-25,400,000.

A figure adds its tracks to one session. The jbrowse CLI writes the same tracks into a config.json instead, where every session that opens it has them: add-track where flags cover the whole track, add-track-json where they do not.

jbrowse add-track https://jbrowse.org/demos/1000g/1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz \
  --trackId kgp_sv_matrix \
  --name "1KGP ensemble SV calls, 3202 samples" \
  --assemblyNames hg38

jbrowse add-track https://jbrowse.org/demos/1000g/1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz \
  --trackId kgp_sv_records \
  --name "1KGP ensemble SV calls" \
  --assemblyNames hg38

Run these where the config.json is, or add --out <dir>, and point each uri at your own file. The config needs hg38 already — jbrowse add-assembly adds yours. The location and the settings the steps carry are session state rather than track config — that half is the Spec tab, or jbrowse set-default-session.

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

{
  "sessionTracks": [
    {
      "type": "VariantTrack",
      "trackId": "kgp_sv_matrix",
      "name": "1KGP ensemble SV calls, 3202 samples",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "VcfTabixAdapter",
        "uri": "https://jbrowse.org/demos/1000g/1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz"
      }
    },
    {
      "type": "VariantTrack",
      "trackId": "kgp_sv_records",
      "name": "1KGP ensemble SV calls",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "VcfTabixAdapter",
        "uri": "https://jbrowse.org/demos/1000g/1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz"
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "1:25,200,000-25,400,000",
      "tracks": [
        {
          "trackId": "kgp_sv_matrix",
          "type": "LinearMultiSampleVariantDisplay",
          "showVariantLane": true,
          "forceLoad": true,
          "height": 290
        },
        {
          "trackId": "cnv_1000g_zarr",
          "type": "LinearWiggleDisplay",
          "mark": "span",
          "origin": 2,
          "scales": {
            "y": {
              "domainMin": 0,
              "domainMax": 4
            }
          },
          "color": {
            "field": "score",
            "scale": "threshold",
            "range": [
              "#2166ac",
              "#b2182b"
            ],
            "title": "Copy number"
          },
          "height": 330,
          "runClustering": true,
          "showTree": false
        },
        {
          "trackId": "kgp_sv_records",
          "type": "LinearVariantDisplay",
          "forceLoad": true,
          "height": 170,
          "color": "#4a5568"
        },
        {
          "trackId": "ncbi_refseq_hg38",
          "type": "LinearBasicDisplay",
          "height": 120,
          "showLabels": "name",
          "showOnlyGenes": true
        }
      ]
    }
  ]
}

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

cat > session.json <<'JSON'
{
  "sessionTracks": [
    {
      "type": "VariantTrack",
      "trackId": "kgp_sv_matrix",
      "name": "1KGP ensemble SV calls, 3202 samples",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "VcfTabixAdapter",
        "uri": "https://jbrowse.org/demos/1000g/1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz"
      }
    },
    {
      "type": "VariantTrack",
      "trackId": "kgp_sv_records",
      "name": "1KGP ensemble SV calls",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "VcfTabixAdapter",
        "uri": "https://jbrowse.org/demos/1000g/1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz"
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "1:25,200,000-25,400,000",
      "tracks": [
        {
          "trackId": "kgp_sv_matrix",
          "type": "LinearMultiSampleVariantDisplay",
          "showVariantLane": true,
          "forceLoad": true,
          "height": 290
        },
        {
          "trackId": "cnv_1000g_zarr",
          "type": "LinearWiggleDisplay",
          "mark": "span",
          "origin": 2,
          "scales": {
            "y": {
              "domainMin": 0,
              "domainMax": 4
            }
          },
          "color": {
            "field": "score",
            "scale": "threshold",
            "range": [
              "#2166ac",
              "#b2182b"
            ],
            "title": "Copy number"
          },
          "height": 330,
          "runClustering": true,
          "showTree": false
        },
        {
          "trackId": "kgp_sv_records",
          "type": "LinearVariantDisplay",
          "forceLoad": true,
          "height": 170,
          "color": "#4a5568"
        },
        {
          "trackId": "ncbi_refseq_hg38",
          "type": "LinearBasicDisplay",
          "height": 120,
          "showLabels": "name",
          "showOnlyGenes": true
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/1000g_cnv/config.json \
  --width 1500 --height 1230 \
  --timeout 300000 \
  --spec session.json -o figure.png

The figure's clicks sort the matrix's rows by genotype at HGSV_1821, which this command does not do, so its picture differs there.

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.

A right-click on the deletion sorts the cohort by genotype there, resolving the callset order into three bands: both copies of RHD deleted, one, then neither.

Open the session the video starts in ↗, then take the steps it shows:

  1. 3202 samples in callset order, which groups nothing
  2. Right-click the deletion and sort the rows by genotype there
  3. Three bands, top to bottom: both copies deleted, one, then neither

Open this view in JBrowse Web ↗ · Open this view 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%2F1000g_cnv%2Fconfig.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22type%22%3A%22VariantTrack%22%2C%22trackId%22%3A%22kgp_sv_matrix%22%2C%22name%22%3A%221KGP+ensemble+SV+calls%2C+3202+samples%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22VcfTabixAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2F1000g%2F1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz%22%7D%7D%2C%7B%22type%22%3A%22VariantTrack%22%2C%22trackId%22%3A%22kgp_sv_records%22%2C%22name%22%3A%221KGP+ensemble+SV+calls%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22VcfTabixAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2F1000g%2F1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz%22%7D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%221%3A25%2C200%2C000-25%2C400%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22kgp_sv_matrix%22%2C%22type%22%3A%22LinearMultiSampleVariantDisplay%22%2C%22showVariantLane%22%3Atrue%2C%22forceLoad%22%3Atrue%2C%22height%22%3A290%7D%2C%7B%22trackId%22%3A%22cnv_1000g_zarr%22%2C%22type%22%3A%22LinearWiggleDisplay%22%2C%22mark%22%3A%22span%22%2C%22origin%22%3A2%2C%22scales%22%3A%7B%22y%22%3A%7B%22domainMin%22%3A0%2C%22domainMax%22%3A4%7D%7D%2C%22color%22%3A%7B%22field%22%3A%22score%22%2C%22scale%22%3A%22threshold%22%2C%22range%22%3A%5B%22%232166ac%22%2C%22%23b2182b%22%5D%2C%22title%22%3A%22Copy+number%22%7D%2C%22height%22%3A330%2C%22runClustering%22%3Atrue%2C%22showTree%22%3Afalse%7D%2C%7B%22trackId%22%3A%22kgp_sv_records%22%2C%22type%22%3A%22LinearVariantDisplay%22%2C%22forceLoad%22%3Atrue%2C%22height%22%3A170%2C%22color%22%3A%22%234a5568%22%7D%2C%7B%22trackId%22%3A%22ncbi_refseq_hg38%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A120%2C%22showLabels%22%3A%22name%22%2C%22showOnlyGenes%22%3Atrue%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+sv%2Fmultisample_sort

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

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

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “1KGP ensemble SV calls, 3202 samples”.
    1. Track menu → Show... → Show variant lane (checked)Draws the variants at their genomic positions in a lane above the genotype rows. Offered only while "Show as genotype matrix" is unchecked.
    2. Click Force load in the track's "Zoom in to see features or force load" message.Loads the region even past the byte-size limit, which can be slow.
  3. Add the next track the same way.This figure uses “1000 Genomes copy number, 2504 individuals (Zarr)”.
    1. Track menu → Plot type → Density
    2. Track menu → Settings → originThe value the bars grow from, which a threshold color with no domain of its own also cuts at. No menu row writes it.
    3. Track menu → Y axis... → RangePins the axis: Min 0 and Max 4. A field left empty follows the data in view.
    4. Track menu → Edit colors/arrangement... → the plot color swatchesThe two colors the plot is drawn in, above and below the baseline; both the same paints a flat plot.
    5. Track menu → Clustering → Cluster rows by similarityOrders the rows by how alike they are across the region in view, and draws the tree it built beside them. It clusters over what is displayed, so the same menu item somewhere else gives a different order.
    6. Track menu → Show... → Show tree (unchecked)On by default. The item is disabled until there is a tree to show, and drops out entirely under an Overlapping plot, which collapses every source onto one row for a dendrogram to align to.
  4. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “1KGP ensemble SV calls”.
    1. Click Force load in the track's "Zoom in to see features or force load" message.Loads the region even past the byte-size limit, which can be slow.
    2. Track menu → Color by... → Solid color... → #4a5568
  5. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes”.
    1. Track menu → Show... → Labels → Name only
    2. Track menu → Show only genes (checked)
  6. Type your region of interest into the location box and press Enter.This figure is at 1:25,200,000-25,400,000.

A figure adds its tracks to one session. The jbrowse CLI writes the same tracks into a config.json instead, where every session that opens it has them: add-track where flags cover the whole track, add-track-json where they do not.

jbrowse add-track https://jbrowse.org/demos/1000g/1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz \
  --trackId kgp_sv_matrix \
  --name "1KGP ensemble SV calls, 3202 samples" \
  --assemblyNames hg38

jbrowse add-track https://jbrowse.org/demos/1000g/1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz \
  --trackId kgp_sv_records \
  --name "1KGP ensemble SV calls" \
  --assemblyNames hg38

Run these where the config.json is, or add --out <dir>, and point each uri at your own file. The config needs hg38 already — jbrowse add-assembly adds yours. The location and the settings the steps carry are session state rather than track config — that half is the Spec tab, or jbrowse set-default-session.

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

{
  "sessionTracks": [
    {
      "type": "VariantTrack",
      "trackId": "kgp_sv_matrix",
      "name": "1KGP ensemble SV calls, 3202 samples",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "VcfTabixAdapter",
        "uri": "https://jbrowse.org/demos/1000g/1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz"
      }
    },
    {
      "type": "VariantTrack",
      "trackId": "kgp_sv_records",
      "name": "1KGP ensemble SV calls",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "VcfTabixAdapter",
        "uri": "https://jbrowse.org/demos/1000g/1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz"
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "1:25,200,000-25,400,000",
      "tracks": [
        {
          "trackId": "kgp_sv_matrix",
          "type": "LinearMultiSampleVariantDisplay",
          "showVariantLane": true,
          "forceLoad": true,
          "height": 290
        },
        {
          "trackId": "cnv_1000g_zarr",
          "type": "LinearWiggleDisplay",
          "mark": "span",
          "origin": 2,
          "scales": {
            "y": {
              "domainMin": 0,
              "domainMax": 4
            }
          },
          "color": {
            "field": "score",
            "scale": "threshold",
            "range": [
              "#2166ac",
              "#b2182b"
            ],
            "title": "Copy number"
          },
          "height": 330,
          "runClustering": true,
          "showTree": false
        },
        {
          "trackId": "kgp_sv_records",
          "type": "LinearVariantDisplay",
          "forceLoad": true,
          "height": 170,
          "color": "#4a5568"
        },
        {
          "trackId": "ncbi_refseq_hg38",
          "type": "LinearBasicDisplay",
          "height": 120,
          "showLabels": "name",
          "showOnlyGenes": true
        }
      ]
    }
  ]
}

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

cat > session.json <<'JSON'
{
  "sessionTracks": [
    {
      "type": "VariantTrack",
      "trackId": "kgp_sv_matrix",
      "name": "1KGP ensemble SV calls, 3202 samples",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "VcfTabixAdapter",
        "uri": "https://jbrowse.org/demos/1000g/1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz"
      }
    },
    {
      "type": "VariantTrack",
      "trackId": "kgp_sv_records",
      "name": "1KGP ensemble SV calls",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "VcfTabixAdapter",
        "uri": "https://jbrowse.org/demos/1000g/1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz"
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "1:25,200,000-25,400,000",
      "tracks": [
        {
          "trackId": "kgp_sv_matrix",
          "type": "LinearMultiSampleVariantDisplay",
          "showVariantLane": true,
          "forceLoad": true,
          "height": 290
        },
        {
          "trackId": "cnv_1000g_zarr",
          "type": "LinearWiggleDisplay",
          "mark": "span",
          "origin": 2,
          "scales": {
            "y": {
              "domainMin": 0,
              "domainMax": 4
            }
          },
          "color": {
            "field": "score",
            "scale": "threshold",
            "range": [
              "#2166ac",
              "#b2182b"
            ],
            "title": "Copy number"
          },
          "height": 330,
          "runClustering": true,
          "showTree": false
        },
        {
          "trackId": "kgp_sv_records",
          "type": "LinearVariantDisplay",
          "forceLoad": true,
          "height": 170,
          "color": "#4a5568"
        },
        {
          "trackId": "ncbi_refseq_hg38",
          "type": "LinearBasicDisplay",
          "height": 120,
          "showLabels": "name",
          "showOnlyGenes": true
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/1000g_cnv/config.json \
  --width 1920 --height 1244 \
  --spec session.json -o figure.png

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

Checking the RHD genotypes against read coverage in three samples

Open three samples' alignments, one per genotype: HG00113 homozygous alt, HG00096 heterozygous, HG00097 homozygous reference. Two settings make them comparable:

  • Turn the pileup off with Show... → Show pileup in the track menu, since at this width the coverage curve shows the difference.
  • Share one axis from Coverage axis... → Share axis with, ticking the other two tracks, so the samples compare by height.
Coverage over the RHD deletion in three samples on one shared axis, with the RHD span banded. Top, HG00113 with no copy; middle, HG00096 with one; bottom, HG00097 with two.
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=https%3A%2F%2Fjbrowse.org%2Fdemos%2F1000g%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%221%3A25%2C200%2C000-25%2C470%2C000%22%2C%22highlight%22%3A%5B%7B%22refName%22%3A%221%22%2C%22start%22%3A25272393%2C%22end%22%3A25330445%2C%22color%22%3A%22rgba%28214%2C137%2C16%2C0.13%29%22%7D%5D%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22ncbi_refseq_109_hg38%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22heightMode%22%3A%22grow%22%2C%22geneGlyphMode%22%3A%22longestCoding%22%2C%22showLabels%22%3A%22name%22%2C%22showOnlyGenes%22%3Atrue%7D%2C%7B%22trackId%22%3A%22HG00113.final%22%2C%22type%22%3A%22LinearAlignmentsDisplay%22%2C%22forceLoad%22%3Atrue%2C%22showPileup%22%3Afalse%2C%22readConnections%22%3A%22off%22%2C%22height%22%3A200%2C%22coverageHeight%22%3A190%2C%22scales%22%3A%7B%22y%22%3A%7B%22autoscaleGroup%22%3A%22depth%22%7D%7D%7D%2C%7B%22trackId%22%3A%22HG00096.final%22%2C%22type%22%3A%22LinearAlignmentsDisplay%22%2C%22forceLoad%22%3Atrue%2C%22showPileup%22%3Afalse%2C%22readConnections%22%3A%22off%22%2C%22height%22%3A200%2C%22coverageHeight%22%3A190%2C%22scales%22%3A%7B%22y%22%3A%7B%22autoscaleGroup%22%3A%22depth%22%7D%7D%7D%2C%7B%22trackId%22%3A%22HG00097.final%22%2C%22type%22%3A%22LinearAlignmentsDisplay%22%2C%22forceLoad%22%3Atrue%2C%22showPileup%22%3Afalse%2C%22readConnections%22%3A%22off%22%2C%22height%22%3A200%2C%22coverageHeight%22%3A190%2C%22scales%22%3A%7B%22y%22%3A%7B%22autoscaleGroup%22%3A%22depth%22%7D%7D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+multisv_rhd_dosage

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

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

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

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq analysis set (GFF3Tabix)”.
    1. Track menu → Feature height → Track sizing → Fixed feature height + autogrow track height
    2. Track menu → Gene glyph → Representative transcript
    3. Track menu → Show... → Labels → Name only
    4. Track menu → Show only genes (checked)
  3. Add the next track the same way. This one needs a CRAM file (.cram + .crai).This figure uses “HG00113.final”.
    1. Click Force load in the track's "Zoom in to see features or force load" message.Loads the region even past the byte-size limit, which can be slow.
    2. Track menu → Show... → Show pileup (unchecked)Drops the stacked-read band and keeps the coverage curve, so several samples can be compared on depth alone.
    3. Track menu → Read connections → None
    4. Drag the bottom edge of the coverage band to resize it.
    5. Track menu → Coverage axis... → Share axis withTick the tracks that share this axis, here every one in group "depth".
  4. Add the next track the same way. This one needs a CRAM file (.cram + .crai).This figure uses “HG00096.final”.
    1. Click Force load in the track's "Zoom in to see features or force load" message.Loads the region even past the byte-size limit, which can be slow.
    2. Track menu → Show... → Show pileup (unchecked)Drops the stacked-read band and keeps the coverage curve, so several samples can be compared on depth alone.
    3. Track menu → Read connections → None
    4. Drag the bottom edge of the coverage band to resize it.
    5. Track menu → Coverage axis... → Share axis withTick the tracks that share this axis, here every one in group "depth".
  5. Add the next track the same way. This one needs a CRAM file (.cram + .crai).This figure uses “HG00097.final”.
    1. Click Force load in the track's "Zoom in to see features or force load" message.Loads the region even past the byte-size limit, which can be slow.
    2. Track menu → Show... → Show pileup (unchecked)Drops the stacked-read band and keeps the coverage curve, so several samples can be compared on depth alone.
    3. Track menu → Read connections → None
    4. Drag the bottom edge of the coverage band to resize it.
    5. Track menu → Coverage axis... → Share axis withTick the tracks that share this axis, here every one in group "depth".
  6. Type your region of interest into the location box and press Enter.This figure is at 1:25,200,000-25,470,000.
  7. View menu → Zoom to region / use the location box, then add a highlightThis figure highlights 1 region; highlights can also be set with the &highlight= URL parameter.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/1000g/config.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "1:25,200,000-25,470,000",
      "highlight": [
        {
          "refName": "1",
          "start": 25272393,
          "end": 25330445,
          "color": "rgba(214,137,16,0.13)"
        }
      ],
      "tracks": [
        {
          "trackId": "ncbi_refseq_109_hg38",
          "type": "LinearBasicDisplay",
          "heightMode": "grow",
          "geneGlyphMode": "longestCoding",
          "showLabels": "name",
          "showOnlyGenes": true
        },
        {
          "trackId": "HG00113.final",
          "type": "LinearAlignmentsDisplay",
          "forceLoad": true,
          "showPileup": false,
          "readConnections": "off",
          "height": 200,
          "coverageHeight": 190,
          "scales": {
            "y": {
              "autoscaleGroup": "depth"
            }
          }
        },
        {
          "trackId": "HG00096.final",
          "type": "LinearAlignmentsDisplay",
          "forceLoad": true,
          "showPileup": false,
          "readConnections": "off",
          "height": 200,
          "coverageHeight": 190,
          "scales": {
            "y": {
              "autoscaleGroup": "depth"
            }
          }
        },
        {
          "trackId": "HG00097.final",
          "type": "LinearAlignmentsDisplay",
          "forceLoad": true,
          "showPileup": false,
          "readConnections": "off",
          "height": 200,
          "coverageHeight": 190,
          "scales": {
            "y": {
              "autoscaleGroup": "depth"
            }
          }
        }
      ]
    }
  ]
}

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/demos/1000g/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "1:25,200,000-25,470,000",
            "highlight": [
                {
                    "refName": "1",
                    "start": 25272393,
                    "end": 25330445,
                    "color": "rgba(214,137,16,0.13)"
                }
            ],
            "tracks": [
                {
                    "trackId": "ncbi_refseq_109_hg38",
                    "type": "LinearBasicDisplay",
                    "heightMode": "grow",
                    "geneGlyphMode": "longestCoding",
                    "showLabels": "name",
                    "showOnlyGenes": True
                },
                {
                    "trackId": "HG00113.final",
                    "type": "LinearAlignmentsDisplay",
                    "forceLoad": True,
                    "showPileup": False,
                    "readConnections": "off",
                    "height": 200,
                    "coverageHeight": 190,
                    "scales": {
                        "y": {
                            "autoscaleGroup": "depth"
                        }
                    }
                },
                {
                    "trackId": "HG00096.final",
                    "type": "LinearAlignmentsDisplay",
                    "forceLoad": True,
                    "showPileup": False,
                    "readConnections": "off",
                    "height": 200,
                    "coverageHeight": 190,
                    "scales": {
                        "y": {
                            "autoscaleGroup": "depth"
                        }
                    }
                },
                {
                    "trackId": "HG00097.final",
                    "type": "LinearAlignmentsDisplay",
                    "forceLoad": True,
                    "showPileup": False,
                    "readConnections": "off",
                    "height": 200,
                    "coverageHeight": 190,
                    "scales": {
                        "y": {
                            "autoscaleGroup": "depth"
                        }
                    }
                }
            ]
        }
    ],
)
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/demos/1000g/config.json \
  --assembly hg38 --loc 1:25,200,000-25,470,000 \
  --track ncbi_refseq_109_hg38 display:LinearBasicDisplay '{"heightMode":"grow","geneGlyphMode":"longestCoding","showLabels":"name","showOnlyGenes":true}' \
  --track HG00113.final display:LinearAlignmentsDisplay '{"forceLoad":true,"showPileup":false,"readConnections":"off","height":200,"coverageHeight":190,"scales":{"y":{"autoscaleGroup":"depth"}}}' \
  --track HG00096.final display:LinearAlignmentsDisplay '{"forceLoad":true,"showPileup":false,"readConnections":"off","height":200,"coverageHeight":190,"scales":{"y":{"autoscaleGroup":"depth"}}}' \
  --track HG00097.final display:LinearAlignmentsDisplay '{"forceLoad":true,"showPileup":false,"readConnections":"off","height":200,"coverageHeight":190,"scales":{"y":{"autoscaleGroup":"depth"}}}' \
  --width 1500 --out figure.svg

It has no flag for this figure's highlight, so its picture can differ there.

--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": "1:25,200,000-25,470,000",
      "highlight": [
        {
          "refName": "1",
          "start": 25272393,
          "end": 25330445,
          "color": "rgba(214,137,16,0.13)"
        }
      ],
      "tracks": [
        {
          "trackId": "ncbi_refseq_109_hg38",
          "type": "LinearBasicDisplay",
          "heightMode": "grow",
          "geneGlyphMode": "longestCoding",
          "showLabels": "name",
          "showOnlyGenes": true
        },
        {
          "trackId": "HG00113.final",
          "type": "LinearAlignmentsDisplay",
          "forceLoad": true,
          "showPileup": false,
          "readConnections": "off",
          "height": 200,
          "coverageHeight": 190,
          "scales": {
            "y": {
              "autoscaleGroup": "depth"
            }
          }
        },
        {
          "trackId": "HG00096.final",
          "type": "LinearAlignmentsDisplay",
          "forceLoad": true,
          "showPileup": false,
          "readConnections": "off",
          "height": 200,
          "coverageHeight": 190,
          "scales": {
            "y": {
              "autoscaleGroup": "depth"
            }
          }
        },
        {
          "trackId": "HG00097.final",
          "type": "LinearAlignmentsDisplay",
          "forceLoad": true,
          "showPileup": false,
          "readConnections": "off",
          "height": 200,
          "coverageHeight": 190,
          "scales": {
            "y": {
              "autoscaleGroup": "depth"
            }
          }
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/1000g/config.json \
  --width 1500 --height 1000 \
  --timeout 600000 \
  --spec session.json -o figure.png

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

Coverage over the deleted span in the top row sits just above zero. The neighbouring gene RHCE, just right of RHD, is nearly identical, so some RHCE reads land in the empty RHD footprint.

Reading a complex call in HG02768 from read-pair orientation

A balanced rearrangement such as an inversion leaves coverage unchanged but changes read-pair orientation, meaning which strand each mate maps to. HG02768 has a complex call, an inversion with a duplicated copy, with coverage like the rest of its arm.

Put 1:39,658,200-39,661,800 in the location box and add HG02768's CRAM as a track the same way as HG00113's.

Read connections → SV channels (pairs by orientation) in the track menu splits the reads into one band per orientation class, each with a separate coverage curve and arcs:

  • The normal-orientation band holds the flat coverage profile
  • The two same-strand bands (both mates on one strand) each draw a bundle of arcs on one pair of breakpoints, the inversion signature
  • The outward-pointing band (mates facing away from each other), where a tandem duplication would go, stays near empty
HG02768's reads at the complex call, split into one band per pair orientation. The two same-strand bands hold arc bundles ending on one pair of breakpoints, the normal band shows the ordinary coverage, and the outward-pointing band is near empty. The last band holds reads whose mate is unmapped or on another chromosome, drawn as inter-chromosomal ticks.
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=https%3A%2F%2Fjbrowse.org%2Fdemos%2F1000g%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%221%3A39%2C658%2C200-39%2C661%2C800%22%2C%22trackLabels%22%3A%22offset%22%2C%22tracks%22%3A%5B%221KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf%22%2C%7B%22trackId%22%3A%22HG02768.final%22%2C%22type%22%3A%22LinearAlignmentsDisplay%22%2C%22showPileup%22%3Afalse%2C%22facet%22%3A%22pairOrientation%22%2C%22readConnections%22%3A%22arc%22%2C%22readConnectionsDown%22%3Atrue%2C%22showOrdinaryPairs%22%3Afalse%2C%22showLegend%22%3Atrue%2C%22coverageHeight%22%3A60%2C%22readConnectionsHeight%22%3A90%2C%22height%22%3A800%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+sv_channels

Or rebuild it from your own data:

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

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

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf”.
  3. Add the next track the same way. This one needs a CRAM file (.cram + .crai).This figure uses “HG02768_father”.
    1. Track menu → Read connections → SV channels (pairs by orientation)
    2. Track menu → Group by... → Pair orientation
    3. Track menu → Read connections → Arc / read cloud band options → Draw arcs below coverage band (checked)
    4. Track menu → Show... → Show legend (checked)
    5. Drag the bottom edge of the coverage band to resize it.
    6. Drag the handle at the edge of the arc band to resize it (90px here).Its tooltip reads "Drag to resize arcs area"; there is no menu entry for the height.
  4. Type your region of interest into the location box and press Enter.This figure is at 1:39,658,200-39,661,800.
  5. View menu → Show... → Offset

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/1000g/config.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "1:39,658,200-39,661,800",
      "trackLabels": "offset",
      "tracks": [
        "1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf",
        {
          "trackId": "HG02768.final",
          "type": "LinearAlignmentsDisplay",
          "showPileup": false,
          "facet": "pairOrientation",
          "readConnections": "arc",
          "readConnectionsDown": true,
          "showOrdinaryPairs": false,
          "showLegend": true,
          "coverageHeight": 60,
          "readConnectionsHeight": 90,
          "height": 800
        }
      ]
    }
  ]
}

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/demos/1000g/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "1:39,658,200-39,661,800",
            "trackLabels": "offset",
            "tracks": [
                "1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf",
                {
                    "trackId": "HG02768.final",
                    "type": "LinearAlignmentsDisplay",
                    "showPileup": False,
                    "facet": "pairOrientation",
                    "readConnections": "arc",
                    "readConnectionsDown": True,
                    "showOrdinaryPairs": False,
                    "showLegend": True,
                    "coverageHeight": 60,
                    "readConnectionsHeight": 90,
                    "height": 800
                }
            ]
        }
    ],
)
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/demos/1000g/config.json \
  --assembly hg38 --loc 1:39,658,200-39,661,800 \
  --trackLabels offset \
  --track 1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf \
  --track HG02768.final display:LinearAlignmentsDisplay '{"showPileup":false,"facet":"pairOrientation","readConnections":"arc","readConnectionsDown":true,"showOrdinaryPairs":false,"showLegend":true,"coverageHeight":60,"readConnectionsHeight":90,"height":800}' \
  --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": "1:39,658,200-39,661,800",
      "trackLabels": "offset",
      "tracks": [
        "1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf",
        {
          "trackId": "HG02768.final",
          "type": "LinearAlignmentsDisplay",
          "showPileup": false,
          "facet": "pairOrientation",
          "readConnections": "arc",
          "readConnectionsDown": true,
          "showOrdinaryPairs": false,
          "showLegend": true,
          "coverageHeight": 60,
          "readConnectionsHeight": 90,
          "height": 800
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/1000g/config.json \
  --width 1500 --height 1150 \
  --spec session.json -o figure.png

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

The call also lists a duplicated copy in INFO.CPX_INTERVALS, which no band shows. A copy inserted beside its origin leaves pair orientation unchanged, so that half of the call rests on coverage, where noise at this size makes bumps as wide as the duplication.

See also

Notes

  1. The file EBI publishes is at https://ftp.1000genomes.ebi.ac.uk/vol1/ftp/data_collections/1000G_2504_high_coverage/working/20210124.SV_Illumina_Integration/1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz and the jbrowse.org copy is byte-for-byte that. The CRAM urls above are the Registry of Open Data mirror of the same 1000 Genomes ftp tree, which answers a range request in a fraction of the time EBI takes. ↩