A map of the human mitochondrial genome

We draw the human mitochondrial genome as a circular map, the way plasmid and organelle genomes are usually pictured, with base-pair ticks around one closed ring and the genes along it in a row per strand, colored by feature type. The same steps make a map of any small circular sequence that NCBI annotates, from a chloroplast to a plasmid. The circular view draws a feature track as a ring and closes a sequence its assembly marks as circular, leaving no gap at its origin.

Prerequisites#

• a JBrowse to open the sessions in (Web or Desktop)
• Node.js, which the JBrowse CLI runs on
• the JBrowse CLI, for jbrowse add-assembly, jbrowse sort-gff and jbrowse add-track
• samtools, for the FASTA index
• htslib (bgzip, tabix), for the GFF3 index

Where the data comes from#

Downloading the sequence and its genes#

We'll start from a GenBank accession, which is all NCBI needs to hand back the sequence and its annotation. Set it once, so the same commands fetch your own organelle or plasmid:

ACC=NC_012920.1

The sequence comes back as FASTA from NCBI's E-utilities:

curl -o genome.fa "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=nuccore&id=$ACC&rettype=fasta"

The annotation comes back as GFF3 from the sequence viewer's export:

curl -o genes.gff3 "https://www.ncbi.nlm.nih.gov/sviewer/viewer.cgi?db=nuccore&report=gff3&id=$ACC"

Two lines of genes.gff3 matter for a circular genome. The ##sequence-region pragma near the top gives the sequence's length, and the D-loop, the control region that spans the origin, is written as one record whose end runs past that length:

grep -e '^##sequence-region' -e 'D_loop' genes.gff3

##sequence-region NC_012920.1 1 16569
NC_012920.1	RefSeq	D_loop	16024	17145	.	-	.	ID=id-NC_012920.1:1..16569;gbkey=D-loop

GFF3 writes a feature that crosses the origin of a circular sequence this way, in coordinates that continue past the end. JBrowse's GFF3 adapters read the length off ##sequence-region and cut such a feature at the origin into a piece before it and a piece after, so keep that line in the file you load.

Loading the genome and the genes#

We'll load the sequence as an assembly, indexed with samtools first:

samtools faidx genome.fa

The assembly is named human_mito, and two of its settings name the sequence NC_012920.1. The add-genome form has a field for neither, so the JSON adds both:

{
  "name": "human_mito",
  "uri": "https://jbrowse.org/code/jb2/main/test_data/human_mito/sequence.fasta.gz",
  "circularRefNames": ["NC_012920.1"],
  "geneticCodes": { "NC_012920.1": 2 }
}

jbrowse add-assembly https://jbrowse.org/code/jb2/main/test_data/human_mito/sequence.fasta.gz \
  --name human_mito \
  --config '{"circularRefNames":["NC_012920.1"],"geneticCodes":{"NC_012920.1":2}}'

• circularRefNames marks the sequence circular, so the circular view closes it into a ring with no gap at its origin.
• geneticCodes translates it with NCBI's vertebrate mitochondrial code, table 2, wherever JBrowse shows a protein.

We'll sort, compress and index the GFF3, keeping the pragma at the top (Quickstart has the general recipe):

jbrowse sort-gff genes.gff3 | bgzip > genes.gff.gz

tabix -p gff genes.gff.gz

In grammar-of-graphics terms, the gene track's facet splits it into a section per strand, and its color is a color scale mapping the GFF3 type field to colors. The name label falls back through the GFF3 attributes, so a record with no gene or product, like the D-loop, takes its gbkey:

{
  "type": "FeatureTrack",
  "trackId": "mito_genes",
  "name": "NCBI genes",
  "assemblyNames": ["human_mito"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "https://jbrowse.org/code/jb2/main/test_data/human_mito/mito.gff.gz"
  },
  "displayDefaults": {
    "labels": {
      "name": "jexl:feature.gene || feature.product || feature.name || feature.gbkey || feature.id"
    },
    "facet": { "field": "strand" },
    "color": { "field": "type" },
    "height": 250
  }
}

jbrowse add-track https://jbrowse.org/code/jb2/main/test_data/human_mito/mito.gff.gz \
  --trackId mito_genes \
  --name "NCBI genes" \
  --assemblyNames human_mito \
  --displayDefaults '{"labels":{"name":"jexl:feature.gene || feature.product || feature.name || feature.gbkey || feature.id"},"facet":{"field":"strand"},"color":{"field":"type"},"height":250}'

{
  "type": "FeatureTrack",
  "trackId": "mito_genes",
  "name": "NCBI genes",
  "assemblyNames": ["human_mito"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "https://jbrowse.org/code/jb2/main/test_data/human_mito/mito.gff.gz"
  },
  "displayDefaults": {
    "labels": {
      "name": "jexl:feature.gene || feature.product || feature.name || feature.gbkey || feature.id"
    },
    "facet": { "field": "strand" },
    "color": { "field": "type" },
    "height": 250
  }
}

Opening the genome as a circle#

We'll open the assembly in a circular view with the gene track. A circular view of one circular sequence closes at position 1, ticks its bases, and prints the sequence's name and length in the middle:

