Skip to main content

Low-mappability regions (SMN)

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.20. Desktop beta builds for Linux and macOS are on the releases page; the Windows build waits on code signing.

A pileup looks the same whether its reads belong at a locus or merely landed there. Where two copies of a sequence are near-identical, an aligner cannot tell which copy a read came from, so the reads, the coverage and any call made from them are unreliable there. We check a locus for this at the SMN1/SMN2 duplication on chromosome 5. We:

  • load hg38's Umap mappability as a quantitative track drawn at its bin minimum, beside gnomAD coverage, GIAB's problematic regions and long-read SV calls
  • add a public 1000 Genomes CRAM as an alignments track colored by mapping quality
  • open a synteny view of UCSC's hg38-to-T2T-CHM13 liftOver chains over the duplication
  • repeat the check at a locus of your own beside a control window

Prerequisites

  • a JBrowse to open the hosted hg38 config in (Web or Desktop)
  • samtools and bigWigToBedGraph, for the counts at your own locus, and the tools listed under Reproduce it end to end for the script

The data

The hosted tracks are files already wired into the genomes.jbrowse.org hg38 config. The reads come from the 1000 Genomes high-coverage short-read release and its ONT long-read release (Gustafson et al. 2024).

You don't need these files to follow the page: the track configs below read the hosted results. The build script streams them to take its counts. Applying the mappability check to another locus runs the same check on your own locus and reads.

What it isFile
GM18501 ONT long reads aligned to GRCh38, which the script counts; the bucket serves no CORS headers, so it cannot load as a trackGM18501-ONT-hg38-R9-LSK110-guppy-sup-5mC.phased.bam
The same sample aligned to T2T-CHM13GM18501-ONT-chm13-R9-LSK110-guppy-sup-5mC.phased.bam
Read by URL (no download needed)
What it isFile
Umap k100 multi-read mappabilityk100.Umap.MultiTrackMappability.bw
GnomAD v3 mean genome coveragegnomad.coverage.mean.bw
GIAB's low-mappability and segmental-duplication regionsalllowmapandsegdupregions.bb
ENCODE's blacklistencBlacklist.bb
The GRC's exclusion listgrcExclusions.bb
UCSC's problematic-regions commentscomments.bb
The DGV merged CNV cataloguedgvMerged.bb
The 1000 Genomes ONT long-read SV callset1kgOnt.bb
NA12878 at 30x, GRCh38, the read track added to the sessionNA12878.final.cram

SMN1 and SMN2: a near-identical gene duplication

SMN1 and SMN2 sit about 900 kb apart on chromosome 5 and are roughly 99.9% identical across their ~28 kb. Spinal muscular atrophy turns on the copy number of SMN1, so which copy a read came from is the clinical question. An aligner given a 150 bp read from either copy has two equally good places to put it and reports mapping quality 0 (MAPQ 0). MAPQ is -10 log10 Pr{mapping position is wrong} (SAM specification), so MAPQ 0 means the chosen position is about as likely wrong as right.

Mappability, coverage and read tracks across the SMN1 and SMN2 region

Turn these tracks on from the track selector of the hosted hg38 config at genomes.jbrowse.org, or add them with the configs below to any JBrowse that has the hg38 assembly. UCSC publishes the mappability and problematic-region tracks for hg38 only:

  • Multi-read mappability - Umap M100, the fraction of overlapping 100-mers at each position that are unique in the genome, computed from the reference alone. The file omits positions with no unique 100-mer, so the track goes blank there.
    • Resolution → Bin summary → Minimum, with Show min and max unchecked, draws the worst position in each bin
    • Y axis... → Range pins the axis at 0 to 1
    • In the 2.5 Mb frame, at about a kilobase per pixel, even Minimum sits on the floor everywhere, so read this track in the narrower read view
  • gnomAD v3 Genome Coverage - Mean Coverage, averaged over tens of thousands of genomes. gnomAD drops reads that do not place uniquely before averaging, so this track falls wherever the Umap track is blank.
  • GIAB Problematic Regions - LowMap+SegDup, the sequence GIAB leaves out of its benchmark.
  • Long-read SVs - 1KG Vienna ONT SVs, the long-read callset.
  • NCBI RefSeq - RefSeq Curated, the gene track the figures draw.

The Umap config holds the Minimum score mode and the 0 to 1 axis:

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

{
  "type": "QuantitativeTrack",
  "trackId": "hg38-umap100Quantitative",
  "name": "Multi-read mappability - Umap M100",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "BigWigAdapter",
    "uri": "https://hgdownload.soe.ucsc.edu/gbdb/hg38/hoffmanMappability/k100.Umap.MultiTrackMappability.bw"
  },
  "displays": [
    {
      "type": "LinearWiggleDisplay",
      "displayId": "hg38-umap100Quantitative-LinearWiggleDisplay",
      "mark": { "extent": "none" },
      "encoding": {
        "y": {
          "field": "minScore",
          "scale": { "domainMin": 0, "domainMax": 1 }
        }
      }
    }
  ]
}
jbrowse add-track-json '{
  "type": "QuantitativeTrack",
  "trackId": "hg38-umap100Quantitative",
  "name": "Multi-read mappability - Umap M100",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "BigWigAdapter",
    "uri": "https://hgdownload.soe.ucsc.edu/gbdb/hg38/hoffmanMappability/k100.Umap.MultiTrackMappability.bw"
  },
  "displays": [
    {
      "type": "LinearWiggleDisplay",
      "displayId": "hg38-umap100Quantitative-LinearWiggleDisplay",
      "mark": { "extent": "none" },
      "encoding": {
        "y": {
          "field": "minScore",
          "scale": { "domainMin": 0, "domainMax": 1 }
        }
      }
    }
  ]
}'

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": "QuantitativeTrack",
  "trackId": "hg38-umap100Quantitative",
  "name": "Multi-read mappability - Umap M100",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "BigWigAdapter",
    "uri": "https://hgdownload.soe.ucsc.edu/gbdb/hg38/hoffmanMappability/k100.Umap.MultiTrackMappability.bw"
  },
  "displays": [
    {
      "type": "LinearWiggleDisplay",
      "displayId": "hg38-umap100Quantitative-LinearWiggleDisplay",
      "mark": { "extent": "none" },
      "encoding": {
        "y": {
          "field": "minScore",
          "scale": { "domainMin": 0, "domainMax": 1 }
        }
      }
    }
  ]
}

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

{
  "trackId": "hg38-gnomad3MeanCoverage",
  "name": "gnomAD v3 Genome Coverage - Mean Coverage",
  "uri": "https://hgdownload.soe.ucsc.edu/gbdb/hg38/gnomAD/coverage/v3-genome/gnomad.coverage.mean.bw",
  "assemblyNames": ["hg38"]
}
jbrowse add-track https://hgdownload.soe.ucsc.edu/gbdb/hg38/gnomAD/coverage/v3-genome/gnomad.coverage.mean.bw \
  --trackId hg38-gnomad3MeanCoverage \
  --name "gnomAD v3 Genome Coverage - Mean 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://hgdownload.soe.ucsc.edu/gbdb/hg38/gnomAD/coverage/v3-genome/gnomad.coverage.mean.bw

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

  • Track name: gnomAD v3 Genome Coverage - Mean Coverage
  • Assembly: hg38

Click Add.

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

{
  "trackId": "hg38-alllowmapandsegdupregions",
  "name": "GIAB Problematic Regions - LowMap+SegDup",
  "uri": "https://hgdownload.soe.ucsc.edu/gbdb/hg38/problematic/GIAB/alllowmapandsegdupregions.bb",
  "assemblyNames": ["hg38"]
}
jbrowse add-track https://hgdownload.soe.ucsc.edu/gbdb/hg38/problematic/GIAB/alllowmapandsegdupregions.bb \
  --trackId hg38-alllowmapandsegdupregions \
  --name "GIAB Problematic Regions - LowMap+SegDup" \
  --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://hgdownload.soe.ucsc.edu/gbdb/hg38/problematic/GIAB/alllowmapandsegdupregions.bb

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

  • Track name: GIAB Problematic Regions - LowMap+SegDup
  • Assembly: hg38

