Skip to main content

Connections

TL;DR: 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. This guide covers the config format; for in-app behavior see the Connections user guide.

Where connections live

Connections come from two places, combined in the track selector:

  • connections: a top-level array in your config.json, alongside assemblies and tracks. These are administrator-defined and available to everyone who loads the config.
  • Session connections: connections a user adds at runtime. These live in the saved session, not the admin config.

Both render identically as categories in the track selector.

Connection config format

Every connection shares the base fields from BaseConnection:

  • type: the connection type (e.g. UCSCTrackHubConnection)
  • connectionId: a unique id for the connection
  • name: a human-readable name, shown as the category label
  • assemblyNames: optional list of assemblies the connection applies to, used to match hub tracks to the assemblies configured in your instance

Each type then adds its own location slot.

UCSC track hub

Points at a hub's hub.txt. See 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. See JB2TrackHubConnection.

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

JBrowse 1 data directory

Points at a legacy JBrowse 1 data directory — the one holding trackList.json and tracks.conf, either of which may be absent. Its tracks are translated to JBrowse 2 equivalents on connect. A JBrowse 1 connection serves one assembly, so assemblyNames is required and holds a single entry. See 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 is a standalone script to adapt: it reads a JBrowse 1 data directory's trackList.json and tracks.conf, follows their includes, and writes the resulting tracks into a JBrowse 2 config.json — a one-time conversion. It follows the same table as jb1ToJb2.ts: covers the usual alignment, variant, annotation, quantitative and sequence stores, matches an unrecognized storeClass on the filename, and leaves a placeholder track naming the format where there's no JBrowse 2 equivalent. Check the result with jbrowse validate config.json.

To keep serving the JBrowse 1 directory itself instead of converting it once, add it as a connection:

jbrowse add-connection https://mysite.com/jbrowse/data/ -a hg19

Same conversion, run on every connect instead of once.

Adding a connection with the CLI

jbrowse add-connection https://example.com/hub.txt \
  --type UCSCTrackHubConnection \
  --name "My Hub"

This appends a connection to the target config.json. See jbrowse add-connection for all options.

How connections are stored in a session

Gotcha

A connection config is only a pointer: the hub's track list is fetched when the connection loads and held in memory, and is not written into a saved or shared session. Only a track you actually open is stored (under connectionTrackConfigs, keyed by trackId), which is what keeps a shared session small even against a very large hub.

In the app the list is fetched when the connection's category is expanded. An opened track reopens on reload without re-fetching the whole hub, and editing it saves the change to the session.

See also