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.17. Desktop beta builds are coming soon.

Take the deletion of RHD, the RhD blood group gene, out of the 1000 Genomes ensemble SV callset. We:

  • load the callset as a multi-sample variant track, with the reads and the copy-number store
  • cluster the rows by genotype to sort the cohort at the deletion
  • open three samples' reads on a shared coverage axis and compare their depth
  • read a complex call from the same cohort by its read-pair orientation

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

The data

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. Your own VCF and CRAM swap in by uri, as Loading the callset, the reads and the copy-number store shows.

The files
What it isFile
The ensemble SV callset, 3202 samples. EBI publishes it with no mirror, so the demo reads a byte-for-byte copy on jbrowse.org11KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf.gz
HG00113 (homozygous alt) high-coverage CRAMHG00113.final.cram
HG00096 (heterozygous) high-coverage CRAMHG00096.final.cram
HG00097 (homozygous reference) high-coverage CRAMHG00097.final.cram
HG02768 high-coverage CRAM, for the complex callHG02768.final.cram
QuicK-mer2 copy number for the cohort, the store the copy-number tutorial also reads. A directory of chunks that 404s at its root, and the adapter takes it as its uriqm2_cn_1kb.zarr

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 ↗

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 ↗

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,
    "encoding": {
      "y": { "scale": { "domainMin": 0, "domainMax": 4 } },
      "color": {
        "scale": { "range": ["#2166ac", "#b2182b"] },
        "legend": { "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,
    "encoding": {
      "y": { "scale": { "domainMin": 0, "domainMax": 4 } },
      "color": {
        "scale": { "range": ["#2166ac", "#b2182b"] },
        "legend": { "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,
    "encoding": {
      "y": { "scale": { "domainMin": 0, "domainMax": 4 } },
      "color": {
        "scale": { "range": ["#2166ac", "#b2182b"] },
        "legend": { "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, encoding.y its y scale and encoding.color a color scale on the 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 every individual, 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 SV callset over RHD with the panel's copy-number calls under it.
Open in JBrowse Web ↗

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... → Variant lane (checked)Draws the variants at their genomic positions in a lane above the genotype rows. Offered only while "Layout → 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. Right-click the track at the column to sort on → Sort rows by genotype hereGroups the samples by their genotype at the record under 1:25,300,122, the shortest one there when records overlap. "Reset row order" in the same menu undoes it.
  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 → Advanced → Edit plot...More than two swatches can say, so Edit plot writes the whole color channel.
    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... → 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 → Filter by... → Genes → Only genesGenes counts every gene, transcript and RNA type, the configured transcript and container types, and a top-level CDS; the rest of a GFF, such as NCBI region and match rows, is not a gene.
  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",
          "variants": {
            "show": true
          },
          "forceLoad": true,
          "sortRowsBy": {
            "refName": "1",
            "pos": 25300121
          },
          "height": 290
        },
        {
          "trackId": "cnv_1000g_zarr",
          "type": "LinearWiggleDisplay",
          "mark": "span",
          "origin": 2,
          "encoding": {
            "y": {
              "scale": {
                "domainMin": 0,
                "domainMax": 4
              }
            },
            "color": {
              "scale": {
                "range": [
                  "#2166ac",
                  "#b2182b"
                ]
              },
              "legend": {
                "title": "Copy number"
              }
            }
          },
          "height": 330,
          "runClustering": true,
          "axis": {
            "tree": false
          }
        },
        {
          "trackId": "kgp_sv_records",
          "forceLoad": true,
          "height": 170,
          "encoding": {
            "color": {
              "value": "#4a5568"
            }
          }
        },
        {
          "trackId": "ncbi_refseq_hg38",
          "height": 120,
          "showLabels": "name",
          "filter": [
            "geneLike"
          ]
        }
      ]
    }
  ]
}

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",
          "variants": {
            "show": true
          },
          "forceLoad": true,
          "sortRowsBy": {
            "refName": "1",
            "pos": 25300121
          },
          "height": 290
        },
        {
          "trackId": "cnv_1000g_zarr",
          "type": "LinearWiggleDisplay",
          "mark": "span",
          "origin": 2,
          "encoding": {
            "y": {
              "scale": {
                "domainMin": 0,
                "domainMax": 4
              }
            },
            "color": {
              "scale": {
                "range": [
                  "#2166ac",
                  "#b2182b"
                ]
              },
              "legend": {
                "title": "Copy number"
              }
            }
          },
          "height": 330,
          "runClustering": true,
          "axis": {
            "tree": false
          }
        },
        {
          "trackId": "kgp_sv_records",
          "forceLoad": true,
          "height": 170,
          "encoding": {
            "color": {
              "value": "#4a5568"
            }
          }
        },
        {
          "trackId": "ncbi_refseq_hg38",
          "height": 120,
          "showLabels": "name",
          "filter": [
            "geneLike"
          ]
        }
      ]
    }
  ]
}
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 1240 \
  --timeout 300000 \
  --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.