Click Add.

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

{
  "trackId": "hg38-lrSv1kgOnt",
  "name": "Long-read SVs - 1KG Vienna ONT SVs",
  "uri": "https://hgdownload.soe.ucsc.edu/gbdb/hg38/lrSv/1kgOnt.bb",
  "assemblyNames": ["hg38"]
}
jbrowse add-track https://hgdownload.soe.ucsc.edu/gbdb/hg38/lrSv/1kgOnt.bb \
  --trackId hg38-lrSv1kgOnt \
  --name "Long-read SVs - 1KG Vienna ONT SVs" \
  --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://hgdownload.soe.ucsc.edu/gbdb/hg38/lrSv/1kgOnt.bb

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

  • Track name: Long-read SVs - 1KG Vienna ONT SVs
  • Assembly: hg38

Click Add.

Then add the NA12878 reads. The CRAM needs its .crai beside it and decodes against hg38; for your own sample, swap the uri. In grammar-of-graphics terms, the track's encoding.color is a color scale on the mapq field:

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

{
  "trackId": "na12878_qc_reads",
  "name": "NA12878, 30x Illumina (1000 Genomes)",
  "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram",
  "assemblyNames": ["hg38"],
  "displayDefaults": { "encoding": { "color": "mapq" } }
}
jbrowse add-track https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram \
  --trackId na12878_qc_reads \
  --name "NA12878, 30x Illumina (1000 Genomes)" \
  --assemblyNames hg38 \
  --displayDefaults '{"encoding":{"color":"mapq"}}'

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

{
  "trackId": "na12878_qc_reads",
  "name": "NA12878, 30x Illumina (1000 Genomes)",
  "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram",
  "assemblyNames": ["hg38"],
  "displayDefaults": { "encoding": { "color": "mapq" } }
}

Open this track in JBrowse Web ↗

Open chr5:69,200,000-71,700,000 for the whole region, and a second view at chr5:70,850,000-71,500,000 for the reads.

Top: the SMN region with coverage and difficult-region tracks. Below: reads colored by mapping quality.
Open in JBrowse Web ↗

Or rebuild it from your own data:

Quickest: open the view, then File → Open track... for your files.

From scratch:

  1. Open your genome: Open new genome in JBrowse Desktop, or jbrowse add-assembly for JBrowse Web.This figure uses hg38, loaded from a .2bit genome.
  2. Add your track: File → Open track..., or check it in the track selector. Needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq Curated”.
    1. 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.
    2. Track menu → Gene glyph → Representative transcript
    3. Track menu → Feature height → Compact
  3. Add the next track the same way. Needs a BigWig file (.bw).This figure uses “gnomAD v3 Genome Coverage - Mean Coverage”.
    1. Track menu → Y axis... → RangePins the axis: Min 0 and Max 40. A field left empty follows the data in view.
    2. Track menu → Resolution → Bin summary → Show min and max (unchecked)
  4. Add the next track the same way. Needs a BigBed file (.bb).This figure uses “GIAB Problematic Regions - LowMap+SegDup”.
  5. Add the next track the same way. Needs a BigBed file (.bb).This figure uses “Long-read SVs - 1KG Vienna ONT SVs”.
  6. Go to your region in the location box.This figure is at chr5:69,200,000-71,700,000.
  7. View menu → Zoom to region / use the location box, then add a highlightThis figure highlights 2 regions; highlights can also be set with the &highlight= URL parameter.

Paste into a coding agent, with your goal on the first line.

My goal: [write yours, e.g. this view of my own files, or these track settings in my config.json]

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/ucsc/hg38/config.json
- Tracks:
  - NCBI RefSeq - RefSeq Curated (hg38-ncbiRefSeqCurated), FeatureTrack, a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi), drawn as LinearBasicDisplay
  - gnomAD v3 Genome Coverage - Mean Coverage (hg38-gnomad3MeanCoverage), QuantitativeTrack, a BigWig file (.bw), drawn as LinearWiggleDisplay
  - GIAB Problematic Regions - LowMap+SegDup (hg38-alllowmapandsegdupregions), FeatureTrack, a BigBed file (.bb), drawn as LinearBasicDisplay
  - Long-read SVs - 1KG Vienna ONT SVs (hg38-lrSv1kgOnt), FeatureTrack, a BigBed file (.bb), drawn as LinearBasicDisplay

Docs: https://jbrowse.org/jb2/docs/agents_authoring/ (writing a config), https://jbrowse.org/jb2/docs/agents/ (driving a running JBrowse). Use the jbrowse-authoring, jbrowse-hosted-data and jbrowse-capture skills if you have them. Check any config with `npx @jbrowse/cli validate`, then render it and look: a config that loads is not yet a track that drew.

The session spec that draws the view:
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr5:69,200,000-71,700,000",
      "highlight": [
        {
          "refName": "chr5",
          "start": 70924940,
          "end": 70953012,
          "assemblyName": "hg38"
        },
        {
          "refName": "chr5",
          "start": 70049523,
          "end": 70077595,
          "assemblyName": "hg38"
        }
      ],
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "height": 60,
          "filter": [
            "geneLike"
          ],
          "geneGlyphMode": "representative",
          "displayMode": "compact"
        },
        {
          "trackId": "hg38-gnomad3MeanCoverage",
          "encoding": {
            "y": {
              "scale": {
                "domainMin": 0,
                "domainMax": 40
              }
            }
          },
          "height": 100,
          "mark": {
            "extent": "none"
          }
        },
        {
          "trackId": "hg38-alllowmapandsegdupregions",
          "height": 40
        },
        {
          "trackId": "hg38-lrSv1kgOnt",
          "height": 100
        }
      ]
    }
  ]
}
Redraw the figure headlessly
cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr5:69,200,000-71,700,000",
      "highlight": [
        {
          "refName": "chr5",
          "start": 70924940,
          "end": 70953012,
          "assemblyName": "hg38"
        },
        {
          "refName": "chr5",
          "start": 70049523,
          "end": 70077595,
          "assemblyName": "hg38"
        }
      ],
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "height": 60,
          "filter": [
            "geneLike"
          ],
          "geneGlyphMode": "representative",
          "displayMode": "compact"
        },
        {
          "trackId": "hg38-gnomad3MeanCoverage",
          "encoding": {
            "y": {
              "scale": {
                "domainMin": 0,
                "domainMax": 40
              }
            }
          },
          "height": 100,
          "mark": {
            "extent": "none"
          }
        },
        {
          "trackId": "hg38-alllowmapandsegdupregions",
          "height": 40
        },
        {
          "trackId": "hg38-lrSv1kgOnt",
          "height": 100
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "mappability dip",
    "fontSize": 19,
    "maxWidth": 340,
    "anchor": {
      "trackId": "hg38-gnomad3MeanCoverage",
      "loc": "chr5:70,400,000",
      "fracY": 0.18
    }
  },
  {
    "type": "text",
    "text": "few long-read calls",
    "fontSize": 18,
    "maxWidth": 340,
    "anchor": {
      "trackId": "hg38-lrSv1kgOnt",
      "loc": "chr5:70,300,000",
      "fracY": 0.55
    }
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/ucsc/hg38/config.json \
  --width 1500 --height 622 \
  --spec session.json --annotations callouts.json -o figure.png

More: Using JBrowse with AI agents.

Adds these tracks to your config.json, styled as in the figure. Point each uri at your file (replace YOUR_FILE).

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "hg38-ncbiRefSeqCurated",
  "name": "NCBI RefSeq - RefSeq Curated",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "height": 60,
    "filter": [
      "geneLike"
    ],
    "geneGlyphMode": "representative",
    "displayMode": "compact"
  }
}'

