Supported file types

TL;DR: every track reads data through an adapter whose type selects the reader, and the file's extension is what picks that type. Find your format in the tables below for the adapter that reads it, a config snippet, and a link to its full config docs. Most adapters accept the uri shorthand, and a track over a format listed here can skip both keys — see the whole-track shorthand.

File locations use a { "uri": "..." } object. See Configuring tracks for the common track fields shared by all of these.

The uri shorthand#

Most adapters accept a uri shorthand: give the data file location and the adapter auto-resolves the companion index by appending the standard suffix (.bai for a .bam, .crai for a .cram, .fai for a .fa, .tbi for a tabix .gz, and so on).

{
  "type": "AlignmentsTrack",
  "trackId": "sample_bam",
  "name": "Sample reads",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "BamAdapter",
    "uri": "https://example.com/sample.bam"
  }
}

jbrowse add-track https://example.com/sample.bam \
  --trackId sample_bam \
  --name "Sample reads" \
  --assemblyNames hg38

{
  "type": "AlignmentsTrack",
  "trackId": "sample_bam",
  "name": "Sample reads",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "BamAdapter",
    "uri": "https://example.com/sample.bam"
  }
}

Spell out the full slot form (e.g. bamLocation plus index.location) only when the index is named differently or lives elsewhere. An adapter that takes an endpoint, a set of files, or another adapter generally has no shorthand. Each adapter's config page states which keys it accepts, or that it accepts none, above its slot table.

Use CSI over TBI/BAI for chromosomes longer than 512 Mb (some plant and animal genomes exceed it; CRAM's .crai has no such limit). BAM and the tabix-indexed adapters (VCF, GFF3, BED, BEDGRAPH, MAF, PAF) accept a csi: true shorthand:

{
  "type": "VariantTrack",
  "trackId": "variants_csi",
  "name": "Variants",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://example.com/variants.vcf.gz",
    "csi": true
  }
}

jbrowse add-track-json '{
  "type": "VariantTrack",
  "trackId": "variants_csi",
  "name": "Variants",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://example.com/variants.vcf.gz",
    "csi": true
  }
}'

{
  "type": "VariantTrack",
  "trackId": "variants_csi",
  "name": "Variants",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://example.com/variants.vcf.gz",
    "csi": true
  }
}

Each adapter's autogenerated config page names its own location slots and shows an example of both forms.

The whole-track shorthand#

Every format in the tables below is one JBrowse recognizes by its extension, and that inference runs on a track config too, not only in the "Add track" dialog:

{
  "trackId": "sample_bam",
  "uri": "https://example.com/sample.bam",
  "assemblyNames": ["hg38"]
}

jbrowse add-track-json '{
  "trackId": "sample_bam",
  "uri": "https://example.com/sample.bam",
  "assemblyNames": ["hg38"]
}'

{
  "trackId": "sample_bam",
  "uri": "https://example.com/sample.bam",
  "assemblyNames": ["hg38"]
}

The Track type column below is what the track becomes, the Adapter column is what it reads through, name defaults to the file name, and a config declaring exactly one assembly supplies assemblyNames. Write any of those keys yourself to override the guess: an explicit type picks a track type the extension would not, and an adapter block replaces the guessed one outright.

A format the tables do not list needs the full form, and so does a file whose extension names one format while it holds another. See the shortest track.

Sequence / assembly#

Sequence adapters go in an assembly definition, not a track.

Most configs name no sequence adapter: give the assembly a name and a sequence-file uri, and JBrowse picks the adapter from the extension and derives the index siblings.

{
  "name": "hg38",
  "uri": "https://example.com/genome.fa"
}

jbrowse add-assembly https://example.com/genome.fa \
  --name hg38

https://example.com/genome.fa
https://example.com/genome.fa.fai

See Configuring assemblies for the full assembly setup including refname aliases and cytobands.

Alignments#

Read alignments are shown with an AlignmentsTrack. See Alignments track configuration for coverage/pileup display options.

{
  "type": "AlignmentsTrack",
  "trackId": "my_reads",
  "name": "My reads",
  "assemblyNames": ["hg19"],
  "adapter": {
    "type": "BamAdapter",
    "uri": "https://example.com/sample.bam"
  }
}

jbrowse add-track https://example.com/sample.bam \
  --trackId my_reads \
  --name "My reads" \
  --assemblyNames hg19

{
  "type": "AlignmentsTrack",
  "trackId": "my_reads",
  "name": "My reads",
  "assemblyNames": ["hg19"],
  "adapter": {
    "type": "BamAdapter",
    "uri": "https://example.com/sample.bam"
  }
}

CRAM decodes against the reference sequence; the sequenceAdapter is supplied automatically from the enclosing assembly, as it is for BamAdapter. See the CramAdapter config docs.

Feature / annotation#

Gene models, repeats, and other interval features use a FeatureTrack.

{
  "type": "FeatureTrack",
  "trackId": "genes",
  "name": "Genes",
  "assemblyNames": ["hg19"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "https://example.com/genes.sorted.gff3.gz"
  }
}

jbrowse add-track https://example.com/genes.sorted.gff3.gz \
  --trackId genes \
  --name Genes \
  --assemblyNames hg19

{
  "type": "FeatureTrack",
  "trackId": "genes",
  "name": "Genes",
  "assemblyNames": ["hg19"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "https://example.com/genes.sorted.gff3.gz"
  }
}

Plain (non-tabix) GFF3/GTF/BED adapters load the whole file into memory and are intended for small files. Prefer the tabix or BigBed forms for large datasets.

GTF gene models#

