# 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](#the-uri-shorthand), and a track over a format listed here can
skip both keys — see [the whole-track shorthand](#the-whole-track-shorthand).

File locations use a `{ "uri": "..." }` object. See
[Configuring tracks](https://jbrowse.org/jb2/docs/config_guides/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).

```json addtrack
{
  "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:

```json addtrack
{
  "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:

```json addtrack
{
  "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](https://jbrowse.org/jb2/docs/config_guides/tracks#the-shortest-track).

## Sequence / assembly

Sequence adapters go in an [assembly](https://jbrowse.org/jb2/docs/config_guides/assemblies)
definition, not a track.

<!-- FILE_TYPES sequence START -->

<!-- prettier-ignore -->
| Format | Adapter | Track type | Notes |
| --- | --- | --- | --- |
| Bgzipped FASTA (.fa.gz + .fai + .gzi) | [](https://jbrowse.org/jb2/docs/config/bgzipfastaadapter) | assembly `sequence` |  |
| chrom.sizes | [](https://jbrowse.org/jb2/docs/config/chromsizesadapter) | assembly `sequence` | Names and lengths only, no sequence |
| Indexed FASTA (.fa + .fai) | [](https://jbrowse.org/jb2/docs/config/indexedfastaadapter) | assembly `sequence` |  |
| Plain FASTA (.fa, no index) | [](https://jbrowse.org/jb2/docs/config/unindexedfastaadapter) | assembly `sequence` | Read entirely into memory; prefer an indexed form for large genomes |
| UCSC 2bit | [](https://jbrowse.org/jb2/docs/config/twobitadapter) | assembly `sequence` |  |

<!-- FILE_TYPES sequence END -->

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.

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

See [Configuring assemblies](https://jbrowse.org/jb2/docs/config_guides/assemblies) for the full
assembly setup including refname aliases and cytobands.

## Alignments

Read alignments are shown with an `AlignmentsTrack`. See
[Alignments track configuration](https://jbrowse.org/jb2/docs/config_guides/alignments_track) for
coverage/pileup display options.

<!-- FILE_TYPES alignments START -->

<!-- prettier-ignore -->
| Format | Adapter | Track type | Notes |
| --- | --- | --- | --- |
| BAM | [](https://jbrowse.org/jb2/docs/config/bamadapter) | [](https://jbrowse.org/jb2/docs/config/alignmentstrack) |  |
| CRAM | [](https://jbrowse.org/jb2/docs/config/cramadapter) | [](https://jbrowse.org/jb2/docs/config/alignmentstrack) |  |
| Htsget BAM | [](https://jbrowse.org/jb2/docs/config/htsgetbamadapter) | [](https://jbrowse.org/jb2/docs/config/alignmentstrack) | Less exercised than plain BAM/CRAM; prefer an indexed file where possible |
| SAM | [](https://jbrowse.org/jb2/docs/config/samadapter) | [](https://jbrowse.org/jb2/docs/config/alignmentstrack) | Unindexed, so the whole file is loaded into memory; prefer BAM or CRAM for sequencing-scale data |

<!-- FILE_TYPES alignments END -->

```json addtrack
{
  "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](https://jbrowse.org/jb2/docs/config/cramadapter).

## Feature / annotation

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

<!-- FILE_TYPES feature START -->

<!-- prettier-ignore -->
| Format | Adapter | Track type | Notes |
| --- | --- | --- | --- |
| BED (plain) | [](https://jbrowse.org/jb2/docs/config/bedadapter) | [](https://jbrowse.org/jb2/docs/config/featuretrack) | Loaded entirely into memory; for small files |
| BED (tabix) | [](https://jbrowse.org/jb2/docs/config/bedtabixadapter) | [](https://jbrowse.org/jb2/docs/config/featuretrack) |  |
| BigBed | [](https://jbrowse.org/jb2/docs/config/bigbedadapter) | [](https://jbrowse.org/jb2/docs/config/featuretrack) |  |
| GFF3 (plain) | [](https://jbrowse.org/jb2/docs/config/gff3adapter) | [](https://jbrowse.org/jb2/docs/config/featuretrack) | Loaded entirely into memory; for small files |
| GFF3 (tabix) | [](https://jbrowse.org/jb2/docs/config/gff3tabixadapter) | [](https://jbrowse.org/jb2/docs/config/featuretrack) |  |
| GTF (plain) | [](https://jbrowse.org/jb2/docs/config/gtfadapter) | [](https://jbrowse.org/jb2/docs/config/featuretrack) | Loaded entirely into memory; for small files |
| GTF (tabix) | [](https://jbrowse.org/jb2/docs/config/gtftabixadapter) | [](https://jbrowse.org/jb2/docs/config/featuretrack) |  |

<!-- FILE_TYPES feature END -->

```json addtrack
{
  "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`](https://jbrowse.org/jb2/docs/config/gtftabixadapter/#slot-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:

```json addtrack
{
  "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):

```bash
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
[](https://jbrowse.org/jb2/docs/config_guides/quantitative_track) and
[](https://jbrowse.org/jb2/docs/config_guides/multiquantitative_track).

<!-- FILE_TYPES quantitative START -->

<!-- prettier-ignore -->
| Format | Adapter | Track type | Notes |
| --- | --- | --- | --- |
| BedGraph (plain) | [](https://jbrowse.org/jb2/docs/config/bedgraphadapter) | [](https://jbrowse.org/jb2/docs/config/quantitativetrack) | Loaded entirely into memory; for small files |
| BedGraph (tabix) | [](https://jbrowse.org/jb2/docs/config/bedgraphtabixadapter) | [](https://jbrowse.org/jb2/docs/config/quantitativetrack) |  |
| BigWig | [](https://jbrowse.org/jb2/docs/config/bigwigadapter) | [](https://jbrowse.org/jb2/docs/config/quantitativetrack) |  |
| GC content | [](https://jbrowse.org/jb2/docs/config/gccontentadapter) | [](https://jbrowse.org/jb2/docs/config/quantitativetrack) | Computed from the assembly sequence, no data file |
| Multiple BigWigs | [](https://jbrowse.org/jb2/docs/config/multiwiggleadapter) | [](https://jbrowse.org/jb2/docs/config/multiquantitativetrack) |  |

<!-- FILE_TYPES quantitative END -->

```json addtrack
{
  "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](https://jbrowse.org/jb2/docs/config_guides/variant_track) for SVTYPE
coloring and multi-sample displays.

<!-- FILE_TYPES variants START -->

<!-- prettier-ignore -->
| Format | Adapter | Track type | Notes |
| --- | --- | --- | --- |
| BEDPE | [](https://jbrowse.org/jb2/docs/config/bedpeadapter) | [](https://jbrowse.org/jb2/docs/config/varianttrack) | Paired/breakend records, e.g. SV calls or Hi-C loops |
| Split VCF (one file per refName) | [](https://jbrowse.org/jb2/docs/config/splitvcftabixadapter) | [](https://jbrowse.org/jb2/docs/config/varianttrack) |  |
| STAR-Fusion | [](https://jbrowse.org/jb2/docs/config/starfusionadapter) | [](https://jbrowse.org/jb2/docs/config/varianttrack) |  |
| VCF (plain) | [](https://jbrowse.org/jb2/docs/config/vcfadapter) | [](https://jbrowse.org/jb2/docs/config/varianttrack) | Loaded entirely into memory; for small files |
| VCF (tabix) | [](https://jbrowse.org/jb2/docs/config/vcftabixadapter) | [](https://jbrowse.org/jb2/docs/config/varianttrack) |  |

<!-- FILE_TYPES variants END -->

```json addtrack
{
  "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](https://jbrowse.org/jb2/docs/config_guides/synteny_track).

<!-- FILE_TYPES synteny START -->

<!-- prettier-ignore -->
| Format | Adapter | Track type | Notes |
| --- | --- | --- | --- |
| All-vs-all indexed PAF (PIF) | [](https://jbrowse.org/jb2/docs/config/allvsallindexedpafadapter) | [](https://jbrowse.org/jb2/docs/config/syntenytrack) | The tabix-indexed form of all-vs-all PAF |
| All-vs-all PAF | [](https://jbrowse.org/jb2/docs/config/allvsallpafadapter) | [](https://jbrowse.org/jb2/docs/config/syntenytrack) | PanSN-prefixed; one file backs every pair in a multi-way view |
| BLAST tabular | [](https://jbrowse.org/jb2/docs/config/blasttabularadapter) | [](https://jbrowse.org/jb2/docs/config/syntenytrack) |  |
| Chain (UCSC liftOver / lastz) | [](https://jbrowse.org/jb2/docs/config/chainadapter) | [](https://jbrowse.org/jb2/docs/config/syntenytrack) |  |
| Delta (MUMmer / nucmer) | [](https://jbrowse.org/jb2/docs/config/deltaadapter) | [](https://jbrowse.org/jb2/docs/config/syntenytrack) |  |
| Indexed PAF (PIF) | [](https://jbrowse.org/jb2/docs/config/pairwiseindexedpafadapter) | [](https://jbrowse.org/jb2/docs/config/syntenytrack) | Built by `jbrowse make-pif`; fetches only the visible region |
| MashMap | [](https://jbrowse.org/jb2/docs/config/mashmapadapter) | [](https://jbrowse.org/jb2/docs/config/syntenytrack) |  |
| MCScan anchors | [](https://jbrowse.org/jb2/docs/config/mcscananchorsadapter) | [](https://jbrowse.org/jb2/docs/config/syntenytrack) | Gene-level synteny; also needs one BED per assembly |
| MCScan blocks | [](https://jbrowse.org/jb2/docs/config/mcscanblocksadapter) | [](https://jbrowse.org/jb2/docs/config/syntenytrack) | Multi-genome, reference-anchored; also needs one BED per assembly |
| MCScan simple anchors | [](https://jbrowse.org/jb2/docs/config/mcscansimpleanchorsadapter) | [](https://jbrowse.org/jb2/docs/config/syntenytrack) | Gene-level synteny; also needs one BED per assembly |
| PAF | [](https://jbrowse.org/jb2/docs/config/pafadapter) | [](https://jbrowse.org/jb2/docs/config/syntenytrack) | Loaded entirely into memory; convert to PIF for large alignments |

<!-- FILE_TYPES synteny END -->

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:

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

Then load `alignment.pif.gz` with the [](https://jbrowse.org/jb2/docs/config/pairwiseindexedpafadapter)
(the `add-track` CLI picks this automatically). See the
[PIF format guide](https://jbrowse.org/jb2/docs/developer_guides/pif_format) and the
[synteny tutorial](https://jbrowse.org/jb2/docs/tutorials/synteny_visualization) for details.

## Multiple alignment (MAF)

Multiple-species alignments use a `MafTrack`. See
[MAF track configuration](https://jbrowse.org/jb2/docs/config_guides/maf_track) for the conservation
band, per-row identity, and codon-view options.

<!-- FILE_TYPES maf START -->

<!-- prettier-ignore -->
| Format | Adapter | Track type | Notes |
| --- | --- | --- | --- |
| BigMaf | [](https://jbrowse.org/jb2/docs/config/bigmafadapter) | [](https://jbrowse.org/jb2/docs/config/maftrack) |  |
| Indexed MAF (bgzip + .tai) | [](https://jbrowse.org/jb2/docs/config/bgzipmafadapter) | [](https://jbrowse.org/jb2/docs/config/maftrack) | A published whole-genome multiple alignment, read by locus |
| MAF (tabix) | [](https://jbrowse.org/jb2/docs/config/maftabixadapter) | [](https://jbrowse.org/jb2/docs/config/maftrack) |  |
| TAF (bgzipped Taffy) | [](https://jbrowse.org/jb2/docs/config/bgziptaffyadapter) | [](https://jbrowse.org/jb2/docs/config/maftrack) |  |

<!-- FILE_TYPES maf END -->

```json addtrack
{
  "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

<!-- FILE_TYPES hic START -->

<!-- prettier-ignore -->
| Format | Adapter | Track type |
| --- | --- | --- |
| .hic contact matrix | [](https://jbrowse.org/jb2/docs/config/hicadapter) | [](https://jbrowse.org/jb2/docs/config/hictrack) |

<!-- FILE_TYPES hic END -->

See [Hi-C track configuration](https://jbrowse.org/jb2/docs/config_guides/hic_track). Loop and
interaction calls are BEDPE, which loads as a `VariantTrack` (see the
[Feature / annotation](#feature--annotation) section above).

## GWAS / LD

See [GWAS track configuration](https://jbrowse.org/jb2/docs/config_guides/gwas_track).

<!-- FILE_TYPES gwas START -->

<!-- prettier-ignore -->
| Format | Adapter | Track type | Notes |
| --- | --- | --- | --- |
| GWAS results (bgzipped, tabix-indexed BED-like) | [](https://jbrowse.org/jb2/docs/config/gwasadapter) | [](https://jbrowse.org/jb2/docs/config/gwastrack) |  |
| PLINK LD (plain .ld) | [](https://jbrowse.org/jb2/docs/config/plinkldadapter) | [](https://jbrowse.org/jb2/docs/config/ldtrack) | PLINK LD table; for regional analyses |
| PLINK LD (tabix-indexed .ld.gz) | [](https://jbrowse.org/jb2/docs/config/plinkldtabixadapter) | [](https://jbrowse.org/jb2/docs/config/ldtrack) | For chromosome-scale or genome-wide LD |

<!-- FILE_TYPES gwas END -->

## Text searching

Text-search adapters power the location search box. See
[](https://jbrowse.org/jb2/docs/config_guides/text_searching).

<!-- FILE_TYPES textsearch START -->

<!-- prettier-ignore -->
| Format | Adapter | Track type | Notes |
| --- | --- | --- | --- |
| JBrowse 1 names index | [](https://jbrowse.org/jb2/docs/config/jbrowse1textsearchadapter) | `aggregateTextSearchAdapters` / `textSearching` | From JBrowse 1 `generate-names.pl` |
| Trix index (.ix/.ixx) | [](https://jbrowse.org/jb2/docs/config/trixtextsearchadapter) | `aggregateTextSearchAdapters` / `textSearching` | Built by `jbrowse text-index` |

<!-- FILE_TYPES textsearch END -->

## Inline data

To embed a small dataset directly in `config.json` without a file, use a
FromConfig adapter. See [](https://jbrowse.org/jb2/docs/config_guides/from_config).

<!-- FILE_TYPES inline START -->

<!-- prettier-ignore -->
| Format | Adapter | Track type | Notes |
| --- | --- | --- | --- |
| Inline features | [](https://jbrowse.org/jb2/docs/config/fromconfigadapter) | [](https://jbrowse.org/jb2/docs/config/featuretrack) | Features written straight into config.json |
| Inline regions | [](https://jbrowse.org/jb2/docs/config/fromconfigregionsadapter) | assembly `sequence` | refNames and sizes only, no sequence |
| Inline sequence | [](https://jbrowse.org/jb2/docs/config/fromconfigsequenceadapter) | assembly `sequence` | Each feature's `seq` holds the bases for its region |

<!-- FILE_TYPES inline END -->

## 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:

- [](https://jbrowse.org/jb2/docs/config/motiflistadapter) — a named motif list (restriction enzymes)
- [](https://jbrowse.org/jb2/docs/config/crisprguideadapter) — CRISPR guide RNAs
- [](https://jbrowse.org/jb2/docs/config/sequencesearchadapter) — a single regex

All three are [`FeatureTrack`](https://jbrowse.org/jb2/docs/config/featuretrack)s.

The [sequence search guide](https://jbrowse.org/jb2/docs/user_guides/sequence_search) drives them from
the view menu; the [cookbook](https://jbrowse.org/jb2/docs/cookbook#reference-scan) 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 [](https://jbrowse.org/jb2/docs/config_guide).

## See also

- [Configuring tracks](https://jbrowse.org/jb2/docs/config_guides/tracks)
- [Configuring assemblies](https://jbrowse.org/jb2/docs/config_guides/assemblies)
- [](https://jbrowse.org/jb2/docs/config_guides/deploying)
- [`@jbrowse/cli` command reference](https://jbrowse.org/jb2/docs/cli)