jbrowse add-track-json '{
  "type": "QuantitativeTrack",
  "trackId": "hg38-gnomad3MeanCoverage",
  "name": "gnomAD v3 Genome Coverage - Mean Coverage",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "BigWigAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "encoding": {
      "y": {
        "scale": {
          "domainMin": 0,
          "domainMax": 40
        }
      }
    },
    "height": 100,
    "mark": {
      "extent": "none"
    }
  }
}'

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "hg38-alllowmapandsegdupregions",
  "name": "GIAB Problematic Regions - LowMap+SegDup",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "BigBedAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "height": 40
  }
}'

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "hg38-lrSv1kgOnt",
  "name": "Long-read SVs - 1KG Vienna ONT SVs",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "BigBedAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "height": 100
  }
}'

Run beside config.json, or add --out <dir>. Needs hg38 in the config (jbrowse add-assembly).

This view in a notebook, with jbrowse-anywidget. Swap a track's uri for your file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/ucsc/hg38/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr5:69,200,000-71,700,000",
            "highlight": [
                {
                    "refName": "chr5",
                    "start": 70924940,
                    "end": 70953012,
                    "assemblyName": "hg38"
                },
                {
                    "refName": "chr5",
                    "start": 70049523,
                    "end": 70077595,
                    "assemblyName": "hg38"
                }
            ],
            "tracks": [
                {
                    "trackId": "hg38-ncbiRefSeqCurated",
                    "height": 60,
                    "filter": [
                        "geneLike"
                    ],
                    "geneGlyphMode": "representative",
                    "displayMode": "compact"
                },
                {
                    "trackId": "hg38-gnomad3MeanCoverage",
                    "encoding": {
                        "y": {
                            "scale": {
                                "domainMin": 0,
                                "domainMax": 40
                            }
                        }
                    },
                    "height": 100,
                    "mark": {
                        "extent": "none"
                    }
                },
                {
                    "trackId": "hg38-alllowmapandsegdupregions",
                    "height": 40
                },
                {
                    "trackId": "hg38-lrSv1kgOnt",
                    "height": 100
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.

npx @jbrowse/img --config https://jbrowse.org/ucsc/hg38/config.json \
  --assembly hg38 --loc chr5:69,200,000-71,700,000 \
  --view '{"highlight":[{"refName":"chr5","start":70924940,"end":70953012,"assemblyName":"hg38"},{"refName":"chr5","start":70049523,"end":70077595,"assemblyName":"hg38"}]}' \
  --track hg38-ncbiRefSeqCurated '{"height":60,"filter":["geneLike"],"geneGlyphMode":"representative","displayMode":"compact"}' \
  --track hg38-gnomad3MeanCoverage '{"encoding":{"y":{"scale":{"domainMin":0,"domainMax":40}}},"height":100,"mark":{"extent":"none"}}' \
  --track hg38-alllowmapandsegdupregions '{"height":40}' \
  --track hg38-lrSv1kgOnt '{"height":100}' \
  --width 1500 --out figure.svg

For a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).

The session spec behind the figure, over this config.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr5:69,200,000-71,700,000",
      "highlight": [
        {
          "refName": "chr5",
          "start": 70924940,
          "end": 70953012,
          "assemblyName": "hg38"
        },
        {
          "refName": "chr5",
          "start": 70049523,
          "end": 70077595,
          "assemblyName": "hg38"
        }
      ],
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "height": 60,
          "filter": [
            "geneLike"
          ],
          "geneGlyphMode": "representative",
          "displayMode": "compact"
        },
        {
          "trackId": "hg38-gnomad3MeanCoverage",
          "encoding": {
            "y": {
              "scale": {
                "domainMin": 0,
                "domainMax": 40
              }
            }
          },
          "height": 100,
          "mark": {
            "extent": "none"
          }
        },
        {
          "trackId": "hg38-alllowmapandsegdupregions",
          "height": 40
        },
        {
          "trackId": "hg38-lrSv1kgOnt",
          "height": 100
        }
      ]
    }
  ]
}
Open in JBrowse Web ↗

Large dataset: slow to open.

Or rebuild it from your own data:

Quickest: open the view, then File → Open track... for your files.

From scratch:

  1. Open your genome: Open new genome in JBrowse Desktop, or jbrowse add-assembly for JBrowse Web.This figure uses hg38, loaded from a .2bit genome.
  2. Add your track: File → Open track..., or check it in the track selector. Needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq Curated”.
    1. 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.
    2. Track menu → Gene glyph → Representative transcript
  3. Add the next track the same way. Needs a BigWig file (.bw).This figure uses “Multi-read mappability - Umap M100”.
    1. Track menu → Resolution → Bin summary → Minimum
    2. Track menu → Y axis... → RangePins the axis: Min 0 and Max 1. A field left empty follows the data in view.
    3. Track menu → Resolution → Bin summary → Show min and max (unchecked)
  4. Add the next track the same way. Needs a BigWig file (.bw).This figure uses “gnomAD v3 Genome Coverage - Mean Coverage”.
    1. Track menu → Y axis... → RangePins the axis: Min 0 and Max 40. A field left empty follows the data in view.
    2. Track menu → Resolution → Bin summary → Show min and max (unchecked)
  5. Add the next track the same way. Needs a CRAM file (.cram + .crai).This figure uses “NA12878, 30x Illumina (1000 Genomes)”.
    1. Track menu → Color by → Mapping quality
    2. Track menu → Show → Legend (checked)
    3. 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.
    4. Track menu → Advanced → Coverage axis... → Clip extreme outliers (checked)
  6. Go to your region in the location box.This figure is at chr5:70,850,000-71,500,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.

Paste into a coding agent, with your goal on the first line.

My goal: [write yours, e.g. this view of my own files, or these track settings in my config.json]

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/ucsc/hg38/config.json
- Tracks:
  - NCBI RefSeq - RefSeq Curated (hg38-ncbiRefSeqCurated), FeatureTrack, a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi), drawn as LinearBasicDisplay
  - Multi-read mappability - Umap M100 (hg38-umap100Quantitative), QuantitativeTrack, a BigWig file (.bw), drawn as LinearWiggleDisplay
  - gnomAD v3 Genome Coverage - Mean Coverage (hg38-gnomad3MeanCoverage), QuantitativeTrack, a BigWig file (.bw), drawn as LinearWiggleDisplay
  - NA12878, 30x Illumina (1000 Genomes) (na12878_qc_reads), AlignmentsTrack, a CRAM file (.cram + .crai), drawn as LinearAlignmentsDisplay

Docs: https://jbrowse.org/jb2/docs/agents_authoring/ (writing a config), https://jbrowse.org/jb2/docs/agents/ (driving a running JBrowse). Use the jbrowse-authoring, jbrowse-hosted-data and jbrowse-capture skills if you have them. Check any config with `npx @jbrowse/cli validate`, then render it and look: a config that loads is not yet a track that drew.