GTF files have no spanning gene line and often no transcript line, so the GTF adapters build the gene model from the per-feature lines: lines sharing a transcript_id are grouped under a transcript (synthesized if absent, per the Cufflinks/StringTie convention), and transcripts sharing a gene_id are grouped into a gene.

The gene's label comes from the aggregateField slot (default gene_name), falling back to the gene_id when the file has no such attribute — so files that carry only a gene_id, like UCSC genePredToGtf or AUGUSTUS output, still get gene models. Point aggregateField at whichever attribute holds your display name:

{
  "type": "FeatureTrack",
  "trackId": "genes_gtf",
  "name": "Genes",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "GtfTabixAdapter",
    "uri": "https://example.com/genes.gtf.gz",
    "aggregateField": "ref_gene_name"
  }
}

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "genes_gtf",
  "name": "Genes",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "GtfTabixAdapter",
    "uri": "https://example.com/genes.gtf.gz",
    "aggregateField": "ref_gene_name"
  }
}'

{
  "type": "FeatureTrack",
  "trackId": "genes_gtf",
  "name": "Genes",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "GtfTabixAdapter",
    "uri": "https://example.com/genes.gtf.gz",
    "aggregateField": "ref_gene_name"
  }
}

Grouping keys on gene_id because gene names are not unique within a reference sequence: a GENCODE chromosome holds hundreds of separate genes named U6 or Y_RNA, and grouping by name merges each set of them into one gene feature spanning the chromosome.

To use the tabix form, sort and index the file first. jbrowse sort-gff works on GTF too (GTF shares GFF's refName/start column layout):

jbrowse sort-gff genes.gtf | bgzip > genes.gtf.gz
tabix -p gff genes.gtf.gz

Quantitative / signal#

Coverage and other numeric signals use a QuantitativeTrack. See Config guide: Quantitative track and Config guide: Multi-quantitative track.

{
  "type": "QuantitativeTrack",
  "trackId": "coverage",
  "name": "Coverage",
  "assemblyNames": ["hg19"],
  "adapter": {
    "type": "BigWigAdapter",
    "uri": "https://example.com/sample.bw"
  }
}

jbrowse add-track https://example.com/sample.bw \
  --trackId coverage \
  --name Coverage \
  --assemblyNames hg19

{
  "type": "QuantitativeTrack",
  "trackId": "coverage",
  "name": "Coverage",
  "assemblyNames": ["hg19"],
  "adapter": {
    "type": "BigWigAdapter",
    "uri": "https://example.com/sample.bw"
  }
}

Variants#

VCF and other variant-like data uses a VariantTrack. See Variant track configuration for SVTYPE coloring and multi-sample displays.

{
  "type": "VariantTrack",
  "trackId": "variants",
  "name": "Variants",
  "assemblyNames": ["hg19"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://example.com/variants.vcf.gz"
  }
}

jbrowse add-track https://example.com/variants.vcf.gz \
  --trackId variants \
  --name Variants \
  --assemblyNames hg19

{
  "type": "VariantTrack",
  "trackId": "variants",
  "name": "Variants",
  "assemblyNames": ["hg19"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://example.com/variants.vcf.gz"
  }
}

Synteny / comparative#

Synteny adapters back dotplot and linear synteny views. See Synteny track config.

For large whole-genome alignments, plain PAF is loaded entirely into memory. Convert it to PIF (Pairwise Indexed Format) first so JBrowse fetches only the alignments overlapping the current viewport, from either assembly's perspective:

jbrowse make-pif alignment.paf   # writes alignment.pif.gz + .tbi

Then load alignment.pif.gz with the PairwiseIndexedPAFAdapter (the add-track CLI picks this automatically). See the PIF format guide and the synteny tutorial for details.

Multiple alignment (MAF)#

Multiple-species alignments use a MafTrack. See MAF track configuration for the conservation band, per-row identity, and codon-view options.

{
  "type": "MafTrack",
  "trackId": "my_maf",
  "name": "My MAF alignment",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "MafTabixAdapter",
    "uri": "https://example.com/alignment.maf.bed.gz",
    "samples": ["hg38", "mm10", "rheMac10"]
  }
}

jbrowse add-track-json '{
  "type": "MafTrack",
  "trackId": "my_maf",
  "name": "My MAF alignment",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "MafTabixAdapter",
    "uri": "https://example.com/alignment.maf.bed.gz",
    "samples": ["hg38", "mm10", "rheMac10"]
  }
}'

{
  "type": "MafTrack",
  "trackId": "my_maf",
  "name": "My MAF alignment",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "MafTabixAdapter",
    "uri": "https://example.com/alignment.maf.bed.gz",
    "samples": ["hg38", "mm10", "rheMac10"]
  }
}

Hi-C#

See Hi-C track configuration. Loop and interaction calls are BEDPE, which loads as a VariantTrack (see the Feature / annotation section above).

GWAS / LD#

See GWAS track configuration.

Text searching#

Text-search adapters power the location search box. See Text searching.

Inline data#

To embed a small dataset directly in config.json without a file, use a FromConfig adapter. See FromConfig adapters.

Computed from the reference#

Three adapters scan the sequence of whatever assembly the track is displayed against and emit the hits as features, so the track config names neither a file nor a sequence:

• MotifListAdapter — a named motif list (restriction enzymes)
• CrisprGuideAdapter — CRISPR guide RNAs
• SequenceSearchAdapter — a single regex

All three are FeatureTracks.

The sequence search guide drives them from the view menu; the cookbook has a whole track config for each.

Full adapter reference#

Each adapter links above to its autogenerated config docs, which list every slot. For the full set of configuration topics, see the Config guide.

See also#

• Configuring tracks
• Configuring assemblies
• Deploying JBrowse Web
• @jbrowse/cli command reference