Right-clicking the deletion sorts the cohort by its genotype there.

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 ↗ ·

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... → Variant lane (checked)Draws the variants at their genomic positions in a lane above the genotype rows. Offered only while "Layout → 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 → Advanced → Edit plot...More than two swatches can say, so Edit plot writes the whole color channel.
    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... → 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 → Filter by... → Genes → Only genesGenes counts every gene, transcript and RNA type, the configured transcript and container types, and a top-level CDS; the rest of a GFF, such as NCBI region and match rows, is not a gene.
  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",
          "variants": {
            "show": true
          },
          "forceLoad": true,
          "height": 290
        },
        {
          "trackId": "cnv_1000g_zarr",
          "type": "LinearWiggleDisplay",
          "mark": "span",
          "origin": 2,
          "encoding": {
            "y": {
              "scale": {
                "domainMin": 0,
                "domainMax": 4
              }
            },
            "color": {
              "scale": {
                "range": [
                  "#2166ac",
                  "#b2182b"
                ]
              },
              "legend": {
                "title": "Copy number"
              }
            }
          },
          "height": 330,
          "runClustering": true,
          "axis": {
            "tree": false
          }
        },
        {
          "trackId": "kgp_sv_records",
          "forceLoad": true,
          "height": 170,
          "encoding": {
            "color": {
              "value": "#4a5568"
            }
          }
        },
        {
          "trackId": "ncbi_refseq_hg38",
          "height": 120,
          "showLabels": "name",
          "filter": [
            "geneLike"
          ]
        }
      ]
    }
  ]
}

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",
          "variants": {
            "show": true
          },
          "forceLoad": true,
          "height": 290
        },
        {
          "trackId": "cnv_1000g_zarr",
          "type": "LinearWiggleDisplay",
          "mark": "span",
          "origin": 2,
          "encoding": {
            "y": {
              "scale": {
                "domainMin": 0,
                "domainMax": 4
              }
            },
            "color": {
              "scale": {
                "range": [
                  "#2166ac",
                  "#b2182b"
                ]
              },
              "legend": {
                "title": "Copy number"
              }
            }
          },
          "height": 330,
          "runClustering": true,
          "axis": {
            "tree": false
          }
        },
        {
          "trackId": "kgp_sv_records",
          "forceLoad": true,
          "height": 170,
          "encoding": {
            "color": {
              "value": "#4a5568"
            }
          }
        },
        {
          "trackId": "ncbi_refseq_hg38",
          "height": 120,
          "showLabels": "name",
          "filter": [
            "geneLike"
          ]
        }
      ]
    }
  ]
}
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... → 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 RHD in samples of each genotype on one shared axis, the RHD span banded.
Open in JBrowse Web ↗

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 → Filter by... → Genes → Only genesGenes counts every gene, transcript and RNA type, the configured transcript and container types, and a top-level CDS; the rest of a GFF, such as NCBI region and match rows, is not a gene.
  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... → Pileup (unchecked)Drops the stacked-read band and keeps the coverage curve, so several samples can be compared on depth alone.
    3. Drag the bottom edge of the coverage band to resize it.
    4. Track menu → Coverage axis... → Share axis withTick the tracks that share this axis, here every one in group "depth".
    5. Track menu → Read connections → Read arcs (unchecked)
  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... → Pileup (unchecked)Drops the stacked-read band and keeps the coverage curve, so several samples can be compared on depth alone.
    3. Drag the bottom edge of the coverage band to resize it.
    4. Track menu → Coverage axis... → Share axis withTick the tracks that share this axis, here every one in group "depth".
    5. Track menu → Read connections → Read arcs (unchecked)
  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... → Pileup (unchecked)Drops the stacked-read band and keeps the coverage curve, so several samples can be compared on depth alone.
    3. Drag the bottom edge of the coverage band to resize it.
    4. Track menu → Coverage axis... → Share axis withTick the tracks that share this axis, here every one in group "depth".
    5. Track menu → Read connections → Read arcs (unchecked)
  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",
          "heightMode": "grow",
          "geneGlyphMode": "longestCoding",
          "showLabels": "name",
          "filter": [
            "geneLike"
          ]
        },
        {
          "trackId": "HG00113.final",
          "forceLoad": true,
          "pileup": {
            "show": false
          },
          "coverage": {
            "height": 190,
            "encoding": {
              "y": {
                "scale": {
                  "group": "depth"
                }
              }
            }
          },
          "readConnections": {
            "show": false
          },
          "height": 200
        },
        {
          "trackId": "HG00096.final",
          "forceLoad": true,
          "pileup": {
            "show": false
          },
          "coverage": {
            "height": 190,
            "encoding": {
              "y": {
                "scale": {
                  "group": "depth"
                }
              }
            }
          },
          "readConnections": {
            "show": false
          },
          "height": 200
        },
        {
          "trackId": "HG00097.final",
          "forceLoad": true,
          "pileup": {
            "show": false
          },
          "coverage": {
            "height": 190,
            "encoding": {
              "y": {
                "scale": {
                  "group": "depth"
                }
              }
            }
          },
          "readConnections": {
            "show": false
          },
          "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/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",
                    "heightMode": "grow",
                    "geneGlyphMode": "longestCoding",
                    "showLabels": "name",
                    "filter": [
                        "geneLike"
                    ]
                },
                {
                    "trackId": "HG00113.final",
                    "forceLoad": True,
                    "pileup": {
                        "show": False
                    },
                    "coverage": {
                        "height": 190,
                        "encoding": {
                            "y": {
                                "scale": {
                                    "group": "depth"
                                }
                            }
                        }
                    },
                    "readConnections": {
                        "show": False
                    },
                    "height": 200
                },
                {
                    "trackId": "HG00096.final",
                    "forceLoad": True,
                    "pileup": {
                        "show": False
                    },
                    "coverage": {
                        "height": 190,
                        "encoding": {
                            "y": {
                                "scale": {
                                    "group": "depth"
                                }
                            }
                        }
                    },
                    "readConnections": {
                        "show": False
                    },
                    "height": 200
                },
                {
                    "trackId": "HG00097.final",
                    "forceLoad": True,
                    "pileup": {
                        "show": False
                    },
                    "coverage": {
                        "height": 190,
                        "encoding": {
                            "y": {
                                "scale": {
                                    "group": "depth"
                                }
                            }
                        }
                    },
                    "readConnections": {
                        "show": False
                    },
                    "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/demos/1000g/config.json \
  --assembly hg38 --loc 1:25,200,000-25,470,000 \
  --view '{"highlight":[{"refName":"1","start":25272393,"end":25330445,"color":"rgba(214,137,16,0.13)"}]}' \
  --track ncbi_refseq_109_hg38 '{"heightMode":"grow","geneGlyphMode":"longestCoding","showLabels":"name","filter":["geneLike"]}' \
  --track HG00113.final '{"forceLoad":true,"pileup":{"show":false},"coverage":{"height":190,"encoding":{"y":{"scale":{"group":"depth"}}}},"readConnections":{"show":false},"height":200}' \
  --track HG00096.final '{"forceLoad":true,"pileup":{"show":false},"coverage":{"height":190,"encoding":{"y":{"scale":{"group":"depth"}}}},"readConnections":{"show":false},"height":200}' \
  --track HG00097.final '{"forceLoad":true,"pileup":{"show":false},"coverage":{"height":190,"encoding":{"y":{"scale":{"group":"depth"}}}},"readConnections":{"show":false},"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": "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",
          "heightMode": "grow",
          "geneGlyphMode": "longestCoding",
          "showLabels": "name",
          "filter": [
            "geneLike"
          ]
        },
        {
          "trackId": "HG00113.final",
          "forceLoad": true,
          "pileup": {
            "show": false
          },
          "coverage": {
            "height": 190,
            "encoding": {
              "y": {
                "scale": {
                  "group": "depth"
                }
              }
            }
          },
          "readConnections": {
            "show": false
          },
          "height": 200
        },
        {
          "trackId": "HG00096.final",
          "forceLoad": true,
          "pileup": {
            "show": false
          },
          "coverage": {
            "height": 190,
            "encoding": {
              "y": {
                "scale": {
                  "group": "depth"
                }
              }
            }
          },
          "readConnections": {
            "show": false
          },
          "height": 200
        },
        {
          "trackId": "HG00097.final",
          "forceLoad": true,
          "pileup": {
            "show": false
          },
          "coverage": {
            "height": 190,
            "encoding": {
              "y": {
                "scale": {
                  "group": "depth"
                }
              }
            }
          },
          "readConnections": {
            "show": false
          },
          "height": 200
        }
      ]
    }
  ]
}
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 map to 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, one band per pair orientation. Reads whose mate is unmapped or elsewhere draw as inter-chromosomal ticks.
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 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 → Advanced → Read connections placement → Below coverage
    3. 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. Drag the bottom edge of the coverage band to resize it.
    5. Track menu → Group by... → Pair orientation
    6. Track menu → Show... → Legend (checked)
  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",
          "pileup": {
            "show": false
          },
          "readConnections": {
            "show": true,
            "placement": "down",
            "ordinaryPairs": {
              "show": false
            },
            "height": 90
          },
          "coverage": {
            "height": 60
          },
          "facet": "pairOrientation",
          "legend": {
            "show": true
          },
          "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",
                    "pileup": {
                        "show": False
                    },
                    "readConnections": {
                        "show": True,
                        "placement": "down",
                        "ordinaryPairs": {
                            "show": False
                        },
                        "height": 90
                    },
                    "coverage": {
                        "height": 60
                    },
                    "facet": "pairOrientation",
                    "legend": {
                        "show": True
                    },
                    "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: a data file opens as the track its name says.

npx @jbrowse/img --config https://jbrowse.org/demos/1000g/config.json \
  --assembly hg38 --loc 1:39,658,200-39,661,800 \
  --view '{"trackLabels":"offset"}' \
  --trackLabels offset \
  --track 1KGP_3202.Illumina_ensemble_callset.freeze_V1.vcf \
  --track HG02768.final '{"pileup":{"show":false},"readConnections":{"show":true,"mark":"link","placement":"down","ordinaryPairs":{"show":false},"height":90},"coverage":{"height":60},"facet":"pairOrientation","legend":{"show":true},"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",
          "pileup": {
            "show": false
          },
          "readConnections": {
            "show": true,
            "placement": "down",
            "ordinaryPairs": {
              "show": false
            },
            "height": 90
          },
          "coverage": {
            "height": 60
          },
          "facet": "pairOrientation",
          "legend": {
            "show": true
          },
          "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. ↩