The session spec that draws the view:
{
  "sessionTracks": [
    {
      "type": "AlignmentsTrack",
      "trackId": "na12878_qc_reads",
      "name": "NA12878, 30x Illumina (1000 Genomes)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "CramAdapter",
        "cramLocation": {
          "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram"
        },
        "craiLocation": {
          "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram.crai"
        }
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr5:70,850,000-71,500,000",
      "highlight": [
        {
          "refName": "chr5",
          "start": 70924940,
          "end": 70953012,
          "assemblyName": "hg38"
        }
      ],
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "height": 60,
          "filter": [
            "geneLike"
          ],
          "geneGlyphMode": "representative"
        },
        {
          "trackId": "hg38-umap100Quantitative",
          "encoding": {
            "y": {
              "field": "minScore",
              "scale": {
                "domainMin": 0,
                "domainMax": 1
              }
            }
          },
          "mark": {
            "extent": "none"
          },
          "height": 70
        },
        {
          "trackId": "hg38-gnomad3MeanCoverage",
          "encoding": {
            "y": {
              "scale": {
                "domainMin": 0,
                "domainMax": 40
              }
            }
          },
          "height": 90,
          "mark": {
            "extent": "none"
          }
        },
        {
          "trackId": "na12878_qc_reads",
          "encoding": {
            "color": "mapq"
          },
          "legend": {
            "show": true
          },
          "forceLoad": true,
          "coverage": {
            "encoding": {
              "y": {
                "scale": {
                  "fenceQuantile": 0.99
                }
              }
            }
          },
          "height": 260
        }
      ]
    }
  ]
}
Redraw the figure headlessly
cat > session.json <<'JSON'
{
  "sessionTracks": [
    {
      "type": "AlignmentsTrack",
      "trackId": "na12878_qc_reads",
      "name": "NA12878, 30x Illumina (1000 Genomes)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "CramAdapter",
        "cramLocation": {
          "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram"
        },
        "craiLocation": {
          "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram.crai"
        }
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr5:70,850,000-71,500,000",
      "highlight": [
        {
          "refName": "chr5",
          "start": 70924940,
          "end": 70953012,
          "assemblyName": "hg38"
        }
      ],
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "height": 60,
          "filter": [
            "geneLike"
          ],
          "geneGlyphMode": "representative"
        },
        {
          "trackId": "hg38-umap100Quantitative",
          "encoding": {
            "y": {
              "field": "minScore",
              "scale": {
                "domainMin": 0,
                "domainMax": 1
              }
            }
          },
          "mark": {
            "extent": "none"
          },
          "height": 70
        },
        {
          "trackId": "hg38-gnomad3MeanCoverage",
          "encoding": {
            "y": {
              "scale": {
                "domainMin": 0,
                "domainMax": 40
              }
            }
          },
          "height": 90,
          "mark": {
            "extent": "none"
          }
        },
        {
          "trackId": "na12878_qc_reads",
          "encoding": {
            "color": "mapq"
          },
          "legend": {
            "show": true
          },
          "forceLoad": true,
          "coverage": {
            "encoding": {
              "y": {
                "scale": {
                  "fenceQuantile": 0.99
                }
              }
            }
          },
          "height": 260
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "SMN1",
    "fontSize": 18,
    "maxWidth": 330,
    "anchor": {
      "trackId": "hg38-gnomad3MeanCoverage",
      "loc": "chr5:70,925,000",
      "alignX": "left",
      "fracY": 0.15
    }
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/ucsc/hg38/config.json \
  --width 1500 --height 805 \
  --timeout 600000 \
  --spec session.json --annotations callouts.json -o figure.png

More: Using JBrowse with AI agents.

Adds these tracks to your config.json, styled as in the figure. Point each uri at your file (replace YOUR_FILE).

jbrowse add-track-json '{
  "type": "AlignmentsTrack",
  "trackId": "na12878_qc_reads",
  "name": "NA12878, 30x Illumina (1000 Genomes)",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "CramAdapter",
    "cramLocation": {
      "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram"
    },
    "craiLocation": {
      "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram.crai"
    }
  },
  "displayDefaults": {
    "encoding": {
      "color": "mapq"
    },
    "legend": {
      "show": true
    },
    "forceLoad": true,
    "coverage": {
      "encoding": {
        "y": {
          "scale": {
            "fenceQuantile": 0.99
          }
        }
      }
    },
    "height": 260
  }
}'

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "hg38-ncbiRefSeqCurated",
  "name": "NCBI RefSeq - RefSeq Curated",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "height": 60,
    "filter": [
      "geneLike"
    ],
    "geneGlyphMode": "representative"
  }
}'

jbrowse add-track-json '{
  "type": "QuantitativeTrack",
  "trackId": "hg38-umap100Quantitative",
  "name": "Multi-read mappability - Umap M100",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "BigWigAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "encoding": {
      "y": {
        "field": "minScore",
        "scale": {
          "domainMin": 0,
          "domainMax": 1
        }
      }
    },
    "mark": {
      "extent": "none"
    },
    "height": 70
  }
}'

jbrowse add-track-json '{
  "type": "QuantitativeTrack",
  "trackId": "hg38-gnomad3MeanCoverage",
  "name": "gnomAD v3 Genome Coverage - Mean Coverage",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "BigWigAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "encoding": {
      "y": {
        "scale": {
          "domainMin": 0,
          "domainMax": 40
        }
      }
    },
    "height": 90,
    "mark": {
      "extent": "none"
    }
  }
}'

Run beside config.json, or add --out <dir>. Needs hg38 in the config (jbrowse add-assembly).

This view in a notebook, with jbrowse-anywidget. Swap a track's uri for your file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/ucsc/hg38/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []) + [
        {
            "type": "AlignmentsTrack",
            "trackId": "na12878_qc_reads",
            "name": "NA12878, 30x Illumina (1000 Genomes)",
            "assemblyNames": [
                "hg38"
            ],
            "adapter": {
                "type": "CramAdapter",
                "cramLocation": {
                    "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram"
                },
                "craiLocation": {
                    "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram.crai"
                }
            }
        }
    ],
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr5:70,850,000-71,500,000",
            "highlight": [
                {
                    "refName": "chr5",
                    "start": 70924940,
                    "end": 70953012,
                    "assemblyName": "hg38"
                }
            ],
            "tracks": [
                {
                    "trackId": "hg38-ncbiRefSeqCurated",
                    "height": 60,
                    "filter": [
                        "geneLike"
                    ],
                    "geneGlyphMode": "representative"
                },
                {
                    "trackId": "hg38-umap100Quantitative",
                    "encoding": {
                        "y": {
                            "field": "minScore",
                            "scale": {
                                "domainMin": 0,
                                "domainMax": 1
                            }
                        }
                    },
                    "mark": {
                        "extent": "none"
                    },
                    "height": 70
                },
                {
                    "trackId": "hg38-gnomad3MeanCoverage",
                    "encoding": {
                        "y": {
                            "scale": {
                                "domainMin": 0,
                                "domainMax": 40
                            }
                        }
                    },
                    "height": 90,
                    "mark": {
                        "extent": "none"
                    }
                },
                {
                    "trackId": "na12878_qc_reads",
                    "encoding": {
                        "color": "mapq"
                    },
                    "legend": {
                        "show": True
                    },
                    "forceLoad": True,
                    "coverage": {
                        "encoding": {
                            "y": {
                                "scale": {
                                    "fenceQuantile": 0.99
                                }
                            }
                        }
                    },
                    "height": 260
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.

cat > tracks.json <<'JSON'
[
  {
    "type": "AlignmentsTrack",
    "trackId": "na12878_qc_reads",
    "name": "NA12878, 30x Illumina (1000 Genomes)",
    "assemblyNames": [
      "hg38"
    ],
    "adapter": {
      "type": "CramAdapter",
      "cramLocation": {
        "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram"
      },
      "craiLocation": {
        "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram.crai"
      }
    }
  }
]
JSON

npx @jbrowse/img --config https://jbrowse.org/ucsc/hg38/config.json \
  --tracks tracks.json \
  --assembly hg38 --loc chr5:70,850,000-71,500,000 \
  --view '{"highlight":[{"refName":"chr5","start":70924940,"end":70953012,"assemblyName":"hg38"}]}' \
  --track hg38-ncbiRefSeqCurated '{"height":60,"filter":["geneLike"],"geneGlyphMode":"representative"}' \
  --track hg38-umap100Quantitative '{"encoding":{"y":{"field":"minScore","scale":{"domainMin":0,"domainMax":1}}},"mark":{"extent":"none"},"height":70}' \
  --track hg38-gnomad3MeanCoverage '{"encoding":{"y":{"scale":{"domainMin":0,"domainMax":40}}},"height":90,"mark":{"extent":"none"}}' \
  --track na12878_qc_reads '{"encoding":{"color":"mapq"},"legend":{"show":true},"forceLoad":true,"coverage":{"encoding":{"y":{"scale":{"fenceQuantile":0.99}}}},"height":260}' \
  --width 1500 --out figure.svg

For a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).

The session spec behind the figure, over this config.

{
  "sessionTracks": [
    {
      "type": "AlignmentsTrack",
      "trackId": "na12878_qc_reads",
      "name": "NA12878, 30x Illumina (1000 Genomes)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "CramAdapter",
        "cramLocation": {
          "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram"
        },
        "craiLocation": {
          "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram.crai"
        }
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr5:70,850,000-71,500,000",
      "highlight": [
        {
          "refName": "chr5",
          "start": 70924940,
          "end": 70953012,
          "assemblyName": "hg38"
        }
      ],
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "height": 60,
          "filter": [
            "geneLike"
          ],
          "geneGlyphMode": "representative"
        },
        {
          "trackId": "hg38-umap100Quantitative",
          "encoding": {
            "y": {
              "field": "minScore",
              "scale": {
                "domainMin": 0,
                "domainMax": 1
              }
            }
          },
          "mark": {
            "extent": "none"
          },
          "height": 70
        },
        {
          "trackId": "hg38-gnomad3MeanCoverage",
          "encoding": {
            "y": {
              "scale": {
                "domainMin": 0,
                "domainMax": 40
              }
            }
          },
          "height": 90,
          "mark": {
            "extent": "none"
          }
        },
        {
          "trackId": "na12878_qc_reads",
          "encoding": {
            "color": "mapq"
          },
          "legend": {
            "show": true
          },
          "forceLoad": true,
          "coverage": {
            "encoding": {
              "y": {
                "scale": {
                  "fenceQuantile": 0.99
                }
              }
            }
          },
          "height": 260
        }
      ]
    }
  ]
}

