Skip to main content

Connections

A connection makes an external hub's tracks available in the track selector without configuring each track by hand. Admin-defined connections go in the top-level connections array; connections a user adds at runtime live in their session. The config format is below; the Connections user guide covers in-app behavior.

Connection config format

Every connection carries the BaseConnection slots (type, connectionId, name, and an optional assemblyNames that matches hub tracks to your configured assemblies), plus one location slot per type. jbrowse add-connection writes one from the command line (CLI reference).

UCSC track hub

Points at a hub's hub.txt (UCSCTrackHubConnection):

{
  "type": "UCSCTrackHubConnection",
  "connectionId": "ucsc_example",
  "name": "UCSC example hub",
  "hubTxtLocation": {
    "uri": "https://example.com/hub.txt"
  }
}

JB2 track hub

Points at another JBrowse 2 config.json, whose tracks array becomes the connection's track list (JB2TrackHubConnection):

{
  "type": "JB2TrackHubConnection",
  "connectionId": "jb2_example",
  "name": "JB2 example hub",
  "configJsonLocation": {
    "uri": "https://example.com/config.json"
  }
}

JBrowse 1 data directory

Points at a JBrowse 1 data directory holding trackList.json and tracks.conf, either of which may be absent, and translates its tracks on connect. A JBrowse 1 connection serves one assembly, so assemblyNames is required and holds a single entry (JBrowse1Connection):

{
  "type": "JBrowse1Connection",
  "connectionId": "jb1_example",
  "name": "JBrowse 1 data",
  "assemblyNames": ["hg19"],
  "dataDirLocation": {
    "uri": "https://example.com/jbrowse1/data/"
  }
}

Migrating a JBrowse 1 instance

This gist converts a directory once: it reads trackList.json and tracks.conf, follows their includes, and writes the tracks into a JBrowse 2 config.json using the same table as jb1ToJb2.ts. An unrecognized storeClass is matched on the filename, and a format with no JBrowse 2 equivalent leaves a placeholder track naming it. Check the result with jbrowse validate config.json.

How connections are stored in a session

Gotcha

JBrowse fetches the hub's track list when the connection loads and holds it in memory, and does not write it into a saved or shared session. The session stores only the tracks you open (under connectionTrackConfigs, keyed by trackId), so a shared session stays small even for a very large hub.

See also