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

A JBrowse 1 connection is also the shortest path off JBrowse 1, since it leaves the data files where they are:

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

The connection reads trackList.json and tracks.conf, follows their includes, and covers the alignment, variant, annotation, quantitative and sequence stores a JBrowse 1 instance usually holds; the exact set is one table in jb1ToJb2.ts. A storeClass it does not recognize is matched on the filename instead, and the few stores with no JBrowse 2 equivalent arrive as placeholder tracks naming the format.

A connection keeps reading the JBrowse 1 directory, which suits a site running both. Writing the tracks into config.json cuts that tie, and this gist is a standalone script along the same lines to adapt. Check either result with jbrowse validate config.json.

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