GIAB flags two long intervals, much larger than the gene, and the gnomAD track stays low across both. The long-read SV track is empty across them. In the read view, the reads stay at MAPQ 0 until well past the end of SMN1, where the Umap track steps up at the same coordinate as the gnomAD coverage.

Zoom the read view to the SMN cassette, chr5:70,889,000-70,989,000.

The SMN cassette with one read per row, colored by mapping quality.
Open in JBrowse Web ↗

Or rebuild it from your own data:

Quickest: open the view, then File → Open track... for your files.

From scratch:

  1. Open your genome: Open new genome in JBrowse Desktop, or jbrowse add-assembly for JBrowse Web.This figure uses hg38, loaded from a .2bit genome.
  2. Add your track: File → Open track..., or check it in the track selector. Needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq Curated”.
    1. Track menu → Gene glyph → Representative transcript
  3. Add the next track the same way. Needs a BigWig file (.bw).This figure uses “Multi-read mappability - Umap M100”.
    1. Track menu → Resolution → Bin summary → Minimum
    2. Track menu → Y axis... → RangePins the axis: Min 0 and Max 1. A field left empty follows the data in view.
    3. Track menu → Resolution → Bin summary → Show min and max (unchecked)
  4. Add the next track the same way. Needs a BigWig file (.bw).This figure uses “gnomAD v3 Genome Coverage - Mean Coverage”.
    1. Track menu → Y axis... → RangePins the axis: Min 0 and Max 40. A field left empty follows the data in view.
  5. Add the next track the same way. Needs a CRAM file (.cram + .crai).This figure uses “NA12878, 30x Illumina (1000 Genomes)”.
    1. Track menu → Color by → Mapping quality
    2. Track menu → Show → Legend (checked)
    3. Track menu → Read height → Custom... → 2px
    4. 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.
    5. Track menu → Advanced → Coverage axis... → Clip extreme outliers (checked)
  6. Go to your region in the location box.This figure is at chr5:70,889,000-70,989,000.

Paste into a coding agent, with your goal on the first line.

My goal: [write yours, e.g. this view of my own files, or these track settings in my config.json]

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/ucsc/hg38/config.json
- Tracks:
  - NCBI RefSeq - RefSeq Curated (hg38-ncbiRefSeqCurated), FeatureTrack, a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi), drawn as LinearBasicDisplay
  - Multi-read mappability - Umap M100 (hg38-umap100Quantitative), QuantitativeTrack, a BigWig file (.bw), drawn as LinearWiggleDisplay
  - gnomAD v3 Genome Coverage - Mean Coverage (hg38-gnomad3MeanCoverage), QuantitativeTrack, a BigWig file (.bw), drawn as LinearWiggleDisplay
  - NA12878, 30x Illumina (1000 Genomes) (na12878_qc_reads), AlignmentsTrack, a CRAM file (.cram + .crai), drawn as LinearAlignmentsDisplay

Docs: https://jbrowse.org/jb2/docs/agents_authoring/ (writing a config), https://jbrowse.org/jb2/docs/agents/ (driving a running JBrowse). Use the jbrowse-authoring, jbrowse-hosted-data and jbrowse-capture skills if you have them. Check any config with `npx @jbrowse/cli validate`, then render it and look: a config that loads is not yet a track that drew.

The session spec that draws the view:
{
  "sessionTracks": [
    {
      "type": "AlignmentsTrack",
      "trackId": "na12878_qc_reads",
      "name": "NA12878, 30x Illumina (1000 Genomes)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "CramAdapter",
        "cramLocation": {
          "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram"
        },
        "craiLocation": {
          "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram.crai"
        }
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr5:70,889,000-70,989,000",
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "height": 70,
          "geneGlyphMode": "representative"
        },
        {
          "trackId": "hg38-umap100Quantitative",
          "encoding": {
            "y": {
              "field": "minScore",
              "scale": {
                "domainMin": 0,
                "domainMax": 1
              }
            }
          },
          "mark": {
            "extent": "none"
          },
          "height": 70
        },
        {
          "trackId": "hg38-gnomad3MeanCoverage",
          "encoding": {
            "y": {
              "scale": {
                "domainMin": 0,
                "domainMax": 40
              }
            }
          },
          "height": 70
        },
        {
          "trackId": "na12878_qc_reads",
          "encoding": {
            "color": "mapq"
          },
          "legend": {
            "show": true
          },
          "pileup": {
            "mark": {
              "height": 2
            }
          },
          "height": 300,
          "forceLoad": true,
          "coverage": {
            "encoding": {
              "y": {
                "scale": {
                  "fenceQuantile": 0.99
                }
              }
            }
          }
        }
      ]
    }
  ]
}
Redraw the figure headlessly
cat > session.json <<'JSON'
{
  "sessionTracks": [
    {
      "type": "AlignmentsTrack",
      "trackId": "na12878_qc_reads",
      "name": "NA12878, 30x Illumina (1000 Genomes)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "CramAdapter",
        "cramLocation": {
          "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram"
        },
        "craiLocation": {
          "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram.crai"
        }
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr5:70,889,000-70,989,000",
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "height": 70,
          "geneGlyphMode": "representative"
        },
        {
          "trackId": "hg38-umap100Quantitative",
          "encoding": {
            "y": {
              "field": "minScore",
              "scale": {
                "domainMin": 0,
                "domainMax": 1
              }
            }
          },
          "mark": {
            "extent": "none"
          },
          "height": 70
        },
        {
          "trackId": "hg38-gnomad3MeanCoverage",
          "encoding": {
            "y": {
              "scale": {
                "domainMin": 0,
                "domainMax": 40
              }
            }
          },
          "height": 70
        },
        {
          "trackId": "na12878_qc_reads",
          "encoding": {
            "color": "mapq"
          },
          "legend": {
            "show": true
          },
          "pileup": {
            "mark": {
              "height": 2
            }
          },
          "height": 300,
          "forceLoad": true,
          "coverage": {
            "encoding": {
              "y": {
                "scale": {
                  "fenceQuantile": 0.99
                }
              }
            }
          }
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "Dark blue is MAPQ 0: mapped here, but they fit elsewhere just as well",
    "fontSize": 20,
    "maxWidth": 430,
    "anchor": {
      "trackId": "na12878_qc_reads",
      "loc": "chr5:70,895,000",
      "fracY": 0.22
    }
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/ucsc/hg38/config.json \
  --width 1500 --height 844 \
  --spec session.json --annotations callouts.json -o figure.png

More: Using JBrowse with AI agents.

Adds these tracks to your config.json, styled as in the figure. Point each uri at your file (replace YOUR_FILE).

jbrowse add-track-json '{
  "type": "AlignmentsTrack",
  "trackId": "na12878_qc_reads",
  "name": "NA12878, 30x Illumina (1000 Genomes)",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "CramAdapter",
    "cramLocation": {
      "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram"
    },
    "craiLocation": {
      "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram.crai"
    }
  },
  "displayDefaults": {
    "encoding": {
      "color": "mapq"
    },
    "legend": {
      "show": true
    },
    "pileup": {
      "mark": {
        "height": 2
      }
    },
    "height": 300,
    "forceLoad": true,
    "coverage": {
      "encoding": {
        "y": {
          "scale": {
            "fenceQuantile": 0.99
          }
        }
      }
    }
  }
}'

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "hg38-ncbiRefSeqCurated",
  "name": "NCBI RefSeq - RefSeq Curated",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "height": 70,
    "geneGlyphMode": "representative"
  }
}'