{
  "defaultSession": {
    "name": "Human mitochondrion as a circle",
    "views": [
      {
        "type": "CircularView",
        "assembly": "human_mito",
        "showLegend": true,
        "tracks": ["mito_genes"]
      }
    ]
  }
}

jbrowse set-default-session --session - << 'EOF'
{
  "name": "Human mitochondrion as a circle",
  "views": [
    {
      "type": "CircularView",
      "assembly": "human_mito",
      "showLegend": true,
      "tracks": ["mito_genes"]
    }
  ]
}
EOF

The config sets the track's facet and color, and the track menu offers both too, under the circular view menu's Tracks item:

• Group by... with strand splits the ring into a row per strand
• Color by... → Attribute... with type colors each feature by its GFF3 type

The track's height is how much of the circle it asks for. A ring takes at most half the circle's radius, and a track that asks for more lays its rows and labels out in the band it gets.

✕

Open in JBrowse Web ↗Open in JBrowse Desktop ↗

Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

Copy

https://jbrowse.org/code/jb2/main/?config=test_data%2Fhuman_mito%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22CircularView%22%2C%22assembly%22%3A%22human_mito%22%2C%22height%22%3A780%2C%22showLegend%22%3Atrue%2C%22tracks%22%3A%5B%22mito_genes%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+organelle_map%2Fmito_ring

Or rebuild it from your own data:

Steps

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 human_mito, 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 genes”.
3. Drag the bar at the bottom edge of the view to resize it (780px here).
4. View menu → Show legend (checked)Offered once the view has a track.

Spec

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/human_mito/config.json, which is what the Web button above opens.

Copy

{
  "views": [
    {
      "type": "CircularView",
      "assembly": "human_mito",
      "height": 780,
      "showLegend": true,
      "tracks": [
        "mito_genes"
      ]
    }
  ]
}

Notebook

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

Copy

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/human_mito/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "CircularView",
            "assembly": "human_mito",
            "height": 780,
            "showLegend": True,
            "tracks": [
                "mito_genes"
            ]
        }
    ],
)
app  # display the widget

Image

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

Copy

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "CircularView",
      "assembly": "human_mito",
      "height": 780,
      "showLegend": true,
      "tracks": [
        "mito_genes"
      ]
    }
  ]
}
JSON

npx @jbrowse/img circular --config https://jbrowse.org/code/jb2/main/test_data/human_mito/config.json \
  --spec session.json \
  --width 1000 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Agent

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.

Copy

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "CircularView",
      "assembly": "human_mito",
      "height": 780,
      "showLegend": true,
      "tracks": [
        "mito_genes"
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/human_mito/config.json \
  --width 1000 --height 900 \
  --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 ND6 against the GFF3#

The minus-strand row holds a single protein-coding gene, ND6, which sits between ND5 and CYTB. Type NC_012920.1:12,000-16,569 into a linear view with the same track to see the three side by side:

✕

Open in JBrowse Web ↗Open in JBrowse Desktop ↗

Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

Copy

https://jbrowse.org/code/jb2/main/?config=test_data%2Fhuman_mito%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22human_mito%22%2C%22loc%22%3A%22NC_012920.1%3A12%2C000-16%2C569%22%2C%22tracks%22%3A%5B%22mito_genes%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+organelle_map%2Fnd6_linear

Or rebuild it from your own data:

Steps

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 human_mito, 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 genes”.
3. Type your region of interest into the location box and press Enter.This figure is at NC_012920.1:12,000-16,569.

Spec

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/human_mito/config.json, which is what the Web button above opens.

Copy

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "human_mito",
      "loc": "NC_012920.1:12,000-16,569",
      "tracks": [
        "mito_genes"
      ]
    }
  ]
}

Notebook

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

Copy

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/human_mito/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "human_mito",
            "loc": "NC_012920.1:12,000-16,569",
            "tracks": [
                "mito_genes"
            ]
        }
    ],
)
app  # display the widget

Image

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

Copy

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/human_mito/config.json \
  --assembly human_mito --loc NC_012920.1:12,000-16,569 \
  --track mito_genes \
  --width 1500 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Agent

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.

Copy

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "human_mito",
      "loc": "NC_012920.1:12,000-16,569",
      "tracks": [
        "mito_genes"
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/human_mito/config.json \
  --width 1500 --height 520 \
  --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.

Listing the minus-strand genes from the GFF3's strand column gives ND6 and eight tRNA genes:

awk -F'\t' '$3 == "gene" && $7 == "-"' genes.gff3 | grep -o 'Name=[^;]*'

Anderson et al. (1981) published the sequence with this layout, twelve of the thirteen protein-coding genes on one strand and ND6 on the other.

See also#

• Tutorial: Synteny on a circle (human and mouse)
• Tutorial: Gene density and transposon density along a chromosome
• User guide: Circular genome view
• Docs: JBrowse web quick start

External links#

• NC_012920.1 at NCBI
• GFF3 specification

Citations#

• Anderson et al. (1981). Sequence and organization of the human mitochondrial genome
• Andrews et al. (1999). Reanalysis and revision of the Cambridge reference sequence for human mitochondrial DNA

Feedback on this tutorial is welcome: contact us.