jbrowse add-track-json '{
  "type": "QuantitativeTrack",
  "trackId": "hg38-umap100Quantitative",
  "name": "Multi-read mappability - Umap M100",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "BigWigAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "encoding": {
      "y": {
        "field": "minScore",
        "scale": {
          "domainMin": 0,
          "domainMax": 1
        }
      }
    },
    "mark": {
      "extent": "none"
    },
    "height": 70
  }
}'

jbrowse add-track-json '{
  "type": "QuantitativeTrack",
  "trackId": "hg38-gnomad3MeanCoverage",
  "name": "gnomAD v3 Genome Coverage - Mean Coverage",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "BigWigAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "encoding": {
      "y": {
        "scale": {
          "domainMin": 0,
          "domainMax": 40
        }
      }
    },
    "height": 70
  }
}'

Run beside config.json, or add --out <dir>. Needs hg38 in the config (jbrowse add-assembly).

This view in a notebook, with jbrowse-anywidget. Swap a track's uri for your file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/ucsc/hg38/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []) + [
        {
            "type": "AlignmentsTrack",
            "trackId": "na12878_qc_reads",
            "name": "NA12878, 30x Illumina (1000 Genomes)",
            "assemblyNames": [
                "hg38"
            ],
            "adapter": {
                "type": "CramAdapter",
                "cramLocation": {
                    "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram"
                },
                "craiLocation": {
                    "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram.crai"
                }
            }
        }
    ],
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr5:70,889,000-70,989,000",
            "tracks": [
                {
                    "trackId": "hg38-ncbiRefSeqCurated",
                    "height": 70,
                    "geneGlyphMode": "representative"
                },
                {
                    "trackId": "hg38-umap100Quantitative",
                    "encoding": {
                        "y": {
                            "field": "minScore",
                            "scale": {
                                "domainMin": 0,
                                "domainMax": 1
                            }
                        }
                    },
                    "mark": {
                        "extent": "none"
                    },
                    "height": 70
                },
                {
                    "trackId": "hg38-gnomad3MeanCoverage",
                    "encoding": {
                        "y": {
                            "scale": {
                                "domainMin": 0,
                                "domainMax": 40
                            }
                        }
                    },
                    "height": 70
                },
                {
                    "trackId": "na12878_qc_reads",
                    "encoding": {
                        "color": "mapq"
                    },
                    "legend": {
                        "show": True
                    },
                    "pileup": {
                        "mark": {
                            "height": 2
                        }
                    },
                    "height": 300,
                    "forceLoad": True,
                    "coverage": {
                        "encoding": {
                            "y": {
                                "scale": {
                                    "fenceQuantile": 0.99
                                }
                            }
                        }
                    }
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.

cat > tracks.json <<'JSON'
[
  {
    "type": "AlignmentsTrack",
    "trackId": "na12878_qc_reads",
    "name": "NA12878, 30x Illumina (1000 Genomes)",
    "assemblyNames": [
      "hg38"
    ],
    "adapter": {
      "type": "CramAdapter",
      "cramLocation": {
        "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram"
      },
      "craiLocation": {
        "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram.crai"
      }
    }
  }
]
JSON

npx @jbrowse/img --config https://jbrowse.org/ucsc/hg38/config.json \
  --tracks tracks.json \
  --assembly hg38 --loc chr5:70,889,000-70,989,000 \
  --track hg38-ncbiRefSeqCurated '{"height":70,"geneGlyphMode":"representative"}' \
  --track hg38-umap100Quantitative '{"encoding":{"y":{"field":"minScore","scale":{"domainMin":0,"domainMax":1}}},"mark":{"extent":"none"},"height":70}' \
  --track hg38-gnomad3MeanCoverage '{"encoding":{"y":{"scale":{"domainMin":0,"domainMax":40}}},"height":70}' \
  --track na12878_qc_reads '{"encoding":{"color":"mapq"},"legend":{"show":true},"pileup":{"mark":{"height":2}},"height":300,"forceLoad":true,"coverage":{"encoding":{"y":{"scale":{"fenceQuantile":0.99}}}}}' \
  --width 1500 --out figure.svg

For a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).

The session spec behind the figure, over this config.

{
  "sessionTracks": [
    {
      "type": "AlignmentsTrack",
      "trackId": "na12878_qc_reads",
      "name": "NA12878, 30x Illumina (1000 Genomes)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "CramAdapter",
        "cramLocation": {
          "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram"
        },
        "craiLocation": {
          "uri": "https://s3.amazonaws.com/1000genomes/1000G_2504_high_coverage/data/ERR3239334/NA12878.final.cram.crai"
        }
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr5:70,889,000-70,989,000",
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "height": 70,
          "geneGlyphMode": "representative"
        },
        {
          "trackId": "hg38-umap100Quantitative",
          "encoding": {
            "y": {
              "field": "minScore",
              "scale": {
                "domainMin": 0,
                "domainMax": 1
              }
            }
          },
          "mark": {
            "extent": "none"
          },
          "height": 70
        },
        {
          "trackId": "hg38-gnomad3MeanCoverage",
          "encoding": {
            "y": {
              "scale": {
                "domainMin": 0,
                "domainMax": 40
              }
            }
          },
          "height": 70
        },
        {
          "trackId": "na12878_qc_reads",
          "encoding": {
            "color": "mapq"
          },
          "legend": {
            "show": true
          },
          "pileup": {
            "mark": {
              "height": 2
            }
          },
          "height": 300,
          "forceLoad": true,
          "coverage": {
            "encoding": {
              "y": {
                "scale": {
                  "fenceQuantile": 0.99
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Dark blue is MAPQ 0; yellow is MAPQ 30 and above. Advanced → Edit plot... on the reads track shows this encoding.color as text and applies edits live.

Does T2T-CHM13 resolve the SMN duplication?

T2T-CHM13, the telomere-to-telomere assembly, is finished on this chromosome. UCSC's hg38-to-CHM13 liftOver forms several long, overlapping chains over the region, some of them reversed:

tabix https://jbrowse.org/ucsc/hg38/liftOver/hg38ToHs1.over.pif.gz \
  tchr5:69200000-71700000

A synteny view between the two assemblies draws each chain as a ribbon. The hosted hg38 config has the track and loads hs1 with it. On another JBrowse, load the hs1 assembly and the chain file, whose query is the genome it lifts to:

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

{
  "name": "hs1",
  "uri": "https://hgdownload.soe.ucsc.edu/goldenPath/hs1/bigZips/hs1.2bit"
}
jbrowse add-assembly https://hgdownload.soe.ucsc.edu/goldenPath/hs1/bigZips/hs1.2bit \
  --name hs1

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

https://hgdownload.soe.ucsc.edu/goldenPath/hs1/bigZips/hs1.2bit

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

  • Genome name: hs1

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

{
  "type": "SyntenyTrack",
  "trackId": "hg38_to_hs1_liftOver",
  "name": "hg38 to Human (hs1) liftOver",
  "assemblyNames": ["hs1", "hg38"],
  "adapter": {
    "type": "PairwiseIndexedPAFAdapter",
    "uri": "https://jbrowse.org/ucsc/hg38/liftOver/hg38ToHs1.over.pif.gz",
    "csi": true,
    "queryAssembly": "hs1",
    "targetAssembly": "hg38"
  }
}
jbrowse add-track-json '{
  "type": "SyntenyTrack",
  "trackId": "hg38_to_hs1_liftOver",
  "name": "hg38 to Human (hs1) liftOver",
  "assemblyNames": ["hs1", "hg38"],
  "adapter": {
    "type": "PairwiseIndexedPAFAdapter",
    "uri": "https://jbrowse.org/ucsc/hg38/liftOver/hg38ToHs1.over.pif.gz",
    "csi": true,
    "queryAssembly": "hs1",
    "targetAssembly": "hg38"
  }
}'

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": "SyntenyTrack",
  "trackId": "hg38_to_hs1_liftOver",
  "name": "hg38 to Human (hs1) liftOver",
  "assemblyNames": ["hs1", "hg38"],
  "adapter": {
    "type": "PairwiseIndexedPAFAdapter",
    "uri": "https://jbrowse.org/ucsc/hg38/liftOver/hg38ToHs1.over.pif.gz",
    "csi": true,
    "queryAssembly": "hs1",
    "targetAssembly": "hg38"
  }
}

That shows it in the linear view. For the synteny view, open Add → Linear synteny view, pick the track under Quick start, and click Launch.

GRCh38 above T2T-CHM13, each on its SMN2-to-SMN1 span, ribbons from UCSC's liftOver chains colored by strand.
Open in JBrowse Web ↗

Large dataset: slow to open.

Or rebuild it from your own data:

Quickest: open the view, then File → Open track... for your files.

From scratch:

  1. Open your genomes: Open new genome in JBrowse Desktop, then File → Open genome... for each of the rest, or jbrowse add-assembly for each in JBrowse Web.This figure's rows, top to bottom: hg38, hs1.
  2. Open the view: Add → Linear synteny view, and set the rows to those assemblies in the import form.
  3. Add your file: click the arrow between two rows and choose New track. Needs a bgzip-indexed PAF (.pif.gz + .tbi).Or pick a synteny track you already have under Quick start, which fills in the rows.This figure uses “hg38 vs T2T-CHM13 (UCSC liftOver)”.
  4. Click Launch.
  5. Synteny view header → palette button → StrandThe palette button's tooltip reads "Color by: ...".
  6. Synteny display settings (the sliders button in the view header) → Opacity → drag to 0.5Lower values let dense overlapping ribbons show through each other.
  7. Synteny display settings (the sliders button in the view header) → Curved lines (checked)
  8. Synteny display settings (the sliders button in the view header) → CIGAR indels → Transparent indelsThe row appears only when the alignments actually carry CIGAR ops — a coarse-tier PIF or a CIGAR-less PAF has none to draw.
  9. Synteny display settings (the sliders button in the view header) → Min length → drag to 10,000bpHides alignments shorter than this, which is what clears the hairball of short spurious chains at whole-genome zoom.
  10. Drag the bar below a synteny level to resize it.This figure's level is 300px tall.
  11. Row 1 (hg38)
    1. Add your track: + → Add track in this view's track selector, or check it there. Needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes”.
      1. 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.
      2. Track menu → Gene glyph → Representative transcript
      3. Track menu → Feature height → Track sizing → Fixed feature height + fixed track height
    2. Go to your region in the location box.This figure is at chr5:69,450,000-71,550,000.
    3. View menu → Show → Offset
  12. Row 2 (hs1)
    1. Add the next track the same way. Needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes”.
      1. 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.
      2. Track menu → Gene glyph → Representative transcript
      3. Track menu → Show → Descriptions (unchecked)
      4. Track menu → Feature height → Track sizing → Fixed feature height + fixed track height
    2. Go to your region in the location box.This figure is at chr5:70,210,000-71,980,000.
    3. View menu → Show → Offset

Paste into a coding agent, with your goal on the first line.

My goal: [write yours, e.g. this view of my own files, or these track settings in my config.json]

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/code/jb2/main/test_data/hg38_hs1_synteny/config.json
- Tracks:
  - hg38 vs T2T-CHM13 (UCSC liftOver) (hg38_hs1_synteny), SyntenyTrack, a bgzip-indexed PAF (.pif.gz + .tbi), drawn as LinearSyntenyDisplay
  - NCBI RefSeq genes (hg38-genes), FeatureTrack, a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi), drawn as LinearBasicDisplay
  - NCBI RefSeq genes (hs1-genes), FeatureTrack, a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi), drawn as LinearBasicDisplay

Docs: https://jbrowse.org/jb2/docs/agents_authoring/ (writing a config), https://jbrowse.org/jb2/docs/agents/ (driving a running JBrowse). Use the jbrowse-authoring, jbrowse-hosted-data and jbrowse-capture skills if you have them. Check any config with `npx @jbrowse/cli validate`, then render it and look: a config that loads is not yet a track that drew.

The session spec that draws the view:
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "encoding": {
        "color": "strand",
        "opacity": 0.5
      },
      "mark": {
        "interpolate": "bump"
      },
      "indels": {
        "encoding": {
          "opacity": 0
        }
      },
      "filter": [
        {
          "field": "length",
          "gte": 10000
        }
      ],
      "levelHeights": [
        300
      ],
      "tracks": [
        [
          "hg38_hs1_synteny"
        ]
      ],
      "views": [
        {
          "assembly": "hg38",
          "loc": "chr5:69,450,000-71,550,000",
          "tracks": [
            {
              "trackId": "hg38-genes",
              "filter": [
                "geneLike"
              ],
              "geneGlyphMode": "representative",
              "heightMode": "fixed",
              "height": 120
            }
          ],
          "trackLabels": "offset"
        },
        {
          "assembly": "hs1",
          "loc": "chr5:70,210,000-71,980,000",
          "tracks": [
            {
              "trackId": "hs1-genes",
              "filter": [
                "geneLike"
              ],
              "geneGlyphMode": "representative",
              "labels": {
                "description": {
                  "show": false
                }
              },
              "heightMode": "fixed",
              "height": 200
            }
          ],
          "trackLabels": "offset"
        }
      ]
    }
  ]
}
Redraw the figure headlessly
cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "encoding": {
        "color": "strand",
        "opacity": 0.5
      },
      "mark": {
        "interpolate": "bump"
      },
      "indels": {
        "encoding": {
          "opacity": 0
        }
      },
      "filter": [
        {
          "field": "length",
          "gte": 10000
        }
      ],
      "levelHeights": [
        300
      ],
      "tracks": [
        [
          "hg38_hs1_synteny"
        ]
      ],
      "views": [
        {
          "assembly": "hg38",
          "loc": "chr5:69,450,000-71,550,000",
          "tracks": [
            {
              "trackId": "hg38-genes",
              "filter": [
                "geneLike"
              ],
              "geneGlyphMode": "representative",
              "heightMode": "fixed",
              "height": 120
            }
          ],
          "trackLabels": "offset"
        },
        {
          "assembly": "hs1",
          "loc": "chr5:70,210,000-71,980,000",
          "tracks": [
            {
              "trackId": "hs1-genes",
              "filter": [
                "geneLike"
              ],
              "geneGlyphMode": "representative",
              "labels": {
                "description": {
                  "show": false
                }
              },
              "heightMode": "fixed",
              "height": 200
            }
          ],
          "trackLabels": "offset"
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "fontSize": 20,
    "maxWidth": 420,
    "anchor": {
      "selector": "[data-testid=\"synteny_canvas\"][data-display-drawn=\"true\"]",
      "alignX": "left",
      "alignY": "top",
      "dx": 24,
      "dy": 30
    },
    "text": "The same GRCh38 sequence chains to more than one place in T2T"
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/hg38_hs1_synteny/config.json \
  --width 1200 --height 900 \
  --timeout 180000 \
  --spec session.json --annotations callouts.json -o figure.png

More: Using JBrowse with AI agents.

Adds these tracks to your config.json, styled as in the figure. Point each uri at your file (replace YOUR_FILE).

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "hg38-genes",
  "name": "NCBI RefSeq genes",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "filter": [
      "geneLike"
    ],
    "geneGlyphMode": "representative",
    "heightMode": "fixed",
    "height": 120
  }
}'

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "hs1-genes",
  "name": "NCBI RefSeq genes",
  "assemblyNames": [
    "hs1"
  ],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "filter": [
      "geneLike"
    ],
    "geneGlyphMode": "representative",
    "labels": {
      "description": {
        "show": false
      }
    },
    "heightMode": "fixed",
    "height": 200
  }
}'

Run beside config.json, or add --out <dir>. Needs hg38, hs1 in the config (jbrowse add-assembly).

This view in a notebook, with jbrowse-anywidget. Swap a track's uri for your file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/hg38_hs1_synteny/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearSyntenyView",
            "encoding": {
                "color": "strand",
                "opacity": 0.5
            },
            "mark": {
                "interpolate": "bump"
            },
            "indels": {
                "encoding": {
                    "opacity": 0
                }
            },
            "filter": [
                {
                    "field": "length",
                    "gte": 10000
                }
            ],
            "levelHeights": [
                300
            ],
            "tracks": [
                [
                    "hg38_hs1_synteny"
                ]
            ],
            "views": [
                {
                    "assembly": "hg38",
                    "loc": "chr5:69,450,000-71,550,000",
                    "tracks": [
                        {
                            "trackId": "hg38-genes",
                            "filter": [
                                "geneLike"
                            ],
                            "geneGlyphMode": "representative",
                            "heightMode": "fixed",
                            "height": 120
                        }
                    ],
                    "trackLabels": "offset"
                },
                {
                    "assembly": "hs1",
                    "loc": "chr5:70,210,000-71,980,000",
                    "tracks": [
                        {
                            "trackId": "hs1-genes",
                            "filter": [
                                "geneLike"
                            ],
                            "geneGlyphMode": "representative",
                            "labels": {
                                "description": {
                                    "show": False
                                }
                            },
                            "heightMode": "fixed",
                            "height": 200
                        }
                    ],
                    "trackLabels": "offset"
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "encoding": {
        "color": "strand",
        "opacity": 0.5
      },
      "mark": {
        "interpolate": "bump"
      },
      "indels": {
        "encoding": {
          "opacity": 0
        }
      },
      "filter": [
        {
          "field": "length",
          "gte": 10000
        }
      ],
      "levelHeights": [
        300
      ],
      "tracks": [
        [
          "hg38_hs1_synteny"
        ]
      ],
      "views": [
        {
          "assembly": "hg38",
          "loc": "chr5:69,450,000-71,550,000",
          "tracks": [
            {
              "trackId": "hg38-genes",
              "filter": [
                "geneLike"
              ],
              "geneGlyphMode": "representative",
              "heightMode": "fixed",
              "height": 120
            }
          ],
          "trackLabels": "offset"
        },
        {
          "assembly": "hs1",
          "loc": "chr5:70,210,000-71,980,000",
          "tracks": [
            {
              "trackId": "hs1-genes",
              "filter": [
                "geneLike"
              ],
              "geneGlyphMode": "representative",
              "labels": {
                "description": {
                  "show": false
                }
              },
              "heightMode": "fixed",
              "height": 200
            }
          ],
          "trackLabels": "offset"
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/img synteny --config https://jbrowse.org/code/jb2/main/test_data/hg38_hs1_synteny/config.json \
  --spec session.json \
  --width 1200 --out figure.svg

For a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).

The session spec behind the figure, over this config.

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "encoding": {
        "color": "strand",
        "opacity": 0.5
      },
      "mark": {
        "interpolate": "bump"
      },
      "indels": {
        "encoding": {
          "opacity": 0
        }
      },
      "filter": [
        {
          "field": "length",
          "gte": 10000
        }
      ],
      "levelHeights": [
        300
      ],
      "tracks": [
        [
          "hg38_hs1_synteny"
        ]
      ],
      "views": [
        {
          "assembly": "hg38",
          "loc": "chr5:69,450,000-71,550,000",
          "tracks": [
            {
              "trackId": "hg38-genes",
              "filter": [
                "geneLike"
              ],
              "geneGlyphMode": "representative",
              "heightMode": "fixed",
              "height": 120
            }
          ],
          "trackLabels": "offset"
        },
        {
          "assembly": "hs1",
          "loc": "chr5:70,210,000-71,980,000",
          "tracks": [
            {
              "trackId": "hs1-genes",
              "filter": [
                "geneLike"
              ],
              "geneGlyphMode": "representative",
              "labels": {
                "description": {
                  "show": false
                }
              },
              "heightMode": "fixed",
              "height": 200
            }
          ],
          "trackLabels": "offset"
        }
      ]
    }
  ]
}

The gene order is the same in both assemblies, SMN2 first and then SMN1. The crossing chains join each GRCh38 copy to both CHM13 copies, so CHM13 has the same duplication, with the two genes closer together, and a read from either copy still has two places to go.

Applying the mappability check to another locus

The same check runs on any hg38 locus and your own reads, read against a control window: depth alone can look the same at a duplicated locus and an ordinary one, and the share of reads at MAPQ 0 separates them.

  • Turn on the four tracks above, with the same Umap settings
  • Add your reads with the uri in the read track config swapped for your BAM or CRAM, colored by mapping quality
  • Open a second window of the same width, from the same sample and outside every flagged interval, beside the first

In numbers, the comparison is three samtools counts per window, with -q a minimum MAPQ:

samtools view -c "$CRAM" chr5:70,900,000-71,000,000            # every read
samtools view -c -q 1 "$CRAM" chr5:70,900,000-71,000,000       # placed at all
samtools view -c -q 60 "$CRAM" chr5:70,900,000-71,000,000      # placed uniquely

The Umap track's value over a window is one command over the same bigWig:

# positions with no unique 100-mer are absent from the file, so the share of
# the span that has any value is the number to read
bigWigToBedGraph -chrom=chr5 -start=70049000 -end=70077000 \
  k100.Umap.MultiTrackMappability.bw stdout |
  awk -v s=70049000 -v e=70077000 \
    '{cov += $3 - $2} END {printf "%.1f%% has a value\n", 100 * cov / (e - s)}'

Run both on the control window too, at the same width.

Reproduce it end to end

scan_mappability_qc.sh measures the SMN region from the files the figures draw. It asks whether a read can be placed at a locus several ways, and reads each answer against a control:

  1. Over SMN1, SMN2 and two controls, it measures how much of each window the Umap track has a value for, gnomAD's mean depth, and the share of NA12878's reads at MAPQ 0. The near control is a window of the same width at the 5' end of BDP1, past both flagged intervals on the same chromosome, so sample, library and chromosome all match; ACTB on chromosome 7 shows the near control is ordinary.
  2. It lists which problematic-region tracks flag the region, and bins the gnomAD track across it to find where the depth recovers.
  3. It counts GM18501's long-read records over SMN1 at MAPQ 0 and MAPQ 60, once on each reference. The release aligned that sample to both with the same pipeline, so the two counts compare.
  4. It counts each SV catalogue's calls inside the region and in a flank of about the same width on either side, and across chr5 the share of calls whose midpoint falls in a flagged region.

The script needs kent tools (bigWigInfo, bigWigToBedGraph, bigBedToBed), bedtools, samtools, curl and awk.

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/scan_mappability_qc.sh
bash scan_mappability_qc.sh

The script measures a locus added to its LOCI list the same way.

See also

Citations